> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

## 概要

XUser は、プラットフォーム間で XBOX ユーザー アカウントと認証を管理するための Gaming Runtime API です。XBOX コンソール、Windows PC およびハンドヘルド、Steam Deck などの Microsoft 以外のプラットフォームで、ユーザーのサインイン、ID、および関連するユーザー フローを処理するための統一されたインターフェイスをゲームに提供します。

GDK のクロスプラットフォーム イニシアチブの一環として、XUser は各環境の異なる機能と制約に対応しながら、すべてのプラットフォームで一貫した API サーフェスを提供します。

### 統合要件

ゲームで XUser を使用するには、ソース ファイルに `XUser.h` を含め、`XGameRuntime.lib` に対してリンクします。プラットフォーム間の主な違いは、ランタイム依存関係の処理方法です。

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

ゲーミング ランタイムは OS に組み込まれており、ストアによって処理されます。ゲームは自動的にシステムの組み込みサービスと UI を使用します。

#### Windows 上の他のストア

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

**Gaming Repair Tool の統合**

Gaming Repair Tool をゲームのインストーラーにカスタム インストール ステップとして追加します。

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

> [!NOTE]
>
> Steam のゲームは、システム サービスが利用できないプラットフォーム (Steam Deck など) をサポートするために、`XGameRuntime.dll` とその依存関係を含める必要があります。
> Steam Deck やその他の Microsoft 以外のプラットフォームでは、Gaming Repair Tool は使用できません。代わりに、`XGameRuntime.dll` とその依存関係をゲーム パッケージにバンドルし、実行時に読み込めるように実行可能ファイルと並べて配置してください。

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

XBOX と Windows では、オペレーティング システムが XBOX Live のサインインとユーザー管理をネイティブで処理し、ユーザー資格情報のためのシステム UI とセキュアなストレージを提供します。XUser はこれらのプラットフォームで組み込みシステム サービスを活用します。Steam Deck やサードパーティ環境などの他のゲーミング プラットフォームでは、このネイティブ サポートは存在しません。

GDK 2510 リリース以降、XUser は一貫した API を通じて両方の種類のプラットフォームでシームレスに動作するように強化されており、新しい API とイベント駆動のパターンにより、システム サポートが利用できない場合にゲームが必要な UI とデータ処理を提供できるようになりました。

* **ネイティブ サポートのあるプラットフォーム (XBOX、Windows)** - XUser は認証、UI、および資格情報ストレージにオペレーティング システムの組み込みサービスを使用します。ゲームは XUser API を呼び出し、システムが詳細を自動的に処理します。

* **ネイティブ サポートのないプラットフォーム (Steam Deck など)** - XUser は同じコア API を公開しますが、ゲームは必要な UI (サインイン用の QR コードの表示など) とデータ ストレージを提供するためにイベント ハンドラーを実装する必要があります。これにより、ゲームは認証エクスペリエンスを完全に制御できます。

プラットフォームに関係なく、ゲームはプレイヤーを表す `XUserHandle` を取得し、XBOX 認証をサポートするサービス (XBOX サービス、PlayFab サービスなど) に使用できます。

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

XUser に導入された新しい API は、プラットフォームに依存しないサインイン フローとデータ処理を可能にすることに焦点を当てています。主な機能は次のとおりです。

### リモート接続認証

ユーザーがセカンダリ デバイスを使用して、デバイス (Steam Deck など) 上で XBOX アカウントでサインインできるようにします。ユーザーは QR コードをスキャンするか、Web サイトでワンタイム コードを入力して認証を完了できます。これは、コード ベースのサインイン プロンプトを表示および閉じるための新しい XUser イベント ハンドラーによって実現されます。

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

ユーザーが複数の場所で同じゲームを同時に実行していないことを保証します。競合が検出された場合、ユーザーは「ここでプレイする」または「アカウントを切り替える」のいずれかを選択するように促されます。新しい API により、ゲームはこの選択肢を提示し、それに応じて応答できます。

> [!NOTE]
>
> XBOX コンソールと Windows では、オペレーティング システムが引き続きほとんどの認証タスクを自動的に処理します。これらのプラットフォームでは、ゲームがこれらのイベントを目にすることはないかもしれません。ただし、XBOX 以外のプラットフォームでは、ゲームは XUser のコールバック メカニズムを介して完全に制御できます。

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

リモート接続は、プレイヤーが別のデバイス (電話や PC など) を介して認証することで、あるデバイス上で XBOX アカウントにサインインできる機能です。これは通常、ゲームによって表示される短いコードまたは QR コードを介して行われます。

### 仕組み

XBOX コンソールでは、この「コード フロー」はシステム UI によって自動的に処理されます。ただし、Steam Deck やその他のサードパーティ環境などのプラットフォームには、システムが管理する XBOX サインイン UI はありません。XUser のリモート接続 API により、ゲームがこのフローを直接容易にすることができます。

#### フロー

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` タスクが正常に戻り、デバイス上で資格情報を直接入力せずにユーザーがサインインされます。

### 実装

リモート接続を使用するには、2 つのコールバック関数を実装して登録します。

```cpp theme={null}
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` が呼び出されたとき、サインイン プロセスが完了しているので、ゲームはプロンプトを非表示にする必要があります。

> [!NOTE]
>
> これらのイベントが正しく処理されるように、`XUserAddAsync` を呼び出す前 (および一般的には `XUserInitialize` の前) に `XUserPlatformRemoteConnectSetEventHandlers` を呼び出してください。

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

優れたユーザー エクスペリエンスを提供するには:

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

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

Single-Session Enforcement (SPoP: Single Point of Presence) は、単一の XBOX Live ユーザー プロファイルが同じタイトルを複数のデバイス上で同時に実行しないことを保証するポリシーです。たとえば、あなたのアカウントで XBOX 上で既に実行中のゲームを PC 上で起動した場合、セーブ ゲームの競合やその他の問題を防ぐために、いずれかのセッションを一時停止またはサインアウトする必要があります。

XBOX コンソールでは、このシナリオはユーザーにゲームが既に別の場所で実行されていることを伝え、続行するかどうかを尋ねる (これは他のデバイスからのサインアウトを引き起こします) システム ダイアログをトリガーします。Microsoft 以外のプラットフォームでは、これを強制する組み込みのメカニズムはありません。XUser の SPoP プロンプト API により、ゲームはこの状況を検出し、プレイヤーに「ここでプレイする、またはアカウントを切り替える」の選択肢を提示できます。

### 仕組み

SPoP API は、リモート接続と同様のイベント ハンドラー パターンを使用します。サインインの競合が検出されると、XUser は直接失敗する代わりにゲームのハンドラーを呼び出し、ゲームがユーザーにオプションを提示できるようにします。

#### フロー

1. **イベント ハンドラーの登録** - ゲームは、`XUserPlatformSpopPromptSetEventHandlers(...)` を使用してサインインを開始する前に SPoP プロンプト イベント ハンドラーを登録します。

2. **競合の検出** - `XUserAddAsync` を呼び出してユーザーを追加するとき、XUser が同じユーザーが同じタイトル内の別の場所で既にアクティブであることを検出した場合、SPoP ハンドラーを呼び出します。

3. **プロンプトの表示** - ゲームのハンドラーは、ユーザーのモダン ゲーマータグと操作ハンドルを受け取ります。ハンドラーは、次のような UI プロンプトを表示する必要があります: "\[Gamertag] が別のデバイスでプレイ中です。ここでプレイしますか (これにより他の場所からサインアウトされます)、それとも別のアカウントに切り替えますか?" と「ここでプレイ」および「アカウントを切り替え」などのオプション。

4. **ユーザーの選択** - ゲームは、ユーザーが選択するのを待ちます。操作は、ゲームが完了 API を呼び出すまで保留のままです。

5. **操作の完了** - ユーザーの選択に基づいて、ゲームは適切な結果で `XUserPlatformSpopPromptComplete` を呼び出します。

   * **ここでプレイ** - `XUserPlatformSpopOperationResult::SignInHere` - このデバイスでサインインし、リモート セッションを終了します。
   * **アカウントを切り替え** - `XUserPlatformSpopOperationResult::SwitchAccount` - このデバイスでのサインインをキャンセルし、ユーザーが別のアカウントを選択できるようにします。
   * **キャンセル** - `XUserPlatformSpopOperationResult::Canceled` - サインイン試行を中止します。

6. **解決** - XUser は結果に基づいて処理を続けます。「ここでプレイ」が選ばれた場合、リモート セッションが終了され (他のデバイスがサインアウト イベントを受け取ります)、ユーザーがローカルでアクティブになります。「アカウントを切り替え」が選ばれた場合、`XUserAddAsync` は失敗し、ゲームは別のアカウントを要求できます。

### 実装

SPoP を使用するには、コールバック関数を実装して登録します。

```cpp theme={null}
HRESULT hr = XUserPlatformSpopPromptSetEventHandlers(nullptr, &OnSpopPrompt, nullptr);
```

`OnSpopPrompt` ハンドラーで、ゲームはユーザー識別子とモダン ゲーマータグを受け取ります。ハンドラーは (サインインが保留中であるため) ゲーム フローを一時停止し、オプション付きの UI プロンプトを表示する必要があります。ハンドラーは操作ハンドルを保存し、すぐには完了しません。

ユーザーが選択したら:

```cpp theme={null}
// 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);
```

> [!NOTE]
>
> * 競合が正しく処理されるように、`XUserAddAsync` を呼び出す前に `XUserPlatformSpopPromptSetEventHandlers` を呼び出してください。
> * 受け取った各 SPoP イベントに対して `XUserPlatformSpopPromptComplete` を厳密に 1 回呼び出す必要があります。呼び出さない場合、サインインが無期限にハングします。
> * ハンドラーが設定されておらず、競合が発生した場合、`XUserAddAsync` はエラー コードで失敗し、ユーザーには競合を優雅に解決する機会はありません。

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

優れたユーザー エクスペリエンスを提供するには:

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

この API がないと、サインインの競合は不明瞭なエラーや警告なしの自動サインアウトをもたらし、ユーザー エクスペリエンスが低下します。SPoP プロンプトは、動作を明示的かつユーザー主導にし、XBOX の単一セッション ポリシーに合わせつつ、プレイヤーに制御を与えます。

## 関連項目

[ユーザー ID と XUser](/ja-jp/build/core-features/common/user/player-identity-xuser)


## Related topics

- [PlayFab Online Subsystem (OSS) クイックスタート](/ja-jp/services/playfab/multiplayer/networking/party-unreal-engine-oss-quickstart.md)
- [クロスプラットフォーム マルチプレイヤーの設計ガイダンス](/ja-jp/services/xbox-services/multiplayer/overviews/multiplayer-design-guidance-cross-platform.md)
- [XBOX サービス タイトル向け PlayFab インテグレーション](/ja-jp/services/xbox-services/playfab-integration.md)
- [ボイス オーディオのノイズ抑制](/ja-jp/services/playfab/community/voice-communications/concepts-noise-suppression.md)
- [リアルタイム オーディオ操作でカスタム ボイス エフェクトを適用する](/ja-jp/services/playfab/community/voice-communications/concepts-realtime-audio-manipulation.md)