Enabling license testing

Article
11/09/2023

This article describes how to set up a development build to be licensable in order to test licensing-related scenarios.

Relevant scenarios and APIs

The following APIs will require the set up described in this page in order to test properly:

API	Usage
XStoreQueryGameLicenseAsync	Querying the characteristics of a trial or that the game is licensed by disc
XStoreQueryLicenseTokenAsync	Generating a valid license token for service-based validation, see Using License Tokens
XStoreQueryAddOnLicensesAsync	Returning add-on licenses (i.e. for durable without package) attached to a digital game license
XStoreRegisterGameLicenseChanged	Registering to detecting a license change (e.g. trial to full license)

Context

In retail scenarios, a game must have a license to be played. This is accomplished by a license request, which is satisfied either by a disc or by a successful license request to Microsoft services. A license is granted if the account is entitled to the product via direct or satisfying purchase (e.g. from a subscription or bundle). Licenses can also be granted in sharing scenarios, more information can be found in Product sharing model for games.

Development scenarios do not follow this behavior by default:

Loose builds (Visual Studio F5 deploy, xbapp/wdapp register/deploy)
Local package builds (makepkg, xbapp/wdapp install)

These builds will launch without any licensing checks or related configuration. Most XStore APIs will still work with the exception of anything related to licensing.

In order to configure a build to behave as licensable, the correct identity values must be applied to the MicrosoftGameConfig (described in Enabling XStore development and testing).

Then the following steps must be taken:

Note content ID specific to the game or DLC
Apply content ID to build, as appropriate to the build type
Console only: Note and apply EKBID to build

Then for each account running the build, an entitlement must be acquired by purchasing the product from the appropriate Store for the platform.

Get ContentID

This can be found in the Packages page, after Showing details:

Packages page on Partner Center

Note

The Content ID between sandbox and retail can be different, be aware if a retail version of the game has been installed and you wish to work in sandbox. Content ID will also be different if regional packages are involved.

Console

This can be found for a package installed from the Store running xbapp list /d (or xbapp listdlc /d for DLC) in the Gaming Command Prompt.

Registered Applications by Package Full Name:

   41336MicrosoftATG.InGameStoreXS_2020.7.27.0_neutral__dspnxghe87tn0  
        Install  
        Drive: Development  
        Size: 0.28 GB.  
        ContentId: {2797FA46-A93B-494C-AD80-B67C9FCA939F}  
        ProductId: {4C544E39-5130-3044-C057-5A3446536A00}  
        EKBID: {37E80840-6BE0-46F8-8EDB-92F877056087}  
        DisplayName: ATG In-Game Store Sample  
        41336MicrosoftATG.InGameStoreXS_dspnxghe87tn0!Game

PC

This is found in a registry location once the package is installed from the Xbox App or Microsoft Store: Computer\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Store\ContentId

Apply content ID to build

For loose builds add the following section in MicrosoftGameConfig:

  <DevelopmentOnly>
    <ContentIdOverride>2797FA46-A93B-494C-AD80-B67C9FCA939F</ContentIdOverride>
    <EKBIDOverride>00000000-0000-0000-0000-000000000001</EKBIDOverride>
  </DevelopmentOnly>

For package builds, pass in the content ID to makepkg, e.g.:

makepkg pack /v /f chunks.xml /d Gaming.Xbox.XboxOne.x64\Layout\Image\Loose /pd ./output /contentid 2797FA46-A93B-494C-AD80-B67C9FCA939F

Package builds made without a /contentid will apply any available ContentIdOverride in the MicrosoftGameConfig when installed from local source.

Builds installed from Store (sandbox or retail) will always have the proper content ID (as seen in Partner Center) applied.

Apply EKBID to build (only applicable to console)

The EKBID (Escrow Key Blob ID) is only needed to be set for console to make the build licensable. For most scenarios, it simply needs to be overridden from the default test value of all zeroes or 33EC8436-5A0E-4F0D-B1CE-3F29C3955039.

This is done by running the following command.

xbapp setekbid <package full name> {<GUID that is not all zeroes or 33EC8436-5A0E-4F0D-B1CE-3F29C3955039>}

e.g.

xbapp setekbid 41336MicrosoftATG.InGameStoreXS_2020.7.27.0_neutral__dspnxghe87tn0 {00000000-0000-0000-0000-000000000001}

This is not relevant to PC (i.e. no wdapp setekbid).

Trials and EKBID

For trials, the actual EKBID must be applied. This can be seen from the xbapp list /d output seen above for a build installed from Store. More information can be found in Implementing trials for your game.

Ensure test account is entitled to game in the sandbox

The easiest way to do this is to go to the game's Store page directly through protocol activation, as products published only to sandbox may not be searchable. The development console or PC must be set to the sandbox where the game is published. See Xbox services Sandboxes overview and particularly for PC Switching sandboxes properly for store operations for more details.

Once signed in properly, use the store protocol link to reach the Store page:

On console:

Use Gaming Command prompt:

xbapp launch ms-windows-store://pdp/?productid=<storeID>

On PC:

In Run box (⊞Win +R) or in a web browser

msxbox://game/?productId=<storeID> (to show game in Xbox App)

ms-windows-store://pdp/?productid=<storeID> (to show game in Microsoft Store)

Once on the Store page, select Buy or Get to acquire a license for the game for your test account. This should start the package download and installation, but if you are simply interested in iterating with local builds, you can cancel.

IMPORTANT: This must be done for each and every account that runs the build and expects license-related XStore API to work.

DLC

In order for local DLC to be licensable, the content ID must be applied to makepkg and xbapp setekbid set to something other than the default values. Only the DLC needs to be configured for licensing, not the base game.

This is relevant to the following API:

More details can be found here:

Manage and license downloadable content (DLC)

How to use a durable without a package

Partager via