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 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. You must call initialize() 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:

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:

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(
  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. 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(
  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, 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
)

Player.PresenceApi.SetPresence(
  BasicPresence basicPresence,
  ExtRichPresencePlayerRequest extRichPresenceRequest,
  CompleteDelegate onComplete
)

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