Vai al contenuto
Torna alla home

Documentazione per i giochi web

Collega il tuo gioco del browser agli eventi della live di TikTok tramite l'app desktop di TikAresV.

Che cos'è e come funziona

TikAresV è un'app desktop che legge gli eventi della live di TikTok dello streamer (regali, commenti, like, follower, condivisioni, abbonamenti, ingressi e spettatori) e li consegna al tuo gioco.

L'app apre sul computer dello streamer una API locale su 127.0.0.1, e il tuo gioco, che gira nel browser di quello stesso computer, si collega a essa con una API key.

  • La API locale esiste solo finché l'app desktop è aperta sul computer dove gira il gioco.
  • Ogni evento arriva con un id stabile, quindi il tuo gioco può ignorare quelli che ha già elaborato.
  • Lo streamer definisce nell'app quale azione scatta con ogni regalo, commento o like, e il tuo gioco esegue solo le azioni che riceve.
  • Puoi ricevere gli eventi tramite WebSocket, che è la soluzione più comoda nel browser, oppure tramite richiesta periodica (long-poll) se preferisci HTTP semplice.

Per ricevere eventi ti servono solo la API key del tuo gioco, un browser sul computer dello streamer e le istruzioni di questa pagina.

Registrazione del gioco e API key

La registrazione dei giochi la fa il team di TikAresV, quindi scrivici per registrare il tuo.

Contatta il team di TikAresV

Quando il tuo gioco sarà registrato riceverai i seguenti dati.

  • Il game_id è l'identificatore univoco del tuo gioco.
  • La API key ha la forma tkv_live_ più 32 caratteri alfanumerici e viene mostrata una sola volta, quindi conservala subito.
  • Il game_guid viene fornito solo per i giochi di Roblox.
Formato della API key, che identifica il tuo gioco.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Se devi cambiare la key, il team ne genera una nuova e la precedente resta valida per 24 ore (86400 secondi) così puoi aggiornare il tuo gioco senza interruzioni.

Tratta la key come una password del tuo gioco e non pubblicarla in repository aperti che non siano tuoi.

Autenticazione con la API key

Ogni chiamata che consegna eventi o configurazione si autentica con la API key del tuo gioco, che ha la forma tkv_live_ seguita da 32 caratteri alfanumerici.

RottaCredenziale
GET /v1/eventskey=<api_key> | x-api-key
GET /v1/events/pollx-api-key
GET /v1/configx-api-key
GET /v1/status—
Esempio di richiesta autenticata con l'intestazione `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 viaggia dentro il codice del tuo gioco e lo identifica come gioco presso l'app, quindi non condividerla con altri giochi.

  • Il WebSocket riceve la key nel parametro key dell'URL, perché il browser non permette di inserire intestazioni in un WebSocket.
  • Le rotte HTTP /v1/events/poll e /v1/config ricevono la key solo nell'intestazione x-api-key, e il parametro key viene ignorato.
  • La rotta /v1/status non richiede una key, quindi serve a sapere se l'app è aperta prima di connettersi.

Avvio rapido

Con questi passaggi il tuo gioco riceve il primo evento in pochi minuti.

  • Chiedi al team di TikAresV di registrare il tuo gioco e conserva la API key che ricevi, perché viene mostrata una sola volta.
  • Chiedi allo streamer di aprire l'app desktop di TikAresV e di accedere.
  • Copia l'esempio di questa sezione in un file .html e sostituisci il segnaposto della API key con la tua.
  • Apri il file nel browser dello stesso computer dove gira l'app, e se Chrome chiede l'accesso alla rete locale, accetta.
  • Chiedi allo streamer di entrare nel suo gioco nell'app, di modificare una regola e di premere il pulsante Prova.
  • Verifica che il registro della pagina mostri una riga con l'id dell'evento di prova e il nome dell'azione.
  • Quando funziona, sostituisci la funzione runAction con il codice del tuo gioco per ogni azione.
Esempio minimo e completo di un gioco web che si connette, si riconnette da solo e mostra le azioni ricevute.
<!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 qualcosa non funziona, consulta la tabella degli errori e la sezione sulla risoluzione dei problemi più sotto.

Stato dell'app: GET /v1/status

Questa rotta indica se l'app è aperta e se può servire eventi, e non richiede una API key.

Richiesta dello stato dell'app.
GET http://127.0.0.1:17920/v1/status
Risposta con lo stato dell'app, della live e dei giochi collegati.
{
  "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"
}
  • Il campo serving è true quando l'app può consegnare eventi al tuo gioco.
  • Il campo serving_reason spiega perché serve o perché non serve, e no_valid_token significa che il piano dello streamer non è valido.
  • Il campo tiktok_state vale disconnected senza acquisizione, waiting in attesa della live e streaming con la live in corso.
  • I campi connected_games e max_connected_games indicano quanti giochi sono collegati e quanti ne consente il piano.

Connessione tramite WebSocket: GET /v1/events

Il WebSocket consegna gli eventi non appena arrivano, ed è il metodo consigliato per i giochi web.

Indirizzo di connessione con la key, i tipi di evento e l'ultimo cursore.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41
  • Il parametro key è obbligatorio e contiene la API key codificata con encodeURIComponent.
  • Il parametro types è facoltativo, elenca i tipi separati da virgole senza spazi, e se manca si ricevono tutti e otto i tipi.
  • Il parametro cursor è facoltativo e riprende la consegna dall'ultimo evento elaborato dal tuo gioco.

Subito dopo la connessione, l'app invia un messaggio hello con lo stato della sessione.

Messaggio `hello` con cui l'app conferma la connessione.
{
  "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"
  }
}
Messaggi che il tuo gioco può ricevere dopo l'`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'app invia un ping ogni 30 secondi e il tuo gioco deve rispondere pong con lo stesso ts entro 10 secondi, altrimenti l'app chiude la connessione con il codice 4408.

Risposta che il tuo gioco deve inviare a ogni `ping`.
{ "type": "pong", "data": { "ts": 1791062130000 } }

Richiesta periodica: GET /v1/events/poll

Questa rotta è l'alternativa ai WebSocket per i client che sanno fare solo richieste HTTP, e attende fino a wait secondi prima di rispondere vuota.

Richiesta con il cursore precedente e un'attesa di 20 secondi.
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
ParametroObbligatorioPredefinitoIntervallo
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)
Risposta con i nuovi eventi e il cursore da inviare nella richiesta successiva.
{
  "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"
}
  • Ripeti la richiesta non appena ricevi la risposta, inviando il cursor della risposta precedente.
  • Il campo has_more è true quando sono rimasti eventi a causa del limite limit, e allora devi richiedere di nuovo senza attendere.
  • Se smetti di fare richieste per 60 secondi, l'app considera il tuo gioco disconnesso.

Regole in vigore: GET /v1/config

Questa rotta restituisce le regole che lo streamer ha configurato per il tuo gioco, e serve a mostrare aiuti sullo schermo.

Richiesta della configurazione con `If-None-Match` per evitare download ripetuti.
GET http://127.0.0.1:17920/v1/config
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If-None-Match: "cfg-7"
Risposta con la versione e le regole della configurazione.
{ "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", "…": "…" } ] } }

Il tuo gioco non ha bisogno di interpretare le regole, perché ogni evento porta già le sue azioni risolte.

Contenuto di ogni evento

Ogni evento ha gli stessi campi comuni, e ogni tipo aggiunge il proprio oggetto con i dati specifici.

Campi comuni di un evento, qui 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 }
  ]
}
  • Il campo v è la versione del formato e oggi vale sempre 1.
  • Il campo id è univoco e stabile per evento, e il tuo gioco deve usarlo per ignorare i duplicati.
  • Il campo type è gift, comment, like, follow, share, subscribe, join o viewers.
  • Il campo ts è l'ora dell'evento nel formato RFC 3339 UTC con millisecondi.
  • I campi live_id, game_id e room_id identificano la live, il tuo gioco e la stanza di TikTok.
  • Il campo test è true solo negli eventi di prova.
  • L'oggetto user descrive lo spettatore ed è null solo negli eventi viewers.
  • Ogni evento porta soltanto l'oggetto del suo tipo (gift, comment, like, viewers o subscribe) e gli altri sono null.
  • L'array actions elenca ciò che il tuo gioco deve fare, ciascuna con action_key, params, rule_id e repeat.
  • Il tuo gioco deve eseguire ogni azione tante volte quante indica repeat, che vale 1 tranne nelle regole di un like ogni N.

Esempi degli otto tipi di 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": []
}

Questi sono gli otto tipi di evento con un esempio reale di ciascuno.

VariabileOrigine
{{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

I testi di params arrivano già con le variabili sostituite, e nessuno supera i 500 caratteri.

Cursore e ripresa

Il cursore è un indicatore opaco che segna fino a quale evento è arrivato il tuo gioco, e serve a non perdere eventi se la connessione si interrompe.

Esempio di cursore, che il tuo gioco si limita a conservare e restituire senza interpretarlo.
1791062100000-42
  • Conserva il cursore di ogni messaggio event o di ogni risposta di richiesta.
  • Alla riconnessione invia l'ultimo cursore conservato per ricevere ciò che ti sei perso.
  • Senza cursore, ricevi solo gli eventi successivi alla connessione.
  • Se il campo reset arriva a true, l'app è stata riavviata o il cursore non è più disponibile, e riceverai solo eventi nuovi.

Il cursore avanza anche sugli eventi che il tuo filtro di tipi scarta, quindi non li riceverai più.

Errori

Tutti gli errori HTTP hanno la stessa forma, con un code stabile che puoi confrontare nel tuo codice e un message in inglese.

Esempio della risposta di errore.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }
CodiceHTTPMotivoCosa fare
ORIGIN_FORBIDDEN403host_not_loopbackCollegati sempre a `127.0.0.1` o `localhost` e non usare un altro nome di host.
LOCAL_KEY_INVALID401key_missingInvia la API key nell'URL del WebSocket o nell'intestazione `x-api-key`.
LOCAL_KEY_INVALID401key_formatVerifica che la key abbia il formato `tkv_live_` seguito da 32 caratteri alfanumerici.
LOCAL_KEY_INVALID401key_unknownVerifica di usare la key vigente del tuo gioco e chiedi al team una nuova key se l'hai persa.
LOCAL_KEY_INVALID401game_inactiveIl tuo gioco è disattivato, quindi contatta il team di TikAresV.
LOCAL_KEY_INVALID401game_not_visibleIl tuo gioco non è disponibile per questo streamer, quindi contatta il team di TikAresV.
LOCAL_KEY_INVALID401unresolved_offlineL'app non ha potuto validare la key per mancanza di internet o per troppi tentativi, quindi attendi qualche secondo e riprova.
LOCAL_ACCESS_EXPIRED403no_valid_tokenIl piano dello streamer non è valido, quindi deve rinnovarlo nella sezione Piano dell'app e il tuo gioco deve riprovare ogni 30 secondi.
LOCAL_GAMES_LIMIT403È stato raggiunto il massimo di giochi collegati del piano, quindi chiudi un altro gioco o chiedi allo streamer un piano con più giochi.
LOCAL_CURSOR_RESET200Non è un errore HTTP, ma l'avviso che l'app è stata riavviata, e il tuo gioco prosegue con i nuovi eventi.
COMMON_VALIDATION_FAILED422Controlla `details.fields` per vedere quale parametro non è valido e correggilo.
COMMON_NOT_FOUND404Controlla la rotta, oppure attendi che l'app scarichi la configurazione del gioco se hai richiesto `/v1/config`.
COMMON_INTERNAL500È un errore imprevisto dell'app, quindi riprova con attesa crescente e avvisa il team se persiste.

La tabella indica cosa fare per ogni errore.

Codici di chiusura del WebSocket

Quando la connessione si chiude, il codice indica cosa deve fare il tuo gioco.

CodiceMotivo
1000normal
1001going_away
1008too_slow
1009message_too_big
4401key_invalid
4403access_expired
4408pong_timeout
  • Il codice 1000 significa che il tuo gioco ha chiuso la connessione, e non richiede azioni.
  • Il codice 1001 significa che l'app si è chiusa o ha cambiato porta, e il tuo gioco deve riconnettersi con attesa crescente e l'ultimo cursore.
  • Il codice 1008 significa che il tuo gioco è troppo lento, e deve riconnettersi con l'ultimo cursore.
  • Il codice 1009 significa che il tuo gioco ha inviato un messaggio troppo grande, e devi correggere il client.
  • Il codice 4401 significa che la key non è valida o è stata revocata, e il tuo gioco non deve riconnettersi finché non la cambia.
  • Il codice 4403 significa che l'accesso è scaduto, e il tuo gioco deve interrogare /v1/status ogni 30 secondi finché serving non è true.
  • Il codice 4408 significa che il tuo gioco non ha risposto al pong in tempo, e deve riconnettersi con attesa crescente e l'ultimo cursore.

Limiti e valori fissi

Questi sono i limiti applicati dalla API locale, e gli identificatori C-### sono i nomi interni di ciascun valore.

CostanteValoreDescrizione
C-02017920Porta predefinita della API locale.
C-02125Attesa massima in secondi di una richiesta periodica e timeout consigliato per il client.
C-02210000Eventi conservati per gioco, o quelli degli ultimi 10 minuti.
C-02630Secondi tra un ping e l'altro del WebSocket.
C-02710Secondi a disposizione del tuo gioco per rispondere al pong.
C-0281, 2, 4, 8, 16, 30Attesa in secondi tra le riconnessioni, con una variazione casuale del 20 %.
C-03465536Dimensione massima in byte di un messaggio del WebSocket.
C-05060Secondi senza richieste prima che l'app consideri il gioco disconnesso.
C-057100Eventi massimi per risposta di una richiesta periodica.
C-13786400Secondi per cui una API key resta valida dopo essere stata ruotata.
C-138tkv_live_ + 32 base62Formato della API key.
C-1413Giochi collegati contemporaneamente per impostazione predefinita.
C-155500Lunghezza massima in caratteri di un testo con variabili.

Avviso di rete locale in Chrome

Quando una pagina pubblica si collega a 127.0.0.1, Chrome mostra un avviso di autorizzazione per l'accesso alla rete locale.

Lo streamer deve accettare quell'avviso una volta, altrimenti il browser bloccherà la connessione del tuo gioco con l'app.

Risposta dell'app alla richiesta preliminare del browser, che include già l'autorizzazione per la rete privata.
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'avviso compare solo nelle pagine pubbliche, e una pagina aperta da un file locale o da http://127.0.0.1 non lo mostra.
  • Se lo streamer ha rifiutato l'autorizzazione, deve abilitarla nelle impostazioni del sito in Chrome e ricaricare la pagina.
  • Usa sempre 127.0.0.1 al posto di localhost, perché il sistema può risolvere localhost prima in ::1 e l'app non è in ascolto lì.

Come provare il tuo gioco

Per provare senza aspettare un regalo reale, lo streamer può inviare eventi di prova dall'app.

  • Apri l'app desktop di TikAresV e accedi.
  • Entra nel gioco dall'elenco dei giochi dell'app.
  • Apri una regola esistente o creane una nuova nell'editor delle regole.
  • Premi il pulsante Prova dell'editor delle regole.
  • Verifica che il tuo gioco riceva l'evento ed esegua l'azione.

Gli eventi di prova arrivano con test: true e con un id che inizia con test:.

Indirizzo della pagina di prova, che si apre nel browser mentre l'app è aperta.
GET http://127.0.0.1:17920/harness

L'app include inoltre una pagina di prova che mostra ciò che riceverebbe un gioco, senza bisogno di averne uno.

Risoluzione dei problemi

Controlla queste cause in ordine quando il tuo gioco non riceve eventi.

  • Se la connessione fallisce subito, apri http://127.0.0.1:17920/v1/status nel browser e verifica che l'app risponda.
  • Se localhost non si collega, passa a 127.0.0.1, perché l'app non è in ascolto su ::1.
  • Se ricevi l'errore 401, verifica che la key abbia il formato tkv_live_ più 32 caratteri e che non sia stata ruotata.
  • Se ricevi l'errore 403 con LOCAL_ACCESS_EXPIRED, chiedi allo streamer di rinnovare il piano nella sezione Piano dell'app.
  • Se ricevi l'errore 403 con LOCAL_GAMES_LIMIT, chiudi un altro gioco collegato o chiedi allo streamer un piano con più giochi.
  • Se il browser blocca la connessione senza mostrare un errore dell'app, accetta l'avviso di rete locale di Chrome.
  • Se la connessione cade ogni pochi secondi, verifica che il tuo gioco risponda pong a ogni ping in meno di 10 secondi.
  • Se vedi eventi ripetuti dopo aver riavviato l'app, ignora quelli già elaborati usando l'id dell'evento.
  • Se vedi il campo reset a true, l'app è stata riavviata e il cursore precedente non è più valido, quindi il tuo gioco riceverà solo eventi nuovi.