Integrating Presence with the client SDK

Last updated on December 5, 2024

Overview​

AccelByte Gaming Services (AGS) Presence can be used to set and retrieve player presence status so you can keep your user base informed of what other players are currently doing in game. To manage these statuses, you will use the AGS Lobby interface to call Presence functions, which will then be sent through WebSocket to ensure statuses are updated in real-time.

Because each game is unique and may need to provide more than just players' online statuses, AGS provides two parameters that you can set and retrieve:

  • Availability: Can be set to one of the following states: Offline, Available, Busy, Away, and Invisible. If a player disconnects from AGS Lobby, this will automatically be updated to offline.

  • Activity: This is customizable in order to allow the game to provide unique or specific details about a player's current state, such as Playing a Game, In Lobby, In a Match, or In Party Looking For Members.

This article provides instructions on how to integrate Presence into your game.

Prerequisites​

To be able to complete the steps in this article, you will need to have integrated AGS Lobby into your game.

Player status retrieval flow​

Before integrating AGS Presence into your game client, familiarize yourself with this general flow for setting and retrieving player statuses:

  1. On game start, connect to AGS Lobby and set the player's status to Available.
  2. Retrieve the statuses of a player's friends so they can be displayed.
  3. Register to listen for changes to friend statuses so that they can be updated.
  4. As the player changes gameplay activities, be sure to set their status accordingly.

Set player status​

To set a player's presence from the game client, you will call the update function and provide both the availability and activity states you want to set for the player as parameters.

Availability Availability = Availability::Available;
FString Activity = FString("My New Activity");

FRegistry::Lobby.Connect();
FRegistry::Lobby.SendSetPresenceStatus(Availability, Activity);

Listen for changes to friend statuses​

In order to receive real-time updates about a friend's status, you will need to register to listen for notifications. As a friend's status changes you can inform the player through the game client of the change, such as letting the player know a friend just came online.

FRegistry::Lobby.Connect();
FRegistry::Lobby.SetUserPresenceNotifDelegate(AccelByte::Api::Lobby::FFriendStatusNotif::CreateLambda([](const FAccelByteModelsUsersPresenceNotice& Result)
{
    // Do something if UserPresenceNotifDelegate has succeeded
}));

Retrieve the friends list statuses​

To provide presence statuses as part of displaying a friends list to players, you can call this function to get the status for all the player's friends:

FRegistry::Lobby.Connect();
FRegistry::Lobby.SetGetOnlineFriendsPresenceResponseDelegate(AccelByte::Api::Lobby::FGetAllFriendsStatusResponse::CreateLambda([](const FAccelByteModelsGetOnlineUsersResponse& Result)
{
   if (Result.Code == "0")
   {
      // Do something if GetOnlineFriendsPresenceResponseDelegate has succeeded
   }
   else
   {
      // Do something if GetOnlineFriendsPresenceResponseDelegate has an error
   }
}));

FRegistry::Lobby.SendGetOnlineFriendPresenceRequest();

Retrieve player statuses in bulk​

In cases where you need to provide the presence statuses between players who are not friends, you can use the function below by passing in a list of user IDs. This is useful in situations such as when players who are not friends are in a group or raid team together and need to coordinate with each other. This function can also be used to provide the count of players in a given status by setting the countOnly parameter to true when calling it.

TArray<FString> UserIds = {FString("12345abcd"), FString("abcd12345")};
bool CountOnly = true;

FRegistry::Lobby.Connect();
FRegistry::Lobby.BulkGetUserPresence(UserIds, THandler<FAccelByteModelsBulkUserStatusNotif>::CreateLambda([](const FAccelByteModelsBulkUserStatusNotif& Result)
{
    // Do something if BulkGetUserPresence has succeeded
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if BulkGetUserPresence has an error
    UE_LOG(LogTemp, Log, TEXT("Error BulkGetUserPresence, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}), CountOnly);

The following is an example of bulk user presence using the v2 version, which utilizes the post endpoint to add user IDs inside the request body. This method supports a maximum query of 100 users per batch.

note

This feature is only available in AGS version 3.76.

TArray<FString> UserIds = {FString("12345abcd"), FString("abcd12345")};
bool CountOnly = true;

FRegistry::Lobby.Connect();
FRegistry::Lobby.BulkGetUserPresenceV2(UserIds, THandler<FAccelByteModelsBulkUserStatusNotif>::CreateLambda([](const FAccelByteModelsBulkUserStatusNotif& Result)
{
    // Do something if BulkGetUserPresence succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if BulkGetUserPresence fails
    UE_LOG(LogTemp, Log, TEXT("Error BulkGetUserPresence, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}), CountOnly);
Last updated on

On this page