Webゲーム向けドキュメント
TikAresVのデスクトップアプリを通じて、ブラウザゲームをTikTokライブのイベントに接続します。
概要と仕組み
TikAresVは、配信者のTikTokライブのイベント(ギフト、コメント、いいね、フォロー、シェア、サブスクリプション、入室、視聴者)を読み取り、あなたのゲームに届けるデスクトップアプリです。
アプリは配信者のコンピューター上で 127.0.0.1 にローカルAPIを開き、同じコンピューターのブラウザで動作するあなたのゲームが、APIキーを使ってそこに接続します。
- ローカルAPIは、ゲームが動作しているコンピューターでデスクトップアプリが開いている間だけ存在します。
- 各イベントには安定した
idが付いているため、ゲームは処理済みのイベントを無視できます。 - ギフト、コメント、いいねごとにどのアクションを実行するかは配信者がアプリで定義し、ゲームは受け取ったアクションだけを実行します。
- イベントは、ブラウザで最も扱いやすいWebSocketで受け取ることも、単純なHTTPを使いたい場合は定期的な問い合わせ(ロングポーリング)で受け取ることもできます。
イベントを受け取るために必要なのは、ゲームのAPIキー、配信者のコンピューターのブラウザ、そしてこのページの手順だけです。
ゲームの登録とAPIキー
ゲームの登録はTikAresVチームが行いますので、ご自身のゲームを登録するにはご連絡ください。
TikAresVチームに連絡するゲームが登録されると、次の情報を受け取ります。
game_idは、ゲームの一意の識別子です。- APIキーは
tkv_live_に英数字32文字が続く形式で、一度しか表示されないため、すぐに保管してください。 game_guidはRobloxのゲームにのみ提供されます。
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxキーを変更する必要がある場合は、チームが新しいキーを生成し、古いキーは24時間(86400秒)有効なままなので、中断なくゲームを更新できます。
キーはゲームのパスワードとして扱い、自分のものではない公開リポジトリに公開しないでください。
APIキーによる認証
イベントや設定を返すすべての呼び出しは、ゲームのAPIキーで認証されます。APIキーは 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にヘッダーを付けられないため、WebSocketはURLの
keyパラメーターでキーを受け取ります。 - HTTPルートの
/v1/events/pollと/v1/configはキーをx-api-keyヘッダーでのみ受け取り、keyパラメーターは無視されます。 /v1/statusルートにはキーが不要なので、接続する前にアプリが開いているかどうかを確認するのに使えます。
クイックスタート
この手順で、ゲームは数分で最初のイベントを受け取れます。
- TikAresVチームにゲームの登録を依頼し、受け取ったAPIキーを保管してください。キーは一度しか表示されません。
- 配信者にTikAresVのデスクトップアプリを開いてログインしてもらいます。
- この節の例を
.htmlファイルにコピーし、APIキーのプレースホルダーを自分のキーに置き換えます。 - アプリが動作している同じコンピューターのブラウザでファイルを開き、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キーは不要です。
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はイベントが届き次第すぐに配信するため、Webゲームに推奨される方法です。
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41keyパラメーターは必須で、encodeURIComponentでエンコードしたAPIキーを指定します。typesパラメーターは任意で、種類をスペースなしのカンマ区切りで指定します。省略すると8種類すべてを受け取ります。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です。
8種類のイベントの例
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": []
}8種類のイベントと、それぞれの実際の例です。
| 変数 | 取得元 |
|---|---|
{{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キーを、WebSocketのURLまたは `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は、アクセスの期限が切れたことを意味し、ゲームは
servingがtrueになるまで30秒ごとに/v1/statusを問い合わせる必要があります。 - コード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 | 定期的な問い合わせの1回のレスポンスに含まれるイベントの最大数です。 |
C-137 | 86400 | ローテーション後にAPIキーが有効なままである秒数です。 |
C-138 | tkv_live_ + 32 base62 | APIキーの形式です。 |
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のサイト設定で有効にしてページを再読み込みする必要があります。
- システムが先に
localhostを::1に解決することがあり、アプリはそこで待ち受けていないため、localhostではなく必ず127.0.0.1を使用してください。
ゲームのテスト方法
実際のギフトを待たずにテストするために、配信者はアプリからテストイベントを送信できます。
- TikAresVのデスクトップアプリを開いてログインします。
- アプリのゲーム一覧からゲームを開きます。
- ルールエディターで既存のルールを開くか、新しいルールを作成します。
- ルールエディターの「テスト」ボタンを押します。
- ゲームがイベントを受け取り、アクションを実行することを確認します。
テストイベントは test: true で届き、id は test: で始まります。
GET http://127.0.0.1:17920/harnessアプリには、ゲームがなくてもゲームが受け取る内容を確認できるテストページも含まれています。
トラブルシューティング
ゲームがイベントを受け取れないときは、次の原因を順番に確認してください。
- 接続がすぐに失敗する場合は、ブラウザで
http://127.0.0.1:17920/v1/statusを開き、アプリが応答することを確認します。 localhostで接続できない場合は、アプリが::1で待ち受けていないため、127.0.0.1に切り替えます。- エラー401が出る場合は、キーが
tkv_live_と32文字の形式であること、およびローテーションされていないことを確認します。 LOCAL_ACCESS_EXPIREDのエラー403が出る場合は、配信者にアプリのプランの項目でプランを更新してもらいます。LOCAL_GAMES_LIMITのエラー403が出る場合は、接続中の別のゲームを閉じるか、配信者にゲーム数の多いプランを依頼します。- アプリのエラーが表示されないままブラウザが接続をブロックする場合は、Chromeのローカルネットワークの通知を許可します。
- 接続が数秒ごとに切れる場合は、ゲームがすべての
pingに10秒以内にpongを返していることを確認します。 - アプリの再起動後に同じイベントが繰り返し表示される場合は、イベントの
idを使って処理済みのものを無視します。 resetフィールドがtrueの場合、アプリが再起動されて以前のカーソルは使えなくなっているため、ゲームは新しいイベントのみを受け取ります。