Compartilhar via

XR-112: Establishing a User and Controller During Initial Activation and Resume *

  • Artigo

Version 1.1, 5/1/2021

Titles must establish one or more active users to function as the primary user or users in the title, and handle the user or users when resuming from suspended and constrained modes. Titles do this in the GDK by using either the Simplified or Advanced User Model.

GDK Simplified User Model Titles

The Simplified User Model in the GDK handles default user acquisition on behalf of the title. The title is still responsible to ensure that a controller is assigned to the user and use that controller for game input. If no controller is assigned to the default user, the title should use XUserFindControllerForUserWithUiAsync to engage the system dialog to select a controller and begin accepting input from the player.

GDK Advanced User Model, ERA, and UWP Multiple User Applications

On initial activation games can choose to determine the initial user based on their game design and preference using either the user who launched the title or by explicitly prompting for a user.

The title must indicate the active user(s) before the first profile-related action (such as saving progress or settings) is taken on that user's profile.

All Microsoft Game Development Kit (GDK) titles using the advanced user model, ERA, and UWP Multiple User Application (MUA) titles must provide an entry point to the account picker to change the active user.

When a title is resumed from suspension or constrained mode, the title must validate the user/controller pairing and react accordingly by resuming the prior user's session or acquiring a new user or users.

More Information

Establishing Users During Initial Activation

GDK Simplified User Model

The initial user is provided to the title by calling XUserAddAsync(silent) and will always return a single result for the launching user.

GDK Advanced User Model, ERA, and UWP Multiple User Applications

If the game is using the user who launched the title:

  • For the GDK the active user can be determined by calling XUserAddAsync(silent). If the system returns that no default present, the title must prompt for a user using XUserAddAsync without the silent option. This will display an account picker for the user.

  • For ERA and UWP the active user can be found from the app activation context's recommended user (CoreApplicationContext.CurrentUser). If the app activation context has not provided a recommended user and the title takes profile-related actions, the title must launch the account picker and set the active user based on the user's profile selection.

If prompting for a User:

  • The title displays an engagement prompt and must show the account picker. The user is based on the selection.

  • For the GDK the account picker is invoked using XUserAddAsync

  • For ERA and UWP the account picker is invoked using ShowAccountPickerAsync.

If the user chooses to cancel out of sign-in, the title must notify users that their progress will not be saved if they continue.

Once a user has been chosen or identified from launch the title then displays the gamertag prior to making any profile related actions are taken. There are no requirements on how or where the title shows who the active user is. Best practices include displaying the user's gamerpic and display name on the main screen of the app or on the title menu of the game.

Establishing Controllers During Initial Activation

Games need to respect the controller and user binding set by the account picker or platform when the game is launched with a signed in user. The Xbox platform will bind the controller to a player any time a player is selected in the account picker during or outside of gameplay.

If the title is using the user who launched the title, the title should use the associated gamepad assigned to that user to drive game play and interaction.

Resuming From Suspend or Constrained Mode

GDK Simplified User Model

The Xbox platform will ensure that the user who launched the game initially is still actively signed in. The title can register for change notifications via UDA; if there is a change using that newly bound controller to drive gameplay.

Any additional users in gameplay will need to be handled accordingly in line with the following guidance in the advanced user model when resuming from a suspended or constrained state.

GDK Advanced User Model, ERA, and UWP Multiple User Applications

When a title is resumed from suspension or exits constrained mode, the title must validate the user/controller pairing and react accordingly:

  • If there are no changes to the user/controller pairing, then the title must proceed.
  • In ERA or UWP a title's previous active user is still signed in but is on a new User object (generally caused by the user signing out and then signing back in while the title is suspended), then the title must use the new signed-in User object as a replacement for the signed-out User object. Usage must continue as if the user had never signed out.
  • If all expected users are paired with a valid, but different, controller, then the title must update and use the new system controller pairings.
  • If the expected user has either no valid controllers then the title must establish an active controller for the user by using the account picker.
  • If the expected player is not signed in, the title must either remove the player from the game or reestablish a user and active controller. Titles generally do this by displaying the account picker. If a new user is chosen as part of reestablishing a user, titles must use that new user's state for gameplay if game state is saved per user.

Additional Resources

For information on player identity using the GDK, read the Users section

Certification Test Cases

The following table shows which test cases for XR-112 apply to your title if using the GDK Simplified User Model or the GDK Advanced User Model, ERA and UWP Multiple User Applications.

Test Cases Applicable to GDK Simplified User Model Applicable to GDK Advanced User Model, ERA and UWP MUA
112-02 Initial User and Controller No Yes
112-03 No signed in User No Yes
112-04 Active User Indication Yes Yes
112-05 Access to Account Picker No Yes
112-06 Handling Profile Change No Yes
112-07 User Change During Constrained Mode No Yes
112-08 User Change During Suspension No Yes

112-02 Initial User and Controller

Test Steps

  1. Sign into Profile A and launch the title.
  2. Verify the active user can control the title.
  3. Repeat step [1] with no signed in profile and verify the title prompts to establish an active user.
  4. Establish the active user and verify the user can control the title.

Expected Result
Titles must set the active user to the controller/user pairing which launched the title, or show an engagement prompt to identify the controller and user, or display the account picker to sign in.

Pass Examples

  1. The title sets the active user to the controller/user pairing which launched the title.
  2. The title shows an engagement prompt to identify the controller and user.
  3. The title displays the account picker to sign in.

Fail Examples

  1. The title does not allow the user to control the title with the first controller used.
  2. The title does not prompt the user to establish an active user when launched with no user signed in.

112-03 No Signed-In User

Test Steps

  1. Verify that no users are signed in.
  2. Launch the title and enter every mode that supports the saving of user data.
  3. Validate that each mode offers the user the opportunity to sign in before any data loss occurs.
  4. Cancel the opportunity to sign in, and verify that the title provides a warning indicating that progress will not be saved.

Expected Result
Titles must offer users the opportunity to sign in if the title is in a mode that would normally save user data or game state. Titles must notify users that their progress will not be saved if they continue with gameplay without signing in

Pass Examples

  1. A user who is not signed in is prompted to sign in when accessing a title mode that would normally save user data or game state.
  2. The user is notified that progress will not be saved if he or she continues in mode without signing in.

Fail Examples

  1. While in a mode that normally saves user data or game state, users are not notified that progress will not be saved if they continue in that mode without signing in.
  2. Users are notified that they will not be able to save their progress after data loss has already occurred.

112-04 Active User Indication

Test Steps

  1. Sign into a profile that has not seen the title before and has no associated save data.
  2. Launch the title.
  3. Verify that the title identifies the active user within the UI prior to performing any profile-related actions. Examples of "profile-related action" include altering a user's saved game or preferences, saving data to the user's profile, awarding achievements, writing statistics for a user, or any other local or cloud usage or manipulation of user data or state.
  4. Create a save.
  5. Re-launch the title and verify that the title identifies the active user within the UI prior to performing any profile-related actions.
  6. Disconnect from Xbox Live.
  7. Re-launch the title and verify that the title identifies the active user within the UI prior to performing any profile-related actions.

Expected Result
Titles must indicate the current user context prior to the first profile-related action.

Pass Examples

  1. The title displays the user's gamertag and/or gamerpic within the title before performing any profile-related actions.
  2. A title that does not use user profiles does not indicate the active user.
  3. A title displays multiple active users for game modes that support multiple users.

Fail Examples

  1. The title does not indicate the active user of the title prior to performing profile-related actions.

112-05 Access to Account Picker

Test Steps

  1. Sign into a profile and launch the title.
  2. Confirm that the title allows the active user to access the account picker in the title and select a different profile.

Expected Result
Titles must allow users to access the account picker in the title to change the active user.

Pass Examples

  1. The title allows the user to access the account picker in the title.

Fail Examples

  1. The title does not allow the user access to the account picker in the title.

112-06 Handling Profile Change

Test Steps

  1. Sign into a profile and launch the title.
  2. Access the account picker and select a different profile.
  3. Verify that the title reacts appropriately and switches the context of the active user to the new profile.
  4. Repeat steps [1]-[4] for every location in the title where there is access to the account picker.

Expected Result
Titles must allow users to seamlessly change to another user's context.

Pass Examples

  1. The title notifies the user that changing the active user could result in data loss and prompts the user for confirmation prior to proceeding to the account picker.
  2. The title updates appropriately to the context of the new active user.

Fail Examples

  1. The title does not appropriately update to the context of the new active user.

112-07 User Change During Constrained Mode

Configuration: Install the title and use 'xbapp list' to return the application user model IDs (AUMID) and package full name (PFN) for the title.

Test Steps

  1. Sign in profile A and launch the title.
  2. At various locations within the title, press the Xbox button to constrain the title.
  3. Verify the title has entered a constrained state by running 'xbapp query [PFN]'.
  4. While the title is constrained, sign out of Profile A and sign into profile B.
  5. Resume the title by selecting the tile from Home.
  6. Verify that the title reacts accordingly to the new active user.

Expected Result When a title is resumed from constrained mode the title must verify if all previously engaged users are still signed into the console

Pass Examples

  1. An application automatically switches the active user context to Profile B upon resuming.
  2. A game title automatically removes Profile A from the title or reestablishes a new user and uses that new user's state for gameplay.

Fail Examples

  1. Titles do not update to remove profile A from the context as the active user.
  2. A game continues to use Profile A's state for gameplay after a new profile is selected.

112-08 User Change During Suspension

Configuration: Install the title and use 'xbapp list' to return the application user model IDs (AUMID) and package full name (PFN) for the title.

Test Steps

  1. Sign in Profile A and launch the title.
  2. At various locations within the title suspend the title using 'xbapp suspend [PFN]'.
  3. Wait at least 30 seconds for the title to fully suspend and for the suspension to interrupt any HTTP request.
  4. Verify the title has entered a suspended state by running 'xbapp query [PFN]'.
  5. While the title is suspended, sign out of profile A and sign into profile B.
  6. Resume the title by selecting the tile from Home.
  7. Verify that the title reacts accordingly to the new active user.
  8. Enter gameplay with the new active user and verify the user is able to make progress.

Expected Result

  1. When a title is resumed from suspension, the title must verify if all previously engaged users are still signed into the console.

Pass Examples

  1. An application automatically switches the active user context to profile B upon resuming.
  2. A game title automatically removes profile A from the title or reestablishes a new user and uses that new user's state for gameplay.

Fail Examples

  1. Titles do not update to remove profile A from the context as the active user.
  2. A game continues to use profile A's state for gameplay after a new profile is selected.