カスタムTikTokブリッジ
組み込みブリッジの代わりに、自作または既存のTikTok LIVEコネクターへVfinityを接続する
通常、Vfinityは接続時に専用のTikTok内部ヘルパーを自動起動します。TikFinityなどの既存コネクターや自作のコネクターを既に使用している場合は、それらのWebSocketサーバーからTikTok LIVEイベントを直接読み込むように切り替えることができます。
Vfinityの起動時に自動で立ち上がり、ポートを開放することなく内部で安全に通信します。回線切断時の自動再参加、配信開始の待機、視聴者のロール取得に対応しています。
常駐させている独自のWebSocketサーバーへ接続します。Vfinityはそのサーバーから送られてくるイベントをそのまま読み込み、LIVEへの参加方法やタイミングはコネクター側に委ねられます。
どちらの方式を選んでも、登録したイベント、アラート、投擲、ゴール、ランキングはまったく同様に動作します。Twitch、Kick、YouTubeの設定には影響しません。
外部コネクターに切り替える
TikTokを切断する
TikTokに接続中は接続方式を変更できません。事前に 設定接続 の TikTok LIVE カードで 切断 をクリックします。
カスタムWebSocketを選択する
同じカード内で 詳細なTikTok接続 を開き、接続の種類 を カスタム WebSocket (TikFinity またはその他) に設定します。
アドレスを入力する
コネクターの設定に合わせて WebSocketホスト と WebSocketポート を入力します（デフォルトは localhost と 21213 です）。
接続する
コネクターを起動した状態で、LIVEに接続 をクリックします。Vfinityは ws://host:port へ接続し、ソケットが開いた瞬間にルーム参加済みとしてカウントします。
組み込みヘルパーは外部ポートを開かないため、Vfinity内の処理がコネクターの待機ポートと競合することはありません。
Vfinityからコネクターへ送信されるコマンド
TikTokユーザー名 欄に入力がある場合、Vfinityはソケット接続直後にそのLIVEルームへの参加をコネクターへ要求します：
{ "command": "connect", "username": "yourname" }コネクター側で監視対象の配信をあらかじめ管理している場合は、ユーザー名欄を空欄にしておいて構いません。
ギフトリストを更新 をクリックすると、{"command":"getGifts"} が送信されます。各ギフトの id、name、diamondCount、imageUrl を配列にした data を含む giftList メッセージを返してください。
コネクターからVfinityへ送信するデータ
1つのメッセージにつき1つのJSONオブジェクトを送信し、イベント名とデータを指定します：
{
"event": "gift",
"data": {
"uniqueId": "mika_22",
"nickname": "Mika",
"profilePictureUrl": "https://example.com/mika.jpg",
"giftId": 5655,
"giftName": "Rose",
"diamondCount": 1,
"repeatCount": 5,
"giftType": 1,
"repeatEnd": true
}
}event の代わりに type を使用することも可能です。data キーがないメッセージは、メッセージ全体がデータ本体として解釈されます。TikTokの巨大カウンター仕様に合わせて、数値は数値文字列として渡しても認識されます。
event | Vfinityが読み取るフィールド |
|---|---|
gift | 視聴者情報、giftId、giftName、diamondCount、repeatCount、giftType、repeatEnd、giftPictureUrl |
chat | 視聴者情報、comment |
like | 視聴者情報、likeCount、totalLikeCount |
follow、share | 視聴者情報 |
subscribe | 視聴者情報、subMonth、gifted |
question | 視聴者情報、questionText |
envelope | 視聴者情報、coins、people |
roomUser | viewerCount |
roomStats | followerCount、viewerCount、totalLikeCount、title |
さらに、組み込みブリッジが送信する形式の member、social、emote、superFan、battle、goalUpdate にも対応しています。未定義のイベント名は安全に無視されます。
視聴者情報
すべての視聴者イベントは共通のフィールドから始まります：uniqueId（@ハンドル名）、nickname、および任意で userId と profilePictureUrl です。uniqueId のない視聴者は「unknown」として表示されます。
ロール制限ルールを正しく機能させるには、roles オブジェクトを追加し、isModerator、isSubscriber、isSuperFan、isFollower、isOwner（真偽値）、および followRole、gifterLevel、teamMemberLevel（数値）を含めてください。不明な項目は省略してください（未指定のロールは false ではなく不明として扱われ、そのロールを要求するルールは通過しません）。
ギフトコンボの処理
TikTokでは視聴者が連打している最中、コンボギフト（giftType が 1）が何度も送信されます。連打中の更新には repeatEnd: false を付与し、最後のメッセージにのみ repeatEnd: true を設定して送信してください。Vfinityは最後のメッセージにのみ反応するため、バラ5個のコンボが「バラ5個のギフト1回」として正しく集約されます。giftType や repeatEnd がない場合、届いたギフトメッセージがすべて個別に発動します。
簡易サーバーでテストする
以下のNode.jsスクリプトはコネクターのモックとして動作します。Vfinityからの送信内容を出力し、チャットメッセージとバラのコンボを返送します。
// npm install ws
const { WebSocketServer } = require('ws');
const server = new WebSocketServer({ port: 21213 });
server.on('connection', (socket) => {
socket.on('message', (raw) => console.log('Vfinity says', raw.toString()));
const viewer = { uniqueId: 'testviewer', nickname: 'Test Viewer' };
socket.send(JSON.stringify({ event: 'chat', data: { ...viewer, comment: 'hello' } }));
socket.send(JSON.stringify({
event: 'gift',
data: { ...viewer, giftId: 5655, giftName: 'Rose', diamondCount: 1,
repeatCount: 5, giftType: 1, repeatEnd: true },
}));
});スクリプトを実行し、Vfinityから localhost と 21213 に接続すると、両方のイベントがダッシュボードのイベントログに表示されます。
組み込みブリッジ専用の機能
LIVEに自動で再参加 と LIVEの開始を待機 は、組み込みブリッジの機能です。カスタムコネクターを使用している場合、カード上にその旨が表示され、ローカルAPIの tiktok.connect でもこれらのパラメーターは無視されます。TikTokへの再接続制御はコネクター側で行ってください。
接続が失敗またはタイムアウトする場合は、コネクターが起動しており、指定したホストとポートで正常に待機しているかを確認してください。10秒以内にソケットが開かない場合、Vfinityは接続を中断します。