网页游戏文档
通过 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 游戏。
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx如果需要更换 key,团队会生成一个新的,旧的会继续有效 24 小时(86400 秒),以便你不中断地更新游戏。
请像对待游戏的密码一样对待 key,不要把它发布到不属于你的公开仓库中。
使用 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该 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 会在事件到达时立即传递,是网页游戏的推荐方式。
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41key参数是必需的,其值是经过encodeURIComponent编码的 API key。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" } } }应用每 30 秒发送一次 ping,你的游戏必须在 10 秒内以相同的 ts 回复 pong,否则应用会以代码 4408 关闭连接。
{ "type": "pong", "data": { "ts": 1791062130000 } }定期查询:GET /v1/events/poll
此路由是只能发送 HTTP 请求的客户端使用 WebSocket 之外的替代方案,它最多等待 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。 - 当因
limit限制而剩余事件时,has_more字段为true,此时你必须不等待地再次查询。 - 如果你停止查询 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对象描述观众,仅在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_FORBIDDEN | 403 | host_not_loopback | 请始终连接到 `127.0.0.1` 或 `localhost`,不要使用其他主机名。 |
LOCAL_KEY_INVALID | 401 | key_missing | 请在 WebSocket 的 URL 或 `x-api-key` 请求头中发送 API key。 |
LOCAL_KEY_INVALID | 401 | key_format | 请检查 key 的格式是否为 `tkv_live_` 加 32 个字母数字字符。 |
LOCAL_KEY_INVALID | 401 | key_unknown | 请确认你使用的是游戏当前有效的 key,如果丢失,请向团队申请新的 key。 |
LOCAL_KEY_INVALID | 401 | game_inactive | 你的游戏已被停用,请联系 TikAresV 团队。 |
LOCAL_KEY_INVALID | 401 | game_not_visible | 你的游戏对该主播不可用,请联系 TikAresV 团队。 |
LOCAL_KEY_INVALID | 401 | unresolved_offline | 由于没有网络或尝试次数过多,应用无法验证 key,请等待几秒后重试。 |
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 表示 key 无效或已被撤销,在更换之前你的游戏不应重新连接。
- 代码 4403 表示访问已过期,你的游戏必须每 30 秒查询一次
/v1/status,直到serving变为true。 - 代码 4408 表示你的游戏没有及时回复
pong,必须以递增的等待时间和最后一个游标重新连接。
限制与固定值
这些是本地 API 应用的限制,C-### 标识符是每个值的内部名称。
| 常量 | 值 | 说明 |
|---|---|---|
C-020 | 17920 | 本地 API 的默认端口。 |
C-021 | 25 | 定期查询的最长等待秒数,以及建议的客户端超时时间。 |
C-022 | 10000 | 每个游戏保留的事件,或最近 10 分钟的事件。 |
C-026 | 30 | WebSocket 每次 ping 之间的秒数。 |
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 错误,请检查 key 的格式是否为
tkv_live_加 32 个字符,以及它是否已被轮换。 - 如果收到带有
LOCAL_ACCESS_EXPIRED的 403 错误,请让主播在应用的套餐部分续订套餐。 - 如果收到带有
LOCAL_GAMES_LIMIT的 403 错误,请关闭另一个已连接的游戏,或让主播升级到支持更多游戏的套餐。 - 如果浏览器在应用没有显示错误的情况下阻止了连接,请接受 Chrome 的本地网络提示。
- 如果连接每隔几秒就断开,请确认你的游戏在 10 秒内对每个
ping回复了pong。 - 如果在重启应用后看到重复的事件,请使用事件的
id忽略你已经处理过的事件。 - 如果你看到
reset字段为true,说明应用已重启,之前的游标不再有效,因此你的游戏只会收到新事件。