Presence Interface

Overview of the presence interface.

Choose your operating system:




When logged into an online service, users can often see information about their friends and other users they've met online, such as whether these users are online, what they're doing, if they're available to join matches, and so on. The Presence Interface provides the Online Subsystem with access to these features.

Presence Status

Most online servies recognize several basic presence states for each user, such as "online", "offline", and "away", as well as game-specific states like "In the lobby" or "Playing a match on (Map)". However, these settings are not always visible, or may be visible to some users but not others, due to service-specific privacy policies and account settings. The Online Subsystem does not interact with these policies or settings, but the information that it retrieves will be affected by them.

Defining Presence

The FOnlineUserPresence class contains all information related to a user's presence. In addition to basic information like whether or not the user is currently online, and whether or not the user is playing a game, the user's presence (using the FOnlineUserPresenceStatus class) stores more in-depth information. This generally includes a localized string for display, an enumerated value (of type EOnlinePresenceState) to describe the user's basic state, and a set of key-value pairs to hold any game-specific custom data, which can be used when building the exact presence display message.

Presence Data on Xbox Live

On Microsoft's Xbox Live service (for the Xbox One), developers can go through the Xbox Developer Portal site's "Rich Presence Strings" section to set up localized status strings and get keys for those strings. To use a string you've set up as your presence status, visible to other users online, put that key into the StatusStr variable within the FOnlineUserPresence parameter that the SetPresence function accepts. These strings support the insertion of variables, indicated by braces. For example, the English-language version of a string might be "Playing a match on {current_map}", where "current_map" is a variable that the game can update when setting presence. To set a variable, add an element to the Properties array of your FOnlinePresence which you pass to SetPresence. In our example, the element would contain the key "Event_current_map" and a value that represents the map name in English, as it should appear in the message, such as "Forest Map".

Presence Data on PlayStation Network

On Sony's Playstation Network, developers can put a non-localized string into the StatusStr variable within the FOnlineUserPresence parameter that the SetPresence function accepts. If this variable is left empty, the Properties variable will be checked for an entry with a key value of "DefaultPresenceKey" to use instead. Other users will see this string when they successfully query your presence status. There is also a hidden string, available by setting up a custom property in your FOnlineUserPresenceStatus parameter with the "CustomData" key (or the CustomPresenceDataKey constant) that will be received by other users running the same game. This string will not be displayed, but can be used for any purpose the developer chooses.

Regardless of whether the status string is sent through the variable or the "DefaultPresenceKey" entry in the Properties variable, it will be stored in the "DefaultPresenceKey" entry in the Properties variable on other users' machines.

The Friends interface has access to some presence information, such as session ID keys, that are not available through the Presence interface on PlayStation Network.

Retrieving Information About Other Users

The basic flow for collecting presence information about a specific user begins with making a request to the online service through QueryPresence, specifying that user by FUniqueNetId. Once that operation finishes, the provided FOnPresenceTaskCompleteDelegate will be called, indicating the user and whether the request succeeded or failed. If successful, the local presence information cache will contain up-to-date presence information, which is available through the GetCachedPresence function.

Some online services proactively notify the Online Subsystem about user presence. On these services, although you don't actually have to call QueryPresence or wait for its delegate, the usual code flow should remain unchanged so that it will work across multiple services.

Setting a User's Presence

The SetPresence function sets the presence status of a local user through the online service. This is an asynchronous call due to the need to verify the new status with the online service, and a delegate of type FOnPresenceTaskCompleteDelegate will be called upon completion. Presence status itself is described by the FOnlineUserPresenceStatus class.

Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey