Steamworks 文献库
游戏通知

原文内容有作更新

此页原文在翻译版发布之后作了更新。
点击此处查看此页更新后的英文版本。

概览

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

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

游戏的责任

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

Steam 管理的内容

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

要求

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

验证及第三方帐户

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

游戏通知 API

技术概览

游戏通知 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": [ // " 变量"数组(上述) ] }

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 使用特定启动参数定义游戏会话并启动游戏。通过此方法启动游戏时,Steam 将提供游戏启动参数“_sessionid”,您可以使用 ISteamApps::GetLaunchQueryParam 获得此参数,如下所示:
const char *pchSessionID = ISteamApps()-> GetLaunchQueryParam("_sessionid");[ /code] 使用以上方式支持直接启动的游戏应在启动时调用此界面,检查会话 ID 字符串是否存在以及是否可供登录的用户使用,同时直接加载游戏。 [section] 本地化 [/section] 游戏开发者可通过应用程序配置中的本地化工具进行本地化。您有责任为输入本地化工具的每一个字符串设置语言翻译。任何没有翻译成玩家语言的字符串都将显示为英文。 游戏通知支持下列属性的本地化: 每个 本地化文本 都需要具备以下两个元素: 标记是一个序列号,以“ #”符号开头,并代表通过应用程序设置中的本地化工具翻译成其他语言的字符串。一个单一的标记可包含多个变量实例,这些实例可以在运行时根据游戏的上下文来替换。实例如下: #InvitationText = "{{user}} has invited you to play a game of Chess." 在上文的实例中, #InvitationText 的英文翻译内含一个名为“用户”的变量。当“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" } } }