概要
Steam ゲーム通知は、チェスのような非同期型のマルチプレイヤーゲームのユーザーに、オフライン通知を配信するシステムです。
このAPIの目的は、ゲームセッションを進めるためにアクションが必要なことをユーザーに通知することです。 たとえば、チェスの場合、ゲームセッションの状態はプレイヤーのターンごとに更新されます。 Steamはゲームセッションの状態に基づき、ユーザーに通知を送信し、ゲームがユーザーのターンを待っている時に知らせます。
ゲーム側で管理
典型的なオフラインゲームは、個々のユーザーの状態を更新してゲームセッションを管理し、ユーザーにゲームを起動して何らかのアクションが必要なことを知らせます。 ゲームの起動とゲーム内でのアクションを行うと、ゲームはセッション内の全ユーザーの最新の状態を取得するために、再度ゲームセッションを更新します。
Steam が管理
Steamは、ゲームにより提供された状態と、ユーザーがそのゲームで選択した各設定に基づき、ゲームセッション内のユーザーに通知を行います。 ゲームに対して何らかのアクションが必要なときは、Steamクライアントとウェブブラウザー内でユーザーへの警告が表示されます。
要件
Web APIメソッドを介して提供されるゲーム通知APIには、有効なパブリッシャーキーが必要です。 Web APIメソッドの呼び出しは、ゲームクライアントから分離されたホストサーバーから送る必要があります。パブリッシャーキーはゲームクライアントコードと共に配布してはなりません。
認証とサードパーティーアカウント
ゲーム通知APIを呼び出すには、まずゲームにログインしているSteamユーザーのIDを確立しなければなりません。 それには2つの方法があります。クライアントゲームで認証セッションチケットを生成してサーバーに戻す方法か、またはWebべースのゲームでOpenIDを使用してユーザーを確認する方法です。 その方法については、
サードパーティーアカウントをSteamアカウントにリンクするをご覧ください。 ゲームクライアントからゲームサーバーに直接送られたメッセージは改ざんされている可能性があるため、メッセージ内のユーザーIDは信頼しないでください。
サードパーティーアカウントを用いるゲームについては、上記の方法に従い、その際ユーザーのSteam IDはお使いのシステム内にキャッシュするようにしてください。
ゲーム通知API
技術概要
ゲーム通知APIの書き込みと公開はWeb APIを介して行われます。またそれぞれのメソッドでは４種類のパラメーターが必要になります:
- 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", //ローカライズトークンにマップする文字列n
"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-bit の値、これがゲームがローンチ時にゲームに渡されます
// これでセッションオブジェクトと、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"
}
}
}
