外掛規格 0.1
每個外掛有一份 s4n-plugin.json。api 目前只接受 0.1。怎麼寫、怎麼測,見 外掛開發 與 外掛 SDK。可編譯的範例是 plugins/example-thanks。
| 欄位 | 說明 |
|---|---|
id |
小寫,至少含一個 . 或 -。官方外掛使用 official.* |
name |
顯示名稱 |
version |
外掛自己的版本 |
api |
"0.1" |
kind |
overlay、dashboard、connector、payment、processor,可多個 |
permissions |
見下方 |
entry |
overlay、dashboard、worker 至少一個路徑 |
settingsSchema |
JSON Schema 物件。密文欄位加 x-s4n-secret: true |
kind 含 payment 時,必須請求 payments.provider,並且提供 entry.worker。有密文欄位就必須請求 secrets。
字串欄位可以加 x-s4n-multiline: true,儀表板會用多行輸入。欄位可以有 default,但密文欄位不行,否則預設值會被送回瀏覽器。default 只在尚未儲存時使用。
聊天來源與聊天疊層
Section titled “聊天來源與聊天疊層”v1 把聊天拆成兩種外掛:
| 角色 | 這次的 id | kind |
做什麼 |
|---|---|---|---|
| 來源 | official.twitch-chat |
connector |
連到平台,送出正規化事件 |
| 顯示 | official.chat-overlay |
overlay |
訂閱那些事件並畫在 OBS |
來源實作 @s4n/plugin-sdk 的 ChatSource:start、stop、applySettings,並透過 ChatSourceHost 發送 s4n.chat.message、s4n.chat.delete、s4n.chat.clear。顯示外掛不匯入任何來源。下一個版本的 YouTube 來源只要實作同一個 ChatSource 並註冊進官方目錄,聊天疊層不用改。
Twitch 來源需要 events.emit、secrets 與 network。頻道名稱是一般設定。Client ID 與 Client Secret 是密文,選填。顯示外掛只要 events.subscribe、overlay.slot、dashboard.settings,自己不連外網。
| 權限 | 誰能用 | 做什麼 |
|---|---|---|
events.subscribe |
所有外掛 | 透過 SDK 訂閱事件 |
events.emit |
所有外掛 | 透過 SDK 發送事件,但不能偽造核心付款事件 |
overlay.slot |
所有外掛 | 宣告疊層版位。要排進共用畫布,清單還要有 overlaySlot 矩形 |
dashboard.settings |
所有外掛 | 儀表板上的設定 |
tts.speak |
所有外掛 | 舊的權限名稱。沒有語音外掛 |
payments.read |
所有外掛 | 唯讀付款資料。這次沒有讀取 API |
payments.provider |
僅官方 | 註冊付款提供者、建立付款、驗證回呼。不能寫帳 |
secrets |
僅官方 | 設定裡可以有密文欄位 |
network |
僅官方 | 對外連線。綠界與歐付寶用它向廠商查單 |
社群外掛的預設是疊層與儀表板設定:events.subscribe、overlay.slot、dashboard.settings。
外掛只能透過 @s4n/plugin-sdk 的 createPluginBus 訂閱與發送。
這些事件會寫進 PostgreSQL 的事件紀錄。每一則有單調的 sequence 與自己的 id。送達是至少一次:斷線的客戶端帶著最後的序號重連,伺服器依序補上,客戶端用 id 排除重複。外掛的 emit 不能假設對方只會收到一次。保留期限、重播上限與升級見 事件紀錄。
核心保留事件,外掛不能發送:
s4n.donation.createds4n.donation.succeededs4n.donation.faileds4n.donation.test(工作台的測試贊助,不寫入帳本)
其餘事件:
s4n.chat.messages4n.chat.deletes4n.chat.clears4n.goal.updateds4n.tts.request(舊事件。沒有外掛會朗讀,疊層也不接收)s4n.media.now_playing
s4n.chat.message 是與平台無關的一則訊息:platform(twitch、youtube,或核心混入的 s4n)、channel、userId、login、displayName、color、badges、fragments(text 或 emote)、text、timestamp、messageId,以及 flags(isMod、isBroadcaster、isSubscriber、isVip)。混入的贊助才帶 donation。s4n.chat.delete 拿掉一則(Twitch 的 CLEARMSG)。s4n.chat.clear 是封鎖、超時或清空頻道(CLEARCHAT);有 userId 時只拿掉那個人,有 durationSeconds 時是超時。
贊助人名稱、留言、聊天內容與點播者名稱都是不受信任文字。跑馬燈與目標名稱也只當純文字。金額以最小貨幣單位的整數表示。這個骨架把 TWD 的 1 單位訂為新台幣 1 元,因為綠界與歐付寶的金額是整數元。
在 settingsSchema.properties 的欄位上設 x-s4n-secret: true。核心加密後存進 EncryptedPluginSetting。儀表板的外掛頁只看得到欄位名稱與是否已設定。沒有這個旗標的欄位是一般設定,出現在 /plugins/:id/settings。@s4n/plugin-sdk 的 secretFieldKeys 與 publicFieldKeys 依這個旗標分開,沒有第二個旗標。
範例見 範例外掛,完整檔案在 plugins/ecpay/s4n-plugin.json 與 plugins/opay/s4n-plugin.json。