Перейти к содержимому
Вернуться на главную

Документация для веб-игр

Подключите свою браузерную игру к событиям прямого эфира TikTok через настольное приложение TikAresV.

Что это и как работает

TikAresV — это настольное приложение, которое считывает события прямого эфира TikTok стримера (подарки, комментарии, лайки, подписчики, репосты, подписки, входы и зрители) и передаёт их вашей игре.

Приложение открывает на компьютере стримера локальный API по адресу 127.0.0.1, а ваша игра, работающая в браузере на этом же компьютере, подключается к нему с помощью API key.

  • Локальный API существует только пока настольное приложение открыто на компьютере, где работает игра.
  • Каждое событие приходит со стабильным id, поэтому ваша игра может игнорировать уже обработанные события.
  • Стример задаёт в приложении, какое действие срабатывает на каждый подарок, комментарий или лайк, а ваша игра выполняет только полученные действия.
  • События можно получать по WebSocket, что удобнее всего в браузере, или с помощью периодических запросов (long-poll), если вы предпочитаете обычный HTTP.

Чтобы получать события, вам нужны только API key вашей игры, браузер на компьютере стримера и инструкции с этой страницы.

Регистрация игры и API key

Регистрацию игр выполняет команда TikAresV, поэтому напишите нам, чтобы зарегистрировать свою.

Связаться с командой TikAresV

Когда ваша игра будет зарегистрирована, вы получите следующие данные.

  • game_id — это уникальный идентификатор вашей игры.
  • API key имеет вид tkv_live_ и 32 буквенно-цифровых символа и показывается только один раз, поэтому сразу сохраните его.
  • game_guid выдаётся только для игр Roblox.
Формат API key, который идентифицирует вашу игру.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Если нужно сменить ключ, команда создаёт новый, а прежний остаётся действительным в течение 24 часов (86400 секунд), чтобы вы могли обновить игру без перерывов.

Относитесь к ключу как к паролю вашей игры и не публикуйте его в открытых репозиториях, которые вам не принадлежат.

Аутентификация с помощью API key

Каждый вызов, который передаёт события или настройки, аутентифицируется с помощью API key вашей игры, имеющего вид tkv_live_ и 32 буквенно-цифровых символа.

МаршрутУчётные данные
GET /v1/eventskey=<api_key> | x-api-key
GET /v1/events/pollx-api-key
GET /v1/configx-api-key
GET /v1/status—
Пример аутентифицированного запроса с заголовком `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

Ключ передаётся из кода вашей игры и идентифицирует её как игру перед приложением, поэтому не делитесь им с другими играми.

  • WebSocket получает ключ в параметре key URL, потому что браузер не позволяет задавать заголовки для WebSocket.
  • HTTP-маршруты /v1/events/poll и /v1/config получают ключ только в заголовке x-api-key, а параметр key в них игнорируется.
  • Маршрут /v1/status не требует ключа, поэтому с его помощью можно проверить, открыто ли приложение, перед подключением.

Быстрый старт

С помощью этих шагов ваша игра получит первое событие за несколько минут.

  • Попросите команду TikAresV зарегистрировать вашу игру и сохраните полученный API key, потому что он показывается только один раз.
  • Попросите стримера открыть настольное приложение TikAresV и войти в аккаунт.
  • Скопируйте пример из этого раздела в файл .html и замените заполнитель API key на свой.
  • Откройте файл в браузере на том же компьютере, где работает приложение, и если Chrome спросит о доступе к локальной сети, разрешите его.
  • Попросите стримера зайти в свою игру в приложении, изменить правило и нажать кнопку «Проверить».
  • Убедитесь, что в журнале страницы появилась строка с id тестового события и названием действия.
  • Когда всё заработает, замените функцию runAction кодом вашей игры для каждого действия.
Минимальный и полный пример веб-игры, которая подключается, сама переподключается и показывает полученные действия.
<!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>

Если что-то не работает, посмотрите таблицу ошибок и раздел об устранении неполадок ниже.

Состояние приложения: GET /v1/status

Этот маршрут показывает, открыто ли приложение и может ли оно отдавать события, и не требует 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"
}
  • Поле serving равно true, когда приложение может передавать события вашей игре.
  • Поле serving_reason объясняет, почему приложение отдаёт или не отдаёт события, а no_valid_token означает, что тариф стримера недействителен.
  • Поле tiktok_state равно disconnected без захвата, waiting в ожидании эфира и streaming во время эфира.
  • Поля connected_games и max_connected_games показывают, сколько игр подключено и сколько разрешает тариф.

Подключение по WebSocket: GET /v1/events

WebSocket передаёт события сразу по мере их поступления и является рекомендуемым способом для веб-игр.

Адрес подключения с ключом, типами событий и последним курсором.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41
  • Параметр key обязателен и содержит API key, закодированный с помощью encodeURIComponent.
  • Параметр types необязателен, перечисляет типы через запятую без пробелов, а если он отсутствует, приходят все восемь типов.
  • Параметр cursor необязателен и возобновляет доставку с последнего события, которое обработала ваша игра.

Сразу после подключения приложение отправляет сообщение hello с состоянием сессии.

Сообщение `hello`, которым приложение подтверждает подключение.
{
  "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"
  }
}
Сообщения, которые ваша игра может получить после `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" } } }

Приложение отправляет ping каждые 30 секунд, и ваша игра должна ответить pong с тем же ts в течение 10 секунд, иначе приложение закроет соединение с кодом 4408.

Ответ, который ваша игра должна отправлять на каждый `ping`.
{ "type": "pong", "data": { "ts": 1791062130000 } }

Периодический запрос: GET /v1/events/poll

Этот маршрут является альтернативой WebSocket для клиентов, которые умеют отправлять только HTTP-запросы, и ждёт до wait секунд, прежде чем вернуть пустой ответ.

Запрос с предыдущим курсором и ожиданием 20 секунд.
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
ПараметрОбязательныйПо умолчаниюДиапазон
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)
Ответ с новыми событиями и курсором, который нужно отправить в следующем запросе.
{
  "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"
}
  • Повторяйте запрос сразу после получения ответа, отправляя cursor из предыдущего ответа.
  • Поле has_more равно true, когда из-за лимита limit остались события, и тогда нужно сразу запросить снова без ожидания.
  • Если вы перестанете делать запросы на 60 секунд, приложение сочтёт, что ваша игра отключилась.

Действующие правила: GET /v1/config

Этот маршрут возвращает правила, которые стример настроил для вашей игры, и пригодится для показа подсказок на экране.

Запрос настроек с `If-None-Match`, чтобы избежать повторных загрузок.
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", "…": "…" } ] } }

Вашей игре не нужно интерпретировать правила, потому что каждое событие уже содержит готовые действия.

Содержимое каждого события

Все события имеют одинаковые общие поля, а каждый тип добавляет собственный объект со специфическими данными.

Общие поля события, здесь на примере подарка.
{
  "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 }
  ]
}
  • Поле v — версия формата, сегодня оно всегда равно 1.
  • Поле id уникально и стабильно для каждого события, и ваша игра должна использовать его, чтобы игнорировать дубликаты.
  • Поле type равно gift, comment, like, follow, share, subscribe, join или viewers.
  • Поле ts — время события в формате RFC 3339 UTC с миллисекундами.
  • Поля live_id, game_id и room_id идентифицируют эфир, вашу игру и комнату TikTok.
  • Поле test равно true только в тестовых событиях.
  • Объект user описывает зрителя и равен null только в событиях viewers.
  • Каждое событие содержит только объект своего типа (gift, comment, like, viewers или subscribe), а остальные равны null.
  • Массив actions перечисляет, что должна сделать ваша игра, каждое действие содержит action_key, params, rule_id и repeat.
  • Ваша игра должна выполнять каждое действие столько раз, сколько указано в repeat; это 1, кроме правил «каждые N лайков».

Примеры восьми типов событий

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

Это восемь типов событий с настоящим примером каждого.

ПеременнаяИсточник
{{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

Тексты в params приходят с уже подставленными переменными, и ни один не превышает 500 символов.

Курсор и возобновление

Курсор — это непрозрачная метка, которая показывает, до какого события дошла ваша игра, и помогает не потерять события при обрыве соединения.

Пример курсора, который ваша игра только сохраняет и возвращает, не интерпретируя.
1791062100000-42
  • Сохраняйте курсор из каждого сообщения event или из каждого ответа на запрос.
  • При переподключении отправьте последний сохранённый курсор, чтобы получить пропущенное.
  • Без курсора вы получаете только события, произошедшие после подключения.
  • Если поле reset приходит со значением true, приложение было перезапущено или курсор больше недоступен, и вы получите только новые события.

Курсор продвигается и по событиям, которые отбрасывает ваш фильтр типов, поэтому вы не получите их повторно.

Ошибки

Все HTTP-ошибки имеют одинаковую форму: стабильный code, который можно сравнивать в вашем коде, и message на английском.

Пример ответа с ошибкой.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }
КодHTTPПричинаЧто делать
ORIGIN_FORBIDDEN403host_not_loopbackВсегда подключайтесь к `127.0.0.1` или `localhost` и не используйте другое имя компьютера.
LOCAL_KEY_INVALID401key_missingОтправляйте API key в URL WebSocket или в заголовке `x-api-key`.
LOCAL_KEY_INVALID401key_formatПроверьте, что ключ имеет формат `tkv_live_` и 32 буквенно-цифровых символа.
LOCAL_KEY_INVALID401key_unknownУбедитесь, что вы используете действующий ключ вашей игры, и попросите у команды новый, если вы его потеряли.
LOCAL_KEY_INVALID401game_inactiveВаша игра отключена, поэтому свяжитесь с командой TikAresV.
LOCAL_KEY_INVALID401game_not_visibleВаша игра недоступна для этого стримера, поэтому свяжитесь с командой TikAresV.
LOCAL_KEY_INVALID401unresolved_offlineПриложение не смогло проверить ключ из-за отсутствия интернета или слишком большого числа попыток, поэтому подождите несколько секунд и повторите.
LOCAL_ACCESS_EXPIRED403no_valid_tokenТариф стримера недействителен, поэтому он должен продлить его в разделе «Тариф» приложения, а ваша игра — повторять попытку каждые 30 секунд.
LOCAL_GAMES_LIMIT403Достигнут максимум подключённых игр по тарифу, поэтому закройте другую игру или попросите стримера оформить тариф с большим числом игр.
LOCAL_CURSOR_RESET200Это не HTTP-ошибка, а уведомление о том, что приложение было перезапущено, и ваша игра продолжает работу с новыми событиями.
COMMON_VALIDATION_FAILED422Посмотрите `details.fields`, чтобы узнать, какой параметр недопустим, и исправьте его.
COMMON_NOT_FOUND404Проверьте маршрут или дождитесь, пока приложение загрузит настройки игры, если вы запросили `/v1/config`.
COMMON_INTERNAL500Это непредвиденная ошибка приложения, поэтому повторяйте с нарастающей задержкой и сообщите команде, если она сохраняется.

В таблице указано, что делать при каждой ошибке.

Коды закрытия WebSocket

Когда соединение закрывается, код показывает, что должна делать ваша игра.

КодПричина
1000normal
1001going_away
1008too_slow
1009message_too_big
4401key_invalid
4403access_expired
4408pong_timeout
  • Код 1000 означает, что ваша игра закрыла соединение, и никаких действий не требуется.
  • Код 1001 означает, что приложение закрылось или сменило порт, и ваша игра должна переподключиться с нарастающей задержкой и последним курсором.
  • Код 1008 означает, что ваша игра слишком медленная, и она должна переподключиться с последним курсором.
  • Код 1009 означает, что ваша игра отправила слишком большое сообщение, и нужно исправить клиент.
  • Код 4401 означает, что ключ недействителен или отозван, и ваша игра не должна переподключаться, пока его не заменят.
  • Код 4403 означает, что доступ истёк, и ваша игра должна запрашивать /v1/status каждые 30 секунд, пока serving не станет true.
  • Код 4408 означает, что ваша игра не ответила pong вовремя, и она должна переподключиться с нарастающей задержкой и последним курсором.

Лимиты и фиксированные значения

Это лимиты, которые применяет локальный API, а идентификаторы C-### — внутренние названия каждого значения.

КонстантаЗначениеОписание
C-02017920Порт локального API по умолчанию.
C-02125Максимальное ожидание периодического запроса в секундах и рекомендуемый тайм-аут для клиента.
C-02210000События, хранимые на игру, или события за последние 10 минут.
C-02630Секунды между пингами WebSocket.
C-02710Секунды, которые есть у вашей игры, чтобы ответить pong.
C-0281, 2, 4, 8, 16, 30Ожидание в секундах между переподключениями со случайным отклонением 20 %.
C-03465536Максимальный размер сообщения WebSocket в байтах.
C-05060Секунды без запросов, после которых приложение считает игру отключённой.
C-057100Максимум событий в ответе на периодический запрос.
C-13786400Секунды, в течение которых API key остаётся действительным после замены.
C-138tkv_live_ + 32 base62Формат API key.
C-1413Число одновременно подключённых игр по умолчанию.
C-155500Максимальная длина текста с переменными в символах.

Уведомление о локальной сети в Chrome

Когда публичная страница подключается к 127.0.0.1, Chrome показывает запрос разрешения на доступ к локальной сети.

Стример должен один раз принять это уведомление, иначе браузер заблокирует подключение вашей игры к приложению.

Ответ приложения на предварительный запрос браузера, который уже включает разрешение для частной сети.
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
  • Уведомление появляется только на публичных страницах, а страница, открытая из локального файла или с http://127.0.0.1, его не показывает.
  • Если стример отклонил разрешение, он должен включить его в настройках сайта в Chrome и перезагрузить страницу.
  • Всегда используйте 127.0.0.1 вместо localhost, потому что система может сначала разрешить localhost в ::1, а приложение там не слушает.

Как проверить вашу игру

Чтобы проверить игру, не дожидаясь настоящего подарка, стример может отправить тестовые события из приложения.

  • Откройте настольное приложение TikAresV и войдите в аккаунт.
  • Зайдите в игру в списке игр приложения.
  • Откройте существующее правило или создайте новое в редакторе правил.
  • Нажмите кнопку «Проверить» в редакторе правил.
  • Убедитесь, что ваша игра получает событие и выполняет действие.

Тестовые события приходят с test: true и с id, который начинается с test:.

Адрес страницы проверки, которая открывается в браузере, пока приложение открыто.
GET http://127.0.0.1:17920/harness

Приложение также включает страницу проверки, которая показывает, что получила бы игра, даже если у вас её ещё нет.

Устранение неполадок

Проверяйте эти причины по порядку, когда игра не получает события.

  • Если подключение сразу не удаётся, откройте http://127.0.0.1:17920/v1/status в браузере и убедитесь, что приложение отвечает.
  • Если localhost не подключается, перейдите на 127.0.0.1, потому что приложение не слушает ::1.
  • Если вы получаете ошибку 401, проверьте, что ключ имеет формат tkv_live_ и 32 символа и что он не был заменён.
  • Если вы получаете ошибку 403 с LOCAL_ACCESS_EXPIRED, попросите стримера продлить тариф в разделе «Тариф» приложения.
  • Если вы получаете ошибку 403 с LOCAL_GAMES_LIMIT, закройте другую подключённую игру или попросите стримера оформить тариф с большим числом игр.
  • Если браузер блокирует подключение, не показывая ошибку приложения, примите уведомление Chrome о локальной сети.
  • Если соединение обрывается каждые несколько секунд, проверьте, что ваша игра отвечает pong на каждый ping менее чем за 10 секунд.
  • Если после перезапуска приложения вы видите повторяющиеся события, игнорируйте уже обработанные, используя id события.
  • Если вы видите поле reset со значением true, приложение было перезапущено, а прежний курсор больше не подходит, поэтому ваша игра получит только новые события.