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
idestá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 TikAresVQuando 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_guidsó é entregue nos jogos de Roblox.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSe 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.
| Rota | Credencial |
|---|---|
GET /v1/events | key=<api_key> | x-api-key |
GET /v1/events/poll | x-api-key |
GET /v1/config | x-api-key |
GET /v1/status | — |
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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxA 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
keyda URL, porque o navegador não permite colocar cabeçalhos em um WebSocket. - As rotas HTTP
/v1/events/polle/v1/configrecebem a key somente no cabeçalhox-api-key, e o parâmetrokeyé ignorado nelas. - A rota
/v1/statusnã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
.htmle 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
iddo evento de teste e o nome da ação. - Quando funcionar, substitua a função
runActionpelo código do seu jogo para cada ação.
<!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.
GET http://127.0.0.1:17920/v1/status{
"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étruequando o app pode entregar eventos ao seu jogo. - O campo
serving_reasonexplica por que serve ou por que não serve, eno_valid_tokensignifica que o plano do streamer não está vigente. - O campo
tiktok_statevaledisconnectedsem captura,waitingesperando a live estreamingcom a live em andamento. - Os campos
connected_gamesemax_connected_gamesindicam 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.
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 comencodeURIComponent. - 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.
{
"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"
}
}{ "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.
{ "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.
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âmetro | Obrigatório | Padrão | Intervalo |
|---|---|---|---|
cursor | no | — | ^[0-9]{13}-[0-9]{1,19}$ |
wait | no | 0 | 0–25 (C-021) |
types | no | gift,comment,like,follow,share,subscribe,join,viewers | gift … viewers |
limit | no | 100 | 1–100 (C-057) |
{
"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
cursorda resposta anterior. - O campo
has_moreétruequando sobraram eventos pelo limitelimit, 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.
GET http://127.0.0.1:17920/v1/config
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If-None-Match: "cfg-7"{ "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.
{
"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 sempre1. - 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,joinouviewers. - O campo
tsé a hora do evento no formato RFC 3339 UTC com milissegundos. - Os campos
live_id,game_ideroom_ididentificam a live, o seu jogo e a sala do TikTok. - O campo
testétruesomente nos eventos de teste. - O objeto
userdescreve o espectador e énullsomente nos eventosviewers. - Cada evento leva apenas o objeto do seu tipo (
gift,comment,like,viewersousubscribe) e os demais ficam emnull. - O array
actionslista o que o seu jogo deve fazer, cada uma comaction_key,params,rule_iderepeat. - O seu jogo deve executar cada ação tantas vezes quanto
repeatindicar, 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ável | Origem |
|---|---|
{{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.
1791062100000-42- Guarde o cursor de cada mensagem
eventou 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
resetchegar emtrue, 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.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }| Código | HTTP | Motivo | O que fazer |
|---|---|---|---|
ORIGIN_FORBIDDEN | 403 | host_not_loopback | Conecte-se sempre a `127.0.0.1` ou `localhost` e não use outro nome de máquina. |
LOCAL_KEY_INVALID | 401 | key_missing | Envie a API key na URL do WebSocket ou no cabeçalho `x-api-key`. |
LOCAL_KEY_INVALID | 401 | key_format | Confira se a key tem o formato `tkv_live_` seguido de 32 caracteres alfanuméricos. |
LOCAL_KEY_INVALID | 401 | key_unknown | Confira se você usa a key vigente do seu jogo e peça uma nova à equipe se a perdeu. |
LOCAL_KEY_INVALID | 401 | game_inactive | O seu jogo está desativado, então fale com a equipe do TikAresV. |
LOCAL_KEY_INVALID | 401 | game_not_visible | O seu jogo não está disponível para este streamer, então fale com a equipe do TikAresV. |
LOCAL_KEY_INVALID | 401 | unresolved_offline | O 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_EXPIRED | 403 | no_valid_token | O 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_LIMIT | 403 | O 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_RESET | 200 | Nã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_FAILED | 422 | Confira `details.fields` para ver qual parâmetro é inválido e corrija-o. | |
COMMON_NOT_FOUND | 404 | Confira a rota, ou espere o app baixar a configuração do jogo se você pediu `/v1/config`. | |
COMMON_INTERNAL | 500 | É 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ódigo | Motivo |
|---|---|
1000 | normal |
1001 | going_away |
1008 | too_slow |
1009 | message_too_big |
4401 | key_invalid |
4403 | access_expired |
4408 | pong_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/statusa cada 30 segundos até queservingsejatrue. - O código 4408 significa que o seu jogo não respondeu o
ponga 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.
| Constante | Valor | Descrição |
|---|---|---|
C-020 | 17920 | Porta padrão da API local. |
C-021 | 25 | Espera máxima em segundos de uma consulta periódica e tempo limite recomendado para o cliente. |
C-022 | 10000 | Eventos retidos por jogo, ou os dos últimos 10 minutos. |
C-026 | 30 | Segundos entre cada ping do WebSocket. |
C-027 | 10 | Segundos que o seu jogo tem para responder o pong. |
C-028 | 1, 2, 4, 8, 16, 30 | Espera em segundos entre reconexões, com uma variação aleatória de 20 %. |
C-034 | 65536 | Tamanho máximo em bytes de uma mensagem do WebSocket. |
C-050 | 60 | Segundos sem consultar para que o app considere o jogo desconectado. |
C-057 | 100 | Eventos máximos por resposta de uma consulta periódica. |
C-137 | 86400 | Segundos que uma API key continua valendo depois de ser rotacionada. |
C-138 | tkv_live_ + 32 base62 | Formato da API key. |
C-141 | 3 | Jogos conectados ao mesmo tempo por padrão. |
C-155 | 500 | Tamanho 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.
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.1nã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.1em vez delocalhost, porque o sistema pode resolverlocalhostprimeiro para::1e 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:.
GET http://127.0.0.1:17920/harnessO 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/statusno navegador e confira se o app responde. - Se
localhostnão conectar, troque para127.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
ponga cadapingem menos de 10 segundos. - Se vir eventos repetidos após reiniciar o app, ignore os que já processou usando o
iddo evento. - Se vir o campo
resetemtrue, o app foi reiniciado e o cursor anterior não serve mais, então o seu jogo só receberá eventos novos.