Client-side use of Xbox services user privileges

Use this topic to check and resolve user privileges that are available on Xbox services, and to determine the upsell system on an Xbox console or Windows PC.

Table of contents

• Prerequisites
• Client-side handling and the user experience for privileges and upsell
• Best practices for app-side privilege handling
• Testing privilege-based access control in your apps
• Privilege IDs to check

Prerequisites

To handle user privileges in your Xbox services client app, configure your title for authentication with Xbox services. For more information, see Authentication and sign-in overview and Xbox services user privileges overview.

Client-side handling and the user experience for privileges and upsell

Client apps are subject to Xbox Requirements (XR) that require privileges to control a portion of the title, such as XR-045: Xbox services and Account Privileges. For more information, see Policies and Xbox Requirements.

For apps that are controlled by privileges, you can use APIs. XUserCheckPrivilege determines whether a user has a specific privilege. XUserResolvePrivilegeWithUiAsync displays a resolution UI that's required user privileges. This presents the necessary UI to explain or upsell if the user doesn't have the privilege.

As an example, an app that's subject to the XPRIVILEGE_MULTIPLAYER_SESSIONS privilege has the following flow.

1. The user sees an option to start a multiplayer session and attempts to start a match by selecting the appropriate option in the UI.
2. The app checks the "hint" by using the XUserCheckPrivilege API.
   • If it's there, assume the user has the privilege and proceed.
   • If it's not there, go to the next step.

   Note

   Xbox services APIs return a status code of 403 (HTTP_E_STATUS_FORBIDDEN) when access is denied to a feature because of a missing privilege in the XToken. All endpoints of Xbox services enforce privilege-based access control as appropriate.

3. In response to the failure code, the title app then calls XUserResolvePrivilegeWithUiAsync with the appropriate privilege ID for the one that you're trying to resolve. This function calls Xbox services to see if the user has the privilege, and then it tells the user why the action failed or show the user the UI to resolve it. The following might result from this API call.
   • Show the UI that's related to the user's enforcement status that was issued by Xbox services policy and enforcement moderators.
   • Show the UI that's related to their parental controls.
   • Promote an applicable subscription service such as an Xbox Live Gold subscription.
   • Return the result to the title (either a success or a failure, with a reason).

   Note

   If Xbox services or the network are unreachable, XUserResolvePrivilegeWithUiAsync fails. This failure should be treated as if the user didn't possess the privilege.

4. On return from XUserResolvePrivilegeWithUiAsync:
   1. If failure is returned, the title should allow the user to keep clicking the button, because (for example) the user's bans might lapse, or parental controls might change.
   2. If success is returned, then the user has been remediated, and your title might attempt the action again. The user's token will contain the needed privileges as part of the remediation performed by XUserResolvePrivilegeWithUiAsync.

Example code

Use the following code example to ensure that you're checking for a user's multiplayer privileges before accessing multiplayer functionality in your title.

XUserPrivilegeDenyReason reason;
bool hasPrivilege = false;

// check the Multiplayer (254) privilege
HRESULT hr = XUserCheckPrivilege(userHandle, XUserPrivilegeOptions::None, XUserPrivilege::Multiplayer, &hasPrivilege, &reason);

// error with the user such that we can't yet check privileges
if(E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED == hr)
{
      asyncBlock.callback = [](XAsyncBlock *async)
      {
         HRESULT hr = XUserResolveIssueWithUiResult(async);
         // if SUCCEEDED(hr), the issue is resolved, try the privilege check again
         // if FAILED(hr), the issue is not resolved, the title should deny access to the user, and perhaps try again later
      };

      hr = XUserResolveIssueWithUiAsync(userHandle, nullptr, &asyncBlock);
}

// user doesn't have the requested privilege, try to resolve the issue
else if(!hasPrivilege)
{
      asyncBlock.callback = [](XAsyncBlock *async)
      {
         HRESULT hr = XUserResolvePrivilegeWithUiResult(async);
         // if SUCCEEDED(hr), all privilege issues are now resolved, the user has the privilege,
         //    and the title should continue. It is not necessary to call XUserCheckPrivilege again.
         // if FAILED(hr), the user did not resolve all privileges, the title should deny access to the user and perhaps try again later
      };

      hr = XUserResolvePrivilegeWithUiAsync(userHandle, XUserPrivilegeOptions::None, XUserPrivilege::Multiplayer, &asyncBlock);
}
else if(hasPrivilege)
{
      // the user has the privilege, continue!
}

Best practices for app-side privilege handling

When handling user privileges in your title, ensure that you're employing the following best practices.

Frequency for resolving privileges in app

For privilege checks, the requirement is to ensure once per launch that the user has the appropriate privileges and resolve them. We recommend checking every logical session and discrete action.

Your definition of a session might vary widely depending on the usage of your app.

The following are examples of best practices.

• For media streaming apps, such as video players, resolve privilege checks once per selection of the Play button (stream start), or at the start of a playlist (for multiple streams, such as a music playlist).
• For messaging apps, check privileges once for the first message that's sent.
• For multiplayer apps that are using third-party match services, resolve privilege checks every session (match) start.

Never assume the subscription tier of a user

Historically, claims from Xbox 360 provided information about the subscription tier of the user (such as Xbox Live Gold status). This claim was deprecated with the introduction of the Xbox One family and later. Ensure that you're making your decisions by using privileges. The user's tier, or how they acquired a privilege, should be opaque to the app.

Offline mode

If XUserCheckPrivilege returns that the service is down or unreachable, then treat this result as if the privilege check returned a failure. By doing so, your app has a fail-safe to keep it XR-compliant.

Targeting the correct user

We recommend always referencing the acting user if another user isn't specified for the privilege check. If your app supports designating a user, use the currently designated user.

For example, there are three users logged in: Bill, Bob, and Beth. Your app supports switching between "active users" to designate whose recommendations, history, and settings to use. Beth launched your app. When your app is running, the active user switched Bob. Bob has a separate profile, set of recommendations, and history. Call to XUserCheckPrivilege to initiate a privilege check for Bob.

Checking without UI, or with the UI out of focus

There are cases in which your app can't present a modal, so the UX for a privilege check is blocked. For example, when the app is playing music in the background, or during incoming calls while the Skype app is running in the background. However, your app must still check for a privilege. We recommended calling XUserCheckPrivilege. XUserCheckPrivilege returns the current permission state of the user, or returns an applicable failure, rather than presenting the UI. Your app can affect the user, as defined by their privileges, and inform the user of the privilege check when your app regains focus.

Conversely, your title can show the user non-modal error information, or another UX, as desired. When it's appropriate to show the user a blocking UX, call to XUserResolvePrivilegeWithUiAsync again to show the proper UX—such as upsell or enforcement status.

Testing privilege-based access control in your apps

Privileges are computed based on the following inputs.

• Effective subscription entitlements of the user
• Effective privilege entitlements of the device
• Effective privilege entitlements of the client platform-
• Effective privilege entitlements of the current title
  • It's possible to package a title with a collection of privileges so that all users of the apps automatically get these privileges for use in the running app. If your title requires this feature, contact your Microsoft account manager.
• Parental controls for parents to decide what privileges to add or remove for the children in their family
• Xbox moderators might ban privileges for users or devices that have been identified for abuse of the service

Managing and Checking User Privileges and Permissions

User privacy settings can be accessed in two ways.

• On PC:
  Go to https://aka.ms/XboxPrivSettings.
• On Xbox:
  Go to Settings -> General -> Online safety & family -> Privacy & online safety -> Xbox privacy

Privileges checked with XUserCheckPrivilege

XUserPrivilege::CrossPlay

• Description: Allows a user to participate in a gameplay session with other real-world players who are not signed into Xbox services in scenarios such as: Synchronous player-vs-player gameplay in the same session, asynchronous turn-based gameplay, Team-based gameplay, User-initiated matchmaking, Sending or accepting invitations, Join-in-progress sessions.
• Requirement: XR-045 - Xbox services and Account Privileges
• Privilege ID: 185
• Setting on PC: You can play with people outside of Xbox services
• Setting on Xbox: You can join cross-network play

XUserPrivilege::Sessions

• Description: Allows a user to participate in connected single-player experiences in shared environments or in scenarios where a title is a hybrid free to play and paid multiplayer title and uses this privilege to gate those experiences Xbox consoles. Single player experiences must not have any features covered under privilege 252 or 254 (Communications and Multiplayer, respectively). Use of this privilege is a title capability that requires platform approval.
• Requirement: XR-045 - Xbox services and Account Privileges
• Privilege ID: 189
• Setting on PC: You can join multiplayer games
• Setting on Xbox: You can join multiplayer games

XUserPrivilege::Multiplayer

• Description: Allows a user to join online multiplayer gameplay sessions with real-world users (not bots) in scenarios such as: Synchronous player-vs-player gameplay in the same session, asynchronous turn-based gameplay, Team-based gameplay, User-initiated matchmaking, Sending or accepting invitations, Join-in-progress sessions. Note this privilege does not pertain to local multiplayer games run on the same device.
• Requirement: XR-045 - Xbox services and Account Privileges
• Privilege ID: 254
• Setting on PC: You can join multiplayer games
• Setting on Xbox: You can join multiplayer games

XUserPrivilege::UserGeneratedContent

• Description: Allows a user to see other users' UGC online, download other users' UGC, or share their own UGC online. This does not restrict usage of previously downloaded UGC.
• Requirement: XR-045 - Xbox services and Account Privileges
• Privilege ID: 247
• Setting on PC: You can see and upload community creations
• Setting on Xbox: You can see and upload community creations

XUserPrivilege::SocialNetworkSharing

• Description: Xbox consoles Only: Allows a user to share information, including game progress, Kinect-generated content, game clips, and so on outside of the Xbox network.
• Requirement: XR-045 - Xbox services and Account Privileges
• Privilege ID: 220
• Setting on Xbox: You can share outside of Xbox

XUserPrivilege::Communications

• Description: Allows a user to communicate with any other Xbox services users through voice or text.
• Requirement: XR-045 - Xbox services and Account Privileges
• Privilege ID: 252
• Setting on PC: Others can communicate with voice, text or invites
• Setting on Xbox: Others can communicate with voice, text or invites

Permissions checked with XblPrivacyCheckPermissionAsync

Titles may also use XblPrivacyBatchCheckPermissionAsync when permissions need to be checked against multiple users and XblPrivacyCheckPermissionForAnonymousUserAsync when checking permissions against a non-Xbox services user.

XblPermission::CommunicateUsingText

• Description: Check whether or not the user can send a message with text content to the target user. This value does not change if the player has muted the target user. Use CommunicateUsingVoice instead. This value will be false if for example you have set your comms to friends only and the target is not a friend. This value will be false if for example if the target user has blocked you. This value will be false if for example you have set your comms settings to Blocked.
• Requirement: XR-015 - Managing Player Communication
  • When checking another Xbox services user
    • Setting on PC: Others can communicate with voice, text or invites
    • Setting on Xbox: Others can communicate with voice, text or invites
  • When checking an anonymous user
    • Setting on PC: You can communicate outside of Xbox services with voice & text
    • Setting on Xbox: You can communicate outside of Xbox with voice & text

XblPermission::CommunicateUsingVoice

• Description: Check whether or not the user can communicate using voice with the target user. This will be false if the player has muted the target user.
• Requirement: XR-015 - Managing Player Communication
  • When checking another Xbox services user
    • Setting on PC: Others can communicate with voice, text or invites
    • Setting on Xbox: Others can communicate with voice, text or invites
  • When checking an anonymous user
    • Setting on PC: You can communicate outside of Xbox services with voice & text
    • Setting on Xbox: You can communicate outside of Xbox with voice & text

Testing privileges that are provided by subscriptions

You can create test accounts with an Xbox Live Gold subscription by using Partner Center. Use these accounts to test your privilege logic for privileges that are offered through an Xbox Live Gold subscription.

You can purchase other subscriptions by using your test account on a development client.

You can't directly purchase retail Xbox Live Gold subscriptions by using a test account that's created through Partner Center. Instead, you can purchase a developer-specific version of Xbox Live Gold that only applies to development scenarios.

Testing privileges that are provided by the running title

If you want to set up an app to automatically issue privileges when users are in the app, contact your Microsoft account manager. Testing this scenario requires configuring your app for Xbox services authentication and running the app with users signed in.

Testing privileges that are removed by parental control

To test your privilege logic with privileges that can be removed by using parental controls (such as XPRIVILEGE_COMMUNICATIONS), set up family accounts on the client device. Parents or guardians might use the device to restrict privileges of the children in their family.

It's also possible for a user to restrict privileges on their own account. We recommend using this method to test scenarios that require that a user's privileges be restricted.

Privilege IDs to check

Your title must check the following privilege IDs. For more information, see XR-045: Xbox services and Account Privileges.

For more information about available privileges, see XUserPrivilege.

Privilege computation logic

Privileges are computed independently for each user that's simultaneously signed in on a console or other device. Privileges are added from the effective entitlements of the user, the device, the title that's currently running, and the platform. Then privileges are removed for each user based on parental controls, Xbox services policy and enforcement status, and the guest status of each user.

Effective entitlements might result from subscriptions that are purchased by the user, purchased by other users logged in at the same time, or subscriptions that are directly associated to a device. Effective entitlements might also result from promotional offers, such as "Free multiplayer weekend" events.

Privilege entitlements that result from the device type

Certain types of devices (such as Xbox One family consoles and Xbox Series consoles, Windows PC, or mobile) automatically grant a collection of privileges to any user that connects to Xbox services from the platform.

Effective privilege entitlements that result from subscriptions

Subscription products might provide a collection of privileges to applicable users. The following scenarios are ways a user is effectively granted subscription-based privileges.

• The user has purchased the subscription product.
• Another active user on the same device has purchased the subscription product.
• The subscription product is associated to the device that the user is currently using.

Starting with Xbox One, the Xbox Live Gold subscription follows this logic. It's possible to associate a Xbox Live Gold subscription to a device, and all users on the device are effectively entitled to privileges that are associated to the Xbox Live Gold subscription tier. Any user, including sponsored guests, that are simultaneously active on a device with a user who purchased a Xbox Live Gold subscription are effectively entitled to the privileges that are associated with the Xbox Live Gold subscription.

Partner subscriptions might also be used to issue privileges to an active user. In addition, privileges that are associated to a partner subscription might be issued only when a specific participating title is running.

Promotional entitlements

Promotional entitlements add privileges for a limited period to users who meet certain dynamic criteria. For example, a promotion might offer the multiplayer privilege to certain users for the duration of a weekend. Historical promotions such as a "Free Xbox Live Gold Weekend" follow the model of promotional entitlements.

Privileges that are removed for sponsored guest accounts

Sponsored guests are guest accounts who are signed in with Xbox services. Sponsored guests only exist in the presence of at least one other active user on the client device, such as a split-screen multiplayer game with only one user signed in. These accounts are authenticated users and get a token like any other authenticated user. Sponsored guests do have privileges, but some privileges are withheld for guest users, regardless of the sponsored guest's effective entitlements or the app that's currently running.

To check privileges for sponsored guests, call XUserCheckPrivilege. This doesn't attempt resolution. You shouldn't need to display a resolution UI, and you shouldn't need to call XUserResolvePrivilegeWithUiAsync, because sponsored guests can't be "resolved". Unlike active Xbox accounts, sponsored guests don't have any path to make purchases, incur enforcement action, or have an otherwise unique set of privileges or restrictions.

If a user isn't currently signed in (which is the case with a "pure guest"), no token is issued for the user. This means that no effective privileges are computed for any user on the device.

XR-045 requires that your title check the privilege 202 by using XPRIVILEGE_SOCIAL_NETWORK_SHARING, or XUserPrivilege::SocialNetworkSharing. This is one of the privileges that are removed for guests.

Online safety and Microsoft enforcement

Xbox services policy and enforcement moderators might remove privileges from abusive users or devices.

Parental controls

Parents can remove privileges from child accounts that are in their family, regardless of the child's subscription or the current running title. This is controlled by using the Xbox One, Xbox 360, or Xbox.com clients.

Privileges for Xbox Live Gold subscribers

Policies for privilege entitlements for a particular subscription are dynamic and will change over time. Keep in mind that even if a subscriber is entitled to a privilege, that subscriber might lose that privilege because of parental control changes or enforcement policies.

XR-045 requires that your title check the privilege 254 by using XPRIVILEGE_MULTIPLAYER_SESSIONS, or XUserPrivilege::Multiplayer. This is one of the privileges that Xbox Live Gold subscribers are entitled to.

Partner subscriptions and privileges

It's possible to configure partner subscriptions to provide a collection of Xbox services privileges. Partner subscriptions are only used to compute the privileges of a user when the user is logged in to apps that have been explicitly associated to the subscription.

To set up partner subscriptions, contact your Microsoft account manager.

Partner subscriptions can be tested in development sandboxes before they're released. Only users and devices that are authorized to use these development sandboxes can purchase these subscriptions.

Free-to-play (F2P) titles and multiplayer privileges

For titles that are specifically configured to operate in a free-to-play (F2P) model, the XPRIVILEGE_MULTIPLAYER_SESSIONS / XUserPrivilege::Multiplayer privilege should be checked, as usual. However, with this setup, users will have multiplayer privilege whether they have an Xbox Live Gold subscription or not. This privilege will only be denied if a user is banned/blocked, or age-restricted in some way. Use of this privilege is a title capability that requires platform approval. Please work with your Microsoft manager or DPM to enable this functionality for your title.

Hybrid titles and multiplayer privileges

For titles that are specifically configured to operate in a hybrid model -- that is, titles which contain multiplayer scenarios that require a paid subscription but also contain scenarios that can be played for free -- the privilege check process is slightly different.

For content which requires a paid subscription, the XPRIVILEGE_MULTIPLAYER_SESSIONS / XUserPrivilege::Multiplayer privilege should be checked. However, for free multiplayer scenarios, the XPRIVILEGE_SESSIONS / XUserPrivilege::Sessions privilege should be checked instead. This privilege will only be denied if a user is banned/blocked, or age-restricted in some way. The Multiplayer privilege will deny for these reasons as well, but also requires a paid subscription to be granted. Use of this privilege is a title capability that requires platform approval. Please work with your Microsoft manager or DPM to enable this functionality for your title.

See also

Policies and Xbox Requirements

XUserCheckPrivilege

XUserPrivilege

XUserPrivilegeDenyReason

XUserPrivilegeOptions