環境與基礎網址

一次接入牽涉兩組彼此獨立的網址——一組是你要指向平台的，另外兩到三組是平台要指向你的。因為分別在接入的兩側配置，很容易搞混。

目前的環境

環境	平台基礎網址	行為採集端點
預備環境（Staging）	https://api.staging.stakegate.io	https://behavior.staging.stakegate.io/v1/client/behavior
正式環境（Production）	即將推出	即將推出

預備環境現在就可以接入——把 ProviderClientOptions.baseUrl 和 BehaviorReporterOptions.ingestUrl 指向上面的值即可開始測試。正式環境 上線後會用同樣的名稱、去掉 .staging. 這一段（例如 api.stakegate.io） ——到時候會回來更新這個表格。

想先看看完整的接入效果？https://demo.staging.stakegate.io 跑的是本平台 自己的參考遊戲工作室，接的就是上面這個預備環境——用瀏覽器打開即可走一遍 啟動 → 旋轉 → 結算的完整流程，用的正是本文件說明的這些 API。

平台的基礎網址（你 → 平台）

你的對接窗口會提供平台的基礎網址——這就是你要傳給 ProviderClientOptions.baseUrl 的值，不帶結尾斜槓。ProviderClient 發出的每一個簽名呼叫都是 ${baseUrl}${path}（例如 https://platform.example.com/v1/wallet/transaction）。

如果你的對接窗口營運不止一個平台部署（例如你正式上線前用來測試的預備環境，和真實玩家所在的正式環境是分開的），每個部署都有自己的 baseUrl以及自己的一組租戶 ID/金鑰。請把每個部署當成完全獨立的接入來對待——為某個部署核發的金鑰在另一個部署上不能用，兩者之間也沒有共用的身份。針對你目前所處的接入階段應該指向哪個 baseUrl，請跟你的對接窗口確認。

行為採集端點

第三組、獨立的網址：你的對接窗口還會提供一個行為採集端點，你要把它傳給 BehaviorReporterOptions.ingestUrl（@moosehq/game-client-sdk/behavior-reporter）。這個端點和本頁其他網址有兩點不同：

• 它是由遊戲客戶端的瀏覽器直接呼叫的——不經過你的伺服器。你自己跑的任何服務都不會轉發這個呼叫。
• 它用玩家的session token 鑑權，以 X-Session-Token 標頭傳送，而不是廠商 HMAC 簽名——瀏覽器沒辦法保存你的金鑰，所以這個端點不用簽名。CORS 允許任何來源，因為遊戲會跑在平台事先不知道的各種網域上。

如果你的對接窗口營運不止一個平台部署，每個部署都有自己的 ingestUrl，和 baseUrl 一樣——不要假設正式環境和預備環境是同一台主機、只是路徑不同。

你要向平台註冊的網址（平台 → 你）

平台需要知道該把玩家帶去哪裡，以及該把簽名呼叫送回哪裡給你。這些是跟你的對接窗口一起配置的，前兩項按遊戲配置，第三項按廠商租戶配置：

設定項	用途	是否必要
launchBaseUrl	你遊戲的入口頁面。平台會拼上 ?session=<token>，運營商再把結果載入 iframe。見取得 session token。	是——每個遊戲都需要
replayBaseUrl	你的單局回放頁面。平台會拼上 ?replay=<token>。見單局回放。	只有你支援單局回放時才需要。若某遊戲沒有設定 replayBaseUrl，運營商請求回放連結會在其自己那一側收到 400。
回呼 baseUrl	平台把簽名呼叫送回你的地方：session 撤銷和免費旋轉發放/查詢/取消。見平台 → 廠商回呼。	只有你實作這些回呼時才需要

時鐘同步

無論哪個方向，每一個簽名呼叫都會被檢查是否落在允許的時鐘偏差範圍內。請保持任何負責簽名或驗證請求的伺服器時鐘透過 NTP 同步。確切的容許範圍，以及時鐘偏移如何表現為無法解釋的 401，見簽名與鑑權。

限流

請求按廠商租戶限流。超出額度會返回 429，附帶 Retry-After 響應頭——完整響應結構，以及 ProviderClient 如何呈現它，見錯誤碼與重試。如果你的接入預期流量需要比預設值更高的限額，請在上線前跟你的對接窗口提出，而不是等正式環境開始出現 429 之後才反映。