Instrumenting Xbox One apps

Instrumenting Xbox One app takes only a few easy steps. At this point you should have configured Xbox One in your Suitest account.


Instrumenting Xbox One native apps

Suitest supports UWP apps for Windows 10 Creators Update SDK (Build 15063) or newer written in C# and XAML. Apps created in C++, Visual Basic and XAML should work as well but we do not guarantee full support.

Instrumentation library in production

When inserting the instrumentation library you must make sure, that you don't accidentally release the app to production with Suitest code in it. Suitest code is intended for testing and could damage the user experience of your app's users.

To instrument your Xbox One native app:

  1. Install Suitest instrumentation library for Xbox One directly from your Visual Studio through NuGet package manager.

  2. Call Suitest.Initialize() from OnLaunched method in the App.xaml.cs file.

    protected override void OnLaunched(LaunchActivatedEventArgs e) 
    {
    
        // ... your code
    
        #if SUITEST
        SuitestLibrary.Suitest.Initialize();
        #endif
    }
    
  3. Update the package manifest:

    In Visual Studio, navigate to your apps project manifest (Package.appxmanifest) then select the Capabilities tab, and check Internet (Client).

  4. Create a dedicated configuration for building your app with the instrumentation library enabled.

Instrumenting Xbox One apps written in HTML5

Suitest supports Xbox One apps built in HTML5. To instrument your HTML5 Xbox One app depending on context:

Local app context

Important: If you have Xbox One with OS version 10.0.17763.2023 please skip to this version's specific section.

  1. Insert the following code into every page of your application that you want to test. For best results put it as the first script element in your HTML file right after the opening tag:

    <script src="/suitest.js"></script>
    

    The JavaScript (suitest.js) file is our instrumentation library. It is automatically uploaded to the app's installation folder on the device. If this file is not present in the app's folder there will be no connection between the app and Suitest (you will not see the Suitest badge on the screen of the device).

  2. Whitelist Suitest domains in the Package.appxmanifest under the Content URIs section:

    Whitelist - http://*.suite.st and https://*.suite.st
    Whitelist - http://*.suite.st and https://*.suite.st
  3. Update the package manifest:

    In Visual Studio, navigate to your apps project manifest (Package.appxmanifest) then select the Capabilities tab, and check Internet (Client).

Web app context

  1. Copy and paste the code snippet from the Suitest configuration page into every HTML file of your application. For best results put it as the first script element in your HTML file right after the opening tag. For apps hosted on HTTPS replace http with https in the code snippet.

  2. In the Package.appxmanifest under the Content URIs do the following:

    • Whitelist ms-appx-web:/// or app's domain name if your app is hosted.
    • Set WinRT Access to All.
    Whitelist - ms-appx-web:///
    Whitelist - ms-appx-web:///
  3. Update the package manifest:

    In Visual Studio, navigate to your apps project manifest (Package.appxmanifest) then select the Capabilities tab, and check Internet (Client).

Uploading app package

Once you have instrumented the code create an app package using your Visual Studio and archive it to a .zip file. Your ZIP file should have the following content:

Xbox One ZIP package content
Xbox One ZIP package content

Upload the created ZIP file to Suitest at the app configuration page. Suitest will automatically install or update the package on the device as necessary when you try running the app on this device.

If you use Suitest Network API you can also send the package with an API request. Suitest will automatically install or update the package on the device as necessary when you try running the app on this device.

Managing native app builds

It is important to exclude the Suitest instrumentation library from your production build but to keep it in the instrumented build that you are going to upload to Suitest.

To achieve this comfortably it is best to create a dedicated build configuration. In Visual Studio 2017 you can do this in the following way:

  1. Create a new configuration in the Configuration Manager and copy the settings from your "Release" configuration. Change the name of the copied configuration to "Suitest" (or to any other name you like).

  2. Open project properties and on the Build tab select "Suitest" in the Configuration field. Then append ;SUITEST to the contents of Conditional compilation symbols field.

  3. Unload project (right click project name in Solution Explorer and choose Unload Project).

  4. Open your .csproj file in the text editor and locate the Suitest package reference. It should look approximately like this:

    <PackageReference Include="Suitest">
        <Version>1.*.*</Version>
    </PackageReference>
    

    Replace the above with (make sure to always use the latest instrumentation library version):

    <Choose>
        <When Condition=" '$(Configuration)' == 'Suitest' ">
            <ItemGroup>
                <PackageReference Include="Suitest">
                    <Version>1.*.*</Version>
                </PackageReference>
            </ItemGroup>
        </When>
    </Choose>
    
  5. Save and close the .csproj file and reload the project (right click on the project name and select Reload Project).

After you have done this only builds created with the Suitest configuration will contain the instrumentation library. All other builds will be completely clean of the instrumentation code.

Instrumenting HTML5 local context app for OS version 10.0.17763.2023

Due to issues with Xbox API for this OS version we are unable to upload our instrumentation library automatically. To work around this issue, please do the following:

  1. Download our instrumentation library.

  2. Insert the file into your Visual Studio project folder.

    Visual Studio project folder - suitest.js inserted
    Visual Studio project folder - suitest.js inserted
  3. In properties of the suitest.js file change the property Package Action so that it is set to Content.

    suitest.js > Properties > Package Action > Content
    suitest.js > Properties > Package Action > Content
  4. Insert the following snippet into every HTML page which you would like to test. The snippet assumes that the file suitest.js is place in the root folder of your project, if that is not the case please correct the path in src.

    <script src="/suitest.js"></script>
    
  5. Whitelist Suitest domains in the Package.appxmanifest under the Content URIs section:

    Whitelist - http://*.suite.st and https://*.suite.st
    Whitelist - http://*.suite.st and https://*.suite.st
  6. Update the package manifest:

    In Visual Studio, navigate to your apps project manifest (Package.appxmanifest) then select the Capabilities tab, and check Internet (Client).