從零製作一個 Combos TikTok 互動遊戲

這篇教學帶你做出 Gift Arena（禮物競技場）：主播攻擊對手，觀眾透過禮物為主播充能、回血，或直接攻擊對手。你會取得完整專案、本機禮物測試台、Combos 發佈步驟，以及真實 TikTok 接入所需的登記清單。適用 Combos SDK 1.1.0。

試玩範例 · 下載完整專案

目前沒有可用的真實 TikTok 互動開通方式。你現在可以完成本機開發、禮物模擬和 Combos 發佈；發佈作品不會自動取得真實禮物。後面的接入材料與真實 LIVE 驗收用於未來平台開放接入後的準備，不是現在就能申請完成的流程。

1. 先宣告禮物，再設計遊戲效果

先確定玩法，不急著連線。範例中，主播初始生命 70、能量 40，對手生命 100。每次攻擊消耗 10 能量、造成 10 傷害；對手存活時反擊 8 點。觀眾使用三種效果協助主播：

// rules.js — this game's contract
export const GIFT_CATALOG = Object.freeze({
  gift_battery: { target: 'energy', perCount: 20, max: 100 },
  gift_heal: { target: 'hp', perCount: 15, max: 100 },
  gift_flash: { target: 'bossHp', perCount: -10, max: 100 },
});

這份宣告放在你自己的遊戲程式碼中。它不是 SDK 的註冊呼叫，也不是 TikTok 禮物目錄。電池、治療、閃擊只是範例的效果名稱，不代表真實 TikTok 禮物的名稱或 ID；不能假定玫瑰或某個價格會自動對應其中一種效果。

接入前還要訂清楚邊界：本範例只接受 1–1000 的整數數量，生命和能量上限 100，對手生命下限 0；禮物不消耗玩家回合。達到上限時，即使數值沒有繼續增加，也視為成功。勝利或失敗後的新指令回傳 false，開始新的一局才繼續接收。這些是範例玩法規則，不是平台限制。自己的遊戲也要明確設計連發疊加、冷卻、跨局處理與高成本效果，並把同一套規則交給設定方。

2. 了解平台和遊戲各自負責什麼

觀眾送禮 → TikTok 禮物對應設定 → Combos → SDK 的 onCommand → 遊戲效果 → 布林執行結果 → Combos → TikTok 回執。

例如，一次已設定的互動產生 instruction: "gift_flash", count: "3"，遊戲就扣除對手 30 點生命。count 是對應後的指令數量，不是金幣價格，也不一定等於送禮件數。連擊如何換算，必須在登記時確認。遊戲不用自行讀取 launchData、簽署 TikTok 請求、另建 WebSocket 或實作 webhook。

3. 實作遊戲收到的協定

type TTLiveCommand = {
  messageId: string;
  instruction: string;
  count: string;
  timestamp: string;
};

目前公開指令沒有觀眾 ID、暱稱或真實禮物 ID，不能用不存在的欄位直接製作送禮觀眾排行榜。

效果確認儲存後回傳 true；確定拒絕時回傳 false；結果無法確認時拋出例外，例如儲存失敗。未知結果不會被確認，之後可能重新投遞。不能把所有例外改成成功，也不能在效果可能部分生效時直接回報失敗。

SDK 會在目前頁面內重送待確認的結果；遊戲還要處理重新整理後的重複訊息。範例把遊戲狀態和訊息執行結果放在同一筆 IndexedDB 交易中儲存，提交後才回傳布林值。重複訊息讀取原結果，不再套用效果；新的一局保留回執。LIVE 存檔按 Combos 帳號與遊戲隔離，也與演練存檔分開。

閱讀連線狀態

getTTLiveClient() 在每個遊戲頁面中回傳同一個用戶端。getLiveStatus() 查詢狀態；onStatusChange() 立即通知目前狀態，再通知變更。狀態包含 state、reason、action 和 confirmedAtMs；最後一項是最近確認啟動或心跳的毫秒時間，0 表示未知。

• connecting：正在連線。connected：互動工作階段已確認。
• recovering：由 SDK 自動重新連線。unknown：暫時無法確認，不等於主播結束直播。
• ended：這次遊戲互動結束。依 action 的 wait、none 或 relaunch_game 處理。需要 relaunch_game 時，讓主播從 LIVE Studio 重新開啟這個遊戲，不要因連線問題要求重啟直播。

4. 執行完整 demo

準備與啟動

下載並解壓縮 ZIP。準備較新的瀏覽器與 Python 3 作為本機靜態伺服器，不需要 Node 或 npm。保留 tiktok-arena 資料夾結構：

cd tiktok-arena
python3 -m http.server 8080 --bind 127.0.0.1

開啟 http://127.0.0.1:8080/，點擊開始演練。不要直接雙擊 index.html，JavaScript 模組需要透過 HTTP 載入。線上範例則不必安裝工具。遊戲支援與本站相同的十種語言。

三個可照著重現的 demo

前兩行測試各自開始前先點「新的一局」；第三行接著第二行做，不重置。初始生命 70、能量 40、對手生命 100。每次點禮物建立新訊息；重複上一則訊息沿用原 ID。

數量 0、1.5、1001、9007199254740993 都應無效果且回傳 false。新的一局用閃擊 ×10 獲勝後，再送新禮物會被拒絕，直到下一局。也用攻擊與充能體驗一般戰鬥。最近一次投遞顯示輸入、結果及最終數值。這些都是本機合成指令，不會購買禮物或向 TikTok 傳送 ACK。

5. 在 Combos 裡連接同一個遊戲

發佈時保留 connection.js 與 game.js。宿主注入 window.combos，不需要額外的 npm SDK，也不要重複載入 SDK 指令碼。連接 Combos LIVE 已實作：

1. 呼叫 init()，確認 getTTLiveSession 能力與用戶端 getter。這個能力名稱不是直接呼叫的公開方法。
2. 從按鈕操作發起 checkSession()，必要時 login()。取消就停止；成功後繼續原操作。
3. 以 getUserInfo() 隔離本機存檔。ID 不是憑據或伺服器授權證明。
4. 訂閱狀態，再用演練的同一個處理函式呼叫 getTTLiveClient().connect({ onCommand })。
5. 重試期間仍可中斷 / 取消；取消或離開頁面時取消訂閱並呼叫 disconnect()。

以下核心處理已包含於下載專案，完整版還會更新介面。store.update() 是 storage.js 的交易方法，不是 SDK API：

import { executeCommand } from './rules.js';
 
// `store` is the account/game-scoped store opened by prepareStore().
function commandHandler(store) {
  return async (command) => {
    const { result } = await store.update((saved) =>
      executeCommand(saved, command),
    );
    return result; // State + receipt committed; no catch-and-return-false.
  };
}

connect() 重試時可能持續等待；Promise 成功不代表真實禮物已生效。LIVE 模式會隱藏模擬按鈕，必須在已登記的工作階段核對效果與執行結果。

6. 發佈到 Combos

安裝官方 Combos CLI 。在 demo 點擊儲存 PNG 封面，把 cover.png 放在 tiktok-arena 資料夾旁，於父資料夾執行：

combos --version
combos account login
combos post create --dir ./tiktok-arena --title 'Gift Arena' --cover ./cover.png --platform pc --screen-orientation landscape --allow-recommend=false
combos post get

在瀏覽器以預定發佈的帳號完成登入。開啟回傳的分享連結，在 Combos 播放器內測試。保留產生的 combos.json 綁定檔，在同一目錄更新同一作品：

combos post update --dir ./tiktok-arena --platform pc

這是 PC 橫向靜態遊戲。上傳資料夾頂層必須有 index.html 與所有相對路徑資源。發佈不會開通 TT。普通分享連結可演練，但沒有已登記的 LIVE Studio 啟動脈絡，就無法自行建立真實互動工作階段。詳見 H5 接入。

7. 準備未來接入所需的材料

目前沒有可用的真實 TikTok 互動開通入口，也沒有已確認的申請流程。遊戲與帳號登記、真實禮物對應方式需要等待平台提供接入說明；SDK 和 CLI 都不提供公開的自助註冊 API。可以先準備以下材料，供未來開放接入時使用。這是準備清單，不是正在開放的申請流程：

測試前，請接入方確認確切的已登記啟動入口、遊戲與帳號資格、禮物對應已生效。真實 ID、名稱、價格來自已設定的目錄。若約定閃擊 ×3，遊戲應收到：

{
  "instruction": "gift_flash",
  "count": "3"
}

不要把 TikTok 密鑰、CAS token 或手工組合的 launchData 放進遊戲，這些由平台處理。登記未完成時，成果是已發佈的 Combos 遊戲與可用模擬器；真實 TikTok 驗收仍待完成。

8. 開通後的真實 LIVE 驗收

只有在平台提供開通方式，並確認遊戲入口、可用帳號及禮物對應關係後，才能執行以下真實驗收。目前可以先完成前面的本機模擬與 Combos 發佈檢查；這些檢查不能代替真實 LIVE 驗收。

1. 使用獲准帳號，從 TikTok LIVE Studio 開啟已登記入口；在遊戲連接 LIVE，確認 connected。
2. 在測試參與者知情同意下觸發一次已設定的測試互動。記錄 messageId、指令 / 數量、前後數值、回傳結果，請接入方確認收到對應 ACK。不記錄憑據或觀眾個人資料。
3. 測試約定的連發數量，核對數量 × 效果、上限、重複投遞不重複生效，與本機 demo 比對。
4. 短暫斷網再恢復，同一已執行指令不能再次生效。在宿主支援的流程內重新整理，確認狀態與回執恢復；如要求重新啟動，依提示處理。
5. 結束互動後確認 ended / relaunch_game，測試連線中取消與離開遊戲，舊訊息不得再產生額外效果。

瀏覽器存檔只支援同一瀏覽器、來源、帳號和遊戲，不提供跨裝置恢復或可信經濟系統。LIVE 期間不要清除資料。到 10,000 筆回執時，範例停止新指令，不會淘汰舊結果。持久獎勵或正式規模需求，應在自己的可信後端同時提交效果與回執，並按已確認結果訂定保留策略。

問題排查

SDK 參考 · 帳號與多語言