Thanks to the Xbox Live Creators Program, the Xbox Live services are available to any developer who wants to code on the UWP platform.
We joined the program and we’re very happy we published ERMO. Being a UWP game, ERMO runs nicely on any Windows10 device, included the Xbox One.
Now we want to share our experience with the Xbox Live SDK and write a detailed How-To showing all the steps required to deal with the Xbox Live API. In other words, lots of monospace characters will follow.
create_task in C++.
At least, we hope you will get the core idea behind the code.
Actually, under the banner of the Creators Program, a developer can leverage the following Xbox Live features:
- Identity authentication
- Profile and SocialGraph querying
- Leaderboard/Stats management
Other features, like basic presence and social feed, are automatically managed by the service, with no keystroke by the developer. The full list on the documentation.
In this post, we focus on features developers have to actively code against the SDK, the subset available with the Creators Program.
- Import Xbox Live SDK
- Xbox Live Authentication
- Retrieve user profile, Gamertag and picture
- Use leaderboards to submit player scores and stats
- Submit multiple score at once
- Retrieving and querying leaderboard scores
- Loading multiple player profiles
Like all Windows based development, NuGet is the way to go to import SDKs, libs and any other dependency. The easiest way is to use the integrated NuGet interface in Visual Studio. A free version of Visual Studio is available as Community Edition.
To import XboxLive SDK, right click on the
References node under the project root and chose
Manage NuGet Packages.... It’s available under the
Project menu too.
Pick the Microsoft.Xbox.Live.SDK.WinRT.UWP and install it. Then wait for the huge download to complete.
At the time of this post, the latest SDK version is 2017.8.x. All code examples and API calls refer to that version.
The mandatory first step to access all XboxLive services is to authenticate the user to the XboxLive system.
There’re a couple of options, but the most straightforward and effective is to use
Once the user is authenticated, you can load its profile with all info associated like the gamertag, score and picture.
We need a
XboxLiveContext to query the profile service and get the data we looking for.
In the following snippet, some utility functions are introduced to make the code cleaner.
Leaderboards and statistics are another services the XboxLive provides. You can define up to 20 of them through the dev center. You need also to localize them in any language your game supports.
Developers under the Creators Collection program don’t get the full leaderboard features, but the service is limited to just player stats.
Key difference is that a leaderboard is composed by multiple stats, like multiple columns in a table where each row is a player entry. Instead, a stat is a simply a list of players and their score (it can be anything), in other words, it’s the common scenario where the game UI displays the score list.
In this post, we stick to stats as they’re enough to make a chart with the player scores.
It’s introduced the
StatisticManager by which we can send scores. Because
StatisticManager is a singleton instance, we reference directly it while the
XboxLiveContext is created. In addition,
StatisticManager needs to know on which players it will operate, thus we add the current player to its users.
In the above snippet, it’s assumed the score is an integer value, but you can use other supported data types(Integer, Numeric, String) and change the call accordingly.
submitScore is a fire and forget function, you won’t receive any value, as the
StatisticManager processes all things in background when you use
If you send too many scores in a short time interval, XboxLive services will begin to throttle all your calls. Official documentation states to flush scores at most once every 5 minutes or so.
To limit this side effect and to avoid throttling, you can submit a batch of scores with one call.
As mentioned earlier, here for leaderboards we intend stats, as we use them to send and get player scores.
StatisticManager works in the background, the process of getting the data isn’t straightforward like a single call, but requires a more elaborate flow.
The process involves polling the
StatisticManager for events and, when ready, processing the results.
setTimeout to delay each call by 100ms. In other contexts or engines you should poll on any frame, thus bounding the call to the frame execution.
The flow isn’t the most linear in the field, but it works nicely when you call just the surface area of the snippet.
To complete the Retrieve leaderboard scenario, the last step is to load all players’ picture. As we did for the user logged in, the profile service comes handy to get all player profiles.
We have to pass the user-id list to get the pictures we want.
With the Xbox Live SDK available for the UWP platform is pretty easy to take advantage of the Xbox Live services. Due to large amount of features, the Xbox Live SDK is huge and the API surface area can be confusing sometimes.
With this HowTo, we hope we eased the integration task for any developer willing to put some efforts on the UWP platform.
If you want you can stay in touch: