Presence Interface

Interface that enables users to inform their friends of their current activities.

10 mins to read

With the Presence Interface, an application can advertise its local player's status, known as presence, and query the presence of other players online. An application may also advertise transient data to others, in order to share more detailed information about the state of the local player. Users can only receive presence information about other users with whom they are friends.

To use the Presence Interface, your product must have Epic Account Services (EAS) active, and must obtain user consent to access Online Presence data. You can activate EAS on the Developer Portal, or learn more in Epic's documentation. Without EAS and user consent, you will still be able to initialize the EOS SDK and the Presence Interface, but all Presence Interface function calls to the back-end service will fail.

Managing Presence Information

To use the Presence Interface, you must acquire a handle of type EOS_HPresence from the Platform Interface function, EOS_Platform_GetPresenceInterface. With this handle, you can download and cache presence information about other users on your friends list, or update your own presence.

Retrieving and Caching Presence Information

To retrieve presence information about a user, call EOS_Presence_QueryPresence with an EOS_Presence_QueryPresenceOptions structure, an optional ClientData parameter, and a callback function. Initialize the EOS_Presence_QueryPresenceOptions with the following field values:

PropertyValue
ApiVersionEOS_FRIENDS_QUERYPRESENCE_API_LATEST
LocalUserIdThe EOS_EpicAccountId of the logged-in user making the request.
TargetUserIdThe EOS_EpicAccountId of the user whose presence data you want to retrieve. This value must either match LocalUserId, or be a friend of that user.

The callback function will receive the ClientData parameter you provide here, and will run following completion of the operation regardless of success or failure. The only exception to this is if the call fails locally due to the EOS_Presence_QueryPresenceOptions structure lacking any of the required information. In the event of failure due to lack of permission to view the target user's presence, the callback function's ResultCode field will be EOS_NotFound. Any other value, aside from EOS_Success, indicates an input or state failure, such as invalid parameters, LocalUserId not matching a local, logged-in user, or the local user being offline.

Updating Presence Information

There are two ways to update presence information in your local cache. The first is to call EOS_Presence_QueryPresence periodically, or shortly before accessing the cache. The second is to receive notification from the Presence Interface when a change has occurred. To enable this feature, call EOS_Presence_AddNotifyOnPresenceChanged. This function requires an EOS_Presence_AddNotifyOnPresenceChangedOptions struct, a user-defined ClientData parameter, and a callback function of type EOS_Presence_OnPresenceChangedCallback. The callback function will receive the ClientData parameter and the EOS_EpicAccountId of the user whose presence changed. Initialize the EOS_Presence_OnPresenceChangedCallback structure as follows:

PropertyValue
ApiVersionEOS_FRIENDS_ADDNOTIFYONPRESENCECHANGED_API_LATEST

If successful, EOS_Presence_AddNotifyOnPresenceChanged will return a valid EOS_NotifcationId. In the case of an error, it will return EOS_INVALID_NOTIFICATIONID.

To deactivate this feature, call EOS_Presence_RemoveNotifyOnPresenceChanged, passing the presence handle and notification ID as parameters. This function stops notifications to a handle previously registered with EOS_Presence_AddNotifyOnPresenceChanged.

There can be multiple callbacks registered at a time. In this case all the callbacks will be called once the event occurs.

Examining Presence Information

Once EOS_Presence_QueryPresence has populated the cache with a user's presence information, you can begin examining it. To establish whether or not the cache contains a given user's presence information, call EOS_Presence_HasPresence with your EOS_HPresence handle, and an EOS_Presence_HasPresenceOptions structure initialized as follows:

PropertyValue
ApiVersionEOS_FRIENDS_HASPRESENCE_API_LATEST
LocalUserIdThe EOS_EpicAccountId of the logged-in user making the request.
TargetUserIdThe EOS_EpicAccountId of the user whose cached presence data you want to locate.

EOS_Presence_HasPresence will return EOS_TRUE if it succeeds and finds data, or EOS_FALSE if it receives bad input or if the cache does not contain data for the target user.

EOS_Presence_CopyPresence provides copies of presence information from the cache. The Presence Interface will return data as a new EOS_Presence_Info object. This function requires your Presence Interface handle, an EOS_Presence_CopyPresenceOptions structure, and an output parameter to hold your new EOS_Presence_Info object. Initialize the EOS_Presence_CopyPresenceOptions structure as follows:

PropertyValue
ApiVersionEOS_FRIENDS_COPYPRESENCE_API_LATEST
LocalUserIdThe EOS_EpicAccountId of the logged-in user making the request.
TargetUserIdThe EOS_EpicAccountId of the user whose cached presence data you want to copy.

If the Presence Interface successfully pulls a copy of the information from the cache, EOS_Presence_CopyPresence will return EOS_Success and fill out the EOS_Presence_Info pointer you provided with a copy of the target user's data. The caller owns this pointer, so the EOS SDK will never modify its contents or free the memory associated with it. Call EOS_Presence_Info_Release with the pointer when you no longer need this data to free it. Failure to do so will result in a memory leak.

EOS_Presence_GetJoinInfo provides an easy way to get the previously set Join Info string from a remote user's presence data. For this function to succeed, the user's presence data must already be in the presence cache. This function requires your Presence Interface handle, an EOS_Presence_GetJoinInfoOptions structure, OutBuffer set to a pointer to a char buffer, and InOutBufferLength set to the maximum length of the char buffer. Initialize the EOS_Presence_GetJoinInfoOptions structure as follows:

ParameterDescription
ApiVersionSet this to EOS_PRESENCE_GETJOININFO_API_LATEST
LocalUserIdThe EOS_EpicAccountId of the logged-in user making the request
TargetUserIdThe EOS_EpicAccountId of the user whose Join Info you want to retrieve. This value must either be a logged-in Local User, or a Friend of LocalUserId.

The length of the OutBuffer char buffer is recommended to be EOS_PRESENCEMODIFICATION_JOININFO_MAX_LENGTH, or it may be too short to store some values and will fail the request.

Note: Updates to presence information, even when using EOS_Presence_AddNotifyOnPresenceChanged, will not be reflected in existing EOS_Presence_Info objects. This is because these objects are copies of cache data, not pointers to the cache, and because the Presence Interface does not own them and will not modify them after the initial copy.

Modifying Local Presence

To modify a local user's presence, you must create an EOS_HPresenceModification handle, and set changes by calling one or more of the following functions:

  • EOS_PresenceModification_SetStatus
  • EOS_PresenceModification_SetRawRichText
  • EOS_PresenceModification_SetData
  • EOS_PresenceModification_DeleteData
  • EOS_PresenceModification_SetJoinInfo

Note: Changes are reflected after a call to EOS_Presence_SetPresence succeeds.

Creating a PresenceModification Handle

To modify a local user's presence, first create a PresenceModification handle by calling EOS_Presence_CreatePresenceModification with a valid EOS_HPresence handle, an initialized EOS_Presence_CreatePresenceModificationOptions struct, and a pointer to an invalid EOS_HPresenceModification handle. Initialize the EOS_Presence_CreatePresenceModificationOptions struct as follows:

PropertyValue
ApiVersionEOS_PRESENCE_CREATEPRESENCEMODIFICATION_API_LATEST
LocalUserIdValid local user in a logged-in state.

If successful, the EOS_Presence_CreatePresenceModification function returns EOS_EResult::EOS_Success, and the OutPresenceModificationHandle will be initialized for use with functions in the EOS_PresenceModification sandbox. The resulting handle must also be released when it is no longer needed by calling the EOS_PresenceModification_Release method.

Making Changes to a PresenceModification

With a valid EOS_HPresenceModification, you can build the update for a user's presence by calling functions within the EOS_PresenceModification function sandbox.

Modifying Presence Status

To set a new status, invoke EOS_PresenceModification_SetStatus with a valid EOS_HPresenceModification handle, and initialize an EOS_PresenceModification_SetStatusOptions struct as follows:

PropertyValue
ApiVersionEOS_PRESENCE_SETSTATUS_API_LATEST
StatusValid EOS_Presence_EStatus value.

If successful, EOS_PresenceModification_SetStatus returns EOS_EResult::EOS_Success. Otherwise, it returns an error code describing an issue with the request. Changes will not be reflected in a user's presence until a call to EOS_Presence_SetPresence completes with EOS_EResult::EOS_Success.

Modifying A Rich Text string

To set a new rich text string, invoke EOS_PresenceModification_SetRawRichText with a valid EOS_HPresenceModification handle, and initialize an EOS_PresenceModification_SetRawRichText struct as follows:

PropertyValue
ApiVersionEOS_PRESENCE_SETRAWRICHTEXT_API_LATEST
RichTextNon-null string that is smaller than byte size of EOS_PRESENCE_RICH_TEXT_MAX_VALUE_LENGTH.

If successful, EOS_PresenceModification_SetRawRichText returns EOS_EResult::EOS_Success; otherwise, it returns an error code describing an issue with the request. Changes will not be reflected in a user's presence until a call to EOS_Presence_SetPresence completes with EOS_EResult::EOS_Success.

Adding or Replacing Presence Data

To add or replace existing presence data to a user's presence, invoke EOS_PresenceModification_SetData with a valid EOS_HPresenceModification handle, and initialize an EOS_PresenceModification_SetDataOptions struct as follows:

PropertyValue
ApiVersionEOS_PRESENCE_SETDATA_API_LATEST
RecordsCountHow many EOS_Presence_DataRecord are present in Records, and Records must be a pointer to an array of EOS_Presence_DataRecord that is at least RecordsCount long.

Initialize EOS_Presence_DataRecord with the following:

PropertyValue
ApiVersionEOS_PRESENCE_DATARECORD_API_LATEST
KeyNon-null string that is smaller than the byte size of EOS_PRESENCE_DATA_MAX_KEY_LENGTH.
ValueNon-null string that is smaller than the byte size of EOS_PRESENCE_DATA_MAX_VALUE_LENGTH.

Note: In the case of conflicting values, such as having multiple DataRecords with the same key, the last conflicting value in the Records array will be used.

If successful, EOS_PresenceModification_SetData returns EOS_EResult::EOS_Success. Otherwise, it returns an error code describing an issue with the request. Changes will not be reflected in a user's presence until a call to EOS_Presence_SetPresence completes with EOS_EResult::EOS_Success.

Deleting Presence Data

Similar to EOS_PresenceModification_SetData, EOS_PresenceModification_DeleteData removes presence data that matches the key of previously set data. To delete presence data, invoke EOS_PresenceModification_DeleteData with a valid EOS_HPresenceModification handle, and initialize an EOS_PresenceModification_DeleteDataOptions struct as follows:

PropertyValue
ApiVersionEOS_PRESENCE_DELETEDATA_API_LATEST
RecordsCountHow many EOS_PresenceModification_DataRecordId are present in Records, and Records must be a pointer to an array of EOS_PresenceModification_DataRecordId.

Initialize EOS_PresenceModification_DataRecordId with the following:

PropertyValue
ApiVersionEOS_PRESENCE_DELETEDATA_API_LATEST
KeyNon-null string that is smaller than the byte size of EOS_PRESENCE_DATA_MAX_KEY_LENGTH.

If a key is marked for delete but does not exist, this part of the pending presence modification process is silently ignored. Additionally, if multiple keys are set to delete the same key, the extra keys will be silently ignored.

If successful, EOS_PresenceModification_DeleteData returns EOS_EResult::EOS_Success; otherwise, it returns an error code describing an issue with the request. Changes will not be reflected in a user's presence until a call to EOS_Presence_SetPresence completes with an EOS_EResult::EOS_Success.

Setting the Presence JoinInfo Data

The helper function EOS_PresenceModification_SetJoinInfo sets the EOS_JoinInfo Presence data key with a specified Join Info string. This data may also be retrieved through usage of the EOS_Presence_GetJoinInfo function. This data will be sent to games when invoking the Join Game feature of the EOS Social Overlay, and should contain whatever information is necessary for a game to find and join a user's match or party, depending on what makes sense for the title.

To invoke the EOS_PresenceModification_SetJoinInfo function successfully, it must be called with a valid EOS_HPresenceModification handle, and a valid EOS_PresenceModifcation_SetJoinInfoOptions struct initialized as follows:

ParameterDescription
ApiVersionSet to EOS_PRESENCEMODIFICATION_SETJOININFO_API_LATEST
JoinInfoA null-terminated string of up to EOS_PRESENCEMODIFICATION_JOININFO_MAX_LENGTH bytes in length, not including the null-terminator.

Applying PresenceModification Changes

Once all changes to an EOS_HPresenceHandle have been made, they must be applied to a user by calling EOS_Presence_SetPresence with a valid EOS_HPresence handle, an optional ClientData field, and an EOS_Presence_SetPresenceCompleteCallback callback function. The Callback function will contain the value of the ClientData parameter. You will also need to provide an EOS_Presence_SetPresenceOptions struct, which you should initialize as follows:

PropertyValue
ApiVersionEOS_PRESENCE_SETPRESENCE_API_LATEST
LocalUserIdLocal user who created the presence modification.
PresenceModificationHandleThe EOS_HPresenceModification handle that has pending changes.

It is safe to release the EOS_HPresenceModification handle immediately after the call to EOS_Presence_SetPresence, however, if there is an error, these changes could be lost. We recommend maintaining this handle until the callback function returns a successful result code or at a time when you want to abandon the changes. Additionally, it is invalid for a single user to have more than EOS_PRESENCE_DATA_MAX_KEYS of unique presence data, and attempting to set more than this many unique presence data keys will fail.

When complete, the callback function will be invoked with an EOS_Presence_SetPresenceCompleteInfo struct that contains the following:

PropertyDescription
ResultCodeThis is the call's result code.
ClientDataThis is the client data from the ClientData parameter.
AccountIdThis is the account identity value of the local user who invoked the call.

If multiple calls to EOS_Presence_SetPresence happen during a single frame, they may be combined automatically. The callback function for all calls will still be invoked separately but they may share a ResultCode. If there are conflicting modifications, such as a status being set twice across one (or multiple) modifications, the last-set field will overwrite previous changes.

Subscribing to Social Overlay Notifications

It is also possible to subscribe to notifications related to the Social Overlay, such as JoinGameAccepted event, via a EOS_Presence_AddNotifyJoinGameAccepted/EOS_Presence_RemoveNotifyJoinGameAccepted pair. For more information please refer to the Social Overlay page.