Presence Event

Last updated on April 5, 2024

AGS Starter

Presence Event is not available on AccelByte Gaming Services (AGS) Starter tier.

Overview

The AccelByte Game SDK supports the Presence Event feature, which works together with the Analytics feature. The Presence Event feature allows you to gauge the presence of players in your game through presence events that show up just like other telemetry events under the Telemetry section in the Admin Portal. These events allow you to understand the in-game activities of your players at a high-level perspective.

Presence events are sent at a regular time interval, which is set at 10 minutes or 600 seconds by default. You can configure the interval in the Game SDK configuration.

By default, the Presence Event feature is turned off and can be turned on in the Game SDK configuration.

Enable Presence Event

Unreal

In the DefaultEngine.ini file, set PresenceBroadcastEVentHeartbeatEnabled under [/Script/AccelByteUe4Sdk.AccelByteSettings] to true.

[/Script/AccelByteUe4Sdk.AccelByteSettings]
PresenceBroadcastEventHeartbeatEnabled=true

Unity

For more information about opening the SDK Config, see Install and configure the SDK. The configuration can be set on Pre-Defined Event Configs > Enable Pre-Defined Game Event.

Configure the time interval

The time interval by default is 10 minutes or 600 seconds. Configure the time interval configured as follows:

Unreal

FTimespan HeartbeatIntervalSecond = FTimespan::FromSeconds(<double: interval second>);
FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
ApiClient->PresenceBroadcastEvent.SetHeartbeatInterval(HeartbeatIntervalSecond);

Unity

Open client editor. The configuration can be set on Presence Broadcast Event Configs > Set Interval In Seconds. The interval duration has minimum value 5 seconds.

Start or stop the presence event

The Presence Event feature can be started or stopped as follows:

Unreal

///Start presence event
FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
ApiClient->PresenceBroadcastEvent.StartHeartbeat();

///Stop Presence event
FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
ApiClient->PresenceBroadcastEvent.StopHeartbeat();

Unity

Presence Event activation is based on the SDK configuration.

Update Game State

The Game State plays a pivotal role in defining the presence of a user in the game. By default, this is set to be OUT_OF_GAMEPLAY, but can be changed to IN_GAMEPLAY or STORE. There are three predefined common states to cover a user's presence in your game. However, you can use a freeform string to define your own game states as well. This empowers you to identify the time spent by your players in specific game states through our Analytics service.

Unreal

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
EAccelByteGameState GameState = EAccelByteGameState::IN_GAMEPLAY;
FString Description = TEXT("Optional Game State Description");
ApiClient->PresenceBroadcastEvent.SetGameState(GameState ,
 FVoidHandler::CreateLambda([]()
 {
  // On success handler
 }),
 FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
 {
  // On error handler
 }), Description);

Unity

// Set Pre Defined game state
AccelByteSDK.GetClientRegistry().GetPresenceBroadcastEvent().SetGameState(AccelByte.Models.PresenceBroadcastEventGameState.InGameplay);
// Set Custom game state
AccelByteSDK.GetClientRegistry().GetPresenceBroadcastEvent().SetGameStateDescription("Optional Game State Description");

Important

It is important to set the Game State correctly as your player traverses through different phases in the game to make sure that the data being populated is correct. For better accuracy around metrics like time spent in game, store, etc. Please make sure your game state implementation is correct.

Preview in Admin Portal

Once implemented correctly, the presence event can be seen in the admin portal under the Telemetry section under Analytics on the left panel. The payload should look something similar to what is shown below:

{
    "EventNamespace": "accelbyte",
    "EventName": "enhanced_presence",
    "Payload":
    {
        "flight_id": "4A252BB44CADA183C26F14963290B6DA",
        "platform_name": "Windows",
        "game_state": "IN_GAMEPLAY",
        "game_context": "pvp"
    },
    "ClientTimestamp": 1684813272
}