概要
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 を介して行われます。またそれぞれのメソッドでは 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", //ローカライズトークンにマップする文字列n
"variables":
[
//"Variable" (上記)の配列
]
}
UserStatus（ユーザー状態）
{
"steamid": "76561197960265729", // uint64
"state": // "UserState" (上記)定数の内の一つ,
"title": //"LocalizedText" (上記)オブジェクト,
"message": // "LocalizedText" (上記)オブジェクト
}
Session（セッション）
{
"sessionid": "1", // uint64
"title": // A "LocalizedText" object (above),
"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"
}
}
}
