次の方法で共有

ユーザー ID と XUser

  • [アーティクル]

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

  • Xbox サービスのサインイン状態をクエリする。
  • ユーザーのゲーマータグをフェッチする。
  • ユーザーのゲーマー アイコンをフェッチする。
  • ユーザーの年齢グループを判別する。
  • リアルタイム通信またはマルチプレイヤー セッションへの参加を許可されるユーザーに与えられている権限を判別する。
  • 認証トークンをフェッチする。

注意

XUserHandle 値が異なっていても、同じユーザーを指し示す可能性があります。 ゲームで、2 つの 異なるXUserHandle 値が異なるユーザーを指し示しているかどうかを比較するには、XUserCompare 関数を使用できます。

XUser 識別子

特定の XUser には 2 つの異なる識別子が関連付けらます。ローカル ID と Xbox サービス ID (XUID) です。

ローカル ID は、ゲーム セッションでのユーザーのライフタイムに渡って維持される識別子です。 ゲームによって生成されるすべてのプロセスで、またはゲームが XLaunchNewGame を呼び出した場合にローカル ID を使用します。 ただし、
ローカル ID を使用して、ゲーム セッションをまたがってユーザーを識別しないでください。

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

Xbox サービス ID (XUID) は、Xbox サービスと通信するとき、またはタイトルの呼び出し可能な UI (TCUI) を呼び出すときに使用する必要がある ID です。 ユーザーの XUID を取得するには、XUserGetId 関数を使用します。 XUID を取得するには、ユーザーの同意が必要な場合があります。 この同意が必要であり、許可されていない場合は、XUserGetIdは E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED を返します。 問題を解決して同意を得るには、ゲームで XUserResolveIssueWithUiAsync を呼び出す必要があります。

XUser の状態

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

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

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

Xbox One ERA のモデルとは異なり、ゲームが対話できるのは、ゲームが XUserAddAsync 関数を呼び出すことで要求したユーザーだけです。 たとえば、ユーザー A とユーザー B の 2 人のユーザーが、本体にサインインしているものとします。

  1. 誰かがゲームを起動します。 このシナリオでは、それが誰であるかは問題ではありません。

  2. ゲームは、XUserRegisterForChangeEvent を使用してユーザー状態の変更に登録します。

  3. ゲームは XUserAddAsync を呼び出し、ユーザー A がゲームにサインインします。

  4. ゲームは、ユーザー A を表す XUserHandle を持つようになります。

  5. ユーザー B が、ガイドからサインアウトを選択します。

  6. ゲームに対し、サインイン変更イベントは発生しません。 ゲームがユーザー B について認識することはありません。

  7. ユーザー A が、ガイドからサインアウトを選択します。

  8. ゲームは、まずユーザー A がサインアウトの処理中であることを示す変更イベントを受け取った後、最終的にユーザー A がサインアウトしたことを示す別のイベントを受け取ります。

ゲームでは、ユーザーをゲームに追加できる一方で、以下に示す方法のうち 1 つを使用してユーザーを削除する方法は限られています。

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

ユーザーの種類

Xbox One でサポートされるユーザーには、Xbox プレイヤーとゲストの 2 種類があります。

Xbox プレイヤーは、システム上のユーザーと同じく、完全な機能を備えています。 このユーザーは最初に、ユーザーをサインインさせるためのシステム提供 UI であるアカウントの選択画面で新しいアカウントを追加することによって作成されます。 Xbox プレイヤーは、設定アプリで明示的に削除されない限り、本体に存在し続けます。

Xbox ゲストは、本体上で 1 回のセッションを利用します。 Xbox ゲストは、ユーザーがゲストとしてプレイすることをアカウントの選択画面で選択したときに作成され、別のサインイン済み Xbox プレイヤーがスポンサーになります。 ゲストは、サインアウトするか、スポンサーの Xbox プレイヤーがサインアウトするか、本体の電源が切られるまで存在し続けます。

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

ユーザーを追加するパターン

ゲームでは必ず初期ユーザーの確立を試行する必要があります。 これを実現するには、主に 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 コンテキストを作成できます。

これらの手順を示すサンプル コードについては、「方法: ユーザーをサインインするためのベストプラクティス」を参照してください。

XUserHandle の管理

各 XUserHandle は、ユーザーを表します。 しかし、このような複数の各ハンドルが同じユーザーを表す場合があります。 この場合は、ゲームでは次の基本的なパターンを使用する必要があります。

  1. ゲームで処理するユーザーのコレクションを表す XUserHandle インスタンスのコレクションを維持します。

  2. XUserRegisterForChangeEvent を呼び出して、XUser の状態変更に登録します。 ユーザーがサインアウトしたことがわかったら、コレクションのユーザーを更新します。

  3. 新しい XUserHandle を XUserAddAsync から取得したら、それが新しいユーザーを表すかどうかを確認します。 XUserCompare を使用して、ハンドルと直接比較することができます。 XUserGetLocalId を呼び出して見つかったローカル ID を使用して比較することもできます。

  4. 複数の XUserHandle インスタンスが同じユーザーを表している場合は、XUserCloseHandle を使用して余分なインスタンスを削除します。