啟動遊戲

啟動呼叫的運營商側沒有客戶端 SDK——你在自己的技術棧裡、於伺服端自行對請求簽名即可。HMAC 構造與獨立的 signRequest 範例，見簽名與身份驗證。

簽名並呼叫啟動介面

下面的 signRequest 就是簽名與身份驗證裡記錄的那個函式。

const path = '/v1/operator/games/launch'
const body = JSON.stringify({
  playerRef,          // 你內部的玩家標識
  gameId,              // 要啟動的遊戲
  currency,             // 例如 "USD"
  mode: 'REAL',        // 'REAL' | 'DEMO'
  language: 'zh-TW',  // 選填——BCP-47 語言標籤，例如 "en"、"zh-TW"
  lobbyUrl: 'https://your-site.example/lobby', // 選填——見下方「返回大廳」
})

const headers = signRequest('POST', path, operatorSecret, body, operatorId)

const res = await fetch(`${platformUrl}${path}`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body,
})
if (!res.ok) {
  // 400/401/403/429 —— 見運營商 API 參考的錯誤列表
  throw new Error(`launch failed: ${res.status} ${await res.text()}`)
}
const { launchUrl, sessionToken } = await res.json()
// launchUrl：遊戲的 URL，已經附帶了 session token —— 直接嵌入 iframe 即可。
// sessionToken：同時也單獨返回；廠商的遊戲客戶端會在自己的錢包呼叫裡帶上它
//   （你自己一般用不到）。

每個欄位都和平台期望的請求體一一對應——精確結構與每一種錯誤情況（包含風控攔截返回的 403），見運營商 API 參考。

選擇幣別

currency 是必填的，且必須落在目標遊戲廠商已設定的支援幣別集合內——這個集合由平台團隊為每個廠商設定一次，該廠商名下所有遊戲共用（沒有按遊戲個別設定幣別）。你可以透過 GameSummary 上的 currencies 欄位查看（見下方「獲取遊戲目錄」），或是直接在你租戶的自助入口網站的「遊戲目錄」頁面裡查看。要求集合之外的幣別會讓啟動呼叫以 400 失敗。

指定語言

language 是選填的——不傳的話遊戲會回退到自己的預設語言（通常是 "en"）。如果要傳，它必須落在目標遊戲廠商已設定的支援語言集合內。你可以用和幣別相同的兩種方式查看：透過 GameSummary 上的 supportedLanguages 欄位，或是你租戶的自助入口網站「遊戲目錄」頁面。要求集合之外的語言會讓啟動呼叫以 400 失敗。

返回大廳

lobbyUrl 是選填的。傳入後，遊戲內的「返回大廳」控制項會直接把整個最上層視窗導向該網址——一次單純的重定向，即使你把遊戲嵌在一個沒有監聽橋接訊息的純 iframe 裡也一樣有效。它必須是絕對的 http 或 https 網址；其他任何值都會讓啟動呼叫以 400 失敗。

如果不傳 lobbyUrl，遊戲會回退到既有行為：透過 EXIT_GAME 橋接訊息請求你的嵌入 shell 把它關閉（見 Shell 端橋接）——遊戲自己無法關閉所在的 iframe，所以由你的 shell 決定「返回」要去哪裡。

`REAL` 與 `DEMO` 模式

REAL（預設）—— 針對你真實的運營商錢包整合，啟動一個真實的 session——這個整合需要實現什麼，見實作錢包回調。同時也受風控啟動檢查（黑名單／自我排除）閘控——被攔截的玩家的啟動呼叫會以 403 失敗。
DEMO —— 啟動一個由臨時虛擬餘額支撐的 session，而不是真實的錢包 session；你的錢包回調 API 完全不會被呼叫。適合在不觸碰真實資金的情況下向玩家（或你自己）演示遊戲，或是在你的錢包後端就緒之前端到端驗證你的 shell 整合——見測試。和 REAL 不同，DEMO 啟動會跳過目錄可見性檢查（所以你可以在平台團隊還沒把某個遊戲設為對你的租戶可見之前先行演示），但風控檢查仍然適用——自我排除的玩家在 DEMO 模式下同樣無法遊玩。

獲取遊戲目錄

// GET /v1/operator/games，簽名方式相同（空請求體）

返回你的運營商租戶可見的遊戲列表——精確結構見參考文件裡的 GameSummary（遊戲 ID、展示名稱、廠商、支援的幣別、支援的語言、啟動基礎網址，以及該遊戲若支援回合回放時的回放基礎網址）。

嵌入遊戲

拿到 launchUrl 後，把它載入到頁面的 iframe 裡：

html

<iframe src="{launchUrl}" allow="..."></iframe>

然後掛上 shell 端的橋接監聽器，接收遊戲的生命週期事件——見 Shell 端橋接。

啟動遊戲 ​

簽名並呼叫啟動介面 ​

選擇幣別 ​

指定語言 ​

返回大廳 ​

REAL 與 DEMO 模式 ​

獲取遊戲目錄 ​

嵌入遊戲 ​