Zum Inhalt springen
Zurück zur Startseite

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 kontaktieren

Wenn dein Spiel registriert ist, erhältst du die folgenden Daten.

  • Die game_id ist 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_guid wird nur bei Roblox-Spielen mitgeliefert.
Format des API-Keys, der dein Spiel identifiziert.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Wenn 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.

RouteZugangsdaten
GET /v1/eventskey=<api_key> | x-api-key
GET /v1/events/pollx-api-key
GET /v1/configx-api-key
GET /v1/status—
Beispiel einer authentifizierten Abfrage mit dem Header `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

Der 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/poll und /v1/config erhalten den Key nur im Header x-api-key, und der Parameter key wird dort ignoriert.
  • Die Route /v1/status braucht 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 id des Testereignisses und dem Namen der Aktion zeigt.
  • Wenn es funktioniert, ersetze die Funktion runAction durch den Code deines Spiels für jede Aktion.
Minimales und vollständiges Beispiel eines Webspiels, das sich verbindet, sich selbst wieder verbindet und die empfangenen Aktionen anzeigt.
<!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.

Abfrage des Status der App.
GET http://127.0.0.1:17920/v1/status
Antwort mit dem Status der App, des Lives und der verbundenen Spiele.
{
  "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 serving ist true, wenn die App Ereignisse an dein Spiel liefern kann.
  • Das Feld serving_reason erklärt, warum sie liefert oder nicht, und no_valid_token bedeutet, dass das Abo des Streamers nicht gültig ist.
  • Das Feld tiktok_state ist disconnected ohne Aufzeichnung, waiting beim Warten auf den Live und streaming bei laufendem Live.
  • Die Felder connected_games und max_connected_games zeigen, 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.

Verbindungsadresse mit dem Key, den Ereignistypen und dem letzten Cursor.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41
  • Der Parameter key ist erforderlich und trägt den mit encodeURIComponent kodierten API-Key.
  • Der Parameter types ist optional, listet die Typen durch Kommas ohne Leerzeichen getrennt auf, und wenn er fehlt, werden alle acht Typen empfangen.
  • Der Parameter cursor ist 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.

`hello`-Nachricht, mit der die App die Verbindung bestätigt.
{
  "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"
  }
}
Nachrichten, die dein Spiel nach dem `hello` empfangen kann.
{ "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.

Antwort, die dein Spiel auf jeden `ping` senden muss.
{ "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.

Abfrage mit dem vorherigen Cursor und einer Wartezeit von 20 Sekunden.
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
ParameterErforderlichStandardBereich
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)
Antwort mit den neuen Ereignissen und dem Cursor, der in der nächsten Abfrage gesendet werden muss.
{
  "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 cursor der vorherigen Antwort.
  • Das Feld has_more ist true, wenn wegen des Limits limit Ereignisse ü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.

Abfrage der Konfiguration mit `If-None-Match`, um wiederholte Downloads zu vermeiden.
GET http://127.0.0.1:17920/v1/config
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If-None-Match: "cfg-7"
Antwort mit der Version und den Regeln der Konfiguration.
{ "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.

Gemeinsame Felder eines Ereignisses, hier mit einem Geschenk.
{
  "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 v ist die Version des Formats und ist heute immer 1.
  • Das Feld id ist pro Ereignis eindeutig und stabil, und dein Spiel muss es nutzen, um Duplikate zu ignorieren.
  • Das Feld type ist gift, comment, like, follow, share, subscribe, join oder viewers.
  • Das Feld ts ist die Zeit des Ereignisses im Format RFC 3339 UTC mit Millisekunden.
  • Die Felder live_id, game_id und room_id identifizieren den Live, dein Spiel und den TikTok-Raum.
  • Das Feld test ist nur bei Testereignissen true.
  • Das Objekt user beschreibt den Zuschauer und ist nur bei viewers-Ereignissen null.
  • Jedes Ereignis trägt nur das Objekt seines Typs (gift, comment, like, viewers oder subscribe), die übrigen sind null.
  • Das Array actions listet auf, was dein Spiel tun muss, jeweils mit action_key, params, rule_id und repeat.
  • Dein Spiel muss jede Aktion so oft ausführen, wie repeat angibt, 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.

VariableHerkunft
{{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.

Beispiel eines Cursors, den dein Spiel nur speichert und zurücksendet, ohne ihn zu interpretieren.
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 reset als true ankommt, 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.

Beispiel der Fehlerantwort.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }
CodeHTTPGrundWas zu tun ist
ORIGIN_FORBIDDEN403host_not_loopbackVerbinde dich immer mit `127.0.0.1` oder `localhost` und verwende keinen anderen Rechnernamen.
LOCAL_KEY_INVALID401key_missingSende den API-Key in der URL des WebSockets oder im Header `x-api-key`.
LOCAL_KEY_INVALID401key_formatPrüfe, ob der Key das Format `tkv_live_` gefolgt von 32 alphanumerischen Zeichen hat.
LOCAL_KEY_INVALID401key_unknownPrüfe, ob du den aktuellen Key deines Spiels verwendest, und fordere beim Team einen neuen an, falls du ihn verloren hast.
LOCAL_KEY_INVALID401game_inactiveDein Spiel ist deaktiviert, also kontaktiere das TikAresV-Team.
LOCAL_KEY_INVALID401game_not_visibleDein Spiel ist für diesen Streamer nicht verfügbar, also kontaktiere das TikAresV-Team.
LOCAL_KEY_INVALID401unresolved_offlineDie App konnte den Key wegen fehlenden Internets oder zu vieler Versuche nicht validieren, also warte einige Sekunden und versuche es erneut.
LOCAL_ACCESS_EXPIRED403no_valid_tokenDas 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_LIMIT403Die 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_RESET200Es ist kein HTTP-Fehler, sondern der Hinweis, dass die App neu gestartet wurde, und dein Spiel macht mit den neuen Ereignissen weiter.
COMMON_VALIDATION_FAILED422Sieh dir `details.fields` an, um zu erkennen, welcher Parameter ungültig ist, und korrigiere ihn.
COMMON_NOT_FOUND404Prüfe die Route, oder warte, bis die App die Konfiguration des Spiels heruntergeladen hat, falls du `/v1/config` angefordert hast.
COMMON_INTERNAL500Es 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.

CodeGrund
1000normal
1001going_away
1008too_slow
1009message_too_big
4401key_invalid
4403access_expired
4408pong_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/status alle 30 Sekunden abfragen, bis serving den Wert true hat.
  • Der Code 4408 bedeutet, dass dein Spiel den pong nicht 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.

KonstanteWertBeschreibung
C-02017920Standardport der lokalen API.
C-02125Maximale Wartezeit in Sekunden einer periodischen Abfrage und empfohlenes Zeitlimit für den Client.
C-02210000Pro Spiel gespeicherte Ereignisse, oder die der letzten 10 Minuten.
C-02630Sekunden zwischen den einzelnen Pings des WebSockets.
C-02710Sekunden, die dein Spiel Zeit hat, den Pong zu beantworten.
C-0281, 2, 4, 8, 16, 30Wartezeit in Sekunden zwischen Wiederverbindungen, mit einer zufälligen Abweichung von 20 %.
C-03465536Maximale Größe einer WebSocket-Nachricht in Bytes.
C-05060Sekunden ohne Abfrage, bis die App das Spiel als getrennt betrachtet.
C-057100Maximale Anzahl Ereignisse pro Antwort einer periodischen Abfrage.
C-13786400Sekunden, die ein API-Key nach der Rotation weiter gültig bleibt.
C-138tkv_live_ + 32 base62Format des API-Keys.
C-1413Standardmäßig gleichzeitig verbundene Spiele.
C-155500Maximale 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.

Antwort der App auf die vorherige Abfrage des Browsers, die bereits die Freigabe für das private Netzwerk enthält.
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.1 geö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.1 statt localhost, weil das System localhost zuerst zu ::1 auflö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.

Adresse der Testseite, die im Browser geöffnet wird, solange die App geöffnet ist.
GET http://127.0.0.1:17920/harness

Die 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/status im Browser und prüfe, ob die App antwortet.
  • Wenn localhost sich nicht verbindet, wechsle zu 127.0.0.1, weil die App nicht auf ::1 lauscht.
  • 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_EXPIRED erhältst, bitte den Streamer, sein Abo im Bereich Abo der App zu verlängern.
  • Wenn du den Fehler 403 mit LOCAL_GAMES_LIMIT erhä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 ping in weniger als 10 Sekunden mit pong beantwortet.
  • Wenn du nach dem Neustart der App wiederholte Ereignisse siehst, ignoriere die bereits verarbeiteten anhand der id des Ereignisses.
  • Wenn du das Feld reset mit true siehst, wurde die App neu gestartet und der vorherige Cursor ist nicht mehr brauchbar, sodass dein Spiel nur neue Ereignisse erhält.