Documentación para juegos web
Conecta tu juego del navegador con los eventos del live de TikTok a través de la app de escritorio de TikAresV.
Qué es y cómo funciona
TikAresV es una app de escritorio que lee los eventos del live de TikTok del streamer (regalos, comentarios, likes, seguidores, comparticiones, suscripciones, entradas y espectadores) y los entrega a tu juego.
La app abre en el computador del streamer una API local en 127.0.0.1, y tu juego, que corre en el navegador de ese mismo computador, se conecta a ella con una API key.
- La API local solo existe mientras la app de escritorio está abierta en el computador donde corre el juego.
- Cada evento llega con un
idestable, así que tu juego puede ignorar los que ya procesó. - El streamer define en la app qué acción se dispara con cada regalo, comentario o like, y tu juego solo ejecuta las acciones que recibe.
- Puedes recibir los eventos por WebSocket, que es lo más cómodo en el navegador, o por consulta periódica (long-poll) si prefieres HTTP simple.
Para recibir eventos solo necesitas la API key de tu juego, un navegador en el computador del streamer y las instrucciones de esta página.
Alta del juego y API key
El alta de los juegos la hace el equipo de TikAresV, así que escríbenos para registrar el tuyo.
Contactar al equipo de TikAresVCuando tu juego esté registrado recibirás los siguientes datos.
- El
game_ides el identificador único de tu juego. - La API key tiene la forma
tkv_live_más 32 caracteres alfanuméricos y se muestra una sola vez, así que guárdala de inmediato. - El
game_guidsolo se entrega en los juegos de Roblox.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSi necesitas cambiar la key, el equipo genera una nueva y la anterior sigue valiendo durante 24 horas (86400 segundos) para que actualices tu juego sin cortes.
Trata la key como una contraseña de tu juego y no la publiques en repositorios abiertos que no sean tuyos.
Autenticación con la API key
Cada llamada que entrega eventos o configuración se autentica con la API key de tu juego, que tiene la forma tkv_live_ seguida de 32 caracteres alfanuméricos.
| Ruta | 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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxLa key viaja dentro del código de tu juego y lo identifica como juego ante la app, así que no la compartas con otros juegos.
- El WebSocket recibe la key en el parámetro
keyde la URL, porque el navegador no permite poner encabezados en un WebSocket. - Las rutas HTTP
/v1/events/polly/v1/configreciben la key solo en el encabezadox-api-key, y el parámetrokeyse ignora en ellas. - La ruta
/v1/statusno necesita key, así que sirve para saber si la app está abierta antes de conectar.
Inicio rápido
Con estos pasos tu juego recibe su primer evento en pocos minutos.
- Pide el alta de tu juego al equipo de TikAresV y guarda la API key que recibes, porque solo se muestra una vez.
- Pide al streamer que abra la app de escritorio de TikAresV e inicie sesión.
- Copia el ejemplo de esta sección en un archivo
.htmly reemplaza el marcador de la API key por la tuya. - Abre el archivo en el navegador del mismo computador donde corre la app, y si Chrome pregunta por el acceso a la red local, acepta.
- Pide al streamer que entre a su juego en la app, que edite una regla y que pulse el botón Probar.
- Comprueba que el registro de la página muestra una línea con el
iddel evento de prueba y el nombre de la acción. - Cuando funcione, reemplaza la función
runActionpor el código de tu juego para cada acción.
<!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>
Si algo falla, revisa la tabla de errores y la sección de solución de problemas más abajo.
Estado de la app: GET /v1/status
Esta ruta indica si la app está abierta y si puede servir eventos, y no necesita 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"
}- El campo
servingestruecuando la app puede entregar eventos a tu juego. - El campo
serving_reasonexplica por qué sirve o por qué no, yno_valid_tokensignifica que el plan del streamer no está vigente. - El campo
tiktok_statevaledisconnectedsin captura,waitingesperando el live ystreamingcon el live en curso. - Los campos
connected_gamesymax_connected_gamesindican cuántos juegos hay conectados y cuántos permite el plan.
Conexión por WebSocket: GET /v1/events
El WebSocket entrega los eventos apenas llegan, y es la forma recomendada para juegos web.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41- El parámetro
keyes obligatorio y lleva la API key codificada conencodeURIComponent. - El parámetro
typeses opcional, lista los tipos separados por comas sin espacios, y si falta se reciben los ocho tipos. - El parámetro
cursores opcional y retoma la entrega desde el último evento que tu juego procesó.
Justo después de conectar, la app envía un mensaje hello con el estado de la sesión.
{
"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" } } }La app envía un ping cada 30 segundos y tu juego debe responder pong con el mismo ts dentro de 10 segundos, o la app cierra la conexión con el código 4408.
{ "type": "pong", "data": { "ts": 1791062130000 } }Consulta periódica: GET /v1/events/poll
Esta ruta es la alternativa a los WebSocket para clientes que solo saben hacer peticiones HTTP, y espera hasta wait segundos antes de responder vacío.
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 | Obligatorio | Por defecto | Rango |
|---|---|---|---|
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"
}- Repite la consulta en cuanto recibas la respuesta, enviando el
cursorde la respuesta anterior. - El campo
has_moreestruecuando quedaron eventos por el límitelimit, y entonces debes consultar de nuevo sin esperar. - Si dejas de consultar durante 60 segundos, la app considera que tu juego se desconectó.
Reglas vigentes: GET /v1/config
Esta ruta devuelve las reglas que el streamer configuró para tu juego, y sirve para mostrar ayudas en pantalla.
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", "…": "…" } ] } }Tu juego no necesita interpretar las reglas, porque cada evento ya trae sus acciones resueltas.
Contenido de cada evento
Cada evento tiene los mismos campos comunes, y cada tipo agrega su propio objeto con los datos 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 }
]
}- El campo
ves la versión del formato y hoy vale siempre1. - El campo
ides único y estable por evento, y tu juego debe usarlo para ignorar duplicados. - El campo
typeesgift,comment,like,follow,share,subscribe,joinoviewers. - El campo
tses la hora del evento en formato RFC 3339 UTC con milisegundos. - Los campos
live_id,game_idyroom_ididentifican el live, tu juego y la sala de TikTok. - El campo
testestruesolo en los eventos de prueba. - El objeto
userdescribe al espectador y esnullsolo en los eventosviewers. - Cada evento lleva únicamente el objeto de su tipo (
gift,comment,like,viewersosubscribe) y los demás ennull. - El arreglo
actionslista lo que tu juego debe hacer, cada una conaction_key,params,rule_idyrepeat. - Tu juego debe ejecutar cada acción tantas veces como indique
repeat, que vale 1 salvo en las reglas de cada N likes.
Ejemplos de los ocho 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": []
}Estos son los ocho tipos de evento con un ejemplo real de cada uno.
| Variable | Origen |
|---|---|
{{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 |
Los textos de params ya vienen con las variables reemplazadas, y ninguno supera los 500 caracteres.
Cursor y reanudación
El cursor es una marca opaca que indica hasta qué evento llegó tu juego, y sirve para no perder eventos si la conexión se corta.
1791062100000-42- Guarda el cursor de cada mensaje
evento de cada respuesta de consulta. - Al reconectar envía el último cursor guardado para recibir lo que te perdiste.
- Sin cursor, solo recibes los eventos posteriores a la conexión.
- Si el campo
resetllega entrue, la app se reinició o el cursor ya no está disponible, y solo recibirás eventos nuevos.
El cursor avanza también sobre los eventos que tu filtro de tipos descarta, así que no los volverás a recibir.
Errores
Todos los errores HTTP tienen la misma forma, con un code estable que puedes comparar en tu código y un message en inglés.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }| Código | HTTP | Motivo | Qué hacer |
|---|---|---|---|
ORIGIN_FORBIDDEN | 403 | host_not_loopback | Conéctate siempre a `127.0.0.1` o `localhost` y no uses otro nombre de equipo. |
LOCAL_KEY_INVALID | 401 | key_missing | Envía la API key en la URL del WebSocket o en el encabezado `x-api-key`. |
LOCAL_KEY_INVALID | 401 | key_format | Revisa que la key tenga el formato `tkv_live_` seguido de 32 caracteres alfanuméricos. |
LOCAL_KEY_INVALID | 401 | key_unknown | Comprueba que usas la key vigente de tu juego y pide una nueva al equipo si la perdiste. |
LOCAL_KEY_INVALID | 401 | game_inactive | Tu juego está desactivado, así que contacta al equipo de TikAresV. |
LOCAL_KEY_INVALID | 401 | game_not_visible | Tu juego no está disponible para este streamer, así que contacta al equipo de TikAresV. |
LOCAL_KEY_INVALID | 401 | unresolved_offline | La app no pudo validar la key por falta de internet o por demasiados intentos, así que espera unos segundos y reintenta. |
LOCAL_ACCESS_EXPIRED | 403 | no_valid_token | El plan del streamer no está vigente, así que debe renovarlo en la sección Plan de la app y tu juego reintentar cada 30 segundos. |
LOCAL_GAMES_LIMIT | 403 | Se alcanzó el máximo de juegos conectados del plan, así que cierra otro juego o pide al streamer un plan con más juegos. | |
LOCAL_CURSOR_RESET | 200 | No es un error HTTP, sino el aviso de que la app se reinició, y tu juego sigue con los eventos nuevos. | |
COMMON_VALIDATION_FAILED | 422 | Revisa `details.fields` para ver qué parámetro es inválido y corrígelo. | |
COMMON_NOT_FOUND | 404 | Revisa la ruta, o espera a que la app descargue la configuración del juego si pediste `/v1/config`. | |
COMMON_INTERNAL | 500 | Es un error inesperado de la app, así que reintenta con espera creciente y avisa al equipo si persiste. |
La tabla indica qué hacer ante cada error.
Códigos de cierre del WebSocket
Cuando la conexión se cierra, el código indica qué debe hacer tu juego.
| Código | Motivo |
|---|---|
1000 | normal |
1001 | going_away |
1008 | too_slow |
1009 | message_too_big |
4401 | key_invalid |
4403 | access_expired |
4408 | pong_timeout |
- El código 1000 significa que tu juego cerró la conexión, y no requiere acción.
- El código 1001 significa que la app se cerró o cambió de puerto, y tu juego debe reconectar con espera creciente y el último cursor.
- El código 1008 significa que tu juego es demasiado lento, y debe reconectar con el último cursor.
- El código 1009 significa que tu juego envió un mensaje demasiado grande, y debes corregir el cliente.
- El código 4401 significa que la key es inválida o fue revocada, y tu juego no debe reconectar hasta cambiarla.
- El código 4403 significa que el acceso venció, y tu juego debe consultar
/v1/statuscada 30 segundos hasta queservingseatrue. - El código 4408 significa que tu juego no respondió el
ponga tiempo, y debe reconectar con espera creciente y el último cursor.
Límites y valores fijos
Estos son los límites que aplica la API local, y los identificadores C-### son los nombres internos de cada valor.
| Constante | Valor | Descripción |
|---|---|---|
C-020 | 17920 | Puerto por defecto de la API local. |
C-021 | 25 | Espera máxima en segundos de una consulta periódica y tiempo límite recomendado para el cliente. |
C-022 | 10000 | Eventos retenidos por juego, o los de los últimos 10 minutos. |
C-026 | 30 | Segundos entre cada ping del WebSocket. |
C-027 | 10 | Segundos que tiene tu juego para responder el pong. |
C-028 | 1, 2, 4, 8, 16, 30 | Espera en segundos entre reconexiones, con una variación aleatoria de 20 %. |
C-034 | 65536 | Tamaño máximo en bytes de un mensaje del WebSocket. |
C-050 | 60 | Segundos sin consultar para que la app considere desconectado al juego. |
C-057 | 100 | Eventos máximos por respuesta de una consulta periódica. |
C-137 | 86400 | Segundos que sigue valiendo una API key después de ser rotada. |
C-138 | tkv_live_ + 32 base62 | Formato de la API key. |
C-141 | 3 | Juegos conectados a la vez por defecto. |
C-155 | 500 | Largo máximo en caracteres de un texto con variables. |
Aviso de red local en Chrome
Cuando una página pública se conecta a 127.0.0.1, Chrome muestra un aviso de permiso de acceso a la red local.
El streamer debe aceptar ese aviso una vez, o el navegador bloqueará la conexión de tu juego con la 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- El aviso aparece solo en páginas públicas, y una página abierta desde un archivo local o desde
http://127.0.0.1no lo muestra. - Si el streamer rechazó el permiso, debe habilitarlo en la configuración del sitio en Chrome y recargar la página.
- Usa siempre
127.0.0.1en lugar delocalhost, porque el sistema puede resolverlocalhostprimero a::1y la app no escucha ahí.
Cómo probar tu juego
Para probar sin esperar un regalo real, el streamer puede enviar eventos de prueba desde la app.
- Abre la app de escritorio de TikAresV e inicia sesión.
- Entra al juego en la lista de juegos de la app.
- Abre una regla existente o crea una nueva en el editor de reglas.
- Pulsa el botón Probar del editor de reglas.
- Comprueba que tu juego recibe el evento y ejecuta la acción.
Los eventos de prueba llegan con test: true y con un id que empieza con test:.
GET http://127.0.0.1:17920/harnessLa app incluye además una página de pruebas que muestra lo que recibiría un juego, sin necesidad de tener uno.
Solución de problemas
Revisa estas causas en orden cuando tu juego no recibe eventos.
- Si la conexión falla de inmediato, abre
http://127.0.0.1:17920/v1/statusen el navegador y comprueba que la app responde. - Si
localhostno conecta, cambia a127.0.0.1, porque la app no escucha en::1. - Si recibes el error 401, revisa que la key tenga el formato
tkv_live_más 32 caracteres y que no haya sido rotada. - Si recibes el error 403 con
LOCAL_ACCESS_EXPIRED, pide al streamer que renueve su plan en la sección Plan de la app. - Si recibes el error 403 con
LOCAL_GAMES_LIMIT, cierra otro juego conectado o pide al streamer un plan con más juegos. - Si el navegador bloquea la conexión sin mostrar un error de la app, acepta el aviso de red local de Chrome.
- Si la conexión se cae cada pocos segundos, comprueba que tu juego responde
ponga cadapingen menos de 10 segundos. - Si ves eventos repetidos tras reiniciar la app, ignora los que ya procesaste usando el
iddel evento. - Si ves el campo
resetentrue, la app se reinició y el cursor anterior ya no sirve, así que tu juego solo recibirá eventos nuevos.