Steamworks 文獻庫
遊戲通知

概覽

Steam 遊戲通知是一套發送離線通知給使用者的系統,適用西洋棋這類非同步的多人遊戲。

此 API 的目的在於通知使用者有遊戲階段需要他們採取行動,方能繼續。 在西洋棋的範例中,遊戲階段狀態會在每個玩家下完一步後受到更新。 Steam 接著便會根據遊戲階段通知使用者現在輪到您了,遊戲正在等待您的回應。

遊戲的責任

大部分的離線遊戲都會管理遊戲階段、更新每位使用者的狀態,同時根據這些狀態發送通知好讓特定使用者知曉他們需要啟動遊戲、採取行動。 一旦啟動並進行遊戲動作,遊戲便應該為所有與該遊戲階段相關的玩家再次更新遊戲階段以反應最新狀態。

Steam 會管理什麼

Steam 會根據遊戲提供的狀態以及使用者為該遊戲特別選擇的設定,在遊戲階段中負責通知使用者。 當遊戲需要使用者採取行動時,Steam 用戶端與網頁瀏覽器中將會顯示通知。

需求

遊戲通知 API 是由 Web API 方法的形式提供,並需要有效的發行商金鑰。 Web API 方法呼叫必須從遊戲伺服器發起,非遊戲用戶端,且發行商金鑰不得與任何遊戲用戶端程式碼一起發送。

驗證與第三方帳戶

想呼叫遊戲通知 API,您首先必須為登入您的遊戲的 Steam 使用者建立身分。 建立方式有以下兩種,擇一即可:用戶端的遊戲可產生驗證階段票證,送回您的伺服器,或網頁遊戲可利用 OpenID 獲取使用者的驗證資料。 詳細作法請見將第三方帳戶連結至 Steam 帳戶。 有一點非常重要,那就是從遊戲用戶端直接發送至您的遊戲伺服器的訊息有遭竄改的可能,請勿信任這些訊息提出的使用者身分。
如果您的遊戲使用第三方帳戶,請同樣採用上述步驟,但記得將使用者的 Steam ID 儲存在您的系統的快取中。

遊戲通知 API

技術總覽

遊戲通知 API 是基於 Web API 架構寫成的,可透過 Web API 使用,每個方法都需要傳入下列 4 個參數:
  • appid(您的遊戲的應用程式 ID)
  • format(結果的格式, 我們推薦傳回值採用 json 格式)
  • input_json(方法需要的所有參數的 json 編碼)
  • key(每個呼叫皆須傳入的發行商金鑰)
如成功,API 將傳回 HTTP 狀態碼 200,並於狀況允許時附上詳細的訊息內文。

常數值

UserState

字串值將為下列其一:
  • waiting - 使用者正在等待其他玩家回應,沒有阻擋任何行動。 因為該使用者在等某個事件發生,因此不會接到通知。
  • ready - 使用者已準備就緒,遊戲階段正在等待該使用者的回應。 在階段清除前,該使用者將接到通知。
  • done - 對該使用者來說,這場遊戲已結束。 使用者將接到遊戲已結束的通知,無需採取任何行動。

資料結構(JSON)

所有資料結構皆以 JSON 格式呈現。

Variable

{ "key": "key_name", // 字串 "value": "value_of_key" // 字串 }

LocalizedText

{ "token": "value", // 對應在地化索引碼的字串 "variables": [ // 「Variable」陣列(如上) ] }

UserStatus

{ "steamid": "76561197960265729", // uint64 "state": // 「UserState」的常數之一(如上所述) "title": // 「LocalizedText」物件(如上所述) "message": // 「LocalizedText」物件(如上所述) }

Session

{ "sessionid": "1", // uint64 "title": // 「LocalizedText」物件(如上所述) "time_created": "100000", // Unix 時間(又稱 Epoch 時間,從 1970 年 1 月 1 日算起) "time_updated": "200000", // Unix 時間(又稱 Epoch 時間,從 1970 年 1 月 1 日算起) // 開發者在建立對話時提供的 64 位元值,當遊戲啟動時,將自動傳入遊戲 // 您便能輕易將工作階段物件與您自己的、Steam 內部不使用的後端物件連結 "context": "31415926", "user_status": [ // 「UserStatus」物件陣列(如上所述) ] }

RequestedSession

{ "sessionid": "1", // uint64 "include_all_user_messages": "0" // bool }

可用的常見 API

詳細清單請見 IGameNotificationsService 單元。

啟動特定的遊戲階段

使用者可於自己的 Steam 社群個人檔案頁中看見所有仍在進行中的遊戲階段。 在遊戲狀態的旁邊,有一個可指示 Steam 使用特定啟動參數定義遊戲階段並啟動遊戲的按鈕。 透過這種方法啟動遊戲時,Steam 將提供遊戲啟動參數「_sessionid」,您可以使用 ISteamApps::GetLaunchQueryParam 獲得這個參數。
範例如下:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
支援使用以上方式直接啟動的遊戲應在啟動時呼叫這個介面,檢查工作階段識別碼字串是否存在、可供登入的使用者使用,同時直接載入遊戲。

在地化

遊戲開發者可透過應用程式設置中的在地化工具進行在地化。 如果您使用在地化工具輸入字串的翻譯版本,您需要為每一個字串負起設定翻譯版本的責任。 任何沒有翻譯成玩家語言的字串都將顯示英文。
遊戲通知支援下列屬性的在地化:

每個翻譯字串都需要具備以下兩個元素:

索引碼的開頭皆為「#」符號,代表這是透過應用程式設置中的在地化工具翻譯成其他語言的字串。 一個索引碼可包含多個執行個體,當文字即將產生時,這些執行個體能在執行階段中根據遊戲情境被代換。 範例如下:
#InvitationText = "{{user}} has invited you to play a game of Chess."

在上方的範例中,#InvitationText 的英文翻譯內含一個名為「user」的變數。 當您希望發送給某位使用指的文字訊息顯示「SteamUserName」邀請他進行遊戲時,請使用以下屬性更新 LocalizationText 物件:
"message": { "token": "#InvitationText", "variables": [ { "key": "user", "value": "Michael" } ] }

玩家在檢視自己的狀態時,將看到這則訊息(以使用者的當地語言顯示):「Michael 邀請您來一場西洋棋。」
在地化索引碼可在您的應用程式的「Steamworks 設定」>「社群」分頁 >「異步在地化」欄位中上傳。
您可以為每種語言上傳個別的 VDF 檔案,如下:
"lang" { "Language" "english" "Tokens" { "TheNameOfTheToken" "The localized text associated with the token" "TheNameOfAnotherToken" "The localized text associated with the second token" } }

或著您也可以上傳包含所有語言索引碼的單一檔案,如下:
"lang" { "english" { "Tokens" { "TheNameOfTheToken" "The localized text associated with the token" "TheNameOfAnotherToken" "The localized text associated with the second token" } } "spanish" { "Tokens" { "TheNameOfTheToken" "El texto localizado asociado con el token" "TheNameOfAnotherToken" "El texto localizado asociado con el segundo token" } } }