Dokumentation für Webspiele
Verbinde dein Browserspiel über die TikAresV-Desktop-App mit den Ereignissen des TikTok-Lives.
Was es ist und wie es funktioniert
TikAresV ist eine Desktop-App, die die Ereignisse des TikTok-Lives des Streamers (Geschenke, Kommentare, Likes, Follower, Shares, Abos, Beitritte und Zuschauer) liest und an dein Spiel weitergibt.
Die App öffnet auf dem Computer des Streamers eine lokale API unter 127.0.0.1, und dein Spiel, das im Browser desselben Computers läuft, verbindet sich mit einem API-Key mit ihr.
- Die lokale API existiert nur, solange die Desktop-App auf dem Computer geöffnet ist, auf dem das Spiel läuft.
- Jedes Ereignis kommt mit einer stabilen
id, sodass dein Spiel bereits verarbeitete Ereignisse ignorieren kann. - Der Streamer legt in der App fest, welche Aktion bei jedem Geschenk, Kommentar oder Like ausgelöst wird, und dein Spiel führt nur die Aktionen aus, die es erhält.
- Du kannst die Ereignisse per WebSocket empfangen, was im Browser am bequemsten ist, oder per periodischer Abfrage (Long-Poll), wenn du einfaches HTTP bevorzugst.
Um Ereignisse zu empfangen, brauchst du nur den API-Key deines Spiels, einen Browser auf dem Computer des Streamers und die Anleitung auf dieser Seite.
Anmeldung des Spiels und API-Key
Die Anmeldung der Spiele übernimmt das TikAresV-Team, also schreib uns, um deines zu registrieren.
Das TikAresV-Team kontaktierenWenn dein Spiel registriert ist, erhältst du die folgenden Daten.
- Die
game_idist die eindeutige Kennung deines Spiels. - Der API-Key hat die Form
tkv_live_plus 32 alphanumerische Zeichen und wird nur einmal angezeigt, also speichere ihn sofort. - Die
game_guidwird nur bei Roblox-Spielen mitgeliefert.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWenn du den Key ändern musst, erzeugt das Team einen neuen, und der alte bleibt 24 Stunden (86400 Sekunden) gültig, damit du dein Spiel ohne Unterbrechung aktualisieren kannst.
Behandle den Key wie ein Passwort deines Spiels und veröffentliche ihn nicht in offenen Repositories, die dir nicht gehören.
Authentifizierung mit dem API-Key
Jeder Aufruf, der Ereignisse oder Konfiguration liefert, wird mit dem API-Key deines Spiels authentifiziert, der die Form tkv_live_ gefolgt von 32 alphanumerischen Zeichen hat.
| Route | Zugangsdaten |
|---|---|
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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxDer Key steckt im Code deines Spiels und identifiziert es gegenüber der App als Spiel, also gib ihn nicht an andere Spiele weiter.
- Der WebSocket erhält den Key im URL-Parameter
key, weil der Browser bei einem WebSocket keine Header erlaubt. - Die HTTP-Routen
/v1/events/pollund/v1/configerhalten den Key nur im Headerx-api-key, und der Parameterkeywird dort ignoriert. - Die Route
/v1/statusbraucht keinen Key und eignet sich daher, um vor dem Verbinden zu prüfen, ob die App geöffnet ist.
Schnellstart
Mit diesen Schritten erhält dein Spiel in wenigen Minuten sein erstes Ereignis.
- Bitte das TikAresV-Team, dein Spiel anzumelden, und bewahre den erhaltenen API-Key auf, denn er wird nur einmal angezeigt.
- Bitte den Streamer, die TikAresV-Desktop-App zu öffnen und sich anzumelden.
- Kopiere das Beispiel dieses Abschnitts in eine
.html-Datei und ersetze den Platzhalter des API-Keys durch deinen. - Öffne die Datei im Browser desselben Computers, auf dem die App läuft, und akzeptiere, falls Chrome nach dem Zugriff auf das lokale Netzwerk fragt.
- Bitte den Streamer, in der App sein Spiel zu öffnen, eine Regel zu bearbeiten und auf die Schaltfläche Testen zu klicken.
- Prüfe, dass das Protokoll der Seite eine Zeile mit der
iddes Testereignisses und dem Namen der Aktion zeigt. - Wenn es funktioniert, ersetze die Funktion
runActiondurch den Code deines Spiels für jede Aktion.
<!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>
Wenn etwas fehlschlägt, sieh dir die Fehlertabelle und den Abschnitt zur Fehlerbehebung weiter unten an.
Status der App: GET /v1/status
Diese Route zeigt an, ob die App geöffnet ist und Ereignisse liefern kann, und sie braucht keinen 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"
}- Das Feld
servingisttrue, wenn die App Ereignisse an dein Spiel liefern kann. - Das Feld
serving_reasonerklärt, warum sie liefert oder nicht, undno_valid_tokenbedeutet, dass das Abo des Streamers nicht gültig ist. - Das Feld
tiktok_stateistdisconnectedohne Aufzeichnung,waitingbeim Warten auf den Live undstreamingbei laufendem Live. - Die Felder
connected_gamesundmax_connected_gameszeigen, wie viele Spiele verbunden sind und wie viele das Abo erlaubt.
WebSocket-Verbindung: GET /v1/events
Der WebSocket liefert die Ereignisse, sobald sie eintreffen, und ist der empfohlene Weg für Webspiele.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41- Der Parameter
keyist erforderlich und trägt den mitencodeURIComponentkodierten API-Key. - Der Parameter
typesist optional, listet die Typen durch Kommas ohne Leerzeichen getrennt auf, und wenn er fehlt, werden alle acht Typen empfangen. - Der Parameter
cursorist optional und setzt die Lieferung ab dem letzten Ereignis fort, das dein Spiel verarbeitet hat.
Direkt nach dem Verbinden sendet die App eine hello-Nachricht mit dem Sitzungsstatus.
{
"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" } } }Die App sendet alle 30 Sekunden einen ping, und dein Spiel muss innerhalb von 10 Sekunden mit pong und demselben ts antworten, sonst schließt die App die Verbindung mit dem Code 4408.
{ "type": "pong", "data": { "ts": 1791062130000 } }Periodische Abfrage: GET /v1/events/poll
Diese Route ist die Alternative zu WebSockets für Clients, die nur HTTP-Anfragen stellen können, und sie wartet bis zu wait Sekunden, bevor sie leer antwortet.
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| Parameter | Erforderlich | Standard | Bereich |
|---|---|---|---|
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"
}- Wiederhole die Abfrage, sobald du die Antwort erhältst, und sende den
cursorder vorherigen Antwort. - Das Feld
has_moreisttrue, wenn wegen des LimitslimitEreignisse übrig geblieben sind, und dann musst du ohne Wartezeit erneut abfragen. - Wenn du 60 Sekunden lang nicht mehr abfragst, geht die App davon aus, dass dein Spiel die Verbindung getrennt hat.
Aktuelle Regeln: GET /v1/config
Diese Route liefert die Regeln, die der Streamer für dein Spiel konfiguriert hat, und dient dazu, Hilfen auf dem Bildschirm anzuzeigen.
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", "…": "…" } ] } }Dein Spiel muss die Regeln nicht interpretieren, weil jedes Ereignis seine aufgelösten Aktionen bereits mitbringt.
Inhalt jedes Ereignisses
Jedes Ereignis hat dieselben gemeinsamen Felder, und jeder Typ fügt sein eigenes Objekt mit den spezifischen Daten hinzu.
{
"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 }
]
}- Das Feld
vist die Version des Formats und ist heute immer1. - Das Feld
idist pro Ereignis eindeutig und stabil, und dein Spiel muss es nutzen, um Duplikate zu ignorieren. - Das Feld
typeistgift,comment,like,follow,share,subscribe,joinoderviewers. - Das Feld
tsist die Zeit des Ereignisses im Format RFC 3339 UTC mit Millisekunden. - Die Felder
live_id,game_idundroom_ididentifizieren den Live, dein Spiel und den TikTok-Raum. - Das Feld
testist nur bei Testereignissentrue. - Das Objekt
userbeschreibt den Zuschauer und ist nur beiviewers-Ereignissennull. - Jedes Ereignis trägt nur das Objekt seines Typs (
gift,comment,like,viewersodersubscribe), die übrigen sindnull. - Das Array
actionslistet auf, was dein Spiel tun muss, jeweils mitaction_key,params,rule_idundrepeat. - Dein Spiel muss jede Aktion so oft ausführen, wie
repeatangibt, was 1 ist, außer bei den Regeln für je N Likes.
Beispiele der acht Ereignistypen
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": []
}Dies sind die acht Ereignistypen mit je einem echten Beispiel.
| Variable | Herkunft |
|---|---|
{{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 |
Die Texte in params kommen bereits mit ersetzten Variablen, und keiner überschreitet 500 Zeichen.
Cursor und Wiederaufnahme
Der Cursor ist eine undurchsichtige Markierung, die anzeigt, bis zu welchem Ereignis dein Spiel gekommen ist, und er verhindert, dass Ereignisse verloren gehen, wenn die Verbindung abbricht.
1791062100000-42- Speichere den Cursor jeder
event-Nachricht oder jeder Abfrageantwort. - Sende beim erneuten Verbinden den zuletzt gespeicherten Cursor, um zu erhalten, was du verpasst hast.
- Ohne Cursor erhältst du nur die Ereignisse nach dem Verbinden.
- Wenn das Feld
resetalstrueankommt, wurde die App neu gestartet oder der Cursor ist nicht mehr verfügbar, und du erhältst nur neue Ereignisse.
Der Cursor rückt auch über Ereignisse vor, die dein Typfilter verwirft, also erhältst du sie nicht noch einmal.
Fehler
Alle HTTP-Fehler haben dieselbe Form, mit einem stabilen code, den du in deinem Code vergleichen kannst, und einer message auf Englisch.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }| Code | HTTP | Grund | Was zu tun ist |
|---|---|---|---|
ORIGIN_FORBIDDEN | 403 | host_not_loopback | Verbinde dich immer mit `127.0.0.1` oder `localhost` und verwende keinen anderen Rechnernamen. |
LOCAL_KEY_INVALID | 401 | key_missing | Sende den API-Key in der URL des WebSockets oder im Header `x-api-key`. |
LOCAL_KEY_INVALID | 401 | key_format | Prüfe, ob der Key das Format `tkv_live_` gefolgt von 32 alphanumerischen Zeichen hat. |
LOCAL_KEY_INVALID | 401 | key_unknown | Prüfe, ob du den aktuellen Key deines Spiels verwendest, und fordere beim Team einen neuen an, falls du ihn verloren hast. |
LOCAL_KEY_INVALID | 401 | game_inactive | Dein Spiel ist deaktiviert, also kontaktiere das TikAresV-Team. |
LOCAL_KEY_INVALID | 401 | game_not_visible | Dein Spiel ist für diesen Streamer nicht verfügbar, also kontaktiere das TikAresV-Team. |
LOCAL_KEY_INVALID | 401 | unresolved_offline | Die App konnte den Key wegen fehlenden Internets oder zu vieler Versuche nicht validieren, also warte einige Sekunden und versuche es erneut. |
LOCAL_ACCESS_EXPIRED | 403 | no_valid_token | Das Abo des Streamers ist nicht gültig, also muss er es im Bereich Abo der App verlängern, und dein Spiel muss alle 30 Sekunden erneut versuchen. |
LOCAL_GAMES_LIMIT | 403 | Die maximale Anzahl verbundener Spiele des Abos ist erreicht, also schließe ein anderes Spiel oder bitte den Streamer um ein Abo mit mehr Spielen. | |
LOCAL_CURSOR_RESET | 200 | Es ist kein HTTP-Fehler, sondern der Hinweis, dass die App neu gestartet wurde, und dein Spiel macht mit den neuen Ereignissen weiter. | |
COMMON_VALIDATION_FAILED | 422 | Sieh dir `details.fields` an, um zu erkennen, welcher Parameter ungültig ist, und korrigiere ihn. | |
COMMON_NOT_FOUND | 404 | Prüfe die Route, oder warte, bis die App die Konfiguration des Spiels heruntergeladen hat, falls du `/v1/config` angefordert hast. | |
COMMON_INTERNAL | 500 | Es ist ein unerwarteter Fehler der App, also versuche es mit zunehmender Wartezeit erneut und informiere das Team, wenn er bestehen bleibt. |
Die Tabelle zeigt, was bei jedem Fehler zu tun ist.
Schließcodes des WebSockets
Wenn die Verbindung geschlossen wird, zeigt der Code an, was dein Spiel tun muss.
| Code | Grund |
|---|---|
1000 | normal |
1001 | going_away |
1008 | too_slow |
1009 | message_too_big |
4401 | key_invalid |
4403 | access_expired |
4408 | pong_timeout |
- Der Code 1000 bedeutet, dass dein Spiel die Verbindung geschlossen hat, und erfordert keine Aktion.
- Der Code 1001 bedeutet, dass die App beendet wurde oder den Port gewechselt hat, und dein Spiel muss sich mit zunehmender Wartezeit und dem letzten Cursor neu verbinden.
- Der Code 1008 bedeutet, dass dein Spiel zu langsam ist, und es muss sich mit dem letzten Cursor neu verbinden.
- Der Code 1009 bedeutet, dass dein Spiel eine zu große Nachricht gesendet hat, und du musst den Client korrigieren.
- Der Code 4401 bedeutet, dass der Key ungültig ist oder widerrufen wurde, und dein Spiel darf sich erst nach dem Wechsel erneut verbinden.
- Der Code 4403 bedeutet, dass der Zugang abgelaufen ist, und dein Spiel muss
/v1/statusalle 30 Sekunden abfragen, bisservingden Werttruehat. - Der Code 4408 bedeutet, dass dein Spiel den
pongnicht rechtzeitig beantwortet hat, und es muss sich mit zunehmender Wartezeit und dem letzten Cursor neu verbinden.
Limits und feste Werte
Dies sind die Limits, die die lokale API anwendet, und die Kennungen C-### sind die internen Namen der einzelnen Werte.
| Konstante | Wert | Beschreibung |
|---|---|---|
C-020 | 17920 | Standardport der lokalen API. |
C-021 | 25 | Maximale Wartezeit in Sekunden einer periodischen Abfrage und empfohlenes Zeitlimit für den Client. |
C-022 | 10000 | Pro Spiel gespeicherte Ereignisse, oder die der letzten 10 Minuten. |
C-026 | 30 | Sekunden zwischen den einzelnen Pings des WebSockets. |
C-027 | 10 | Sekunden, die dein Spiel Zeit hat, den Pong zu beantworten. |
C-028 | 1, 2, 4, 8, 16, 30 | Wartezeit in Sekunden zwischen Wiederverbindungen, mit einer zufälligen Abweichung von 20 %. |
C-034 | 65536 | Maximale Größe einer WebSocket-Nachricht in Bytes. |
C-050 | 60 | Sekunden ohne Abfrage, bis die App das Spiel als getrennt betrachtet. |
C-057 | 100 | Maximale Anzahl Ereignisse pro Antwort einer periodischen Abfrage. |
C-137 | 86400 | Sekunden, die ein API-Key nach der Rotation weiter gültig bleibt. |
C-138 | tkv_live_ + 32 base62 | Format des API-Keys. |
C-141 | 3 | Standardmäßig gleichzeitig verbundene Spiele. |
C-155 | 500 | Maximale Länge in Zeichen eines Textes mit Variablen. |
Hinweis zum lokalen Netzwerk in Chrome
Wenn sich eine öffentliche Seite mit 127.0.0.1 verbindet, zeigt Chrome eine Berechtigungsabfrage für den Zugriff auf das lokale Netzwerk an.
Der Streamer muss diese Abfrage einmal akzeptieren, sonst blockiert der Browser die Verbindung deines Spiels mit der App.
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- Der Hinweis erscheint nur auf öffentlichen Seiten, und eine Seite, die aus einer lokalen Datei oder von
http://127.0.0.1geöffnet wird, zeigt ihn nicht an. - Wenn der Streamer die Berechtigung abgelehnt hat, muss er sie in den Website-Einstellungen von Chrome aktivieren und die Seite neu laden.
- Verwende immer
127.0.0.1stattlocalhost, weil das Systemlocalhostzuerst zu::1auflösen kann und die App dort nicht lauscht.
So testest du dein Spiel
Um zu testen, ohne auf ein echtes Geschenk zu warten, kann der Streamer Testereignisse aus der App senden.
- Öffne die TikAresV-Desktop-App und melde dich an.
- Gehe in der Spieleliste der App in das Spiel.
- Öffne eine vorhandene Regel oder erstelle im Regeleditor eine neue.
- Klicke im Regeleditor auf die Schaltfläche Testen.
- Prüfe, dass dein Spiel das Ereignis empfängt und die Aktion ausführt.
Testereignisse kommen mit test: true und mit einer id, die mit test: beginnt.
GET http://127.0.0.1:17920/harnessDie App enthält außerdem eine Testseite, die zeigt, was ein Spiel empfangen würde, ohne dass man eines haben muss.
Fehlerbehebung
Prüfe diese Ursachen der Reihe nach, wenn dein Spiel keine Ereignisse empfängt.
- Wenn die Verbindung sofort fehlschlägt, öffne
http://127.0.0.1:17920/v1/statusim Browser und prüfe, ob die App antwortet. - Wenn
localhostsich nicht verbindet, wechsle zu127.0.0.1, weil die App nicht auf::1lauscht. - Wenn du den Fehler 401 erhältst, prüfe, ob der Key das Format
tkv_live_plus 32 Zeichen hat und nicht rotiert wurde. - Wenn du den Fehler 403 mit
LOCAL_ACCESS_EXPIREDerhältst, bitte den Streamer, sein Abo im Bereich Abo der App zu verlängern. - Wenn du den Fehler 403 mit
LOCAL_GAMES_LIMITerhältst, schließe ein anderes verbundenes Spiel oder bitte den Streamer um ein Abo mit mehr Spielen. - Wenn der Browser die Verbindung blockiert, ohne einen Fehler der App zu zeigen, akzeptiere den Hinweis zum lokalen Netzwerk von Chrome.
- Wenn die Verbindung alle paar Sekunden abbricht, prüfe, ob dein Spiel jeden
pingin weniger als 10 Sekunden mitpongbeantwortet. - Wenn du nach dem Neustart der App wiederholte Ereignisse siehst, ignoriere die bereits verarbeiteten anhand der
iddes Ereignisses. - Wenn du das Feld
resetmittruesiehst, wurde die App neu gestartet und der vorherige Cursor ist nicht mehr brauchbar, sodass dein Spiel nur neue Ereignisse erhält.