XUser のクロスプラットフォーム サポート

​

概要

​

統合要件

​

XBOX コンソールと Windows 上の Microsoft Store / Game Pass

​

Windows 上の他のストア

• ゲームは OS の組み込みサービスと UI を使用します。
• インストーラーは GamingRepair.exe を実行して、Gaming Runtime Service がインストールされていることを確認する必要があります。

1. ツールをゲーム パッケージに含める – GDK の [GDK]\bin\GamingRepair.exe に含まれています。
2. カスタム アクションを追加する – ゲームがインストールされる前にツールを実行します (例: start /wait “Installing Gaming Services” GamingRepair.exe scenarioExternal)。これにより、不足している Gaming Runtime コンポーネントを検証、ダウンロード、インストール、または修復します。
3. エラー処理 – ツールの終了コードを確認します。失敗した場合は、ユーザーに通知し、手動インストール手順を提供します。

​

プラットフォームの違いと統一 API

• ネイティブ サポートのあるプラットフォーム (XBOX、Windows) - XUser は認証、UI、および資格情報ストレージにオペレーティング システムの組み込みサービスを使用します。ゲームは XUser API を呼び出し、システムが詳細を自動的に処理します。
• ネイティブ サポートのないプラットフォーム (Steam Deck など) - XUser は同じコア API を公開しますが、ゲームは必要な UI (サインイン用の QR コードの表示など) とデータ ストレージを提供するためにイベント ハンドラーを実装する必要があります。これにより、ゲームは認証エクスペリエンスを完全に制御できます。

​

新しいクロスプラットフォーム機能

​

リモート接続認証

​

単一セッション適用 (SPoP)

​

クロスデバイス サインインのためのリモート接続

​

仕組み

​

フロー

1. イベント ハンドラーの登録 - ゲームは、XUserPlatformRemoteConnectSetEventHandlers(...) を使用してサインインを開始する前にリモート接続イベント ハンドラーを登録します。タイトルは、次の 2 つの主要なイベントを処理するコールバックを提供します。
   • Show イベント - XUser がゲームにワンタイム コードまたは QR コードを表示するように要求したときにトリガーされます。ハンドラーは、コードと指示 (例: “この QR コードをスキャンするか、xbox.com/play にアクセスしてコード ABCD を入力してサインインしてください”) を含むダイアログまたはオーバーレイを表示します。
   • Close イベント - リモート サインイン プロセスが完了またはキャンセルされたときにトリガーされ、ゲームにコード ダイアログを非表示または閉じるように通知します。
2. ユーザー サインインの開始 - 新しいユーザーを追加するために XUserAddAsync を呼び出すとき、ローカル ユーザーがまだサインインしていない場合、XUser システムはリモート接続フローを使用することがあります (特にヘッドレスまたはサードパーティ プラットフォームで)。
3. コードの表示 - XUser は「show」コールバックを呼び出し、認証コードまたは URL を提供します。ゲームの UI ハンドラー (OnRemoteConnectShow など) は、QR コードまたはコード文字列をユーザーに表示します。
4. ユーザー認証 - プレイヤーは電話または Web ブラウザーを使用して、提供されたコードでサインインし、XBOX アカウントを現在のセッションにリンクします。
5. 完了 - バックエンドで認証が完了すると、XUser は「close」コールバックを呼び出し、コードを画面から削除できることを通知します。この時点で、XUser はユーザーの XBOX Live トークンを取得し、XUserHandle を作成します。
6. 成功 - XUserAddAsync タスクが正常に戻り、デバイス上で資格情報を直接入力せずにユーザーがサインインされます。

​

実装

XUserPlatformRemoteConnectEventHandlers remoteConnect = {};
remoteConnect.context = nullptr;
remoteConnect.show = &OnRemoteConnectShow;   // Display QR/code dialog
remoteConnect.close = &OnRemoteConnectClose; // Dismiss dialog

HRESULT hr = XUserPlatformRemoteConnectSetEventHandlers(nullptr, &remoteConnect);

​

ユーザー エクスペリエンスの考慮事項

• 明確な指示 - コードを表示するときにユーザーが何をする必要があるかを明確に説明してください。
• エラー処理 - ユーザーがリモート側でキャンセルするかエラーが発生した場合、XUser はサインイン試行を失敗させます。これは XUserAddAsync の通常の完了コールバックで処理してください。
• タイムリーな解除 - ユーザーの混乱を避けるために、close イベントが発生したらすぐにコードを非表示にしてください。
• 視覚的なデザイン - QR コードと指示がターゲット デバイス上で十分に大きく、はっきりと見えるようにしてください。

​

単一セッション適用 (SPoP)

​

仕組み

​

フロー

1. イベント ハンドラーの登録 - ゲームは、XUserPlatformSpopPromptSetEventHandlers(...) を使用してサインインを開始する前に SPoP プロンプト イベント ハンドラーを登録します。
2. 競合の検出 - XUserAddAsync を呼び出してユーザーを追加するとき、XUser が同じユーザーが同じタイトル内の別の場所で既にアクティブであることを検出した場合、SPoP ハンドラーを呼び出します。
3. プロンプトの表示 - ゲームのハンドラーは、ユーザーのモダン ゲーマータグと操作ハンドルを受け取ります。ハンドラーは、次のような UI プロンプトを表示する必要があります: “[Gamertag] が別のデバイスでプレイ中です。ここでプレイしますか (これにより他の場所からサインアウトされます)、それとも別のアカウントに切り替えますか?” と「ここでプレイ」および「アカウントを切り替え」などのオプション。
4. ユーザーの選択 - ゲームは、ユーザーが選択するのを待ちます。操作は、ゲームが完了 API を呼び出すまで保留のままです。
5. 操作の完了 - ユーザーの選択に基づいて、ゲームは適切な結果で XUserPlatformSpopPromptComplete を呼び出します。
   • ここでプレイ - XUserPlatformSpopOperationResult::SignInHere - このデバイスでサインインし、リモート セッションを終了します。
   • アカウントを切り替え - XUserPlatformSpopOperationResult::SwitchAccount - このデバイスでのサインインをキャンセルし、ユーザーが別のアカウントを選択できるようにします。
   • キャンセル - XUserPlatformSpopOperationResult::Canceled - サインイン試行を中止します。
6. 解決 - XUser は結果に基づいて処理を続けます。「ここでプレイ」が選ばれた場合、リモート セッションが終了され (他のデバイスがサインアウト イベントを受け取ります)、ユーザーがローカルでアクティブになります。「アカウントを切り替え」が選ばれた場合、XUserAddAsync は失敗し、ゲームは別のアカウントを要求できます。

​

実装

HRESULT hr = XUserPlatformSpopPromptSetEventHandlers(nullptr, &OnSpopPrompt, nullptr);

// 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);

​

ユーザー エクスペリエンスの考慮事項

• 明確なメッセージ - ユーザーのゲーマータグを表示し、続行すると他のデバイスからサインアウトされることを明確に説明してください。
• 可視のオプション - “ここでプレイ” と “アカウントを切り替え” の両方のオプションを明確に表示し、理解しやすくしてください。
• セーブ競合の防止 - これによりセーブ ゲームの競合や同時ゲームプレイの問題が防止されることを強調してください。
• プラットフォーム固有の動作 - XBOX と Windows では、OS がこれを自動的に処理し、SPoP ハンドラーは呼び出されません。他のプラットフォームでは、ゲームがこの選択肢を提示する責任があります。

​

関連項目