Ir para o conteúdo
Voltar ao início

Documentação para jogos web

Conecte o seu jogo do navegador aos eventos da live do TikTok por meio do app de desktop do TikAresV.

O que é e como funciona

O TikAresV é um app de desktop que lê os eventos da live do TikTok do streamer (presentes, comentários, curtidas, seguidores, compartilhamentos, assinaturas, entradas e espectadores) e os entrega ao seu jogo.

O app abre no computador do streamer uma API local em 127.0.0.1, e o seu jogo, que roda no navegador desse mesmo computador, se conecta a ela com uma API key.

  • A API local só existe enquanto o app de desktop está aberto no computador onde o jogo roda.
  • Cada evento chega com um id estável, então o seu jogo pode ignorar os que já processou.
  • O streamer define no app qual ação é disparada com cada presente, comentário ou curtida, e o seu jogo só executa as ações que recebe.
  • Você pode receber os eventos por WebSocket, que é o mais cômodo no navegador, ou por consulta periódica (long-poll) se preferir HTTP simples.

Para receber eventos você só precisa da API key do seu jogo, de um navegador no computador do streamer e das instruções desta página.

Cadastro do jogo e API key

O cadastro dos jogos é feito pela equipe do TikAresV, então escreva para nós para registrar o seu.

Contatar a equipe do TikAresV

Quando o seu jogo estiver registrado, você receberá os seguintes dados.

  • O game_id é o identificador único do seu jogo.
  • A API key tem a forma tkv_live_ mais 32 caracteres alfanuméricos e é exibida uma única vez, então guarde-a imediatamente.
  • O game_guid só é entregue nos jogos de Roblox.
Formato da API key, que identifica o seu jogo.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Se precisar trocar a key, a equipe gera uma nova e a anterior continua valendo por 24 horas (86400 segundos) para que você atualize o seu jogo sem interrupções.

Trate a key como uma senha do seu jogo e não a publique em repositórios abertos que não sejam seus.

Autenticação com a API key

Cada chamada que entrega eventos ou configuração é autenticada com a API key do seu jogo, que tem a forma tkv_live_ seguida de 32 caracteres alfanuméricos.

RotaCredencial
GET /v1/eventskey=<api_key> | x-api-key
GET /v1/events/pollx-api-key
GET /v1/configx-api-key
GET /v1/status—
Exemplo de uma consulta autenticada com o cabeçalho `x-api-key`.
GET http://127.0.0.1:17920/v1/events/poll?wait=0 HTTP/1.1
Host: 127.0.0.1:17920
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A key viaja dentro do código do seu jogo e o identifica como jogo perante o app, então não a compartilhe com outros jogos.

  • O WebSocket recebe a key no parâmetro key da URL, porque o navegador não permite colocar cabeçalhos em um WebSocket.
  • As rotas HTTP /v1/events/poll e /v1/config recebem a key somente no cabeçalho x-api-key, e o parâmetro key é ignorado nelas.
  • A rota /v1/status não precisa de key, então serve para saber se o app está aberto antes de conectar.

Início rápido

Com estes passos o seu jogo recebe o primeiro evento em poucos minutos.

  • Peça o cadastro do seu jogo à equipe do TikAresV e guarde a API key que receber, porque ela só é exibida uma vez.
  • Peça ao streamer que abra o app de desktop do TikAresV e faça login.
  • Copie o exemplo desta seção para um arquivo .html e substitua o marcador da API key pela sua.
  • Abra o arquivo no navegador do mesmo computador onde o app roda, e se o Chrome perguntar sobre o acesso à rede local, aceite.
  • Peça ao streamer que entre no jogo dele no app, edite uma regra e clique no botão Testar.
  • Confira se o registro da página mostra uma linha com o id do evento de teste e o nome da ação.
  • Quando funcionar, substitua a função runAction pelo código do seu jogo para cada ação.
Exemplo mínimo e completo de um jogo web que se conecta, se reconecta sozinho e mostra as ações recebidas.
<!doctype html>
<html lang="es">
<head>
<meta charset="utf-8">
<title>TikAresV: juego web de ejemplo</title>
</head>
<body>
<pre id="log"></pre>
<script>
const API_KEY = 'tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; // la key de tu juego
const PORT = 17920; // C-020
const TYPES = 'gift,comment,like,follow,share,subscribe,join';
const BACKOFF_S = [1, 2, 4, 8, 16, 30]; // C-028
let cursor = null;
let attempt = 0;

function log(line) {
  document.getElementById('log').textContent += line + '\n';
}

// Aquí va el código de tu juego para cada acción.
function runAction(actionKey, params) {
  console.log('acción', actionKey, params);
}

function handleEvent(ev) {
  for (const action of ev.actions) {
    log(ev.id + ' ' + action.action_key);
    for (let i = 0; i < (action.repeat || 1); i++) runAction(action.action_key, action.params);
  }
}

function retryIn(seconds) {
  const jitter = 0.8 + Math.random() * 0.4;
  setTimeout(connect, seconds * 1000 * jitter);
}

function onClose(code) {
  if (code === 4401) return log('key inválida (4401): cámbiala antes de reconectar');
  if (code === 1009) return log('mensaje demasiado grande (1009): corrige el cliente');
  if (code === 1000) return log('conexión cerrada por el juego (1000)');
  if (code === 4403) return retryIn(30); // el plan del streamer no está vigente
  retryIn(BACKOFF_S[Math.min(attempt++, BACKOFF_S.length - 1)]); // 1001, 1008, 4408 y caídas
}

function connect() {
  let url = 'ws://127.0.0.1:' + PORT + '/v1/events?key=' + encodeURIComponent(API_KEY) + '&types=' + TYPES;
  if (cursor) url += '&cursor=' + encodeURIComponent(cursor);
  const ws = new WebSocket(url);
  ws.onmessage = (message) => {
    const msg = JSON.parse(message.data);
    if (msg.type === 'hello') {
      attempt = 0;
      if (msg.data.reset) log('la app se reinició: solo llegarán eventos nuevos');
    } else if (msg.type === 'event') {
      cursor = msg.data.cursor;
      handleEvent(msg.data.event);
    } else if (msg.type === 'ping') {
      ws.send(JSON.stringify({ type: 'pong', data: { ts: msg.data.ts } }));
    } else if (msg.type === 'config.changed') {
      log('config.changed ' + msg.data.config_version);
    } else if (msg.type === 'error') {
      log('error ' + msg.data.code);
    }
  };
  ws.onclose = (close) => onClose(close.code);
}

connect();
</script>
</body>
</html>

Se algo falhar, confira a tabela de erros e a seção de solução de problemas mais abaixo.

Estado do app: GET /v1/status

Esta rota indica se o app está aberto e se pode servir eventos, e não precisa de API key.

Consulta do estado do app.
GET http://127.0.0.1:17920/v1/status
Resposta com o estado do app, da live e dos jogos conectados.
{
  "api": "local/v1",
  "agent_version": "0.1.245",
  "port": 17920,
  "server_time": "2026-10-03T21:15:30.000Z",
  "tiktok_state": "streaming",
  "live": { "active": true, "observer": false, "started_at": "2026-10-03T21:15:00.000Z" },
  "serving": true,
  "serving_reason": "live_started_with_token",
  "connected_games": 1,
  "max_connected_games": 3,
  "control_channel": "websocket"
}
  • O campo serving é true quando o app pode entregar eventos ao seu jogo.
  • O campo serving_reason explica por que serve ou por que não serve, e no_valid_token significa que o plano do streamer não está vigente.
  • O campo tiktok_state vale disconnected sem captura, waiting esperando a live e streaming com a live em andamento.
  • Os campos connected_games e max_connected_games indicam quantos jogos estão conectados e quantos o plano permite.

Conexão por WebSocket: GET /v1/events

O WebSocket entrega os eventos assim que chegam, e é a forma recomendada para jogos web.

Endereço de conexão com a key, os tipos de evento e o último cursor.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41
  • O parâmetro key é obrigatório e leva a API key codificada com encodeURIComponent.
  • O parâmetro types é opcional, lista os tipos separados por vírgulas sem espaços, e se faltar são recebidos os oito tipos.
  • O parâmetro cursor é opcional e retoma a entrega a partir do último evento que o seu jogo processou.

Logo após conectar, o app envia uma mensagem hello com o estado da sessão.

Mensagem `hello` com a qual o app confirma a conexão.
{
  "type": "hello",
  "data": {
    "api": "local/v1", "agent_version": "0.1.245", "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
    "game_name": "Juego de prueba", "platform": "web", "types": ["gift", "comment"],
    "cursor": "1791062100000-41", "reset": false, "config_version": 7,
    "live": { "live_id": "01a1039e-c820-7028-9d1f-b2da68991b17", "unique_id": "ana_streams", "observer": false,
              "started_at": "2026-10-03T21:15:00.000Z" },
    "server_time": "2026-10-03T21:15:30.010Z"
  }
}
Mensagens que o seu jogo pode receber depois do `hello`.
{ "type": "event", "data": { "cursor": "1791062100000-42", "event": { "v": 1, "id": "tt:7421234567890001001", "…": "…" } } }
{ "type": "config.changed", "data": { "config_version": 8 } }
{ "type": "ping", "data": { "ts": 1791062130000 } }
{ "type": "error", "data": { "code": "LOCAL_ACCESS_EXPIRED", "message": "local access expired", "details": { "reason": "no_valid_token" } } }

O app envia um ping a cada 30 segundos e o seu jogo deve responder pong com o mesmo ts em até 10 segundos, ou o app encerra a conexão com o código 4408.

Resposta que o seu jogo deve enviar a cada `ping`.
{ "type": "pong", "data": { "ts": 1791062130000 } }

Consulta periódica: GET /v1/events/poll

Esta rota é a alternativa aos WebSockets para clientes que só sabem fazer requisições HTTP, e espera até wait segundos antes de responder vazia.

Consulta com o cursor anterior e uma espera de 20 segundos.
GET http://127.0.0.1:17920/v1/events/poll?cursor=1791062100000-41&wait=20&types=gift,comment&limit=100
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ParâmetroObrigatórioPadrãoIntervalo
cursorno—^[0-9]{13}-[0-9]{1,19}$
waitno00–25 (C-021)
typesnogift,comment,like,follow,share,subscribe,join,viewersgift … viewers
limitno1001–100 (C-057)
Resposta com os eventos novos e o cursor que deve ser enviado na consulta seguinte.
{
  "events": [ { "v": 1, "id": "tt:7421234567890001001", "type": "gift", "…": "…" } ],
  "cursor": "1791062100000-43",
  "reset": false,
  "has_more": false,
  "config_version": 7,
  "live": { "live_id": "01a1039e-c820-7028-9d1f-b2da68991b17", "unique_id": "ana_streams", "observer": false,
            "started_at": "2026-10-03T21:15:00.000Z" },
  "server_time": "2026-10-03T21:15:30.010Z"
}
  • Repita a consulta assim que receber a resposta, enviando o cursor da resposta anterior.
  • O campo has_more é true quando sobraram eventos pelo limite limit, e então você deve consultar de novo sem esperar.
  • Se você parar de consultar por 60 segundos, o app considera que o seu jogo se desconectou.

Regras vigentes: GET /v1/config

Esta rota devolve as regras que o streamer configurou para o seu jogo, e serve para mostrar ajudas na tela.

Consulta da configuração com `If-None-Match` para evitar downloads repetidos.
GET http://127.0.0.1:17920/v1/config
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If-None-Match: "cfg-7"
Resposta com a versão e as regras da configuração.
{ "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e", "config_version": 7, "updated_at": "2026-10-03T20:58:41.512Z",
  "is_default": false, "config": { "schema": "config/v1", "rules": [ { "rule_id": "r-rosa-mensaje", "…": "…" } ] } }

O seu jogo não precisa interpretar as regras, porque cada evento já traz as suas ações resolvidas.

Conteúdo de cada evento

Todo evento tem os mesmos campos comuns, e cada tipo acrescenta o seu próprio objeto com os dados específicos.

Campos comuns de um evento, aqui com um presente.
{
  "v": 1,
  "id": "tt:7421234567890001001",
  "type": "gift",
  "ts": "2026-10-03T21:15:04.512Z",
  "live_id": "01a1039e-c820-7028-9d1f-b2da68991b17",
  "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
  "room_id": "7421234567890123456",
  "test": false,
  "user": { "user_id": "…", "unique_id": "…", "nickname": "…", "avatar_url": "…", "badges": { "…": "…" } },
  "gift": { "…": "…" }, "comment": null, "like": null, "viewers": null, "subscribe": null,
  "actions": [
    { "action_key": "show_message", "params": { "text": "…", "color": "#FF3366" }, "rule_id": "r-rosa-mensaje", "repeat": 1 }
  ]
}
  • O campo v é a versão do formato e hoje vale sempre 1.
  • O campo id é único e estável por evento, e o seu jogo deve usá-lo para ignorar duplicatas.
  • O campo type é gift, comment, like, follow, share, subscribe, join ou viewers.
  • O campo ts é a hora do evento no formato RFC 3339 UTC com milissegundos.
  • Os campos live_id, game_id e room_id identificam a live, o seu jogo e a sala do TikTok.
  • O campo test é true somente nos eventos de teste.
  • O objeto user descreve o espectador e é null somente nos eventos viewers.
  • Cada evento leva apenas o objeto do seu tipo (gift, comment, like, viewers ou subscribe) e os demais ficam em null.
  • O array actions lista o que o seu jogo deve fazer, cada uma com action_key, params, rule_id e repeat.
  • O seu jogo deve executar cada ação tantas vezes quanto repeat indicar, que vale 1 exceto nas regras de cada N curtidas.

Exemplos dos oito tipos de evento

gift
{
  "v": 1,
  "id": "tt:7421000000000001001",
  "type": "gift",
  "ts": "2026-10-03T18:05:12.345Z",
  "live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
  "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
  "room_id": "7421000000000000001",
  "test": false,
  "user": {
    "user_id": "6800000000000000001",
    "unique_id": "ana_streams",
    "nickname": "Ana",
    "avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
    "badges": {
      "moderator": false,
      "subscriber": false,
      "follower": true,
      "top_gifter": false,
      "fan_club_level": 0,
      "gifter_level": 3
    }
  },
  "gift": {
    "gift_id": "5655",
    "name": "Rose",
    "image_url": "https://p16-webcast.tiktokcdn.com/img/maliva/webcast-va/eba3a9bb85c33e017f3648eaf88d7189-tplv-obj.webp",
    "roblox_image_id": null,
    "count": 2,
    "diamonds_unit": 1,
    "diamonds_total": 2,
    "streakable": true,
    "streak": {
      "streak_id": "7421000000000000777",
      "total": 3,
      "ended": false
    }
  },
  "comment": null,
  "like": null,
  "viewers": null,
  "subscribe": null,
  "actions": [
    {
      "action_key": "show_message",
      "params": {
        "text": "Ana envió 3 Rose",
        "color": "#FF3B5C"
      },
      "rule_id": "rose-message",
      "repeat": 1
    }
  ]
}
comment
{
  "v": 1,
  "id": "tt:7421000000000001002",
  "type": "comment",
  "ts": "2026-10-03T18:05:13.100Z",
  "live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
  "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
  "room_id": "7421000000000000001",
  "test": false,
  "user": {
    "user_id": "6800000000000000001",
    "unique_id": "ana_streams",
    "nickname": "Ana",
    "avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
    "badges": {
      "moderator": false,
      "subscriber": false,
      "follower": true,
      "top_gifter": false,
      "fan_club_level": 0,
      "gifter_level": 3
    }
  },
  "gift": null,
  "comment": {
    "text": "!spawn 2 por favor"
  },
  "like": null,
  "viewers": null,
  "subscribe": null,
  "actions": [
    {
      "action_key": "spawn_item",
      "params": {
        "count": 1
      },
      "rule_id": "spawn-command",
      "repeat": 1
    },
    {
      "action_key": "show_message",
      "params": {
        "text": "Ana usó !spawn",
        "color": "#22C55E"
      },
      "rule_id": "spawn-command",
      "repeat": 1
    }
  ]
}
like
{
  "v": 1,
  "id": "tt:7421000000000001003",
  "type": "like",
  "ts": "2026-10-03T18:05:14.020Z",
  "live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
  "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
  "room_id": "7421000000000000001",
  "test": false,
  "user": {
    "user_id": "6800000000000000001",
    "unique_id": "ana_streams",
    "nickname": "Ana",
    "avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
    "badges": {
      "moderator": false,
      "subscriber": false,
      "follower": true,
      "top_gifter": false,
      "fan_club_level": 0,
      "gifter_level": 3
    }
  },
  "gift": null,
  "comment": null,
  "like": {
    "count": 15,
    "total": 1200
  },
  "viewers": null,
  "subscribe": null,
  "actions": [
    {
      "action_key": "spawn_item",
      "params": {
        "count": 5
      },
      "rule_id": "likes-100",
      "repeat": 1
    }
  ]
}
follow
{
  "v": 1,
  "id": "tt:7421000000000001004",
  "type": "follow",
  "ts": "2026-10-03T18:05:15.500Z",
  "live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
  "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
  "room_id": "7421000000000000001",
  "test": false,
  "user": {
    "user_id": "6800000000000000001",
    "unique_id": "ana_streams",
    "nickname": "Ana",
    "avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
    "badges": {
      "moderator": false,
      "subscriber": false,
      "follower": true,
      "top_gifter": false,
      "fan_club_level": 0,
      "gifter_level": 3
    }
  },
  "gift": null,
  "comment": null,
  "like": null,
  "viewers": null,
  "subscribe": null,
  "actions": [
    {
      "action_key": "show_message",
      "params": {
        "text": "¡Gracias por seguir, Ana!",
        "color": "#3B82F6"
      },
      "rule_id": "follow-thanks",
      "repeat": 1
    }
  ]
}
share
{
  "v": 1,
  "id": "tt:7421000000000001005",
  "type": "share",
  "ts": "2026-10-03T18:05:16.250Z",
  "live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
  "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
  "room_id": "7421000000000000001",
  "test": false,
  "user": {
    "user_id": "6800000000000000001",
    "unique_id": "ana_streams",
    "nickname": "Ana",
    "avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
    "badges": {
      "moderator": false,
      "subscriber": false,
      "follower": true,
      "top_gifter": false,
      "fan_club_level": 0,
      "gifter_level": 3
    }
  },
  "gift": null,
  "comment": null,
  "like": null,
  "viewers": null,
  "subscribe": null,
  "actions": []
}
subscribe
{
  "v": 1,
  "id": "tt:7421000000000001006",
  "type": "subscribe",
  "ts": "2026-10-03T18:05:17.000Z",
  "live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
  "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
  "room_id": "7421000000000000001",
  "test": false,
  "user": {
    "user_id": "6800000000000000001",
    "unique_id": "ana_streams",
    "nickname": "Ana",
    "avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
    "badges": {
      "moderator": false,
      "subscriber": true,
      "follower": true,
      "top_gifter": false,
      "fan_club_level": 4,
      "gifter_level": 3
    }
  },
  "gift": null,
  "comment": null,
  "like": null,
  "viewers": null,
  "subscribe": {
    "months": 3
  },
  "actions": []
}
join
{
  "v": 1,
  "id": "tt:7421000000000001007",
  "type": "join",
  "ts": "2026-10-03T18:05:18.750Z",
  "live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
  "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
  "room_id": "7421000000000000001",
  "test": false,
  "user": {
    "user_id": "6800000000000000002",
    "unique_id": "beto",
    "nickname": "Beto",
    "avatar_url": "https://api.tikaresv.com/v1/media/avatars/default.png",
    "badges": {
      "moderator": false,
      "subscriber": false,
      "follower": false,
      "top_gifter": false,
      "fan_club_level": 0,
      "gifter_level": 0
    }
  },
  "gift": null,
  "comment": null,
  "like": null,
  "viewers": null,
  "subscribe": null,
  "actions": []
}
viewers
{
  "v": 1,
  "id": "ag:01928f3d-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
  "type": "viewers",
  "ts": "2026-10-03T18:05:20.000Z",
  "live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
  "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
  "room_id": "7421000000000000001",
  "test": false,
  "user": null,
  "gift": null,
  "comment": null,
  "like": null,
  "viewers": {
    "current": 1234,
    "total_unique": 5678
  },
  "subscribe": null,
  "actions": []
}

Estes são os oito tipos de evento com um exemplo real de cada um.

VariávelOrigem
{{nickname}}user.nickname
{{unique_id}}user.unique_id
{{gift_name}}gift.name
{{gift_count}}gift.count
{{diamonds}}gift.diamonds_total
{{comment}}comment.text
{{likes}}like.total

Os textos de params já vêm com as variáveis substituídas, e nenhum passa de 500 caracteres.

Cursor e retomada

O cursor é uma marca opaca que indica até qual evento o seu jogo chegou, e serve para não perder eventos se a conexão cair.

Exemplo de cursor, que o seu jogo apenas guarda e devolve sem interpretá-lo.
1791062100000-42
  • Guarde o cursor de cada mensagem event ou de cada resposta de consulta.
  • Ao reconectar, envie o último cursor guardado para receber o que você perdeu.
  • Sem cursor, você só recebe os eventos posteriores à conexão.
  • Se o campo reset chegar em true, o app foi reiniciado ou o cursor não está mais disponível, e você só receberá eventos novos.

O cursor avança também sobre os eventos que o seu filtro de tipos descarta, então você não voltará a recebê-los.

Erros

Todos os erros HTTP têm a mesma forma, com um code estável que você pode comparar no seu código e uma message em inglês.

Exemplo da resposta de erro.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }
CódigoHTTPMotivoO que fazer
ORIGIN_FORBIDDEN403host_not_loopbackConecte-se sempre a `127.0.0.1` ou `localhost` e não use outro nome de máquina.
LOCAL_KEY_INVALID401key_missingEnvie a API key na URL do WebSocket ou no cabeçalho `x-api-key`.
LOCAL_KEY_INVALID401key_formatConfira se a key tem o formato `tkv_live_` seguido de 32 caracteres alfanuméricos.
LOCAL_KEY_INVALID401key_unknownConfira se você usa a key vigente do seu jogo e peça uma nova à equipe se a perdeu.
LOCAL_KEY_INVALID401game_inactiveO seu jogo está desativado, então fale com a equipe do TikAresV.
LOCAL_KEY_INVALID401game_not_visibleO seu jogo não está disponível para este streamer, então fale com a equipe do TikAresV.
LOCAL_KEY_INVALID401unresolved_offlineO app não conseguiu validar a key por falta de internet ou por excesso de tentativas, então espere alguns segundos e tente de novo.
LOCAL_ACCESS_EXPIRED403no_valid_tokenO plano do streamer não está vigente, então ele deve renová-lo na seção Plano do app e o seu jogo tentar de novo a cada 30 segundos.
LOCAL_GAMES_LIMIT403O máximo de jogos conectados do plano foi atingido, então feche outro jogo ou peça ao streamer um plano com mais jogos.
LOCAL_CURSOR_RESET200Não é um erro HTTP, e sim o aviso de que o app foi reiniciado, e o seu jogo segue com os eventos novos.
COMMON_VALIDATION_FAILED422Confira `details.fields` para ver qual parâmetro é inválido e corrija-o.
COMMON_NOT_FOUND404Confira a rota, ou espere o app baixar a configuração do jogo se você pediu `/v1/config`.
COMMON_INTERNAL500É um erro inesperado do app, então tente de novo com espera crescente e avise a equipe se persistir.

A tabela indica o que fazer diante de cada erro.

Códigos de encerramento do WebSocket

Quando a conexão é encerrada, o código indica o que o seu jogo deve fazer.

CódigoMotivo
1000normal
1001going_away
1008too_slow
1009message_too_big
4401key_invalid
4403access_expired
4408pong_timeout
  • O código 1000 significa que o seu jogo encerrou a conexão, e não requer ação.
  • O código 1001 significa que o app foi fechado ou mudou de porta, e o seu jogo deve reconectar com espera crescente e o último cursor.
  • O código 1008 significa que o seu jogo é lento demais, e deve reconectar com o último cursor.
  • O código 1009 significa que o seu jogo enviou uma mensagem grande demais, e você deve corrigir o cliente.
  • O código 4401 significa que a key é inválida ou foi revogada, e o seu jogo não deve reconectar até trocá-la.
  • O código 4403 significa que o acesso venceu, e o seu jogo deve consultar /v1/status a cada 30 segundos até que serving seja true.
  • O código 4408 significa que o seu jogo não respondeu o pong a tempo, e deve reconectar com espera crescente e o último cursor.

Limites e valores fixos

Estes são os limites que a API local aplica, e os identificadores C-### são os nomes internos de cada valor.

ConstanteValorDescrição
C-02017920Porta padrão da API local.
C-02125Espera máxima em segundos de uma consulta periódica e tempo limite recomendado para o cliente.
C-02210000Eventos retidos por jogo, ou os dos últimos 10 minutos.
C-02630Segundos entre cada ping do WebSocket.
C-02710Segundos que o seu jogo tem para responder o pong.
C-0281, 2, 4, 8, 16, 30Espera em segundos entre reconexões, com uma variação aleatória de 20 %.
C-03465536Tamanho máximo em bytes de uma mensagem do WebSocket.
C-05060Segundos sem consultar para que o app considere o jogo desconectado.
C-057100Eventos máximos por resposta de uma consulta periódica.
C-13786400Segundos que uma API key continua valendo depois de ser rotacionada.
C-138tkv_live_ + 32 base62Formato da API key.
C-1413Jogos conectados ao mesmo tempo por padrão.
C-155500Tamanho máximo em caracteres de um texto com variáveis.

Aviso de rede local no Chrome

Quando uma página pública se conecta a 127.0.0.1, o Chrome mostra um aviso de permissão de acesso à rede local.

O streamer deve aceitar esse aviso uma vez, ou o navegador bloqueará a conexão do seu jogo com o app.

Resposta do app à consulta prévia do navegador, que já inclui a autorização de rede privada.
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: x-api-key, if-none-match
Access-Control-Allow-Private-Network: true
Access-Control-Max-Age: 600
  • O aviso aparece somente em páginas públicas, e uma página aberta a partir de um arquivo local ou de http://127.0.0.1 não o mostra.
  • Se o streamer recusou a permissão, ele deve habilitá-la nas configurações do site no Chrome e recarregar a página.
  • Use sempre 127.0.0.1 em vez de localhost, porque o sistema pode resolver localhost primeiro para ::1 e o app não escuta ali.

Como testar o seu jogo

Para testar sem esperar um presente real, o streamer pode enviar eventos de teste pelo app.

  • Abra o app de desktop do TikAresV e faça login.
  • Entre no jogo na lista de jogos do app.
  • Abra uma regra existente ou crie uma nova no editor de regras.
  • Clique no botão Testar do editor de regras.
  • Confira se o seu jogo recebe o evento e executa a ação.

Os eventos de teste chegam com test: true e com um id que começa com test:.

Endereço da página de testes, que se abre no navegador enquanto o app está aberto.
GET http://127.0.0.1:17920/harness

O app inclui também uma página de testes que mostra o que um jogo receberia, sem precisar ter um.

Solução de problemas

Confira estas causas em ordem quando o seu jogo não receber eventos.

  • Se a conexão falhar de imediato, abra http://127.0.0.1:17920/v1/status no navegador e confira se o app responde.
  • Se localhost não conectar, troque para 127.0.0.1, porque o app não escuta em ::1.
  • Se receber o erro 401, confira se a key tem o formato tkv_live_ mais 32 caracteres e se não foi rotacionada.
  • Se receber o erro 403 com LOCAL_ACCESS_EXPIRED, peça ao streamer que renove o plano dele na seção Plano do app.
  • Se receber o erro 403 com LOCAL_GAMES_LIMIT, feche outro jogo conectado ou peça ao streamer um plano com mais jogos.
  • Se o navegador bloquear a conexão sem mostrar um erro do app, aceite o aviso de rede local do Chrome.
  • Se a conexão cair a cada poucos segundos, confira se o seu jogo responde pong a cada ping em menos de 10 segundos.
  • Se vir eventos repetidos após reiniciar o app, ignore os que já processou usando o id do evento.
  • Se vir o campo reset em true, o app foi reiniciado e o cursor anterior não serve mais, então o seu jogo só receberá eventos novos.