Presence Tasks #
When a user first logs on, no presence status exists. Upon logout, crash, or disconnect, Pragma will automatically remove the presence status.
Using the Presence API, you can:
- Initialize the Presence service (Required)
- Set status as online
- Set status as away
- Set custom (rich) presence
- Set basic and rich presences at the same time
- Retrieve current presence status
- Disable presence updates
Initialize Presence SDK (Required) #
Before you can use the Presence features, you must initialize the Presence service using the Presence API Initialize
method:
Initialize()
can only be called after login. Upon logout, the service is un-initialized and theOn*
action-handlers are unbound. You must callinitialize()
on the service when you log back in.
Player->PresenceApi().Initialize(
const FOnCompleteDelegate& OnComplete
);
Player.PresenceApi.Initialize(
CompleteDelegate onComplete
);
Calling Initialize
will fetch the player’s presence state from the Pragma Engine backend. If a presence exists on the backend, SDK cache is updated and the OnPresenceChanged
event fires. After you receive a successful response, you can begin using the Presence API.
While the Pragma SDK constantly attempts to stay in sync with the Pragma Engine backend, there may be instances where the two components become out of sync due to connection issues. To forcibly synchronize the client’s state with the platform, call the Presence API ForceSync
function.
Related events:
Set status as online #
To set a user’s presence status to “online”, thus making them appear online to members of their friend list, use the Presence API SetAsOnline
method:
Player->PresenceApi().SetAsOnline(
const FOnCompleteDelegate& OnComplete
);
Player.PresenceApi.SetAsOnline(
CompleteDelegate onComplete
);
If the user does not currently have a basic presence status, this method creates one. Otherwise, it updates the current basic presence value. If the user does not currently have a rich presence status, this method creates an empty RichPresence
ext.
Related events:
OnPresenceChanged - OnFriendUpdated - OnFriendListChanged Related errors:
Set status as away #
To set a user’s presence to “away”, thus making them appear away to members of their friend list, use the Presence API SetAsAway
method:
Player->PresenceApi().SetAsAway(
const FOnCompleteDelegate& OnComplete
);
Player.PresenceApi.SetAsAway(
CompleteDelegate onComplete
);
If the user does not currently have a basic presence status, this method creates one. Otherwise, the call updates the current basic presence value. If the user does not currently have a rich presence status, this method creates an empty RichPresence
ext.
Related events:
OnFriendListChanged Related errors:
Set rich presence #
The rich presence ext
(ExtRichPresence
) allows you to define custom presence data beyond simply “online” or “away”. For example, you may want a player’s friends to see their team’s current score, or allow players to set a custom away message.
Rich presence data can be set or updated by various components, allowing you to handle the data coming from the player, game server, or backend separately.
A user must have a basic presence set before adding a rich presence. If a basic presence is not set, attempting to add a rich presence will result in a Presence_PresenceNotFound
error.
Set from player client #
To set or update a rich presence from the player client, use the Presence API’s SetRichPresence
SDK method for Unreal or Unity with the ExtRichPresencePlayerRequest
payload.
Player->PresenceApi().SetRichPresence(
const FPragma_Presence_ExtRichPresencePlayerRequest& RichPresenceRequest,
const FOnCompleteDelegate& OnComplete
);
Player.PresenceApi.SetRichPresence(
ExtRichPresencePlayerRequest richPresenceRequest,
CompleteDelegate onComplete
);
The Presence API’s SetRichPresence
call invokes the Presence Plugin’s updateRichPresenceFromPlayer()
method and provides it with the ExtRichPresencePlayerRequest
payload. Use this method to validate data arriving from the player client and update ExtRichPresence
.
interface PresencePlugin {
suspend fun updateRichPresenceFromPlayer(
socialId: SocialId,
gameShardId: GameShardId,
currentPresence: Presence?,
requestExt: ExtRichPresencePlayerRequest
): ExtRichPresence
}
Set from game server #
To set or update a rich presence from the game server, use the Match API’s SetRichPresence
SDK method with the ExtRichPresenceBackendRequest
payload.
Server->MatchApi().SetRichPresence(
const FString& SocialId,
const FPragma_Presence_ExtRichPresenceBackendRequest& RichPresenceRequest,
const FOnCompleteDelegate& OnComplete
)
SetPresenceV1(SetPresenceV1Request request,
Protocol.OnComplete<SetPresenceV1Response> callback)
The Match API’s SetRichPresence
call invokes the Presence Plugin’s updateRichPresenceFromBackend()
method and provides it with the ExtRichPresenceBackendRequest
payload. Use this method to create or update ExtRichPresence
.
interface PresencePlugin {
suspend fun updateRichPresenceFromBackend(
socialId: SocialId,
gameShardId: GameShardId,
currentPresence: Presence?,
requestExt: ExtRichPresenceBackendRequest
): ExtRichPresence
}
Set from backend #
To set or update a rich presence from a Pragma plugin or backend service, create an instance of the PresenceApi.kt
Kotlin class in a plugin or custom service.
private val presenceApi: PresenceApi = PresenceApi(service)
The PresenceApi class depends on theSocialBackendPartnerClientNodeService
. To use the PresenceApi in a custom service, addSocialBackendPartnerClientNodeService
as a dependency.
Then, call the PresenceApi class’s setRichPresence()
method with the social ID of the player whose presence to update and the ExtRichPresenceBackendRequest
payload:
class PresenceApi(
private val service: Service,
) {
suspend fun setRichPresence(
socialId: SocialId,
richPresenceRequest: ExtRichPresenceBackendRequest
)
}
The setRichPresence()
method on the PresenceApi class invokes the Presence Plugin’s updateRichPresenceFromBackend()
method, as shown in the Set from game server section above.
Related events:
OnPresenceChanged - OnFriendUpdated - OnFriendListChanged Related errors:
Set both basic and rich presence #
A player client can set a basic presence and a rich presence at the same time using the Presence API’s SetPresence
with a basic presence value and an ExtRichPresencePlayerRequest
payload. If the user does not currently have a basic or rich presence status, SetPresence
creates one. Otherwise, the call updates the current presence values.
Player->PresenceApi().SetPresence(
EBasicPresence,
FPragma_Presence_ExtRichPresencePlayerRequest,
FOnCompleteDelegate
)
Player.PresenceApi.SetPresence(
BasicPresence basicPresence,
ExtRichPresencePlayerRequest extRichPresenceRequest,
CompleteDelegate onComplete
)
The SetPresence
call invokes the Presence Plugin’s updateRichPresenceFromPlayer
method, as shown in the Set from player client section above.
Retrieve current presence status #
You can retrieve the presence status for the current player the presence cache in the Presence API:
Player->PresenceApi().GetPresenceCache()->GetPresence();
Related events:
Disable presence updates #
The enablePresenceUpdates
configuration setting in the FriendServiceConfig
configuration block of your configuration file determines whether presence statuses can be updated. By default, this value is true
. To disable both basic and rich presence updates, set enablePresenceUpdates
to false
.
social:
serviceConfig:
FriendServiceConfig:
enablePresenceUpdates: false
The Presence API’s GetPresenceCache
method is still available and will return presence values (if any) at the time enablePresenceUpdates
was set to false
. A player’s presence status will still be removed when the player logs out.