Документация для веб-игр
Подключите свою браузерную игру к событиям прямого эфира 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.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxЕсли нужно сменить ключ, команда создаёт новый, а прежний остаётся действительным в течение 24 часов (86400 секунд), чтобы вы могли обновить игру без перерывов.
Относитесь к ключу как к паролю вашей игры и не публикуйте его в открытых репозиториях, которые вам не принадлежат.
Аутентификация с помощью API key
Каждый вызов, который передаёт события или настройки, аутентифицируется с помощью API key вашей игры, имеющего вид tkv_live_ и 32 буквенно-цифровых символа.
| Маршрут | Учётные данные |
|---|---|
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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxКлюч передаётся из кода вашей игры и идентифицирует её как игру перед приложением, поэтому не делитесь им с другими играми.
- WebSocket получает ключ в параметре
keyURL, потому что браузер не позволяет задавать заголовки для 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 с состоянием сессии.
{
"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" } } }Приложение отправляет ping каждые 30 секунд, и ваша игра должна ответить pong с тем же ts в течение 10 секунд, иначе приложение закроет соединение с кодом 4408.
{ "type": "pong", "data": { "ts": 1791062130000 } }Периодический запрос: GET /v1/events/poll
Этот маршрут является альтернативой WebSocket для клиентов, которые умеют отправлять только HTTP-запросы, и ждёт до wait секунд, прежде чем вернуть пустой ответ.
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| Параметр | Обязательный | По умолчанию | Диапазон |
|---|---|---|---|
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"
}- Повторяйте запрос сразу после получения ответа, отправляя
cursorиз предыдущего ответа. - Поле
has_moreравноtrue, когда из-за лимитаlimitостались события, и тогда нужно сразу запросить снова без ожидания. - Если вы перестанете делать запросы на 60 секунд, приложение сочтёт, что ваша игра отключилась.
Действующие правила: GET /v1/config
Этот маршрут возвращает правила, которые стример настроил для вашей игры, и пригодится для показа подсказок на экране.
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_FORBIDDEN | 403 | host_not_loopback | Всегда подключайтесь к `127.0.0.1` или `localhost` и не используйте другое имя компьютера. |
LOCAL_KEY_INVALID | 401 | key_missing | Отправляйте API key в URL WebSocket или в заголовке `x-api-key`. |
LOCAL_KEY_INVALID | 401 | key_format | Проверьте, что ключ имеет формат `tkv_live_` и 32 буквенно-цифровых символа. |
LOCAL_KEY_INVALID | 401 | key_unknown | Убедитесь, что вы используете действующий ключ вашей игры, и попросите у команды новый, если вы его потеряли. |
LOCAL_KEY_INVALID | 401 | game_inactive | Ваша игра отключена, поэтому свяжитесь с командой TikAresV. |
LOCAL_KEY_INVALID | 401 | game_not_visible | Ваша игра недоступна для этого стримера, поэтому свяжитесь с командой TikAresV. |
LOCAL_KEY_INVALID | 401 | unresolved_offline | Приложение не смогло проверить ключ из-за отсутствия интернета или слишком большого числа попыток, поэтому подождите несколько секунд и повторите. |
LOCAL_ACCESS_EXPIRED | 403 | no_valid_token | Тариф стримера недействителен, поэтому он должен продлить его в разделе «Тариф» приложения, а ваша игра — повторять попытку каждые 30 секунд. |
LOCAL_GAMES_LIMIT | 403 | Достигнут максимум подключённых игр по тарифу, поэтому закройте другую игру или попросите стримера оформить тариф с большим числом игр. | |
LOCAL_CURSOR_RESET | 200 | Это не HTTP-ошибка, а уведомление о том, что приложение было перезапущено, и ваша игра продолжает работу с новыми событиями. | |
COMMON_VALIDATION_FAILED | 422 | Посмотрите `details.fields`, чтобы узнать, какой параметр недопустим, и исправьте его. | |
COMMON_NOT_FOUND | 404 | Проверьте маршрут или дождитесь, пока приложение загрузит настройки игры, если вы запросили `/v1/config`. | |
COMMON_INTERNAL | 500 | Это непредвиденная ошибка приложения, поэтому повторяйте с нарастающей задержкой и сообщите команде, если она сохраняется. |
В таблице указано, что делать при каждой ошибке.
Коды закрытия WebSocket
Когда соединение закрывается, код показывает, что должна делать ваша игра.
| Код | Причина |
|---|---|
1000 | normal |
1001 | going_away |
1008 | too_slow |
1009 | message_too_big |
4401 | key_invalid |
4403 | access_expired |
4408 | pong_timeout |
- Код 1000 означает, что ваша игра закрыла соединение, и никаких действий не требуется.
- Код 1001 означает, что приложение закрылось или сменило порт, и ваша игра должна переподключиться с нарастающей задержкой и последним курсором.
- Код 1008 означает, что ваша игра слишком медленная, и она должна переподключиться с последним курсором.
- Код 1009 означает, что ваша игра отправила слишком большое сообщение, и нужно исправить клиент.
- Код 4401 означает, что ключ недействителен или отозван, и ваша игра не должна переподключаться, пока его не заменят.
- Код 4403 означает, что доступ истёк, и ваша игра должна запрашивать
/v1/statusкаждые 30 секунд, покаservingне станетtrue. - Код 4408 означает, что ваша игра не ответила
pongвовремя, и она должна переподключиться с нарастающей задержкой и последним курсором.
Лимиты и фиксированные значения
Это лимиты, которые применяет локальный API, а идентификаторы C-### — внутренние названия каждого значения.
| Константа | Значение | Описание |
|---|---|---|
C-020 | 17920 | Порт локального API по умолчанию. |
C-021 | 25 | Максимальное ожидание периодического запроса в секундах и рекомендуемый тайм-аут для клиента. |
C-022 | 10000 | События, хранимые на игру, или события за последние 10 минут. |
C-026 | 30 | Секунды между пингами WebSocket. |
C-027 | 10 | Секунды, которые есть у вашей игры, чтобы ответить pong. |
C-028 | 1, 2, 4, 8, 16, 30 | Ожидание в секундах между переподключениями со случайным отклонением 20 %. |
C-034 | 65536 | Максимальный размер сообщения WebSocket в байтах. |
C-050 | 60 | Секунды без запросов, после которых приложение считает игру отключённой. |
C-057 | 100 | Максимум событий в ответе на периодический запрос. |
C-137 | 86400 | Секунды, в течение которых API key остаётся действительным после замены. |
C-138 | tkv_live_ + 32 base62 | Формат API key. |
C-141 | 3 | Число одновременно подключённых игр по умолчанию. |
C-155 | 500 | Максимальная длина текста с переменными в символах. |
Уведомление о локальной сети в 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, приложение было перезапущено, а прежний курсор больше не подходит, поэтому ваша игра получит только новые события.