Steamworks 文献库
游戏通知

概览

Steam 游戏通知是一套向用户发送离线通知的系统,适用于国际象棋这类异步多人游戏。

此 API 的目的在于通知用户需要他们对某游戏会话采取行动,方能继续。 在国际象棋的示例中,游戏会话会在每个玩家下完一步后进行更新。 Steam 随后便会根据游戏会话通知用户现在轮到您了,这款游戏正在等待您的响应。

游戏的责任

大部分的离线游戏都会管理游戏会话、更新每位用户的状态,同时根据这些状态发送通知,以便用户知晓他们需要启动游戏并采取行动。 一旦启动游戏和采取游戏行动,游戏便应该为处于该会话中的所有玩家再次更新游戏会话,以反应最新状态。

Steam 管理的内容

Steam 会根据游戏提供的状态以及用户为该游戏选择的特定设置,负责在游戏会话中通知用户。 当游戏需要用户采取行动时,Steam 客户端与网页浏览器中将会显示提示。

要求

游戏通知 API 以网页 API 方法的形式提供,并要求有效的发行商序列号。 网页 API 方法调用必须从独立于游戏客户端的托管服务器发起,发行商序列号不得与任何游戏客户端代码一起发送。

验证及第三方帐户

如需调用游戏通知 API,您首先必须为登入您的游戏的 Steam 用户建立身份。 可通过以下两种方式建立,择一即可:客户端的游戏可产生验证会话表单并发送回您的服务器,或网页游戏可使用 OpenID 验证用户。 详细做法请见将第三方帐户链接至 Steam 帐户。 非常重要的一点是,从游戏客户端直接发送至您的游戏服务器的消息有遭篡改的可能,因此请勿信任这些消息中的用户身份。
如果您的游戏使用第三方帐户,请同样采用上述步骤,但记得将用户的 Steam ID 保存在您系统的缓存中。

游戏通知 API

技术概览

游戏通知 API 基于网页 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 时间戳(从 1970 年 1 月 1 日起) "time_updated": "200000", // Unix 时间戳(从 1970 年 1 月 1 日起) // 开发者在创建会话时提供的 64 位值,当游戏启动时将传入游戏。 // 您能够用此值轻松地将会话对象与您自己的后端对象绑定在一起,而 Steam 不会在内部使用。 "context": "31415926", "user_status": [ // “UserStatus”对象数组(前述) ] }

RequestedSession

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

可用的常见 API

详细列表请见 IGameNotificationsService

启动特定的游戏会话

用户可于 Steam 社区个人资料页面中看见所有进行中的游戏会话。 在游戏状态旁边,有一个按钮,可指示 Steam 使用特定启动参数定义游戏会话并启动游戏。 以这种方式启动游戏时,将向游戏提供一个 _sessionid 的启动参数,您可以使用 ISteamApps::GetLaunchQueryParam 接收此参加数。
如下所示:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
使用以上方式支持直接启动的游戏应在启动时调用此接口,检查登录用户的会话 ID 字符串是否存在并有效,同时直接载入游戏。

本地化

游戏开发者可通过应用程序配置中的本地化工具进行本地化。 您有责任为输入本地化工具的每一个字符串设置各语言翻译。 任何没有翻译成玩家语言的字符串都将显示为英文。
游戏通知支持下列属性的本地化:

每个本地化文本都需要具备以下两个元素:

令牌是一个键,以“#”符号开头,并代表通过应用程序配置中的本地化工具翻译成其他语言的字符串。 一个单一的令牌可包含多个变量实例,这些实例可以在运行时根据游戏在文本即将生成时的上下文来替换。 示例:
#InvitationText = "{{user}} has invited you to play a game of Chess."

在上文的实例中, #InvitationText 的英文翻译内含一个名为“user”的变量。 当“SteamUserName”邀请一位用户玩游戏,并且您希望将此文本信息呈现给该用户时,请使用以下属性更新 LocalizationText 对象:
"message": { "token": "#InvitationText", "variables": [ { "key": "user", "value": "Michael" } ] }

玩家在查看自己的状态时,将看到这则消息(以其当地语言显示):“ Michael has invited you to play a game of Chess. ”。
本地化令牌可上传并显示于您的应用程序的“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" } } }