Aller au contenu
Retour à l’accueil

Documentation pour les jeux web

Connectez votre jeu de navigateur aux événements du live TikTok grâce à l'application de bureau TikAresV.

Ce que c'est et comment ça fonctionne

TikAresV est une application de bureau qui lit les événements du live TikTok du streamer (cadeaux, commentaires, likes, abonnés, partages, abonnements, arrivées et spectateurs) et les transmet à votre jeu.

L'application ouvre sur l'ordinateur du streamer une API locale sur 127.0.0.1, et votre jeu, qui s'exécute dans le navigateur de ce même ordinateur, s'y connecte avec une API key.

  • L'API locale n'existe que tant que l'application de bureau est ouverte sur l'ordinateur où le jeu s'exécute.
  • Chaque événement arrive avec un id stable, de sorte que votre jeu peut ignorer ceux qu'il a déjà traités.
  • Le streamer définit dans l'application quelle action se déclenche avec chaque cadeau, commentaire ou like, et votre jeu n'exécute que les actions qu'il reçoit.
  • Vous pouvez recevoir les événements par WebSocket, ce qui est le plus pratique dans le navigateur, ou par requêtes périodiques (long-poll) si vous préférez du HTTP simple.

Pour recevoir des événements, vous n'avez besoin que de l'API key de votre jeu, d'un navigateur sur l'ordinateur du streamer et des instructions de cette page.

Enregistrement du jeu et API key

L'enregistrement des jeux est fait par l'équipe TikAresV, alors écrivez-nous pour enregistrer le vôtre.

Contacter l'équipe TikAresV

Quand votre jeu sera enregistré, vous recevrez les données suivantes.

  • Le game_id est l'identifiant unique de votre jeu.
  • L'API key a la forme tkv_live_ plus 32 caractères alphanumériques et n'est affichée qu'une seule fois, alors conservez-la immédiatement.
  • Le game_guid n'est fourni que pour les jeux Roblox.
Format de l'API key, qui identifie votre jeu.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Si vous devez changer la key, l'équipe en génère une nouvelle et l'ancienne reste valable pendant 24 heures (86400 secondes) pour que vous mettiez à jour votre jeu sans interruption.

Traitez la key comme un mot de passe de votre jeu et ne la publiez pas dans des dépôts ouverts qui ne sont pas les vôtres.

Authentification avec l'API key

Chaque appel qui livre des événements ou de la configuration est authentifié avec l'API key de votre jeu, qui a la forme tkv_live_ suivie de 32 caractères alphanumériques.

RouteIdentifiant
GET /v1/eventskey=<api_key> | x-api-key
GET /v1/events/pollx-api-key
GET /v1/configx-api-key
GET /v1/status—
Exemple de requête authentifiée avec l'en-tête `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 voyage dans le code de votre jeu et l'identifie comme jeu auprès de l'application, donc ne la partagez pas avec d'autres jeux.

  • Le WebSocket reçoit la key dans le paramètre key de l'URL, car le navigateur ne permet pas d'ajouter des en-têtes à un WebSocket.
  • Les routes HTTP /v1/events/poll et /v1/config reçoivent la key uniquement dans l'en-tête x-api-key, et le paramètre key y est ignoré.
  • La route /v1/status n'a pas besoin de key, elle sert donc à savoir si l'application est ouverte avant de se connecter.

Démarrage rapide

Avec ces étapes, votre jeu reçoit son premier événement en quelques minutes.

  • Demandez l'enregistrement de votre jeu à l'équipe TikAresV et conservez l'API key que vous recevez, car elle n'est affichée qu'une seule fois.
  • Demandez au streamer d'ouvrir l'application de bureau TikAresV et de se connecter.
  • Copiez l'exemple de cette section dans un fichier .html et remplacez le marqueur de l'API key par la vôtre.
  • Ouvrez le fichier dans le navigateur du même ordinateur où l'application s'exécute, et si Chrome demande l'accès au réseau local, acceptez.
  • Demandez au streamer d'entrer dans son jeu dans l'application, de modifier une règle et d'appuyer sur le bouton Tester.
  • Vérifiez que le journal de la page affiche une ligne avec l'id de l'événement de test et le nom de l'action.
  • Quand cela fonctionne, remplacez la fonction runAction par le code de votre jeu pour chaque action.
Exemple minimal et complet d'un jeu web qui se connecte, se reconnecte tout seul et affiche les actions reçues.
<!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 quelque chose échoue, consultez le tableau des erreurs et la section de dépannage plus bas.

État de l'application : GET /v1/status

Cette route indique si l'application est ouverte et si elle peut servir des événements, et elle n'a pas besoin d'API key.

Requête de l'état de l'application.
GET http://127.0.0.1:17920/v1/status
Réponse avec l'état de l'application, du live et des jeux connectés.
{
  "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"
}
  • Le champ serving vaut true quand l'application peut livrer des événements à votre jeu.
  • Le champ serving_reason explique pourquoi elle sert ou ne sert pas, et no_valid_token signifie que l'abonnement du streamer n'est pas en cours de validité.
  • Le champ tiktok_state vaut disconnected sans capture, waiting en attente du live et streaming quand le live est en cours.
  • Les champs connected_games et max_connected_games indiquent combien de jeux sont connectés et combien l'abonnement en permet.

Connexion par WebSocket : GET /v1/events

Le WebSocket livre les événements dès qu'ils arrivent, et c'est la méthode recommandée pour les jeux web.

Adresse de connexion avec la key, les types d'événement et le dernier curseur.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41
  • Le paramètre key est obligatoire et contient l'API key encodée avec encodeURIComponent.
  • Le paramètre types est facultatif, liste les types séparés par des virgules sans espaces, et s'il manque, les huit types sont reçus.
  • Le paramètre cursor est facultatif et reprend la livraison à partir du dernier événement que votre jeu a traité.

Juste après la connexion, l'application envoie un message hello avec l'état de la session.

Message `hello` par lequel l'application confirme la connexion.
{
  "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"
  }
}
Messages que votre jeu peut recevoir après le `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'application envoie un ping toutes les 30 secondes et votre jeu doit répondre pong avec le même ts dans les 10 secondes, sinon l'application ferme la connexion avec le code 4408.

Réponse que votre jeu doit envoyer à chaque `ping`.
{ "type": "pong", "data": { "ts": 1791062130000 } }

Requête périodique : GET /v1/events/poll

Cette route est l'alternative aux WebSocket pour les clients qui ne savent faire que des requêtes HTTP, et elle attend jusqu'à wait secondes avant de répondre à vide.

Requête avec le curseur précédent et une attente de 20 secondes.
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
ParamètreObligatoirePar défautPlage
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)
Réponse avec les nouveaux événements et le curseur à envoyer dans la requête suivante.
{
  "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"
}
  • Répétez la requête dès que vous recevez la réponse, en envoyant le cursor de la réponse précédente.
  • Le champ has_more vaut true quand il reste des événements à cause de la limite limit, et vous devez alors interroger de nouveau sans attendre.
  • Si vous cessez d'interroger pendant 60 secondes, l'application considère que votre jeu s'est déconnecté.

Règles en vigueur : GET /v1/config

Cette route renvoie les règles que le streamer a configurées pour votre jeu, et sert à afficher des aides à l'écran.

Requête de la configuration avec `If-None-Match` pour éviter les téléchargements répétés.
GET http://127.0.0.1:17920/v1/config
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If-None-Match: "cfg-7"
Réponse avec la version et les règles de la configuration.
{ "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", "…": "…" } ] } }

Votre jeu n'a pas besoin d'interpréter les règles, car chaque événement contient déjà ses actions résolues.

Contenu de chaque événement

Chaque événement a les mêmes champs communs, et chaque type ajoute son propre objet avec les données spécifiques.

Champs communs d'un événement, ici avec un cadeau.
{
  "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 }
  ]
}
  • Le champ v est la version du format et vaut toujours 1 aujourd'hui.
  • Le champ id est unique et stable par événement, et votre jeu doit l'utiliser pour ignorer les doublons.
  • Le champ type vaut gift, comment, like, follow, share, subscribe, join ou viewers.
  • Le champ ts est l'heure de l'événement au format RFC 3339 UTC avec millisecondes.
  • Les champs live_id, game_id et room_id identifient le live, votre jeu et la salle TikTok.
  • Le champ test vaut true uniquement dans les événements de test.
  • L'objet user décrit le spectateur et vaut null uniquement dans les événements viewers.
  • Chaque événement ne porte que l'objet de son type (gift, comment, like, viewers ou subscribe) et les autres valent null.
  • Le tableau actions liste ce que votre jeu doit faire, chacune avec action_key, params, rule_id et repeat.
  • Votre jeu doit exécuter chaque action autant de fois que l'indique repeat, qui vaut 1 sauf dans les règles d'un like tous les N.

Exemples des huit types d'événement

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

Voici les huit types d'événement avec un exemple réel de chacun.

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

Les textes de params arrivent déjà avec les variables remplacées, et aucun ne dépasse 500 caractères.

Curseur et reprise

Le curseur est un repère opaque qui indique jusqu'à quel événement votre jeu est arrivé, et il sert à ne pas perdre d'événements si la connexion est coupée.

Exemple de curseur, que votre jeu se contente de conserver et de renvoyer sans l'interpréter.
1791062100000-42
  • Conservez le curseur de chaque message event ou de chaque réponse de requête.
  • À la reconnexion, envoyez le dernier curseur conservé pour recevoir ce que vous avez manqué.
  • Sans curseur, vous ne recevez que les événements postérieurs à la connexion.
  • Si le champ reset arrive à true, l'application a redémarré ou le curseur n'est plus disponible, et vous ne recevrez que de nouveaux événements.

Le curseur avance aussi sur les événements que votre filtre de types écarte, donc vous ne les recevrez plus.

Erreurs

Toutes les erreurs HTTP ont la même forme, avec un code stable que vous pouvez comparer dans votre code et un message en anglais.

Exemple de la réponse d'erreur.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }
CodeHTTPMotifQue faire
ORIGIN_FORBIDDEN403host_not_loopbackConnectez-vous toujours à `127.0.0.1` ou `localhost` et n'utilisez pas d'autre nom d'hôte.
LOCAL_KEY_INVALID401key_missingEnvoyez l'API key dans l'URL du WebSocket ou dans l'en-tête `x-api-key`.
LOCAL_KEY_INVALID401key_formatVérifiez que la key a le format `tkv_live_` suivi de 32 caractères alphanumériques.
LOCAL_KEY_INVALID401key_unknownVérifiez que vous utilisez la key en vigueur de votre jeu et demandez-en une nouvelle à l'équipe si vous l'avez perdue.
LOCAL_KEY_INVALID401game_inactiveVotre jeu est désactivé, donc contactez l'équipe TikAresV.
LOCAL_KEY_INVALID401game_not_visibleVotre jeu n'est pas disponible pour ce streamer, donc contactez l'équipe TikAresV.
LOCAL_KEY_INVALID401unresolved_offlineL'application n'a pas pu valider la key faute d'internet ou à cause de trop nombreuses tentatives, donc attendez quelques secondes et réessayez.
LOCAL_ACCESS_EXPIRED403no_valid_tokenL'abonnement du streamer n'est pas en cours de validité, donc il doit le renouveler dans la section Abonnement de l'application et votre jeu réessayer toutes les 30 secondes.
LOCAL_GAMES_LIMIT403Le nombre maximal de jeux connectés de l'abonnement est atteint, donc fermez un autre jeu ou demandez au streamer un abonnement avec plus de jeux.
LOCAL_CURSOR_RESET200Ce n'est pas une erreur HTTP, mais l'avis que l'application a redémarré, et votre jeu continue avec les nouveaux événements.
COMMON_VALIDATION_FAILED422Consultez `details.fields` pour voir quel paramètre est invalide et corrigez-le.
COMMON_NOT_FOUND404Vérifiez la route, ou attendez que l'application télécharge la configuration du jeu si vous avez demandé `/v1/config`.
COMMON_INTERNAL500C'est une erreur inattendue de l'application, donc réessayez avec une attente croissante et prévenez l'équipe si elle persiste.

Le tableau indique quoi faire face à chaque erreur.

Codes de fermeture du WebSocket

Quand la connexion se ferme, le code indique ce que votre jeu doit faire.

CodeMotif
1000normal
1001going_away
1008too_slow
1009message_too_big
4401key_invalid
4403access_expired
4408pong_timeout
  • Le code 1000 signifie que votre jeu a fermé la connexion, et aucune action n'est requise.
  • Le code 1001 signifie que l'application s'est fermée ou a changé de port, et votre jeu doit se reconnecter avec une attente croissante et le dernier curseur.
  • Le code 1008 signifie que votre jeu est trop lent, et il doit se reconnecter avec le dernier curseur.
  • Le code 1009 signifie que votre jeu a envoyé un message trop gros, et vous devez corriger le client.
  • Le code 4401 signifie que la key est invalide ou a été révoquée, et votre jeu ne doit pas se reconnecter avant de la changer.
  • Le code 4403 signifie que l'accès a expiré, et votre jeu doit interroger /v1/status toutes les 30 secondes jusqu'à ce que serving vaille true.
  • Le code 4408 signifie que votre jeu n'a pas répondu le pong à temps, et il doit se reconnecter avec une attente croissante et le dernier curseur.

Limites et valeurs fixes

Voici les limites qu'applique l'API locale, et les identifiants C-### sont les noms internes de chaque valeur.

ConstanteValeurDescription
C-02017920Port par défaut de l'API locale.
C-02125Attente maximale en secondes d'une requête périodique et délai limite recommandé pour le client.
C-02210000Événements conservés par jeu, ou ceux des 10 dernières minutes.
C-02630Secondes entre chaque ping du WebSocket.
C-02710Secondes dont dispose votre jeu pour répondre au pong.
C-0281, 2, 4, 8, 16, 30Attente en secondes entre les reconnexions, avec une variation aléatoire de 20 %.
C-03465536Taille maximale en octets d'un message du WebSocket.
C-05060Secondes sans requête avant que l'application considère le jeu comme déconnecté.
C-057100Nombre maximal d'événements par réponse d'une requête périodique.
C-13786400Secondes pendant lesquelles une API key reste valable après avoir été renouvelée.
C-138tkv_live_ + 32 base62Format de l'API key.
C-1413Jeux connectés en même temps par défaut.
C-155500Longueur maximale en caractères d'un texte avec variables.

Avis de réseau local dans Chrome

Quand une page publique se connecte à 127.0.0.1, Chrome affiche une demande d'autorisation d'accès au réseau local.

Le streamer doit accepter cet avis une fois, sinon le navigateur bloquera la connexion de votre jeu avec l'application.

Réponse de l'application à la requête préalable du navigateur, qui inclut déjà l'autorisation de réseau privé.
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'avis n'apparaît que sur les pages publiques, et une page ouverte depuis un fichier local ou depuis http://127.0.0.1 ne l'affiche pas.
  • Si le streamer a refusé l'autorisation, il doit l'activer dans les paramètres du site dans Chrome et recharger la page.
  • Utilisez toujours 127.0.0.1 au lieu de localhost, car le système peut résoudre localhost d'abord en ::1 et l'application n'écoute pas à cette adresse.

Comment tester votre jeu

Pour tester sans attendre un vrai cadeau, le streamer peut envoyer des événements de test depuis l'application.

  • Ouvrez l'application de bureau TikAresV et connectez-vous.
  • Entrez dans le jeu depuis la liste des jeux de l'application.
  • Ouvrez une règle existante ou créez-en une nouvelle dans l'éditeur de règles.
  • Appuyez sur le bouton Tester de l'éditeur de règles.
  • Vérifiez que votre jeu reçoit l'événement et exécute l'action.

Les événements de test arrivent avec test: true et avec un id qui commence par test:.

Adresse de la page de tests, qui s'ouvre dans le navigateur tant que l'application est ouverte.
GET http://127.0.0.1:17920/harness

L'application inclut aussi une page de tests qui affiche ce que recevrait un jeu, sans avoir besoin d'en avoir un.

Dépannage

Vérifiez ces causes dans l'ordre quand votre jeu ne reçoit pas d'événements.

  • Si la connexion échoue immédiatement, ouvrez http://127.0.0.1:17920/v1/status dans le navigateur et vérifiez que l'application répond.
  • Si localhost ne se connecte pas, passez à 127.0.0.1, car l'application n'écoute pas sur ::1.
  • Si vous recevez l'erreur 401, vérifiez que la key a le format tkv_live_ plus 32 caractères et qu'elle n'a pas été renouvelée.
  • Si vous recevez l'erreur 403 avec LOCAL_ACCESS_EXPIRED, demandez au streamer de renouveler son abonnement dans la section Abonnement de l'application.
  • Si vous recevez l'erreur 403 avec LOCAL_GAMES_LIMIT, fermez un autre jeu connecté ou demandez au streamer un abonnement avec plus de jeux.
  • Si le navigateur bloque la connexion sans afficher d'erreur de l'application, acceptez l'avis de réseau local de Chrome.
  • Si la connexion tombe toutes les quelques secondes, vérifiez que votre jeu répond pong à chaque ping en moins de 10 secondes.
  • Si vous voyez des événements répétés après le redémarrage de l'application, ignorez ceux que vous avez déjà traités grâce à l'id de l'événement.
  • Si vous voyez le champ reset à true, l'application a redémarré et l'ancien curseur n'est plus valable, donc votre jeu ne recevra que de nouveaux événements.