User and controller APIs
User and Controller APIs
Properly handling user and controller state changes through the User and Controller APIs is the key to understanding who’s playing your game and attributing content correctly.
User APIs
Titles can call User::Users at any time to get the set of User objects representing the users who are signed into the system. Additionally, the User.UserAdded Event and the User.UserRemoved Event allow titles to track changes to this set of users.
The CoreApplicationContext.CurrentUser Property of Windows.Xbox.ApplicationModel.Core.CoreApplicationContext provides the recommended user context based on the originating app that activated your title. If your title was activated by Home, this value is set to the user whose Home content was being displayed. If no user’s content was being displayed, this value will be set to null.
Each User object contains a number of important properties, some of which are described in the following table.
| Property | Description |
|---|---|
| Id | A unique number that identifies the user, scoped to the console |
| XboxUserId | A unique string that identifies the user across Xbox Live services |
| Controllers | A list of controllers paired to this user |
| DisplayInfo | A UserDisplayInfo Class object that contains common data that can be displayed about the user, including the user’s gamertag |
| IsGuest | A Boolean value that indicates whether the user is a guest. IsGuest is true for sponsored users and false for Xbox Live users. |
| Sponsor | Identifies a guest’s sponsor, an Xbox Live user. This value is null if the user is not sponsored. |
For a demonstration of the User API, see the sample User Management, available on the Xbox Game Developer’s Samples page.
Controller APIs
The Controller.Controllers Property provides your title with the set of controllers being tracked by the system. In addition, specific controller types provide their own APIs to access controllers and their unique properties.
For example, gamepad state can be polled by calling Gamepad.Gamepads Property. Human bodies tracked by Kinect are represented as body controllers and can be accessed through BodyController.BodyControllers Property. SmartGlass devices are represented as NavigationControllers. Like the User API, Controller provides a set of events when the state of controller tracking changes, including the Controller.ControllerAdded Event, the Controller.ControllerRemoved Event, and the Controller.ControllerPairingChanged Event.
Every Controller object has a few common properties, described in the following table:
| Property | Description |
|---|---|
| Id | A unique number that identifies the controller on the console |
| Type | A string that represents the type of controller |
| User | The user paired to this controller. This value is null for unknown controllers. |
For a demonstration of the Controller API, see User Gamepad Pairing, a sample available on the Xbox Game Developer’s Samples page.
Note Even though the state of signed-in users and tracked controllers can be polled at any time, we recommend that your title not poll them every frame because of the negative effect on performance. Instead, your title should cache the results at the beginning of execution and update the cached results only when it encounters events for added, removed, or changed controllers.