Events overview
Note: This article only applies if you are using event-based User Stats, not title-managed User Stats.
Note Application Insights has been deprecated. Please use fiddler to monitor events.
Writing game events to the Xbox services User Statistics service
The most exciting moments in games are when something significant happens—defeating an opponent, being defeated, moving to a location, shooting a weapon, picking a flower. By using Xbox services, titles can share information about the important events in a player's game. Details can be sent to Xbox services, which records statistics about users. These statistics can be retrieved for use in user stats, leaderboards, and matchmaking.
Once the event, and any data that is sent as part of the event, reaches the service, Xbox services processes rules that you defined in the service configuration for your title to create or update user statistics, leaderboards, etc.
Configuration on Partner Center
First, define your events on Partner Center in the Player Stats | Stat rules page. Once you have an event and stat defined in Partner Center, you can perform the following steps to send an event.
Writing an event
For a Microsoft Game Development Kit (GDK) title, the API to send an event is different than that for an Xbox One Software Development Kit title, and use of the manifest file is not needed.
The XblEventsWriteInGameEvent function is declared as:
STDAPI XblEventsWriteInGameEvent(
_In_ XblContextHandle xboxLiveContext,
_In_z_ const char* eventName,
_In_opt_z_ const char* dimensionsJson,
_In_opt_z_ const char* measurementsJson
) XBL_NOEXCEPT;
xboxLiveContext is the Xbox services context handle.
eventName is the Event name as defined on Partner Center.
dimensions is a property bag corresponding to event properties that take on a finite set of values. For example: level, weapon, or character.
measurements is a property bag corresponding to event properties that have an indeterminate set of values. For example: miles driven, enemies killed, or minutes played.
Dimensions and Measurements are discussed more below.
Measurements and Dimensions
When calling XblEventsWriteInGameEvent for the purposes of events on Xbox services, there is no difference if you pass an event property as a dimension or measurement. These differences are only relevant if you are analyzing the events on Application Insights for your telemetry - this has no impact on the gameplay experience. There is more information at Application Insights API for custom events and metrics.
Dimensions can be used to filter or pivot on your events. Eg: Show users to completed Level 6, or show all "Enemies Killed" events where the weapon used was "Minigun".
Measurements could be displayed graphically or make sense to use on a leaderboard. Eg: Track time, consecutive rounds won, etc.
But for the purposes of use with Xbox services, whether you pass an event property as a measurement or dimension makes no difference, this will be processed identically for the purposes of unlocking achievements and other Xbox services related functionality.
Debugging Xbox services Events
If events from your title are not successfully reaching Xbox services, then hero stats and leaderboards will not update. If you suspect that events are not successfully being received by Xbox services, try the following steps:
Verify your sandbox is correct.
Set up Fiddler on the device. In Fiddler, you should see events as follows:
Look for calls to v10.vortex-win.data.microsoft.com. You will need to decode the request body as shown, then if you look at the JSON you will see something such as the following:
You can verify the event name is what you expect. Your title ID will be prepended to the name. You should also verify you are getting a 200 return code.