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 and the On* action-handlers are unbound. 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:

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:

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.

Set rich presence

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 the SocialBackendPartnerClientNodeService. To use the PresenceApi in a custom service, add SocialBackendPartnerClientNodeService 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:

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.


Presence Overview
Presence Backend Reference