Salta al contingut
Torna a l’inici

Documentació per a jocs web

Connecta el teu joc del navegador amb els esdeveniments del directe de TikTok mitjançant l'aplicació d'escriptori de TikAresV.

Què és i com funciona

TikAresV és una aplicació d'escriptori que llegeix els esdeveniments del directe de TikTok de l'streamer (regals, comentaris, likes, seguidors, comparticions, subscripcions, entrades i espectadors) i els lliura al teu joc.

L'aplicació obre a l'ordinador de l'streamer una API local a 127.0.0.1, i el teu joc, que s'executa al navegador d'aquell mateix ordinador, s'hi connecta amb una API key.

  • L'API local només existeix mentre l'aplicació d'escriptori és oberta a l'ordinador on s'executa el joc.
  • Cada esdeveniment arriba amb un id estable, de manera que el teu joc pot ignorar els que ja ha processat.
  • El streamer defineix a l'aplicació quina acció es dispara amb cada regal, comentari o like, i el teu joc només executa les accions que rep.
  • Pots rebre els esdeveniments per WebSocket, que és el més còmode al navegador, o per consulta periòdica (long-poll) si prefereixes HTTP simple.

Per rebre esdeveniments només necessites l'API key del teu joc, un navegador a l'ordinador de l'streamer i les instruccions d'aquesta pàgina.

Alta del joc i API key

L'alta dels jocs la fa l'equip de TikAresV, així que escriu-nos per registrar el teu.

Contactar amb l'equip de TikAresV

Quan el teu joc estigui registrat rebràs les dades següents.

  • El game_id és l'identificador únic del teu joc.
  • L'API key té la forma tkv_live_ més 32 caràcters alfanumèrics i es mostra una sola vegada, així que guarda-la de seguida.
  • El game_guid només es lliura als jocs de Roblox.
Format de l'API key, que identifica el teu joc.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Si necessites canviar la key, l'equip en genera una de nova i l'anterior continua valent durant 24 hores (86400 segons) perquè actualitzis el teu joc sense talls.

Tracta la key com una contrasenya del teu joc i no la publiquis en repositoris oberts que no siguin teus.

Autenticació amb l'API key

Cada crida que lliura esdeveniments o configuració s'autentica amb l'API key del teu joc, que té la forma tkv_live_ seguida de 32 caràcters alfanumèrics.

RutaCredencial
GET /v1/eventskey=<api_key> | x-api-key
GET /v1/events/pollx-api-key
GET /v1/configx-api-key
GET /v1/status—
Exemple d'una consulta autenticada amb la capçalera `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 viatja dins del codi del teu joc i l'identifica com a joc davant l'aplicació, així que no la comparteixis amb altres jocs.

  • El WebSocket rep la key al paràmetre key de l'URL, perquè el navegador no permet posar capçaleres en un WebSocket.
  • Les rutes HTTP /v1/events/poll i /v1/config reben la key només a la capçalera x-api-key, i el paràmetre key s'hi ignora.
  • La ruta /v1/status no necessita key, així que serveix per saber si l'aplicació és oberta abans de connectar.

Inici ràpid

Amb aquests passos el teu joc rep el primer esdeveniment en pocs minuts.

  • Demana l'alta del teu joc a l'equip de TikAresV i guarda l'API key que rebis, perquè només es mostra una vegada.
  • Demana a l'streamer que obri l'aplicació d'escriptori de TikAresV i iniciï sessió.
  • Copia l'exemple d'aquesta secció en un fitxer .html i substitueix el marcador de l'API key per la teva.
  • Obre el fitxer al navegador del mateix ordinador on s'executa l'aplicació, i si Chrome pregunta per l'accés a la xarxa local, accepta.
  • Demana a l'streamer que entri al seu joc a l'aplicació, que editi una regla i que premi el botó Provar.
  • Comprova que el registre de la pàgina mostra una línia amb l'id de l'esdeveniment de prova i el nom de l'acció.
  • Quan funcioni, substitueix la funció runAction pel codi del teu joc per a cada acció.
Exemple mínim i complet d'un joc web que es connecta, es reconnecta sol i mostra les accions rebudes.
<!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 alguna cosa falla, revisa la taula d'errors i la secció de resolució de problemes més avall.

Estat de l'aplicació: GET /v1/status

Aquesta ruta indica si l'aplicació és oberta i si pot servir esdeveniments, i no necessita API key.

Consulta de l'estat de l'aplicació.
GET http://127.0.0.1:17920/v1/status
Resposta amb l'estat de l'aplicació, del directe i dels jocs connectats.
{
  "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 camp serving és true quan l'aplicació pot lliurar esdeveniments al teu joc.
  • El camp serving_reason explica per què serveix o per què no, i no_valid_token vol dir que el pla de l'streamer no és vigent.
  • El camp tiktok_state val disconnected sense captura, waiting esperant el directe i streaming amb el directe en curs.
  • Els camps connected_games i max_connected_games indiquen quants jocs hi ha connectats i quants en permet el pla.

Connexió per WebSocket: GET /v1/events

El WebSocket lliura els esdeveniments tan bon punt arriben, i és la forma recomanada per a jocs web.

Adreça de connexió amb la key, els tipus d'esdeveniment i l'últim cursor.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41
  • El paràmetre key és obligatori i porta l'API key codificada amb encodeURIComponent.
  • El paràmetre types és opcional, llista els tipus separats per comes sense espais, i si falta es reben els vuit tipus.
  • El paràmetre cursor és opcional i reprèn el lliurament des de l'últim esdeveniment que el teu joc va processar.

Just després de connectar, l'aplicació envia un missatge hello amb l'estat de la sessió.

Missatge `hello` amb el qual l'aplicació confirma la connexió.
{
  "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"
  }
}
Missatges que el teu joc pot rebre despré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" } } }

L'aplicació envia un ping cada 30 segons i el teu joc ha de respondre pong amb el mateix ts dins de 10 segons, o l'aplicació tanca la connexió amb el codi 4408.

Resposta que el teu joc ha d'enviar a cada `ping`.
{ "type": "pong", "data": { "ts": 1791062130000 } }

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

Aquesta ruta és l'alternativa als WebSocket per a clients que només saben fer peticions HTTP, i espera fins a wait segons abans de respondre buida.

Consulta amb el cursor anterior i una espera de 20 segons.
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àmetreObligatoriPer defecteRang
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 amb els esdeveniments nous i el cursor que s'ha d'enviar a la consulta següent.
{
  "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"
}
  • Repeteix la consulta tan bon punt rebis la resposta, enviant el cursor de la resposta anterior.
  • El camp has_more és true quan han quedat esdeveniments pel límit limit, i llavors has de consultar de nou sense esperar.
  • Si deixes de consultar durant 60 segons, l'aplicació considera que el teu joc s'ha desconnectat.

Regles vigents: GET /v1/config

Aquesta ruta retorna les regles que l'streamer ha configurat per al teu joc, i serveix per mostrar ajudes en pantalla.

Consulta de la configuració amb `If-None-Match` per evitar baixades repetides.
GET http://127.0.0.1:17920/v1/config
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If-None-Match: "cfg-7"
Resposta amb la versió i les regles de la configuració.
{ "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", "…": "…" } ] } }

El teu joc no necessita interpretar les regles, perquè cada esdeveniment ja porta les seves accions resoltes.

Contingut de cada esdeveniment

Cada esdeveniment té els mateixos camps comuns, i cada tipus afegeix el seu propi objecte amb les dades específiques.

Camps comuns d'un esdeveniment, aquí amb un regal.
{
  "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 camp v és la versió del format i avui val sempre 1.
  • El camp id és únic i estable per esdeveniment, i el teu joc l'ha d'usar per ignorar duplicats.
  • El camp type és gift, comment, like, follow, share, subscribe, join o viewers.
  • El camp ts és l'hora de l'esdeveniment en format RFC 3339 UTC amb mil·lisegons.
  • Els camps live_id, game_id i room_id identifiquen el directe, el teu joc i la sala de TikTok.
  • El camp test és true només en els esdeveniments de prova.
  • L'objecte user descriu l'espectador i és null només en els esdeveniments viewers.
  • Cada esdeveniment porta únicament l'objecte del seu tipus (gift, comment, like, viewers o subscribe) i els altres són null.
  • L'array actions llista el que el teu joc ha de fer, cadascuna amb action_key, params, rule_id i repeat.
  • El teu joc ha d'executar cada acció tantes vegades com indiqui repeat, que val 1 tret de les regles de cada N likes.

Exemples dels vuit tipus d'esdeveniment

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": []
}

Aquests són els vuit tipus d'esdeveniment amb un exemple real de cadascun.

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

Els textos de params ja vénen amb les variables substituïdes, i cap no supera els 500 caràcters.

Cursor i represa

El cursor és una marca opaca que indica fins a quin esdeveniment ha arribat el teu joc, i serveix per no perdre esdeveniments si la connexió es talla.

Exemple de cursor, que el teu joc només guarda i retorna sense interpretar-lo.
1791062100000-42
  • Guarda el cursor de cada missatge event o de cada resposta de consulta.
  • En reconnectar, envia l'últim cursor guardat per rebre el que t'has perdut.
  • Sense cursor, només reps els esdeveniments posteriors a la connexió.
  • Si el camp reset arriba en true, l'aplicació s'ha reiniciat o el cursor ja no està disponible, i només rebràs esdeveniments nous.

El cursor avança també sobre els esdeveniments que el teu filtre de tipus descarta, així que no els tornaràs a rebre.

Errors

Tots els errors HTTP tenen la mateixa forma, amb un code estable que pots comparar al teu codi i un message en anglès.

Exemple de la resposta d'error.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }
CodiHTTPMotiuQuè cal fer
ORIGIN_FORBIDDEN403host_not_loopbackConnecta't sempre a `127.0.0.1` o `localhost` i no facis servir cap altre nom d'equip.
LOCAL_KEY_INVALID401key_missingEnvia l'API key a l'URL del WebSocket o a la capçalera `x-api-key`.
LOCAL_KEY_INVALID401key_formatRevisa que la key tingui el format `tkv_live_` seguit de 32 caràcters alfanumèrics.
LOCAL_KEY_INVALID401key_unknownComprova que fas servir la key vigent del teu joc i demana'n una de nova a l'equip si l'has perdut.
LOCAL_KEY_INVALID401game_inactiveEl teu joc està desactivat, així que contacta amb l'equip de TikAresV.
LOCAL_KEY_INVALID401game_not_visibleEl teu joc no està disponible per a aquest streamer, així que contacta amb l'equip de TikAresV.
LOCAL_KEY_INVALID401unresolved_offlineL'aplicació no ha pogut validar la key per manca d'internet o per massa intents, així que espera uns segons i reintenta.
LOCAL_ACCESS_EXPIRED403no_valid_tokenEl pla de l'streamer no és vigent, així que l'ha de renovar a la secció Pla de l'aplicació i el teu joc ha de reintentar cada 30 segons.
LOCAL_GAMES_LIMIT403S'ha arribat al màxim de jocs connectats del pla, així que tanca un altre joc o demana a l'streamer un pla amb més jocs.
LOCAL_CURSOR_RESET200No és un error HTTP, sinó l'avís que l'aplicació s'ha reiniciat, i el teu joc continua amb els esdeveniments nous.
COMMON_VALIDATION_FAILED422Revisa `details.fields` per veure quin paràmetre no és vàlid i corregeix-lo.
COMMON_NOT_FOUND404Revisa la ruta, o espera que l'aplicació baixi la configuració del joc si has demanat `/v1/config`.
COMMON_INTERNAL500És un error inesperat de l'aplicació, així que reintenta amb espera creixent i avisa l'equip si persisteix.

La taula indica què cal fer davant de cada error.

Codis de tancament del WebSocket

Quan la connexió es tanca, el codi indica què ha de fer el teu joc.

CodiMotiu
1000normal
1001going_away
1008too_slow
1009message_too_big
4401key_invalid
4403access_expired
4408pong_timeout
  • El codi 1000 vol dir que el teu joc ha tancat la connexió, i no requereix cap acció.
  • El codi 1001 vol dir que l'aplicació s'ha tancat o ha canviat de port, i el teu joc s'ha de reconnectar amb espera creixent i l'últim cursor.
  • El codi 1008 vol dir que el teu joc és massa lent, i s'ha de reconnectar amb l'últim cursor.
  • El codi 1009 vol dir que el teu joc ha enviat un missatge massa gran, i has de corregir el client.
  • El codi 4401 vol dir que la key no és vàlida o ha estat revocada, i el teu joc no s'ha de reconnectar fins a canviar-la.
  • El codi 4403 vol dir que l'accés ha vençut, i el teu joc ha de consultar /v1/status cada 30 segons fins que serving sigui true.
  • El codi 4408 vol dir que el teu joc no ha respost el pong a temps, i s'ha de reconnectar amb espera creixent i l'últim cursor.

Límits i valors fixos

Aquests són els límits que aplica l'API local, i els identificadors C-### són els noms interns de cada valor.

ConstantValorDescripció
C-02017920Port per defecte de l'API local.
C-02125Espera màxima en segons d'una consulta periòdica i temps límit recomanat per al client.
C-02210000Esdeveniments retinguts per joc, o els dels últims 10 minuts.
C-02630Segons entre cada ping del WebSocket.
C-02710Segons que té el teu joc per respondre el pong.
C-0281, 2, 4, 8, 16, 30Espera en segons entre reconnexions, amb una variació aleatòria del 20 %.
C-03465536Mida màxima en bytes d'un missatge del WebSocket.
C-05060Segons sense consultar perquè l'aplicació consideri el joc desconnectat.
C-057100Esdeveniments màxims per resposta d'una consulta periòdica.
C-13786400Segons que continua valent una API key després de ser rotada.
C-138tkv_live_ + 32 base62Format de l'API key.
C-1413Jocs connectats alhora per defecte.
C-155500Llargada màxima en caràcters d'un text amb variables.

Avís de xarxa local a Chrome

Quan una pàgina pública es connecta a 127.0.0.1, Chrome mostra un avís de permís d'accés a la xarxa local.

El streamer ha d'acceptar aquest avís una vegada, o el navegador bloquejarà la connexió del teu joc amb l'aplicació.

Resposta de l'aplicació a la consulta prèvia del navegador, que ja inclou l'autorització de xarxa 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
  • L'avís apareix només en pàgines públiques, i una pàgina oberta des d'un fitxer local o des de http://127.0.0.1 no el mostra.
  • Si l'streamer ha rebutjat el permís, l'ha d'habilitar a la configuració del lloc a Chrome i recarregar la pàgina.
  • Fes servir sempre 127.0.0.1 en lloc de localhost, perquè el sistema pot resoldre localhost primer a ::1 i l'aplicació no hi escolta.

Com provar el teu joc

Per provar sense esperar un regal real, l'streamer pot enviar esdeveniments de prova des de l'aplicació.

  • Obre l'aplicació d'escriptori de TikAresV i inicia sessió.
  • Entra al joc a la llista de jocs de l'aplicació.
  • Obre una regla existent o crea'n una de nova a l'editor de regles.
  • Prem el botó Provar de l'editor de regles.
  • Comprova que el teu joc rep l'esdeveniment i executa l'acció.

Els esdeveniments de prova arriben amb test: true i amb un id que comença per test:.

Adreça de la pàgina de proves, que s'obre al navegador mentre l'aplicació és oberta.
GET http://127.0.0.1:17920/harness

L'aplicació inclou a més una pàgina de proves que mostra el que rebria un joc, sense necessitat de tenir-ne un.

Resolució de problemes

Revisa aquestes causes per ordre quan el teu joc no rebi esdeveniments.

  • Si la connexió falla de seguida, obre http://127.0.0.1:17920/v1/status al navegador i comprova que l'aplicació respon.
  • Si localhost no connecta, canvia a 127.0.0.1, perquè l'aplicació no escolta a ::1.
  • Si reps l'error 401, revisa que la key tingui el format tkv_live_ més 32 caràcters i que no hagi estat rotada.
  • Si reps l'error 403 amb LOCAL_ACCESS_EXPIRED, demana a l'streamer que renovi el seu pla a la secció Pla de l'aplicació.
  • Si reps l'error 403 amb LOCAL_GAMES_LIMIT, tanca un altre joc connectat o demana a l'streamer un pla amb més jocs.
  • Si el navegador bloqueja la connexió sense mostrar un error de l'aplicació, accepta l'avís de xarxa local de Chrome.
  • Si la connexió cau cada pocs segons, comprova que el teu joc respon pong a cada ping en menys de 10 segons.
  • Si veus esdeveniments repetits després de reiniciar l'aplicació, ignora els que ja has processat fent servir l'id de l'esdeveniment.
  • Si veus el camp reset en true, l'aplicació s'ha reiniciat i el cursor anterior ja no serveix, així que el teu joc només rebrà esdeveniments nous.