概要
XUser は、プラットフォーム間で Xbox ユーザー アカウントと認証を管理するためのゲーム ランタイム API です。 Xbox 本体、Windows PC、ハンドヘルド、および Steam Deck などの Microsoft 以外のプラットフォームでユーザー サインイン、ID、および関連するユーザー フローを処理するための統合インターフェイスが提供されます。
GDK のクロスプラットフォーム イニシアチブの一環として、XUser は、各環境のさまざまな機能と制約に対応しながら、すべてのプラットフォームで一貫した API サーフェスを提供します。
統合要件
ゲームで XUser を使用するには、ソース ファイルに XUser.h を含めて、XGameRuntime.lib に対してリンクします。 プラットフォーム間の主な違いは、ランタイムの依存関係の処理方法です:
Xbox 本体と Microsoft Store / Windows での Game Pass
ゲーム ランタイムは OS に組み込まれており、ストアによって処理されます。 ゲームでは、システムの組み込みのサービスと UI が自動的に使用されます。
Windows 上のその他のストア
- ゲームでは、OS の組み込みのサービスと UI が使用されます。
- インストーラーは GamingRepair.exe を実行して、ゲーム ランタイム サービスがインストールされていることを確認する必要があります。
ゲーム修復ツールの統合
ゲーム修復ツールをカスタム インストール手順としてゲームのインストーラーに追加します:
-
ゲーム パッケージにツールを含める -
[GDK]\bin\GamingRepair.exeの GDK に含まれています。 - カスタム アクションを追加 – ゲームをインストールする前にツールを実行します (例: start /wait "Installing Gaming Services" GamingRepair.exe scenarioExternal)。 これにより、不足しているゲーム ランタイム コンポーネントを検証、ダウンロード、インストール、または修復します。
- エラーの処理 – ツールの終了コードを確認します。 失敗した場合は、ユーザーに通知し、手動でインストール手順を指定します。
Important
Steam ゲームは、システム サービスが利用できないプラットフォーム (Steam Deck など) をサポートするために XGameRuntime.dll とその依存関係を含める必要があります。
Steam Deck またはその他の Microsoft 以外のプラットフォームでは、ゲーム修復ツールは使用できません。 代わりに、XGameRuntime.dll とその依存関係をゲーム パッケージにバンドルし、実行可能ファイルと一緒に配置して、実行時に読み込むことができます。
プラットフォームの違いと Unified API
Xbox と Windows では、オペレーティング システムは Xbox Live サインインとユーザー管理をネイティブに処理し、システム UI とユーザー資格情報のセキュリティで保護されたストレージを提供します。 XUser は、これらのプラットフォームでこれらの組み込みシステム サービスを利用します。 Steam Deck やサード パーティの環境などの他のゲーム プラットフォームでは、このネイティブ サポートは存在しません。
GDK 2510 リリース以降、XUser は、一貫性のある API を介して両方の種類のプラットフォームでシームレスに動作するように強化されました。新しい API とイベントドリブン パターンにより、ゲームでシステム サポートが利用できない場合に必要な UI とデータ処理を提供できるようになりました:
ネイティブ サポート (Xbox、Windows) を使用するプラットフォームの場合 - XUser は、オペレーティング システムの組み込みサービスを認証、UI、資格情報ストレージに使用します。 ゲームは XUser API を呼び出し、システムによって詳細が自動的に処理されます。
ネイティブサポートのないプラットフォーム上 (Steam デッキなど) - XUser は同じコア API を公開しますが、ゲームではイベント ハンドラーを実装して、必要な UI (サインイン用の QR コードの表示など) とデータ ストレージを提供する必要があります。 これにより、ゲームは認証エクスペリエンスを完全に制御できます。
プラットフォームに関係なく、ゲームはプレイヤーを表す XUserHandle を取得し、Xbox 認証をサポートするサービス (Xbox サービス、PlayFab サービスなど) に使用できます。
新しいクロスプラットフォーム機能
XUser 用に導入された新しい API では、プラットフォームに依存しないサインイン フローとデータ処理を有効にすることに重点が置かれている。 主な機能は次のとおりです:
リモート接続認証
ユーザーがセカンダリ デバイスを使用してデバイス (Steam Deck など) に Xbox アカウントでサインインできるようにします。 ユーザーは QR コードをスキャンするか、Web サイトでワンタイム コードを入力して認証を完了できます。 これは、コード ベースのサインイン プロンプトを表示および終了するための新しい XUser イベント ハンドラーによって実現されます。
単一セッションの強制 (SPoP)
ユーザーが複数の場所で同じゲームを同時に実行しないようにします。 競合が検出された場合、ユーザーは "ここでプレイする" か "アカウントを切り替える" かを選択するように求められます。新しい API を使用すると、ゲームはこの選択肢を提示し、それに応じて応答できます。
注意
Xbox 本体と Windows では、オペレーティング システムは引き続きほとんどの認証タスクを自動的に処理します。 ゲームでは、これらのプラットフォームでこれらのイベントが表示されない場合があります。 ただし、Xbox 以外のプラットフォームでは、ゲームは XUser のコールバック メカニズムを通じて完全に制御できます。
クロスデバイス サインイン用のリモート接続
リモート接続は、プレイヤーが別のデバイス (電話や PC など) を介して認証することで、デバイス上の Xbox アカウントにサインインできるようにする機能です。 これは通常、ゲームによって表示される短いコードまたは QR コードを使用して行われます。
しくみ
Xbox 本体では、この "コード フロー" はシステム UI によって自動的に処理されます。 ただし、Steam Deck やその他のサード パーティ環境などのプラットフォームでは、システムで管理される Xbox サインイン UI はありません。 XUser のリモート接続 API を使用すると、ゲームはこのフローを直接容易に行うことができます。
フロー
イベント ハンドラーの登録 - ゲームは、
XUserPlatformRemoteConnectSetEventHandlers(...)を使用してサインインを開始する前に、リモート接続イベント ハンドラーを登録します。 タイトルは、次の 2 つの主要なイベントを処理するためのコールバックを提供します:イベントの表示 - XUser がゲームにワンタイム コードまたは QR コードを表示する必要がある場合にトリガーされます。 ハンドラーは、コードと命令を含むダイアログまたはオーバーレイを表示します (たとえば、「この QR コードをスキャンするか、xbox.com/play にアクセスして、サインインするコード ABCD を入力してください」)。
close イベント - リモート サインイン プロセスが完了またはキャンセルされたときにトリガーされ、コード ダイアログを非表示または閉じるようゲームに通知されます。
ユーザー サインインの開始 -
XUserAddAsyncを呼び出して新しいユーザーを追加する場合、ローカル ユーザーがまだサインインしていない場合、XUser システムはリモート接続フローを使用する可能性があります (特にヘッドレスまたはサード パーティ製のプラットフォーム)。コードの表示 - XUser は認証コードまたは URL を指定して "show" コールバックを呼び出します。 ゲームの UI ハンドラー (
OnRemoteConnectShowなど) は、QR コードまたはコード文字列をユーザーに表示します。ユーザー認証 - プレイヤーは電話または Web ブラウザーを使用して指定されたコードでログインし、Xbox アカウントを現在のセッションにリンクします。
完了 - バックエンドで認証が完了すると、XUser は "close" コールバックを呼び出し、コードを画面から削除できることを通知します。 この時点で、XUser はユーザーの Xbox Live トークンを取得し、
XUserHandleを作成します。成功 -
XUserAddAsyncタスクは正常に戻り、ユーザーはデバイスで資格情報を直接入力せずにサインインします。
実装
リモート接続を使用するには、2 つのコールバック関数を実装し、それらを登録します:
XUserPlatformRemoteConnectEventHandlers remoteConnect = {};
remoteConnect.context = nullptr;
remoteConnect.show = &OnRemoteConnectShow; // Display QR/code dialog
remoteConnect.close = &OnRemoteConnectClose; // Dismiss dialog
HRESULT hr = XUserPlatformRemoteConnectSetEventHandlers(nullptr, &remoteConnect);
ハンドラーを登録したら、通常どおり XUserAddAsync を呼び出して、新しいユーザーを追加します。
OnRemoteConnectShow ハンドラーで、提供された情報 (XUser API を介してアクセス可能—通常は URL とコード) を取得し、ポップアップまたはオーバーレイでユーザーに表示します。
OnRemoteConnectClose が呼び出されると、サインイン プロセスが完了し、ゲームはプロンプトを非表示にする必要があります。
Important
XUserAddAsync を呼び出す前に (および通常は XUserInitialize の前)、XUserPlatformRemoteConnectSetEventHandlers を呼び出して、これらのイベントが適切に処理されるようにします。
ユーザー エクスペリエンスに関する考慮事項
優れたユーザー エクスペリエンスを提供するには:
- 手順のクリア - コードを表示するときにユーザーが実行する必要がある操作を明確に説明します。
-
エラー処理 - ユーザーがリモート側でキャンセルした場合、またはエラーが発生した場合、XUser はサインイン試行に失敗します。 これは、
XUserAddAsyncの通常の完了コールバックで処理します。 - タイムリーな無視 - ユーザーの混乱を避けるために、close イベントが発生したときにすぐにコードを非表示にします。
- ビジュアル デザイン - QR コードと命令が十分な大きさで、ターゲット デバイスで明確に表示されていることを確認します。
単一セッションの強制 (SPoP)
単一セッションの強制、または SPoP (Single Point of Presence) は、単一の Xbox Live ユーザー プロファイルが複数のデバイスで同時に同じタイトルを実行しないようにするポリシーです。 たとえば、Xbox 上のアカウントで既に実行されている状態で PC でゲームを起動する場合、ゲームの競合やその他の問題を保存しないように、1 つのセッションを中断またはサインアウトする必要があります。
Xbox 本体では、このシナリオでは、ゲームが既に他の場所で実行されていることをユーザーに知らせるシステム ダイアログがトリガーされ、続行するかどうかを確認します (これで他のデバイスからサインアウトされます)。 Microsoft 以外のプラットフォームでは、これを適用するための組み込みメカニズムはありません。 XUser SPoP プロンプト API を使用すると、ゲームはこの状況を検出し、プレイヤーに "ここでプレイするまたはアカウントを切り替える" 選択を提示できます。
しくみ
SPoP API は、リモート接続と同様のイベント ハンドラー パターンを使用します。 サインインの競合が検出されると、XUser は完全に失敗するのではなくゲームのハンドラーを呼び出し、ゲームがユーザーにオプションを提示できるようにします。
フロー
イベント ハンドラーの登録 - ゲームは、
XUserPlatformSpopPromptSetEventHandlers(...)を使用してサインインを開始する前に SPoP プロンプト イベント ハンドラーを登録します。競合検出 -
XUserAddAsyncを呼び出してユーザーを追加するときに、XUser が同じユーザーが同じタイトル内の別の場所で既にアクティブになっていることを検出すると、SPoP ハンドラーが呼び出されます。表示プロンプト - ゲームのハンドラーは、ユーザーの最新のゲーマータグと操作ハンドルを受け取ります。 ハンドラーは、次のような UI プロンプトを表示する必要があります。"[Gamertag] は既に別のデバイスでプレイしています。 代わりにここでプレイしますか (他の場所でサインアウトします)、または別のアカウントに切り替えますか?" [ここでプレイ] や [アカウントの切り替え] などのオプションを用意します。
ユーザーの選択 - ゲームは、ユーザーが選択を行うのを待ちます。 ゲームが完了 API を呼び出すまで、操作は保留中のままです。
操作の完了 - ユーザーの選択に基づいて、ゲームは適切な結果で
XUserPlatformSpopPromptCompleteを呼び出します:-
ここでプレイ -
XUserPlatformSpopOperationResult::SignInHere- このデバイスにサインインし、リモート セッションを終了します。 -
アカウントの切り替え -
XUserPlatformSpopOperationResult::SwitchAccount- このデバイスでのサインインを取り消し、ユーザーが別のアカウントを選択できるようにします。 -
キャンセル -
XUserPlatformSpopOperationResult::Canceled- サインイン試行を中止します。
-
ここでプレイ -
解決策 - XUser は結果に基づいて続行します。 "ここでプレイ" が選択された場合、リモート セッションは終了され (もう一方のデバイスはサインアウト イベントを受信します)、ユーザーはローカルでアクティブになります。 "アカウントの切り替え" が選択されている場合、
XUserAddAsyncは失敗し、ゲームは別のアカウントの入力を求めることができます。
実装
SPoP を使用するには、コールバック関数を実装して登録します:
HRESULT hr = XUserPlatformSpopPromptSetEventHandlers(nullptr, &OnSpopPrompt, nullptr);
OnSpopPrompt ハンドラーでは、ゲームはユーザー識別子と最新のゲーマータグを受け取ります。 ハンドラーは、(サインインが保留中であるため) ゲーム フローを一時停止し、オプションを含む UI プロンプトを表示する必要があります。 ハンドラーは操作ハンドルを格納し、すぐには完了しません。
ユーザーが選択を行うとき:
// If user chose "Play here"
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::SignInHere);
// If user chose "Switch account"
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::SwitchAccount);
// If dialog was canceled
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::Canceled);
Important
-
XUserAddAsyncを呼び出す前にXUserPlatformSpopPromptSetEventHandlersを呼び出して、競合が適切に処理されるようにします。 - 受信した SPoP イベントごとに 1 回だけ
XUserPlatformSpopPromptCompleteを呼び出す必要があります。それ以外の場合、サインインは無期限にハングします。 - ハンドラーが設定されておらず、競合が発生した場合、
XUserAddAsyncはエラー コードで失敗し、ユーザーは競合を適切に解決できません。
ユーザー エクスペリエンスに関する考慮事項
優れたユーザー エクスペリエンスを提供するには:
- メッセージングのクリア - ユーザーのゲーマータグを表示し、続行すると他のデバイスでサインアウトされることを明確に説明します。
- 表示オプション - [ここでプレイ] と [アカウントの切り替え] オプションの両方を明確に表示して理解できるようにします。
- 競合の保存の防止 - セーブ データの競合や同時ゲームプレイの問題を防ぐことを強調します。
- プラットフォーム固有の動作 - Xbox と Windows では、OS はこれを自動的に処理し、SPoP ハンドラーは呼び出されません。 他のプラットフォームでは、この選択を提示する責任はゲームにあります。
この API を使用しない場合、サインインの競合により、わかりにくいエラーや自動サインアウトが警告なしで発生し、ユーザー エクスペリエンスが低下します。 SPoP プロンプトは、プレイヤーに制御を与えながら、Xbox の単一セッション ポリシーに合わせて、動作を明示的かつユーザー主導にします。