プレゼンスを 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.

Unreal Engine

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

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

Unity

UserStatus status = UserStatus.Online;
string activity = "My New Activity";

AccelByteSDK.GetClientRegistry().GetApi().GetLobby().Connect();
AccelByteSDK.GetClientRegistry().GetApi().GetLobby().SetUserStatus(status, activity, result =>
{
    if (result.IsError)
    {
        // Do something if SetUserStatus has an error
        Debug.Log($"Error SetUserStatus, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
    }
    else
    {
        // Do something if SetUserStatus has succeeded
    }
});

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.

Unreal Engine

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

Unity

AccelByteSDK.GetClientRegistry().GetApi().GetLobby().Connect();
AccelByteSDK.GetClientRegistry().GetApi().GetLobby().FriendsStatusChanged += result =>
{
    if (result.IsError)
    {
        // Do something if FriendsStatusChanged has an error
        Debug.Log($"Error FriendsStatusChanged, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
    }
    else
    {
        // Do something if FriendsStatusChanged 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:

Unreal Engine

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

Unity

AccelByteSDK.GetClientRegistry().GetApi().GetLobby().Connect();
AccelByteSDK.GetClientRegistry().GetApi().GetLobby().ListFriendsStatus(result =>
{
    if (result.IsError)
    {
        // Do something if ListFriendsStatus has an error
        Debug.Log($"Error ListFriendsStatus, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
    }
    else
    {
        // Do something if ListFriendsStatus has succeeded
    }
});

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.

Unreal Engine

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);

Unity

string[] userIds = { "12345abcd", "abcd12345" };
bool countOnly = true;

AccelByteSDK.GetClientRegistry().GetApi().GetLobby().Connect();
AccelByteSDK.GetClientRegistry().GetApi().GetLobby().BulkGetUserPresence(userIds, result =>
{
    if (result.IsError)
    {
        // Do something if BulkGetUserPresence has an error
        Debug.Log($"Error BulkGetUserPresence, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
    }
    else
    {
        // Do something if BulkGetUserPresence has succeeded
    }
}, 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.

注記

This feature is only available in AGS version 3.76.

Unreal Engine

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);

Unity

This feature is not yet available for Unity.