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
idstable, 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 TikAresVQuand votre jeu sera enregistré, vous recevrez les données suivantes.
- Le
game_idest 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_guidn'est fourni que pour les jeux Roblox.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSi 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.
| Route | Identifiant |
|---|---|
GET /v1/events | key=<api_key> | x-api-key |
GET /v1/events/poll | x-api-key |
GET /v1/config | x-api-key |
GET /v1/status | — |
GET http://127.0.0.1:17920/v1/events/poll?wait=0 HTTP/1.1
Host: 127.0.0.1:17920
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxLa key 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
keyde l'URL, car le navigateur ne permet pas d'ajouter des en-têtes à un WebSocket. - Les routes HTTP
/v1/events/pollet/v1/configreçoivent la key uniquement dans l'en-têtex-api-key, et le paramètrekeyy est ignoré. - La route
/v1/statusn'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
.htmlet 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'
idde l'événement de test et le nom de l'action. - Quand cela fonctionne, remplacez la fonction
runActionpar le code de votre jeu pour chaque action.
<!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.
GET http://127.0.0.1:17920/v1/status{
"api": "local/v1",
"agent_version": "0.1.245",
"port": 17920,
"server_time": "2026-10-03T21:15:30.000Z",
"tiktok_state": "streaming",
"live": { "active": true, "observer": false, "started_at": "2026-10-03T21:15:00.000Z" },
"serving": true,
"serving_reason": "live_started_with_token",
"connected_games": 1,
"max_connected_games": 3,
"control_channel": "websocket"
}- Le champ
servingvauttruequand l'application peut livrer des événements à votre jeu. - Le champ
serving_reasonexplique pourquoi elle sert ou ne sert pas, etno_valid_tokensignifie que l'abonnement du streamer n'est pas en cours de validité. - Le champ
tiktok_statevautdisconnectedsans capture,waitingen attente du live etstreamingquand le live est en cours. - Les champs
connected_gamesetmax_connected_gamesindiquent 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.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41- Le paramètre
keyest obligatoire et contient l'API key encodée avecencodeURIComponent. - Le paramètre
typesest 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
cursorest 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.
{
"type": "hello",
"data": {
"api": "local/v1", "agent_version": "0.1.245", "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"game_name": "Juego de prueba", "platform": "web", "types": ["gift", "comment"],
"cursor": "1791062100000-41", "reset": false, "config_version": 7,
"live": { "live_id": "01a1039e-c820-7028-9d1f-b2da68991b17", "unique_id": "ana_streams", "observer": false,
"started_at": "2026-10-03T21:15:00.000Z" },
"server_time": "2026-10-03T21:15:30.010Z"
}
}{ "type": "event", "data": { "cursor": "1791062100000-42", "event": { "v": 1, "id": "tt:7421234567890001001", "…": "…" } } }
{ "type": "config.changed", "data": { "config_version": 8 } }
{ "type": "ping", "data": { "ts": 1791062130000 } }
{ "type": "error", "data": { "code": "LOCAL_ACCESS_EXPIRED", "message": "local access expired", "details": { "reason": "no_valid_token" } } }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.
{ "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.
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ètre | Obligatoire | Par défaut | Plage |
|---|---|---|---|
cursor | no | — | ^[0-9]{13}-[0-9]{1,19}$ |
wait | no | 0 | 0–25 (C-021) |
types | no | gift,comment,like,follow,share,subscribe,join,viewers | gift … viewers |
limit | no | 100 | 1–100 (C-057) |
{
"events": [ { "v": 1, "id": "tt:7421234567890001001", "type": "gift", "…": "…" } ],
"cursor": "1791062100000-43",
"reset": false,
"has_more": false,
"config_version": 7,
"live": { "live_id": "01a1039e-c820-7028-9d1f-b2da68991b17", "unique_id": "ana_streams", "observer": false,
"started_at": "2026-10-03T21:15:00.000Z" },
"server_time": "2026-10-03T21:15:30.010Z"
}- Répétez la requête dès que vous recevez la réponse, en envoyant le
cursorde la réponse précédente. - Le champ
has_morevauttruequand il reste des événements à cause de la limitelimit, 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.
GET http://127.0.0.1:17920/v1/config
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If-None-Match: "cfg-7"{ "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e", "config_version": 7, "updated_at": "2026-10-03T20:58:41.512Z",
"is_default": false, "config": { "schema": "config/v1", "rules": [ { "rule_id": "r-rosa-mensaje", "…": "…" } ] } }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.
{
"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
vest la version du format et vaut toujours1aujourd'hui. - Le champ
idest unique et stable par événement, et votre jeu doit l'utiliser pour ignorer les doublons. - Le champ
typevautgift,comment,like,follow,share,subscribe,joinouviewers. - Le champ
tsest l'heure de l'événement au format RFC 3339 UTC avec millisecondes. - Les champs
live_id,game_idetroom_ididentifient le live, votre jeu et la salle TikTok. - Le champ
testvauttrueuniquement dans les événements de test. - L'objet
userdécrit le spectateur et vautnulluniquement dans les événementsviewers. - Chaque événement ne porte que l'objet de son type (
gift,comment,like,viewersousubscribe) et les autres valentnull. - Le tableau
actionsliste ce que votre jeu doit faire, chacune avecaction_key,params,rule_idetrepeat. - 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.
| Variable | Origine |
|---|---|
{{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.
1791062100000-42- Conservez le curseur de chaque message
eventou 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
resetarrive à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.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }| Code | HTTP | Motif | Que faire |
|---|---|---|---|
ORIGIN_FORBIDDEN | 403 | host_not_loopback | Connectez-vous toujours à `127.0.0.1` ou `localhost` et n'utilisez pas d'autre nom d'hôte. |
LOCAL_KEY_INVALID | 401 | key_missing | Envoyez l'API key dans l'URL du WebSocket ou dans l'en-tête `x-api-key`. |
LOCAL_KEY_INVALID | 401 | key_format | Vérifiez que la key a le format `tkv_live_` suivi de 32 caractères alphanumériques. |
LOCAL_KEY_INVALID | 401 | key_unknown | Vé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_INVALID | 401 | game_inactive | Votre jeu est désactivé, donc contactez l'équipe TikAresV. |
LOCAL_KEY_INVALID | 401 | game_not_visible | Votre jeu n'est pas disponible pour ce streamer, donc contactez l'équipe TikAresV. |
LOCAL_KEY_INVALID | 401 | unresolved_offline | L'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_EXPIRED | 403 | no_valid_token | L'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_LIMIT | 403 | Le 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_RESET | 200 | Ce 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_FAILED | 422 | Consultez `details.fields` pour voir quel paramètre est invalide et corrigez-le. | |
COMMON_NOT_FOUND | 404 | Vérifiez la route, ou attendez que l'application télécharge la configuration du jeu si vous avez demandé `/v1/config`. | |
COMMON_INTERNAL | 500 | C'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.
| Code | Motif |
|---|---|
1000 | normal |
1001 | going_away |
1008 | too_slow |
1009 | message_too_big |
4401 | key_invalid |
4403 | access_expired |
4408 | pong_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/statustoutes les 30 secondes jusqu'à ce queservingvailletrue. - 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.
| Constante | Valeur | Description |
|---|---|---|
C-020 | 17920 | Port par défaut de l'API locale. |
C-021 | 25 | Attente maximale en secondes d'une requête périodique et délai limite recommandé pour le client. |
C-022 | 10000 | Événements conservés par jeu, ou ceux des 10 dernières minutes. |
C-026 | 30 | Secondes entre chaque ping du WebSocket. |
C-027 | 10 | Secondes dont dispose votre jeu pour répondre au pong. |
C-028 | 1, 2, 4, 8, 16, 30 | Attente en secondes entre les reconnexions, avec une variation aléatoire de 20 %. |
C-034 | 65536 | Taille maximale en octets d'un message du WebSocket. |
C-050 | 60 | Secondes sans requête avant que l'application considère le jeu comme déconnecté. |
C-057 | 100 | Nombre maximal d'événements par réponse d'une requête périodique. |
C-137 | 86400 | Secondes pendant lesquelles une API key reste valable après avoir été renouvelée. |
C-138 | tkv_live_ + 32 base62 | Format de l'API key. |
C-141 | 3 | Jeux connectés en même temps par défaut. |
C-155 | 500 | Longueur 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.
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.1ne 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.1au lieu delocalhost, car le système peut résoudrelocalhostd'abord en::1et 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:.
GET http://127.0.0.1:17920/harnessL'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/statusdans le navigateur et vérifiez que l'application répond. - Si
localhostne 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à chaquepingen 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'
idde 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.