Xbox Live App Macoscleverwars



Last month, a post from the GDC 2019 scheduling website hinted that Microsoft was preparing to launch a new software development kit that would sync your Xbox Live data to any compatible iOS app.

-->

Note

The Xbox Live Unity plugin is only recommended for members of the Xbox Live Creators Program, since currently there is no support for achievements or multiplayer. See Choosing an Xbox Live developer program.

With the Xbox Live Unity Plugin, adding Xbox Live support to a Unity game is easy, giving you more time to focus on using Xbox Live in ways that best suit your title.

  • Setting up your Xbox One console. Activate Developer Mode on your Xbox One. Download the app, get the activation code, and then enter it into the Manage Xbox One consoles page in your Partner Center app developer account. For more information, see Xbox One Developer Mode activation. Open the Dev Mode Activation app and select Switch and restart.
  • Microsoft’s Xbox app update for iOS and iPadOS is now live, allowing Xbox One owners to stream games to their devices. A new Xbox app is available in the App Store that includes a remote play.

This article shows how to set up the Xbox Live plugin in Unity.

Prerequisites

You will need the following before you can use Xbox Live in Unity:

  1. An Xbox Live account.
  2. Enrollment in the Partner Center developer program.
  3. Windows 10 Anniversary Update or later
  4. Unity versions 5.5.4p5 (or newer), 2017.1p5 (or newer), or 2017.2.0f3 (or newer) with Microsoft Visual Studio Tools for Unity and Windows Store .NET Scripting Backend.
  5. Visual Studio 2015 or Visual Studio 2017 15.3.3 (or newer) with the Universal Windows App Development Tools.
  6. Xbox Live Platform Extensions SDK.

Note

If you want to use the IL2CPP scripting backend with Xbox Live, you will need Unity 2017.2.0p2 or newer and the Xbox Live Unity plugin version '1802 Preview Release' or higher.

Import the Unity plugin

To import the plugin into your new or existing Unity project, follow these steps:

  1. Navigate to the Xbox Live Unity Plugin release tab on https://github.com/Microsoft/xbox-live-unity-plugin/releases.
  2. Download XboxLive.unitypackage.
  3. In Unity, click Assets > Import Package > Custom Package and navigate to XboxLive.unitypackage.
Live

(Optional) Configure the plugin to work in the Unity Editor (.NET 4.6 or IL2CPP only)

Note

Support for changing the Scripting Runtime Version in Unity requires the Xbox Live Unity Plugin version '1711 Release' or higher for .NET 4.6 and version '1802 Preview Release' or higher for IL2CPP.

There are three settings that can be configured in Unity to define how your code is compiled:

  1. The scripting backend is the compiler that is used. Unity supports two different scripting backends for Universal Windows Platform: .NET and IL2CPP.
  2. The Scripting Runtime Version is the version of the scripting runtime that runs the Unity Editor.
  3. The API Compatibility Level is the API surface you'll build your game against.

The following table shows the current scripting support matrix for the Xbox Live Unity Plugin:

Scripting BackendScripting Runtime VersionSupportedMinimum Unity Version Required
IL2CPP.NET 3.5 EquivalentNoN/A
Il2CPP.NET 4.6 EquivalentYes2017.2.0p2
.NET.NET 3.5 EquivalentYesSame as prerequisites
.NET.NET 4.6 EquivalentYesSame as prerequisites

We've added additional scripting runtime support to the Xbox Live Unity Plugin, starting with version '1711 Release'.By default, the plugin is configured to run in the Unity editor with the .NET scripting backend and scripting runtime version of .NET 3.5.

If your project is using the scripting runtime version of .NET 4.6, you will need to configure the plugin to work properly in the editor, as follows:

  1. In the Unity project explorer, navigate to Xbox LiveLibsUnityEditorNET46 and select all of the DLLs in the folder.

  2. In the Inspector window, check Editor under Include Platforms.

  3. In the Unity project explorer, navigate to Xbox LiveLibsUnityEditorNET35 and select all of the DLLs in the folder.

  4. In the Inspector window, uncheck Editor under Include Platforms.

Important

These steps will need to be reversed if you change the scripting runtime version in your project back to 3.5.

Set Visual Studio as the IDE in Unity

Visual Studio is required to build a Universal Windows Platform (UWP) game.You can set your IDE in Unity to Visual Studio by going into Edit > Preferences > External Tools and setting the External Script Editor to Visual Studio.

Unity plugin file structure

The Unity plugin's file structure is broken into the following parts:

  • Xbox Live contains the actual plugin assets that are included in the published .unitypackage.
  • Editor contains scripts that provide the basic Unity configuration UI and processes the projects during build.
  • Examples contains a set of simple scene files that show how to use the various prefabs and connect them together.
  • Images is a small set of images that are used by the prefabs.
  • Libs is where the Xbox Live libraries are stored.
  • Prefabs contains various Unity prefab objects that implement Xbox Live functionality.
  • Scripts contains all the code files that call the Xbox Live APIs from the prefabs. This is a great place to look for examples about how to properly call the Xbox Live APIs.
  • ToolsAssociationWizard contains the Xbox Live Association Wizard, used to pull down application configuration from Partner Center for use within Unity.

Enable Xbox Live

For your title to interact with Xbox Live, you'll need to setup the initial Xbox Live configuration.

You can do this easily and inside of Unity by using the Xbox Live Association Wizard, as follows:

  1. In the Xbox Live menu, select Configuration.

  2. In the Xbox Live window, select Run Xbox Live Association Wizard.

  3. In the Associate Your title with the Windows Store dialog, click Next, and then sign in with your Partner Center account.

  4. Select the app that you want to associate with this project, and then click Select. If you don't see it there, try clicking Refresh. Alternatively, you can create a new app by reserving a name and clicking Reserve.

  5. You will be prompted to enable Xbox Live if you have not already. Click Enable to enable Xbox Live in your title.

  6. Click Finish to save your configuration.

To call Xbox Live services, your desktop must be in developer mode and set to the same sandbox as your title is in the Xbox Live configuration.

You can verify both by looking at the Xbox Live Configuration window in Unity:

  1. Developer Mode Configuration should say Enabled. If it says Disabled, click Switch to Developer Mode.

  2. Title Configuration > Sandbox should have the same ID as Developer Mode Configuration > Developer Mode.

See Xbox Live Sandboxes overview for information about sandboxes.

Build and test the project

When running your title in the editor, you will see fake data when you try to use Xbox Live functionality.For example, if you add sign in capabilities to your scene (per Sign-in in Unity through prefabs or scripting (pre-1804 release)) and try to sign in, you will see Fake User appear as your profile name, with a placeholder icon.To sign in with a real profile and test out Xbox Live functionality in your title, you'll need to build a UWP solution and run it in Visual Studio.

You can build the UWP project in Unity, as follows:

  1. Open the Build Settings window by selecting File > Build Settings.

  2. Add all of the scenes that you want to include in your build under the Scenes In Build section.

  3. Switch to the Universal Windows Platform by selecting Universal Windows Platform under Platform and clicking Switch Platform.

  4. Set SDK to 10.0.15063.0 or greater.

  5. To enable script debugging check Unity C# Projects.

  6. Click Build and specify the location of the project.

Once the build has finished, Unity will have generated a new UWP solution file which you will need to run in Visual Studio:

  1. In the folder that you specified, open <ProjectName>.sln in Visual Studio.

  2. In the toolbar at the top, select x64 and deploy to the Local Machine.

If you enabled script debugging when you built the UWP solution from Unity, then your scripts will be located under the Assembly-CSharp (Universal Windows) project.

App

Note

Before using your Visual Studio build to test your game with real data, follow the checklist in Testing a Unity game build in Visual Studio to help ensure your title will be able to access the Xbox Live service.

Important

Starting May 2018, to test your UWP title properly in Visual Studio, you must update the package.appxmanifest.xml file. To do this:

  1. Search the Solution Explorer for the package.appxmanifest.xml file.

  2. Right-click the file and then click View Code.If the View Code option is not available, or the package.appxmanifest file does not have an extension, you will need to open the file as an XML file and then continue with the remaining steps.

Xbox Live App Android

  1. In the <Properties> section, add the following line: <uap:SupportedUsers>multiple</uap:SupportedUsers>.
  1. Deploy the game to the Xbox console by starting a remote debugging build from Visual Studio.To set up your title on an Xbox, see Set up your UWP on Xbox development environment.

The piece of configuration that is changed may look like it is enabling multi-player, but it is still necessary to run your game in single-player scenarios.

Try out the examples

You can now start using Xbox Live in your Unity project.Try opening scenes in the Xbox Live/Examples folder to see the plugin in action, and for examples of how to use the functionality yourself.

Running the examples in the editor will give you fake data - to sign in with your gamertag, build the project in Visual Studio and associate your Xbox Live account with the sandbox; see Authorize test accounts, for Creators.

  • Try the SignInAndProfile scene for signing into your Microsoft Account.
  • Try the Leaderboard scene for creating a leaderboard.
  • Try the UpdateStat scene for displaying and updating stats.

See also

-->

Using Xbox Live services

There are two ways to get information from the Xbox Live services:

  • Use a client-side API called Xbox Live Services API (XSAPI).
  • Call the Xbox Live REST endpoints directly.

The advantages of using the Xbox Live Services API (XSAPI) include:

  • Details of authentication, encoding, and HTTP sending and receiving are taken care of for you.
  • Arguments to, and data returned from, the wrapper API is handled in native data types; so, you don't need to perform JSON encoding and decoding.
  • Calling web services directly involves multiple asynchronous steps, which the wrapper API encapsulates; this makes title code easier to read and write.
  • Some functionality, such as writing game events, is only available in XSAPI.

The advantages of using the Xbox Live REST endpoints directly include:

Xbox Live App Macoscleverwars
  • The ability to call Xbox Live endpoints from a web service
  • The ability to call endpoints which aren't included in XSAPI. XSAPI only includes APIs that we believe games will use, so if there's anything missing let us know via the forums.
  • Some functionality available via the REST endpoints may not have a corresponding XSAPI wrapper.

Your games and apps are not limited to using just one of these methods. You can use the XSAPI wrapper and still call the REST endpoints directly if needed.

Overview of the Xbox Live Services API

The Xbox Live Services API (XSAPI) exposes three sets of client side APIs that support a wide range of customer scenarios:

  • XSAPI C based API (New as of June 2018)

Comparing the APIs:

XSAPI WinRT-based API

  • Supports applications written with C++/CX, C#, and JavaScript.
    • C++/CX is a Microsoft C++ extension to make WinRT programming easy for example using ^ as WinRT pointers.
  • Supports applications targeting Xbox One XDK platform, and Universal Windows Platform (UWP) x86, x64 and ARM architectures.
  • Errors are handled via exceptions in all languages including C++/CX.
  • C++/WinRT is also supported. More information about C++/WinRT can be found at https://moderncpp.com/2016/10/13/cppwinrt-available-on-github/
  • For more information on WinRT reference, see Xbox Live WinRT SDK API Reference ⬀

Here's an example of calling the XSAPI WinRT API using C++/WinRT:

If you want to mix C++/CX and C++/WinRT as you are migrating code you can do this too but is a little more complex.
Here's an example of calling the XSAPI WinRT API using C++/WinRT given C++/CX User^ object.

XSAPI C++11-based API

  • Uses cross platform ISO standard C++11
  • Supports applications written with C++
  • Supports applications targeting Xbox One XDK platform, and Universal Windows Platform (UWP) x86, x64 and ARM architectures.
  • Errors are handled via std::error_code.
  • The C++11 based API is the recommended API to use for C++ game engines for better performance, and better debugging.
  • If you are in the Xbox Live Creators Program, before including the XSAPI header define XBOX_LIVE_CREATORS_SDK. This limits the API surface area to only those that are usable by developers in the Xbox Live Creators Program and changes the sign-in method to work for titles in the Creators program. For example:
  • C++/WinRT is also supported. More information about C++/WinRT can be found at https://moderncpp.com/2016/10/13/cppwinrt-available-on-github/

Xbox Live App

To use C++/WinRT with the XSAPI C++ API, before including the XSAPI header, define XSAPI_CPPWINRT. For example:

Here's an example of calling the XSAPI C++ API using C++/WinRT:

XSAPI C-based API

  • Allows titles to control the memory allocations when calling XSAPI.
  • Allows titles to gain full control of thread handling when calling XSAPI.
  • Uses a new HTTP library, libHttpClient, designed for game developers.

See Introduction to the Xbox Live C APIs.