Saltar al contenido
Volver al inicio

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 id estable, 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 TikAresV

Cuando tu juego esté registrado recibirás los siguientes datos.

  • El game_id es 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_guid solo se entrega en los juegos de Roblox.
Formato de la API key, que identifica a tu juego.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Si 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.

RutaCredencial
GET /v1/eventskey=<api_key> | x-api-key
GET /v1/events/pollx-api-key
GET /v1/configx-api-key
GET /v1/status—
Ejemplo de una consulta autenticada con el encabezado `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

La 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 key de la URL, porque el navegador no permite poner encabezados en un WebSocket.
  • Las rutas HTTP /v1/events/poll y /v1/config reciben la key solo en el encabezado x-api-key, y el parámetro key se ignora en ellas.
  • La ruta /v1/status no 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 .html y 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 id del evento de prueba y el nombre de la acción.
  • Cuando funcione, reemplaza la función runAction por el código de tu juego para cada acción.
Ejemplo mínimo y completo de un juego web que se conecta, se reconecta solo y muestra las acciones recibidas.
<!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.

Consulta del estado de la app.
GET http://127.0.0.1:17920/v1/status
Respuesta con el estado de la app, del live y de los juegos 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"
}
  • El campo serving es true cuando la app puede entregar eventos a tu juego.
  • El campo serving_reason explica por qué sirve o por qué no, y no_valid_token significa que el plan del streamer no está vigente.
  • El campo tiktok_state vale disconnected sin captura, waiting esperando el live y streaming con el live en curso.
  • Los campos connected_games y max_connected_games indican 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.

Dirección de conexión con la key, los tipos de evento y el último cursor.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41
  • El parámetro key es obligatorio y lleva la API key codificada con encodeURIComponent.
  • El parámetro types es opcional, lista los tipos separados por comas sin espacios, y si falta se reciben los ocho tipos.
  • El parámetro cursor es 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.

Mensaje `hello` con el que la app confirma la conexió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"
  }
}
Mensajes que tu juego puede recibir después del `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" } } }

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.

Respuesta que tu juego debe enviar a cada `ping`.
{ "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.

Consulta con el cursor anterior y una 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ámetroObligatorioPor defectoRango
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)
Respuesta con los eventos nuevos y el cursor que se debe enviar en la siguiente consulta.
{
  "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 cursor de la respuesta anterior.
  • El campo has_more es true cuando quedaron eventos por el límite limit, 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.

Consulta de la configuración con `If-None-Match` para evitar descargas repetidas.
GET http://127.0.0.1:17920/v1/config
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If-None-Match: "cfg-7"
Respuesta con la versión y las reglas de la configuración.
{ "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.

Campos comunes de un evento, aquí con un regalo.
{
  "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 v es la versión del formato y hoy vale siempre 1.
  • El campo id es único y estable por evento, y tu juego debe usarlo para ignorar duplicados.
  • El campo type es gift, comment, like, follow, share, subscribe, join o viewers.
  • El campo ts es la hora del evento en formato RFC 3339 UTC con milisegundos.
  • Los campos live_id, game_id y room_id identifican el live, tu juego y la sala de TikTok.
  • El campo test es true solo en los eventos de prueba.
  • El objeto user describe al espectador y es null solo en los eventos viewers.
  • Cada evento lleva únicamente el objeto de su tipo (gift, comment, like, viewers o subscribe) y los demás en null.
  • El arreglo actions lista lo que tu juego debe hacer, cada una con action_key, params, rule_id y repeat.
  • 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.

VariableOrigen
{{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.

Ejemplo de cursor, que tu juego solo guarda y devuelve sin interpretarlo.
1791062100000-42
  • Guarda el cursor de cada mensaje event o 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 reset llega en true, 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.

Ejemplo de la respuesta de error.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }
CódigoHTTPMotivoQué hacer
ORIGIN_FORBIDDEN403host_not_loopbackConéctate siempre a `127.0.0.1` o `localhost` y no uses otro nombre de equipo.
LOCAL_KEY_INVALID401key_missingEnvía la API key en la URL del WebSocket o en el encabezado `x-api-key`.
LOCAL_KEY_INVALID401key_formatRevisa que la key tenga el formato `tkv_live_` seguido de 32 caracteres alfanuméricos.
LOCAL_KEY_INVALID401key_unknownComprueba que usas la key vigente de tu juego y pide una nueva al equipo si la perdiste.
LOCAL_KEY_INVALID401game_inactiveTu juego está desactivado, así que contacta al equipo de TikAresV.
LOCAL_KEY_INVALID401game_not_visibleTu juego no está disponible para este streamer, así que contacta al equipo de TikAresV.
LOCAL_KEY_INVALID401unresolved_offlineLa app no pudo validar la key por falta de internet o por demasiados intentos, así que espera unos segundos y reintenta.
LOCAL_ACCESS_EXPIRED403no_valid_tokenEl 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_LIMIT403Se 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_RESET200No es un error HTTP, sino el aviso de que la app se reinició, y tu juego sigue con los eventos nuevos.
COMMON_VALIDATION_FAILED422Revisa `details.fields` para ver qué parámetro es inválido y corrígelo.
COMMON_NOT_FOUND404Revisa la ruta, o espera a que la app descargue la configuración del juego si pediste `/v1/config`.
COMMON_INTERNAL500Es 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ódigoMotivo
1000normal
1001going_away
1008too_slow
1009message_too_big
4401key_invalid
4403access_expired
4408pong_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/status cada 30 segundos hasta que serving sea true.
  • El código 4408 significa que tu juego no respondió el pong a 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.

ConstanteValorDescripción
C-02017920Puerto por defecto de la API local.
C-02125Espera máxima en segundos de una consulta periódica y tiempo límite recomendado para el cliente.
C-02210000Eventos retenidos por juego, o los de los últimos 10 minutos.
C-02630Segundos entre cada ping del WebSocket.
C-02710Segundos que tiene tu juego para responder el pong.
C-0281, 2, 4, 8, 16, 30Espera en segundos entre reconexiones, con una variación aleatoria de 20 %.
C-03465536Tamaño máximo en bytes de un mensaje del WebSocket.
C-05060Segundos sin consultar para que la app considere desconectado al juego.
C-057100Eventos máximos por respuesta de una consulta periódica.
C-13786400Segundos que sigue valiendo una API key después de ser rotada.
C-138tkv_live_ + 32 base62Formato de la API key.
C-1413Juegos conectados a la vez por defecto.
C-155500Largo 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.

Respuesta de la app a la consulta previa del navegador, que ya incluye la autorización de red 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
  • El aviso aparece solo en páginas públicas, y una página abierta desde un archivo local o desde http://127.0.0.1 no 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.1 en lugar de localhost, porque el sistema puede resolver localhost primero a ::1 y 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:.

Dirección de la página de pruebas, que se abre en el navegador mientras la app está abierta.
GET http://127.0.0.1:17920/harness

La 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/status en el navegador y comprueba que la app responde.
  • Si localhost no conecta, cambia a 127.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 pong a cada ping en menos de 10 segundos.
  • Si ves eventos repetidos tras reiniciar la app, ignora los que ya procesaste usando el id del evento.
  • Si ves el campo reset en true, la app se reinició y el cursor anterior ya no sirve, así que tu juego solo recibirá eventos nuevos.