コンテンツへスキップ
ホームに戻る

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のゲームにのみ提供されます。
ゲームを識別するAPIキーの形式です。
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

キーを変更する必要がある場合は、チームが新しいキーを生成し、古いキーは24時間(86400秒)有効なままなので、中断なくゲームを更新できます。

キーはゲームのパスワードとして扱い、自分のものではない公開リポジトリに公開しないでください。

APIキーによる認証

イベントや設定を返すすべての呼び出しは、ゲームのAPIキーで認証されます。APIキーは 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にヘッダーを付けられないため、WebSocketはURLの key パラメーターでキーを受け取ります。
  • HTTPルートの /v1/events/poll と /v1/config はキーを x-api-key ヘッダーでのみ受け取り、key パラメーターは無視されます。
  • /v1/status ルートにはキーが不要なので、接続する前にアプリが開いているかどうかを確認するのに使えます。

クイックスタート

この手順で、ゲームは数分で最初のイベントを受け取れます。

  • TikAresVチームにゲームの登録を依頼し、受け取ったAPIキーを保管してください。キーは一度しか表示されません。
  • 配信者にTikAresVのデスクトップアプリを開いてログインしてもらいます。
  • この節の例を .html ファイルにコピーし、APIキーのプレースホルダーを自分のキーに置き換えます。
  • アプリが動作している同じコンピューターのブラウザでファイルを開き、Chromeがローカルネットワークへのアクセスを尋ねたら許可します。
  • 配信者にアプリで自分のゲームを開き、ルールを編集して「テスト」ボタンを押してもらいます。
  • ページのログに、テストイベントの id とアクション名が書かれた行が表示されることを確認します。
  • 動作したら、runAction 関数を各アクションに対応するゲームのコードに置き換えます。
接続し、自動で再接続し、受け取ったアクションを表示するWebゲームの、最小かつ完全な例です。
<!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-41
  • key パラメーターは必須で、encodeURIComponent でエンコードしたAPIキーを指定します。
  • types パラメーターは任意で、種類をスペースなしのカンマ区切りで指定します。省略すると8種類すべてを受け取ります。
  • 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です。

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_FORBIDDEN403host_not_loopback常に `127.0.0.1` または `localhost` に接続し、他のホスト名は使用しないでください。
LOCAL_KEY_INVALID401key_missingAPIキーを、WebSocketのURLまたは `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_RESET200HTTPエラーではなく、アプリが再起動されたことの通知であり、ゲームは新しいイベントで続行します。
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は、アクセスの期限が切れたことを意味し、ゲームは serving が true になるまで30秒ごとに /v1/status を問い合わせる必要があります。
  • コード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定期的な問い合わせの1回のレスポンスに含まれるイベントの最大数です。
C-13786400ローテーション後にAPIキーが有効なままである秒数です。
C-138tkv_live_ + 32 base62APIキーの形式です。
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のサイト設定で有効にしてページを再読み込みする必要があります。
  • システムが先に 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 の場合、アプリが再起動されて以前のカーソルは使えなくなっているため、ゲームは新しいイベントのみを受け取ります。