跳到内容
返回首页

网页游戏文档

通过 TikAresV 桌面应用,将你的浏览器游戏连接到 TikTok 直播事件。

它是什么以及如何工作

TikAresV 是一款桌面应用,它读取主播 TikTok 直播的事件(礼物、评论、点赞、关注、分享、订阅、进入直播间和观众),并将其传递给你的游戏。

应用会在主播的电脑上通过 127.0.0.1 开启一个本地 API,而在同一台电脑的浏览器中运行的你的游戏,使用 API key 连接到它。

  • 只有在运行游戏的电脑上打开桌面应用时,本地 API 才存在。
  • 每个事件都带有稳定的 id,因此你的游戏可以忽略已经处理过的事件。
  • 主播在应用中定义每个礼物、评论或点赞触发哪个动作,而你的游戏只执行收到的动作。
  • 你可以通过 WebSocket 接收事件,这在浏览器中最方便;如果你更喜欢简单的 HTTP,也可以使用定期查询(long-poll)。

要接收事件,你只需要游戏的 API key、主播电脑上的浏览器,以及本页的说明。

游戏登记与 API key

游戏的登记由 TikAresV 团队完成,请联系我们登记你的游戏。

联系 TikAresV 团队

游戏登记后,你将收到以下信息。

  • game_id 是你游戏的唯一标识符。
  • API key 的格式为 tkv_live_ 加 32 个字母数字字符,并且只显示一次,因此请立即保存。
  • game_guid 仅提供给 Roblox 游戏。
用于标识你游戏的 API key 的格式。
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

如果需要更换 key,团队会生成一个新的,旧的会继续有效 24 小时(86400 秒),以便你不中断地更新游戏。

请像对待游戏的密码一样对待 key,不要把它发布到不属于你的公开仓库中。

使用 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

该 key 随你游戏的代码一起传输,并向应用标识这是你的游戏,因此不要与其他游戏共享。

  • WebSocket 通过 URL 的 key 参数接收 key,因为浏览器不允许为 WebSocket 设置请求头。
  • HTTP 路由 /v1/events/poll 和 /v1/config 只在 x-api-key 请求头中接收 key,其中的 key 参数会被忽略。
  • /v1/status 路由不需要 key,因此可用于在连接之前确认应用是否已打开。

快速开始

按照这些步骤,你的游戏可以在几分钟内收到第一个事件。

  • 请 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 会在事件到达时立即传递,是网页游戏的推荐方式。

包含 key、事件类型和最后一个游标的连接地址。
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41
  • key 参数是必需的,其值是经过 encodeURIComponent 编码的 API key。
  • 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" } } }

应用每 30 秒发送一次 ping,你的游戏必须在 10 秒内以相同的 ts 回复 pong,否则应用会以代码 4408 关闭连接。

你的游戏必须对每个 `ping` 发送的回复。
{ "type": "pong", "data": { "ts": 1791062130000 } }

定期查询:GET /v1/events/poll

此路由是只能发送 HTTP 请求的客户端使用 WebSocket 之外的替代方案,它最多等待 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。
  • 当因 limit 限制而剩余事件时,has_more 字段为 true,此时你必须不等待地再次查询。
  • 如果你停止查询 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 对象描述观众,仅在 viewers 事件中为 null。
  • 每个事件只携带其类型对应的对象(gift、comment、like、viewers 或 subscribe),其余均为 null。
  • actions 数组列出你的游戏应做的事情,每一项都有 action_key、params、rule_id 和 repeat。
  • 你的游戏必须按 repeat 指示的次数执行每个动作;除了每 N 个点赞触发的规则外,该值为 1。

八种事件类型的示例

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请在 WebSocket 的 URL 或 `x-api-key` 请求头中发送 API key。
LOCAL_KEY_INVALID401key_format请检查 key 的格式是否为 `tkv_live_` 加 32 个字母数字字符。
LOCAL_KEY_INVALID401key_unknown请确认你使用的是游戏当前有效的 key,如果丢失,请向团队申请新的 key。
LOCAL_KEY_INVALID401game_inactive你的游戏已被停用,请联系 TikAresV 团队。
LOCAL_KEY_INVALID401game_not_visible你的游戏对该主播不可用,请联系 TikAresV 团队。
LOCAL_KEY_INVALID401unresolved_offline由于没有网络或尝试次数过多,应用无法验证 key,请等待几秒后重试。
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 表示 key 无效或已被撤销,在更换之前你的游戏不应重新连接。
  • 代码 4403 表示访问已过期,你的游戏必须每 30 秒查询一次 /v1/status,直到 serving 变为 true。
  • 代码 4408 表示你的游戏没有及时回复 pong,必须以递增的等待时间和最后一个游标重新连接。

限制与固定值

这些是本地 API 应用的限制,C-### 标识符是每个值的内部名称。

常量值说明
C-02017920本地 API 的默认端口。
C-02125定期查询的最长等待秒数,以及建议的客户端超时时间。
C-02210000每个游戏保留的事件,或最近 10 分钟的事件。
C-02630WebSocket 每次 ping 之间的秒数。
C-02710你的游戏回复 pong 的时限(秒)。
C-0281, 2, 4, 8, 16, 30重新连接之间的等待秒数,带有 20 % 的随机波动。
C-03465536WebSocket 消息的最大字节数。
C-05060在没有查询的情况下,经过这些秒数后应用会认为游戏已断开。
C-057100定期查询的每次响应中的最大事件数。
C-13786400API key 被轮换后继续有效的秒数。
C-138tkv_live_ + 32 base62API 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 错误,请检查 key 的格式是否为 tkv_live_ 加 32 个字符,以及它是否已被轮换。
  • 如果收到带有 LOCAL_ACCESS_EXPIRED 的 403 错误,请让主播在应用的套餐部分续订套餐。
  • 如果收到带有 LOCAL_GAMES_LIMIT 的 403 错误,请关闭另一个已连接的游戏,或让主播升级到支持更多游戏的套餐。
  • 如果浏览器在应用没有显示错误的情况下阻止了连接,请接受 Chrome 的本地网络提示。
  • 如果连接每隔几秒就断开,请确认你的游戏在 10 秒内对每个 ping 回复了 pong。
  • 如果在重启应用后看到重复的事件,请使用事件的 id 忽略你已经处理过的事件。
  • 如果你看到 reset 字段为 true,说明应用已重启,之前的游标不再有效,因此你的游戏只会收到新事件。