概要
Steamゲーム通知は、チェスのような非同期型のマルチプレイヤーゲームのユーザーに、オフライン通知を配信するシステムです。
このAPIの目的は、ゲームセッションを進めるためにアクションが必要なことをユーザーに通知することです。 例えば、チェスの場合、ゲームセッションの状態はプレイヤーのターンごとに更新されます。 Steamはゲームセッションの状態に基づき、ユーザーに通知を送信し、ゲームがユーザーのターンを待っている時に知らせます。
ゲーム側で管理
典型的なオフラインゲームは、個々のユーザーの状態を更新してゲームセッションを管理し、ユーザーにゲームを起動して何らかのアクションが必要なことを知らせます。 ゲームの起動とゲーム内でのアクションを行うと、ゲームはセッション内の全ユーザーの最新の状態を取得するために、再度ゲームセッションを更新します。
Steamが管理
Steamは、ゲームにより提供された状態と、ユーザーがそのゲームで選択した各設定に基づき、ゲームセッション内のユーザーに通知を行います。 ゲームに対して何らかのアクションが必要なときは、SteamクライアントとWebブラウザー内でユーザーへの警告が表示されます。
要件
Web APIメソッドを介して提供されるゲーム通知APIには、有効なパブリッシャーキーが必要です。 Web APIメソッドの呼び出しは、ゲームクライアントから分離されたホストサーバーから送る必要があります。パブリッシャーキーはゲームクライアントコードと共に配布してはなりません。
認証とサードパーティーアカウント
ゲーム通知APIを呼び出すには、まずゲームにログインしているSteamユーザーのIDを確立しなければなりません。 それには2つの方法があります。クライアントゲームで認証セッションチケットを生成してサーバーに戻す方法か、またはWebべースのゲームでOpenIDを使用してユーザーを確認する方法です。 その方法については、
サードパーティーアカウントをSteamアカウントにリンクするをご覧ください。 ゲームクライアントからゲームサーバーに直接送られたメッセージは改ざんされている可能性があるため、メッセージ内のユーザーIDは信頼しないでください。
サードパーティーアカウントを用いるゲームについては、上記の方法に従い、その際ユーザーのSteam IDはお使いのシステム内にキャッシュするようにしてください。
ゲーム通知API
技術概要
ゲーム通知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エポック時間（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" // ブール
}
使用可能な共通API
ゲーム通知APIの全一覧は、
IGameNotificationsServiceを参照してください。
特定のゲームセッションの起動
ユーザーは、Steamの自分のコミュニティプロフィールページ内から、アクティブなゲームセッションを確認できます。 ゲームの状態とともに、Steamにゲームセッションを定義する特定の起動パラメーターでゲームを起動させるボタンも表示されます。 この方法でゲームが起動されると「_sessionid」という起動パラメーターがゲームに提供されます。このパラメーターは、
ISteamApps::GetLaunchQueryParamを使用して取得できます。
以下がその例です。
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
この方法での直接起動をサポートしているゲームは、起動時にこのインターフェイスを呼び出し、セッションIDの文字列が存在するかどうか、またサインインしたユーザーに対して有効であるかどうかを判断した後、直接ゲームを起動します。
ローカライゼーション
ローカライゼーションは、開発者自身がアプリケーション設定の一部であるローカライゼーションツールを使って行います。 ローカライゼーションツールに入力されたすべての文字列に対して、各言語用の翻訳を開発者の責任で設定してください。 プレイヤーの言語に翻訳されていない文字列はすべて英語で表示されます。
ゲーム通知では以下のプロパティのローカライゼーションに対応しています。
各
ローカライズ済みテキストは、2つのコンポーネントで構成されています。
トークンとは、「#」から始まるキーで、アプリケーション設定のローカライゼーションツールで別言語にローカライズされた文字列を表します。 1つのトークンには、複数の変数インスタンスが含まれます。それらの変数インスタンスは、実行時にテキストが生成されたときのゲームのコンテキストに基づいて置き換えることができます。 以下はその例です。
#InvitationText = "{{user}} has invited you to play a game of Chess."上の例の#InvitationTextに対する英語翻訳にはuserと呼ばれる1つの変数が含まれます。 「SteamUserName」がプレイヤーをゲームに招待したときにこのテキストメッセージを表示したい場合は、以下のプロパティで LocalizationText オブジェクトを更新してください:
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
}
プレイヤーが自分のステータスを確認する際に、このメッセージが（ユーザーの選択した言語で）表示されます：「Michael has invited you to play a game of Chess.（Michealから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"
}
}
}
