利用禮物和聊天製作遊戲與獎勵

可以，你的遊戲能夠響應 TikTok 禮物

Social Stream Ninja 擷取事件併傳送到你的頁面，再由你的 JavaScript 決定效果：推進火箭、種植花園、生成敵人或推進共同目標。操作和閾值由你在遊戲中設定。SSN 不能更改平臺禮物價格。

從這裡開始： 試用三個模板，然後選擇規則使用的計量方式：平臺單位、禮物身份或估算 USD.

要觸發聲音、提示、OBS 操作或 webhook，請先使用 Event Flow。需要遊戲介面或自己的遊戲狀態時，可以使用自定義 HTML 頁面。現成遊戲請檢視遊戲庫.

三個小型可編輯模板

每個預覽都有示例按鈕和“最近收到的資料”檢查器。示例是虛構事件，不會購買禮物。預覽模式不會加入直播會話。

金幣火箭: 每 10 枚 TikTok 金幣、100 個 Twitch Bits 或 100 顆 Facebook Stars 可推進一次。餘量按觀眾和平臺分別累計。修改 COST 以設定金額。
共同支援目標: 合併四個平臺估算的 USD 支援來建設月球基地。修改 GOAL_USD ，或將進度顯示替換為傷害、燃料或計時器。
禮物與事件花園: 選定的 TikTok 禮物增加花朵，擷取到的 TikTok 關注增加樹木，免費的 !water 聊天命令增加水量。將 GIFT_ID 設為擷取到的 ID，或者將 GIFT_NAME 設為確切名稱。“Demo flower” 是虛構示例。

開啟 HTML 原始碼並查詢 EDIT THIS RULE 或 EDIT THESE RULES。 receive(data) 函式用於將示例操作替換成你的遊戲邏輯。連線和計數輔助函式位於 starter.js；視覺樣式位於 starter.css.

將模板連線到直播

啟動 SSN 並連線聊天來源，確認聊天和禮物/支援記錄到達 dock。TikTok 設定請參閱連線模式.
開啟模板時不要加 ?demo，使用你的 SSN 會話 ID。如果設定了會話密碼，也需要提供。
先在瀏覽器檢查頁面，再將同一網址加入 OBS 瀏覽器源，例如設定為 1000 × 800。新增 &clean 以隱藏檢查器、連線狀態和主播按鈕。

https://socialstream.ninja/games/templates/coin-rocket.html?session=YOUR_SESSION&password=YOUR_PASSWORD&clean

使用 beta 網站時，請保留 /beta/ 在以下路徑之前： games/。沒有密碼時請省略密碼引數。請勿公開會話連結。

預設連線使用與 SSN 疊加層相同的 iframe 橋接。若要使用託管 WebSocket 的已擷取聊天通道，請在 SSN 啟用 透過伺服器將擴充功能中的訊息傳送到停駐面板 設定並附加 &server2。請參閱 WebSocket 指南瞭解本地設定；這些模板也接受 &server2&localserver 和 &localserverport=3000. localserver 本身不會啟用通道。舊的 server 使用不同通道，並可能需要 dock 向該通道釋出資料。

製作自己的副本

下載 beta 原始碼 ZIP 並解壓。編輯以下目錄中的檔案： games/templates/，並保留目錄結構：模板還需要載入 js/local-server-url.js，支援目標還會載入 currency.js 從程式碼庫根目錄載入。

透過本地網頁伺服器提供解壓後的目錄。如果已安裝 Python，請在該目錄執行：

python -m http.server 8080 --bind 127.0.0.1

然後使用 http://127.0.0.1:8080/games/templates/coin-rocket.html?session=YOUR_SESSION 在瀏覽器或 OBS 中開啟。在其他位置託管時保持相同的相對路徑，無需構建。

如何選擇操作所需的金幣數量？

先決定要衡量什麼，再選擇數值：

規則	閱讀	範例
平臺原生單位	TikTok `meta.coinsPerGift × meta.tiktokGiftCount` （若有提供），或明確的 `hasDonation` 標籤，例如 `10 coins`, `100 bits`，或 `100 Stars`.	每 10 枚金幣推進一次。
指定禮物	TikTok `meta.giftId` 或 `meta.giftName`及其數量。	每份匹配禮物增加一朵花，與估算的 USD 價值無關。
可比較的支援價值	`getDonationValueUSD(data)` 來自 `currency.js`.	每估算 1 美元增加 10 點燃料；25 美元完成目標。
免費操作或會員操作	來源實際提供的 `event`或聊天命令。	關注長出一棵樹；新訂閱播放動畫。

確定金額採用 精確匹配 (coins === 10）、 每個事件的最低值 (coins >= 10），或 累計餘額。火箭使用累計餘額：25 枚金幣產生兩次推進，並剩餘 5 枚。僅匹配“恰好 10”的規則會忽略 25 枚金幣。如果每個事件只能從多個檔位中觸發一個操作，請先檢查最高閾值，避免同時觸發所有較低檔位。

在 TikTok 上，觀眾購買金幣並用來贈送禮物；禮物會顯示金幣價格。選擇自己 LIVE 中可用的禮物，釋出規則前檢查擷取資料。禮物名稱、禮物數量、金幣和鑽石是不同計量方式。不要將 USD 估值反算成“精確金幣數”，也不要把鑽石數當成金幣數。 TikTok 關於金幣和禮物的說明.

若擷取只提供禮物名稱/數量或鑽石標籤，金幣模板會跳過該事件，除非含有明確的金幣後設資料。可改用禮物身份規則或估算 USD 模板。金幣後設資料也可能來自 SSN 禮物對映；需要準確價格時，請與當前 LIVE 禮物列表核對。禮物目錄和擷取方式各異，沒有保證每條 TikTok 訊息都包含的通用金幣欄位。

各平臺傳送什麼

type 標識來源； event 在存在時標識操作。是否可用取決於擷取模式、設定和平臺開放的資料。示例描述的是 SSN 當前程式碼路徑，不保證每個賬號都提供所有事件。

平台	支援與事件資料	注意區分
TikTok	`type: "tiktok"`, `event: "gift"`。贊助擷取可能提供 `hasDonation` 和 `donoValue`。禮物後設資料可能包括 ID、名稱、數量、每份禮物的金幣數或鑽石數，以及連送標識。	金幣用於購買禮物；鑽石是創作者獎勵。SSApp 的 WebSocket 擷取先結算連送再轉發；瀏覽器擷取可能傳送累計更新。關閉 TikTok 贊助擷取後，禮物事件可能不含金額欄位。
Twitch	Cheers 使用 Bits，例如 `hasDonation: "100 bits"`。API 擷取可能使用 `event: "cheer"` 和 `donoValue: 1`；頁面聊天擷取可能沒有事件標記。	訂閱、贈送訂閱、突襲和頻道積分是不同操作。普通訊息上的訂閱者徽章不表示新訂閱。直接 Cheers 與 Twitch 擴充套件中使用的 Bits 屬於不同整合。
Facebook	可見的 Live Chat Stars 記錄會提供例如 `hasDonation: "100 Stars"` 和 `donoValue: 1`，不含 `event` 標記。	評論 API 不會從聊天文字推斷 Stars。DOM 擷取需要可見的 Stars 記錄；普通評論和互動不能證明付款金額。
YouTube	`superchat` 和 `supersticker` 將原始貨幣金額放在 `hasDonation`。禮物使用 `jeweldonation` 帶有 `N Jewels`，或 `1 YouTube Gift` （金額隱藏時）。	觀眾花費 Jewels 購買禮物，創作者獲得 Rubies。會員和贈送會員是獨立事件，不是 Jewels。Super Thanks 是另一個產品，並不保證產生直播聊天贊助事件。

平臺參考資料： TikTok 鑽石; Twitch Bits 與訂閱; Meta 的 Stars 概述; YouTube Super Chat 與 Super Stickers; YouTube Jewels、Gifts 與 Rubies。術語核對日期為 2026 年 9 月 29 日；資格和可用性請以平臺當前說明為準。

其他來源也可能報告小費、禮物、會員或購買。請檢查事件參考，然後才加入模板的 isSupport 過濾器。商品銷售或贈送訂閱不自動等於小費。例如 YouTube 區分禮物購買與接收者領取通知，同時計入會讓同一禮物獲得兩次獎勵。

正確使用 donoValue 和 currency.js

hasDonation 是原始顯示標籤，例如 €5.00 或 100 bits. donoValue 是來源可選提供的數字 USD 金額。根據標籤估算前，應優先採用有效覆蓋值，包括零。保留原始標籤用於顯示。

<script src="../../currency.js"></script>
<script>
// From games/templates/: use the existing helper, including its zero handling.
var usd = getDonationValueUSD(data);
// Use usd for your rule; display data.hasDonation for the original amount/unit.
</script>

現有換算行為： SSN 當前估算一枚 TikTok 金幣為 0.01 美元、一顆 TikTok 鑽石為 0.005 美元、一個 Twitch Bit 或 Facebook Star 為 0.01 美元、一顆 YouTube Jewel 為 0.005 美元。無價格的 TikTok 禮物預設每份按一枚金幣估算；沒有 Jewel 數量的 YouTube Gift 使用獨立的 0.01 美元佔位估值。法幣換算也使用內部近似匯率，並非實時匯率服務。

這些只是 SSN 用於比較的數值，並不統一代表觀眾花費、創作者淨收入或可提現餘額。不同擷取方式可能產生不同估值。尤其是未知 TikTok 禮物回退為一枚金幣，並不能證明它實際只需一枚金幣。

不要使用 donoValue || convertToUSD(...)：這會丟棄有意設定的零值。請勿從以下欄位提取數字來判斷付款： chatmessage 來檢測付款，也不要強制要求 event === "donation"：Facebook Stars 和部分 Cheers 沒有事件標記。支援目標模板先篩選支援型別，再呼叫共用換算函式。

來源： currency.js 以及資料格式參考。禮物後設資料是可選的；示例不會虛構擷取中缺少的欄位。

同一連送只計一次

TikTok 可能為同一次連送依次報告累計數量 1、2、3。這是三份禮物，不是六份。累加操作應儲存已收到的最大數量或金額，只應用增加部分。總量相同的完成通知不再增加數值。

// All three events refer to the same streak:
// incoming total: 1, 2, 3, 3
// added to game:  1, 1, 1, 0
var newCoins = RewardStarter.increment(data, RewardStarter.coins(data), 'coins');

輔助函式優先採用可用的 TikTok 原生群組/傳送者/禮物 ID，其次使用 meta.tiktokGiftStreakId 或訊息 ID。普通訊息 ID 也能阻止重複投遞。它不會等待 repeatEnd ，因為瀏覽器擷取可能從不提供該欄位。如果設計要求在連送結束後只觸發一次，需要基於實際連線提供的欄位另寫完成規則。

這些教學模板最多在記憶體中儲存 2,000 個標識。重置或重新整理會清除記憶和遊戲進度。沒有穩定 ID 的訊息無法可靠去重；同一頻道的第二條擷取通道也可能使用不同 ID。請先使用單一擷取通道。火箭按平臺和使用者 ID 區分餘額，缺少 ID 時改用顯示名稱，因此同名使用者可能共用餘額。需要長期儲存的遊戲應先加入狀態儲存和重播處理，再依賴付費獎勵在重啟後保留。

無需自定義遊戲的獎勵

在 Event Flow，使用 比較屬性 帶有 donoValue, 大於或等於以及 USD 閾值，然後連線聲音、動畫或 OBS 控制等操作。比較時優先採用來源提供的有效值，必要時使用現有的貨幣換算。

要匹配指定 TikTok 禮物，請比較 meta.giftId 或 meta.giftName，並將流程限定為 TikTok 禮物事件。對以下欄位的數值比較： hasDonation 也會轉換為 USD，並非直接比較金幣。金幣專用規則應採用原生後設資料或自定義程式碼。

按每條訊息判斷閾值，與累計餘額或連送計數不同。不要假定 Event Flow 閾值會自動實現模板的累計和去重邏輯。請使用狀態節點處理需要狀態的流程，或將這些邏輯保留在遊戲中。

連線付費操作前先測試

使用示例按鈕測試。1 → 2 → 3 連送應只增加三份禮物的價值；顯式零值示例不應增加 USD；未知價格不應增加精確金幣數。
連線真實來源並檢查實際擷取的資料。確認禮物名稱/ID、金額/單位、數量，以及規則需要的事件。示例只能驗證規則，不能證明平臺直播採整合功。
在 OBS 場景中驗證重複事件、重連和重新整理。如果需要保留記憶體中的當前進度，請避免關閉或重新整理該瀏覽器源。

無人值守或 AFK 遊戲需要 SSN、來源擷取和遊戲頁面持續執行。電腦休眠、登入過期或斷線會中斷操作；這些模板不會補發遺漏事件，也不處理退款。自動響應不代表允許透過無人值守直播獲利；請核對平臺對該直播形式的現行 LIVE 和變現規則。

如果收不到資料，先檢查 SSN dock，再檢查會話/密碼和傳輸設定。如果聊天能到達但禮物不匹配，請檢查資料和贊助/事件過濾器。關注和訂閱事件的可用性因來源而異；請參閱事件參考。更多連線說明請參閱自定義疊加層.