> ## 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.

# ユーザー ID と XUser

> ユーザー ID と XUser

XBOX One は、ゲームと対話するユーザーの ID を `XUser` オブジェクトで管理します。各 `XUser` インスタンスは、ゲームにサインインしているユーザーを表します。各ユーザーは `XUserHandle` によって表されます。ゲームは `XUserHandle` を使用して次のことを実行できます。

* XBOX サービスのサインイン状態を照会します。
* ユーザーのゲーマータグを取得します。
* ユーザーのゲーマー画像を取得します。
* ユーザーの年齢グループを判別します。
* リアルタイム通信に参加したり、マルチプレイヤー セッションに参加したりすることが許可されるユーザーに対して、どの特権が許可されているかを判別します。
* 認証されたトークンを取得します。

## XUser 識別子

任意の `XUser` には 2 つの異なる識別子が関連付けられます: ローカル ID と XBOX services ID (XUID) です。

*ローカル ID* は、ゲーム セッション内のユーザーの生存期間中、そのユーザーと共に留まる識別子です。ゲームが生成する任意のプロセス、またはゲームが `XLaunchNewGame` を呼び出す場合には、ローカル ID を使用します。ただし、ゲーム セッションをまたいでユーザーを識別するためにローカル ID を使用しないでください。<br />

ユーザーのローカル ID を取得するには、`XUserGetLocalId` 関数を使用します。

*Xbox services ID (XUID)* は、XBOX サービスと通信する際、またはタイトル呼び出し可能 UI (TCUI) を呼び出す際に使用する必要がある識別子です。ユーザーの XUID を取得するには、`XUserGetId` 関数を使用します。XUID を取得するにはユーザーの同意が必要な場合があります。この同意が必要で得られていない場合、`XUserGetId` は E\_GAMEUSER\_RESOLVE\_USER\_ISSUE\_REQUIRED を返します。問題を解決して同意を得るには、ゲームはその後 `XUserResolveIssueWithUiAsync` を呼び出す必要があります。

## XUser の状態

ユーザーは、XBOX サービスにサインインしている、XBOX サービスからサインアウトしている途中、または完全にサインアウトしている、の 3 つの状態のいずれかにあります。ゲームは、`XUserGetState` 関数を使用して、指定したユーザーのこの状態を照会できます。ゲームは、`XUserRegisterForChangeEvent` 関数を使用して変更通知を登録することもできます。

`XUser` の状態に基づいてネットワーク接続を判断しないでください。`XUserState` が `SignedIn` である場合、これはユーザーがある時点で XBOX サービスで認証され、アクティブ ユーザーとして扱えることを示します。ただし、ネットワークは接続されていない可能性があります。

## ゲームへのユーザーの追加または削除

XBOX One ERA のモデルとは異なり、ゲームは、`XUserAddAsync` 関数を呼び出してゲームが要求したユーザーとのみ対話できます。たとえば、コンソールに 2 人のユーザーがサインインしているとします: ユーザー A とユーザー B。

1. 誰かがゲームを起動します。このシナリオでは、誰が起動したかは重要ではありません。
2. ゲームは `XUserRegisterForChangeEvent` を使用してユーザー状態の変更を登録します。
3. ゲームは `XUserAddAsync` を呼び出し、ユーザー A がゲームにサインインします。
4. ゲームは現在、ユーザー A を表す `XUserHandle` を持っています。
5. ガイドから、ユーザー B がサインアウトを選択します。
6. サインイン変更イベントはゲームに発火されません。ゲームはユーザー B について知りませんでした。
7. ガイドから、ユーザー A がサインアウトを選択します。
8. ゲームは、まずユーザー A がサインアウト中であることを示す変更イベントを取得し、最終的に、ユーザー A が現在サインアウトされていることを示す別のイベントを取得します。

ゲームはゲームにユーザーを追加できますが、次のいずれかの方法を使用してユーザーを削除する方法はいくつかしかありません。

* ゲームは、`XUserCloseHandle` 関数を使用してユーザーを表すすべてのハンドルを閉じることができます。
* ユーザーはガイドを使用してコンソールからサインアウトします。
* ユーザーが別のデバイスにサインインします。

## ユーザーの種類

XBOX One は 2 種類のユーザーをサポートします: XBOX プレイヤーとゲストです。

*Xbox プレイヤー* は、システム上のユーザーとしてのフル機能を持ちます。彼らは、ユーザーをサインインするためのシステム提供の UI である Account Picker で新しいアカウントを追加することによって最初に作成されます。XBOX プレイヤーは、Settings アプリで明示的に削除されるまでコンソールに残り続けます。

*Xbox ゲスト* は、コンソール上で 1 つのセッションを持ちます。彼らは、Account Picker でゲストとしてプレイすることを選択したときに作成され、別のサインインしている XBOX プレイヤーによってスポンサーされます。ゲストは、サインアウトするか、スポンサーの XBOX プレイヤーがサインアウトするか、またはコンソールの電源が切られるまで続きます。

ゲストを許可したいゲームは、`XUserAddAsync` を呼び出す際に `AllowGuest` オプションを指定する必要があります。

## ユーザーを追加するパターン<a id="pattern_for_adding" />

ゲームは常に最初のユーザーを確立しようとする必要があります。これを実現するには、主に 2 つの方法があります。

#### オプション 1: UI を表示せずに可能な限り早くユーザーを判別する

1. `AddDefaultUserSilently` を使用して `XUserAddAsync` を呼び出します。この関数は、UI を表示せずに誰がゲームを起動したかを判別しようとします。
2. `XUserAddAsync` の呼び出しは `E\_GAMEUSER\_NO\_DEFAULT\_USER` で失敗する可能性があります。これが発生した場合、ゲームが最初に起動されたときに誰もサインインしていませんでした。最初のユーザーを確立するために、ゲームは `AddDefaultUserSilently` フラグを使用せずに `XUserAddAsync` を呼び出す必要があります。「サイレント」オプションとは異なり、この呼び出しは同意に関するすべての問題が完全に解決され、呼び出しが成功した場合、ユーザーが XBOX サービスにサインインしていることを保証します。ゲームはそのユーザーに対して XBOX コンテキストを作成できます。

#### オプション 2: UI を表示する可能性を伴ってユーザーを判別する

`AddDefaultUserAllowingUI` を使用して `XUserAddAsync` を呼び出します。前のオプション (「サイレント」を伴うもの) と同様に、この関数は誰がゲームを起動したかを判別しようとします。前のオプションとは異なり、既定のユーザーを判別できない場合、プレイヤーがサインインするか自分自身を選択できるように UI を表示します。`XUserAddResult` が成功した場合、ゲームには XBOX サービスに完全にサインインしたユーザーがあり、ゲームはそのユーザーの XBOX コンテキストを作成できます。

これらの手順を示すサンプル コードについては、[How to: ユーザーをサインインさせるためのベスト プラクティス](/build/core-features/common/user/xuser_howto_best_practice_signing_in) を参照してください。

## XUserHandle の管理

各 `XUserHandle` は 1 人のユーザーを表します。ただし、複数のそのようなハンドルがそれぞれ同じユーザーを表すことも可能です。ゲームは次の基本パターンを使用する必要があります。

1. ゲームが関心を持つユーザーのコレクションを表す `XUserHandle` インスタンスのコレクションを保持します。
2. `XUserRegisterForChangeEvent` を呼び出して `XUser` 状態変更を登録します。ユーザーがサインアウトされているのを確認したら、ユーザーのコレクションを更新します。
3. `XUserAddAsync` から新しい `XUserHandle` を取得したときは、これが新しいユーザーを表すかどうかを必ずチェックしてください。`XUserCompare` を使用してハンドルを直接比較できます。`XUserGetLocalId` を呼び出して見つけたローカル ID を使用して比較することもできます。
4. 同じユーザーを表す複数の `XUserHandle` インスタンスがある場合は、`XUserCloseHandle` を使用して余分なインスタンスを削除します。

*ローカル ID* は、ゲーム セッション内のユーザーの生存期間中、そのユーザーと共に留まる識別子です。ゲームが生成する任意のプロセス、またはゲームが `XLaunchNewGame` を呼び出す場合には、ローカル ID を使用します。ただし、ゲーム セッションをまたいでユーザーを識別するためにローカル ID を使用しないでください。


## Related topics

- [GDK のユーザー ID と XUser API](/ja-jp/build/core-features/common/user/index.md)
- [ゲスト ユーザーの概要](/ja-jp/build/core-features/common/user/users-guest-overview.md)
- [ユーザー](/ja-jp/build/core-features/common/user/user-toc.md)
- [How to: ユーザーをサインインさせるためのベスト プラクティス](/ja-jp/build/core-features/common/user/xuser_howto_best_practice_signing_in.md)
- [アカウント認証とアクセスの概要](/ja-jp/services/xbox-services/fundamentals/identity/auth/live-authentication-overview.md)