Share via

XR-052: User State and Title-Save Location, Roaming and Dependencies

  • Article

Titles must associate progress, saved state, preferences, achievements, and other rewards with the user(s) who have recorded that progress, chosen the preferences, or earned the rewards. Titles accomplish this by properly handling user-change notifications. Titles must avoid saving state for users who are no longer signed in. Game save data must not have any dependencies on shared content or local storage.

For games that use the same TitleID across platforms, devices and/or console generations, game save progress must roam when the user is signed into the Xbox network as follows:

  • Within the same platform (Xbox consoles).
  • Within devices on the same platform (e.g., Xbox One and Xbox One S).
  • Across generations in the device platform (e.g., Xbox One and Xbox Series X|S).
  • Across PCs in the Windows platform (e.g., between two different PCs).
  • Across PCs in the Windows platform and Xbox console platforms (e.g., Windows and Xbox Series X|S) game save roaming is not required but is recommended to support the player's experience.
  • For non-Microsoft platforms (e.g., iOS, Android, Switch, PlayStation®) game save roaming is not required but is recommended to support the player's experience.

More Information

Shared content is content that may not be present on a roamed console, such as a game add-on, when a game save is loaded. The content might not be available because it has not been downloaded by or is not owned by the current signed-in user.

APIs and services for saving player data varies by SDK:

GDK/SDK Roaming Save Required? Supporting API
GDK Required XGameSave API in xgamesave.h
ERA using the XDK Required ConnectedStorage API in Windows.Xbox.Storage namespace
Windows SDK - UWP Required GameSaveProvider API in Windows.Gaming.XboxLive.Storage namespace
  • For information on saving game state using the GDK, read Game Saves.
  • For information on managing game state and saving data using the GDK, read the Xbox Game Life Cycle.

A key aspect of this requirement pertains to handling situations in which the primary user of a title changes while the title is active, suspended, or terminated. The title's "primary user" changes when the title is activated from the Home screen of a user other than the one who activated the title last, and other users on the console can sign in or out at any point in the title's lifetime. Titles are required to provide an experience that is appropriate to the primary user and the other users on the console and to save title-state information for each user. Because users can sign in to (and out of) the Xbox network outside the context of any given title, titles must be robust in the case of users changing. For instance, titles should avoid using the tokens or identifiers of users who are no longer signed in.

Titles must not cause unintentional loss of user data.

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

Test Cases Applicable to GDK Simplified User Model Applicable to GDK Advanced User Model, ERA and UWP MUA
052-01 User Sign-In and Sign-Out No Yes
052-02 User Change During Suspended or Terminated State No Yes
052-05 Correct User Association Yes Yes
052-06 Cloud Storage: Roaming Yes Yes

052-01 User Sign-In and Sign-Out

Configuration:
This test case only applies to console. For Xbox devices, the xbuser command-line utility can be used to test users being signed in or out at anytime.

  • xbuser signin /i:\<user ID> [/p:password]
  • xbuser signin /e:\<email> [/p:password]
  • xbuser signout /i:\<user ID> [/p:password]
  • xbuser signout /e:\<email> [/p:password]

Test Steps

  1. Ensure that Profile A and Profile B have set the console to Home.
  2. Ensure that Profile A has save data including game progress and user preferences.
  3. Ensure that Profile B does not have any save data.
  4. Sign into Profile A and launch the title. Ensure all save data and preferences have been preserved by visiting all areas of the title, including but not limited to:
    • Single-player or multiplayer game sessions.
    • Menus.
    • Video or audio playback.
  5. Sign out of Profile A and sign into Profile B.
  6. Verify that the title correctly updates the user progress, saved state, preferences, achievements, or other awards of Profile B by revisiting all areas of the title validated in step 4.
  7. Begin gameplay to create save progress, and alter user preferences for Profile B.
  8. Terminate and re-launch the title and verify that the save data from step 7 is reflected accurately.
  9. Sign out of Profile B.
  10. Delete save data 'Everywhere' from Profile A and repeat steps 4-8.

Expected Result
Changes to the primary user should be treated appropriately by the title.

Pass Examples

  1. User progress, saved state, preferences, achievements, or other awards are associated with the correct user following a user change.

Fail Examples

  1. The title incorrectly associates user progress, saved state, preferences, achievements, or other awards with a user following a user change.
  2. The title continues to award save data to the first user.
  3. A new user can alter a prior user's save data, state or profile after they have signed out.

052-02 User Change During Suspended or Terminated State

Configuration:
This test case only applies to console. To test process lifetime management (PLM) state transitions, these commands are useful in the GDK:

  • xbapp suspend [package full name]
  • xbapp resume [package full name]

Note: If you prefer working with a GUI instead of the command prompt, consider using Xbox One Manager. It is a desktop application that allows you to manage users and test PLM events on your console as well as other common tasks.

Test Steps

  1. Sign in to a profile and launch the title.
  2. Visit all areas of the title, including but not limited to:
    • Single-player or multiplayer game sessions
    • Menus
    • Video or audio playback
  3. Suspend the title by running xbapp suspend [package full name].
  4. Wait at least 30 seconds for the title to fully suspend and for the suspension to interrupt any HTTP request.
  5. Sign out the primary user and sign in as a different user.
  6. Launch the title using the new user and attempt to continue from the previous user's location.
  7. Repeat Steps 1-6 for all areas of the title.
  8. Repeat Steps 1-7 but terminating the title rather than suspending it.

Expected Result
Changes to the primary user should be treated appropriately by the title.

Pass Examples

  1. The title state upon launching with a different user is contextually appropriate for the type of title.
  2. User progress, saved state, preferences, achievements, or other awards are associated with the correct user following a user change.

Fail Examples

  1. The title incorrectly associates user progress, saved state, preferences, achievements, or other awards with a user following a user change.
  2. The title continues to award save data to the first user.
  3. A new user can alter a prior user's save data, state or profile after they have signed out.

052-05 Correct User Association

Test Steps

  1. Sign in to a profile and Launch the title.
  2. Progress into gameplay and save game progress.
  3. Terminate the title.
  4. Sign out of the profile from Step 1 and sign in to a new profile.
  5. Launch the title and attempt to access saved progress.

Expected Result
Progress saved for the original user must not be visible/accessible to the new profile.

Pass Examples

  1. Only saved progress associated with the new profile in step 4 is shown in step 5.

Fail Examples

  1. The title allows a new profile to load a different profile's saved progress.

052-06 Cloud Storage: Roaming

Devices Needed:

  • Xbox One
  • Xbox One S
  • Xbox One X
  • Xbox Series X Dev Kit (using Xbox Series X|S retail console mode)
  • 2 PCs

Test Steps

  1. Sign in to an Xbox profile on device A and launch the title.
  2. Begin gameplay and make save progress (if possible, create a settings save by changing or adding a new setting configuration).
  3. Exit the title.
  4. Sign in on a second device from the same platform/generation (e.g., Xbox Series S and Xbox Series X, Xbox One and Xbox One S and a second PC) that was used in Step 1 with the same profile used in Step 1.
    • Launch the same title from Step 1 and verify that all saved games and any settings and/or configuration files can be accessed and loaded correctly and they don't have any dependencies on shared content.
  5. For games using the same TitleID on the same platform across generations (e.g., Xbox One and Xbox Series X|S), repeat step 4.
  6. For PC games using the same TitleID on the Windows platform, repeat step 4.
  7. If supported, for games using the same TitleID across platforms (e.g., Windows and Xbox Series X|S):
    • Launch the same title from Step 1 on the other supported platforms and verify that all saved games and any settings and/or configuration files can be accessed and loaded correctly and they don't have any dependencies on shared content.

Expected Result
Title-save progress must be associated with a user profile and must roam between like devices/platforms when the user is signed into Xbox services. For games using the same TitleID on the same platform across generations, game save data must roam between these platforms. For PC games using the same TitleID on the Windows platform, game save data must roam between different PCs. Game save data must not have any dependencies on shared content.

Pass Examples

  1. Game saves and associated settings files can be downloaded successfully on a second console on the same console platform/generation (e.g., Xbox Series S and Xbox Series X or Xbox One and Xbox One S).
  2. Game saves and associated settings files can be downloaded successfully on a second PC on the Windows platform.
  3. For console games that share the same TitleID on the same platform across generations (e.g. Xbox One and Xbox Series X|S), saves and associated settings files can be roamed between these devices.
  4. Game save data does not have any dependencies on shared content.

Fail Examples

  1. Game saves and associated settings files cannot be downloaded successfully on a second console on the same platform/generation (e.g., Xbox Series S and Xbox Series X or Xbox One and Xbox One S).
  2. Game saves and associated settings files cannot be downloaded successfully on a second PC on the Windows platform.
  3. For console games that share the same TitleID on the same platform across generations (e.g. Xbox One and Xbox Series X|S), saves and associated settings files cannot be roamed between these devices.
  4. The saves in the cloud are not recognized by the title on first launch, and through no user interaction, are subsequently overwritten on the second device.
  5. Game save data has dependencies on shared content.