Presence Tasks #

When a user first logs on, no presence status exists. Upon logout, Pragma will automatically remove the presence status.

Using the Presence API, you can:

Pragma currently supports the Presence API in the Unreal SDK. Unity implementation is available through FriendServiceRaw.cs.

Initialize Friend service (Required) #

Before you can use the Presence features, you must initialize the Friend service using the Friend API Initialize method:

Player->FriendApi().Initialize(
    FOnCompleteDelegate
);

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(
    FOnCompleteDelegate
)

SetPresenceV1(SetPresenceV1Request request,
            Protocol.OnComplete<SetPresenceV1Response> callback)

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:

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(
    FOnCompleteDelegate
)

SetPresenceV1(SetPresenceV1Request request,
            Protocol.OnComplete<SetPresenceV1Response> callback)

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:

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.

The ExtRichPresence data can be set by various components, allowing you to handle the data coming from the player, game server, or backend plugin separately. You can set ExtRichPresence using:

ComponentMethodExample usage
player clientPresenceApi.SetRichPresenceplayer-supplied data that requires validation/sanitation before being implemented
game serverMatchApi.SetRichPresencecalculations from the game server, such as team score
backend plugins or custom servicesPresenceGameBackendClient.setRichPresencecustom presence data supplied by a Pragma plugin, such as by the Party Plugin when a new player is added
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 with the ExtRichPresencePlayerRequest payload.

Player->PresenceApi().SetRichPresence(
    FPragma_Presence_ExtRichPresencePlayerRequest,
    FOnCompleteDelegate
)

SetPresenceV1(SetPresenceV1Request request,
            Protocol.OnComplete<SetPresenceV1Response> callback)

The Presence API’s SetRichPresence call invokes the Presence Plugin’s updateRichPresenceFromPlayer method and provides it with the ExtRichPresencePlayerRequest payload. Data arriving from the player client should be validated within this method. Based on validation, create or update the ExtRichPresence for the player.

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(
    SocialId,
    FPragma_Presence_ExtRichPresenceBackendRequest,
    FOnCompleteDelegate
)

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, which is used to create or update the ExtRichPresence for the player.

suspend fun updateRichPresenceFromBackend(
    socialId: SocialId,
    gameShardId: GameShardId,
    currentPresence: Presence?,
    requestExt: ExtRichPresenceBackendRequest
): ExtRichPresence

Set from backend plugins or custom services #

To set or update a rich presence from a Pragma plugin, first create a PresenceGameBackendClient object in the desired plugin, as shown in the following example:

class MyPartyPlugin(
    private val service: Service,
    private val contentDataNodeService: ContentDataNodeService
): PartyPlugin {
    private val presenceClient: PresenceGameBackendClient = PresenceGameBackendClient(service)
    ...
}

To set or update a rich presence from custom service, add the SocialBackendPartnerClientNodeService dependency and create a PresenceGameBackendClient object in the desired service, as shown in the following example:

@PragmaService(
    backendTypes = [BackendType.GAME],
    dependencies = [SocialBackendPartnerClientNodeService::class]
)
class MyCustomService(
    pragmaNode: PragmaNode,
    instanceId: InstanceId,
) : DistributedService(pragmaNode, instanceId) {
    private val presenceClient: PresenceGameBackendClient = PresenceGameBackendClient(this)
    ...
}

After preparing your plugin or custom service, call the PresenceGameBackendClient class’s setRichPresence method with the social ID of the player whose presence to update and the ExtRichPresenceBackendRequest payload.

suspend fun setRichPresence(
    socialId: SocialId,
    richPresenceRequest: ExtRichPresenceBackendRequest
)

The PresenceGameBackendClient.setRichPresence method invokes the Presence Plugin’s updateRichPresenceFromBackend method and provides it with the ExtRichPresenceBackendRequest payload, which is used to create or update the ExtRichPresence for the player.

suspend fun updateRichPresenceFromBackend(
    socialId: SocialId,
    gameShardId: GameShardId,
    currentPresence: Presence?,
    requestExt: ExtRichPresenceBackendRequest
): ExtRichPresence

Related events:

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
)

SetPresenceV1(SetPresenceV1Request request,
            Protocol.OnComplete<SetPresenceV1Response> callback)

The SetPresence call invokes the Presence Plugin’s updateRichPresenceFromPlayer method and provides it with the ExtRichPresencePlayerRequest payload, which is used to create or update the ExtRichPresence for the player.

suspend fun updateRichPresenceFromPlayer(
    socialId: SocialId,
    gameShardId: GameShardId,
    gameTitleId: GameTitleId?,
    currentExt: ExtRichPresence?,
    requestExt: ExtRichPresencePlayerRequest
): ExtRichPresence

Related events:

Related errors:

Retrieve current presence status #

To retrieve the presence status for the current player, use the Presence API GetPresence method:

Player->PresenceApi().GetPresence()

Related events:

Related errors:

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 GetPresence 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.


Presence Overview
Presence Reference