Choose your operating system:
Windows
macOS
Linux
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.