Configure the Lobby with the SDK

Last updated on April 23, 2024

Overview

AccelByte Lobby service provides a continuous connection between your game and players. Since the Lobby serves as the main hub of your game, it is connected to many of our other services.

The Lobby service uses The WebSocket Protocol, which ensures reliable, real-time data transfer by allowing two-way communication between the server and clients.

Goals for this Topic

• How to connect to the Lobby service
• How to handle connect/disconnect events
• How to handle user presence
• How to listen to notifications

Prerequisites

• You should be familiar with our Authentication flow, that occurs before a player reaches the Lobby.
• You have access to the Admin Portal, and can log in.
• You have installed the AccelByte Unreal or Unity SDK. This includes credentials for your game client:
  • Client ID
  • Client Secret
• You have access to the AccelByte Lobby API documentation.

Implement the Lobby in Client SDKs

Connect to the Lobby

You can connect the AccelByte Lobby service to your game by using the command below:

OSS

There are two ways to connect to lobby in the AccelByte Online Subsystem (OSS):

1. Setting bAutoLobbyConnectAfterLoginSuccess to true in the DefaultEngine.ini, [OnlineSubsystemAccelByte] section. Once set, OSS will try to connect to the lobby upon a successful user login.
2. If it's not automatically connected, you can call FOnlineIdentityAccelByte::ConnectAccelByteLobby.

// Manually connect to lobby

int32 LocalUserNum = 0;

FOnlineIdentityAccelBytePtr IdentityInterface = StaticCastSharedPtr<FOnlineIdentityAccelByte>(OnlineSubsystem->GetIdentityInterface());
AB_TEST_TRUE(IdentityInterface.IsValid());
IdentityInterface->ConnectAccelByteLobby(LocalUserNum);

Unreal Engine

AccelByte::FRegistry::Lobby.Connect();

Unity

AccelByteSDK.GetClientRegistry().GetApi().GetLobby().Connect();

Once you have set up a Lobby connection, you can add lobby features such as Presence, Party, Friends, and Chat.

Handle Connect/Disconnect Events

note

1. For troubleshooting purposes, make sure you call the disconnect function when your player voluntarily quits the game (e.g., through the menu, using Alt+F4, turning off the game console, etc.). You do not need to call the function on accidental shutdowns (e.g., game crashes, power outages, etc.).

2. You can look up the code of the Disconnected callbacks in your developer environment (e.g., https://prod.gamingservices.accelbyte.io/lobby/v1/messages).

3. A SetReconnectingDelegate will be triggered when the SDK automatically reconnects to the lobby.

4. ConnectionClosed will be triggered if auto-reconnect times out with the following status code:

EWebsocketErrorTypes::DisconnectFromExternalReconnect (4042)
Reconnection total timeout limit reached

This feature notifies the game of any changes to the Lobby server connection. The SDK already provides an auto-reconnect mechanism, but when the auto-reconnect times out, you must reconnect manually.

OSS

In OSS, the Lobby will automatically disconnect when a user logs out.

Unreal Engine

FRegistry::Lobby.Connect();
FRegistry::Lobby.SetConnectSuccessDelegate(AccelByte::Api::Lobby::ConnectSuccess.CreateLambda([]()
{
    // Do something If ConnectSuccessDelegate has been successful
}));
FRegistry::Lobby.SetConnectFailedDelegate(AccelByte::Api::Lobby::ConnectError.CreateLambda([]()
{
    // Do something if ConnectFailedDelegate has been successful
}));
FRegistry::Lobby.SetConnectionClosedDelegate(AccelByte::Api::Lobby::ConnectionClosed.CreateLambda([]()
{
    // Do something if ConnectionClosedDelegate has been successful
}));

Unity

var lobby = AccelByteSDK.GetClientRegistry().GetApi().GetLobby();

lobby.Connect();
lobby.Connected += () =>
{
    // Do something if Lobby Connected
};

lobby.Disconnected += error =>
{
    // Do something if Lobby Disconnected
    Debug.Log($"Lobby Disconnected, Error Code: {(int) error}");
};

Presence

The Presence service is part of the Social package. The Presence service handles user presence (availability and activity) status.

Availability status is how users want to be seen when going online (for example: online, offline, away). Activity status is an arbitrary string value that can be used to show the user's current activity (for example: idle, playing shooter game, in Lobby, in matchmaking, in match). The Presence service depends on the Friends service, as a filter to list online friends and get changing presence status.

General workflow:

1. Get all friends' presence status (availability and activity), after the user initializes a connection with the Lobby.
2. Set the user status every time the user changes activity.
3. Listen for friends' presence status updates, and update friends' presence status.
4. User availability will be automatically reset to 0 when the user gets disconnected from the Lobby server.
5. User activity will be kept when the user gets disconnected from the Lobby server.

Availability represented as an enum integer:

• 0 : offline
• 1 : available
• 2 : busy
• 3 : invisible

Activity can be set as any string. For example:

• "Playing Survival"
• "In Lobby"
• "In Match"

Create a Status and View a Friend's Status

A player's presence can be set either by a game, the Player Portal, or the Launcher. This allows the player's friends to see when the player is online and what they are doing.

OSS

OnlineSubsystem = static_cast<FOnlineSubsystemAccelByte*>(IOnlineSubsystem::Get(ACCELBYTE_SUBSYSTEM));
PresenceInterface = OnlineSubsystem->GetPresenceInterface();

// listen to friend presence change notification
auto OnPresenceReceived = PresenceInterface->AddOnPresenceReceivedDelegate_Handle(FOnPresenceReceivedDelegate::CreateLambda([](const class FUniqueNetId& UserId, const TSharedRef<FOnlineUserPresence>& Presence)
  {
     // do something when friend presence changed
  }));

// create / change status
PresenceInterface->SetPresence(*CurrentUser.Get(), Status, IOnlinePresence::FOnPresenceTaskCompleteDelegate::CreateLambda([](const FUniqueNetId& User, bool bWasSuccessful)
  {
     // do something when presence set presence success
  }));

Unreal Engine

// View Changed Friend's Status
AccelByte::FRegistry::Lobby.SetUserPresenceNotifDelegate(THandler<FAccelByteModelsUsersPresenceNotice>::CreateLambda([](const FAccelByteModelsUsersPresenceNotice Result)
{
    UE_LOG(LogTemp, Log, TEXT("Friend %s, Activity: %s | Availability: %s "), Result.UserID, Result.Activity, Result.Availability);
}
));

// Create/Change Status
AccelByte::FRegistry::Lobby.SetUserPresenceResponseDelegate(Api::Lobby::FSetUserPresenceResponse::CreateLambda([](FAccelByteModelsSetOnlineUsersResponse result)
{
    UE_LOG(LogTemp, Log, TEXT("User Status Changed!"));
}));

FString UserActivity = TEXT("Playing Game");
AccelByte::FRegistry::Lobby.SendSetPresenceStatus(Availability::Busy, UserActivity);

Unity

AccelByteSDK.GetClientRegistry().GetApi().GetLobby().FriendsStatusChanged += result =>
{
    if (result.IsError)
    {
        // Do something when received an error from FriendsStatusChanged
        Debug.Log(result.Error.Message);
        return;
    }

    // Do something when receiving a FriendsStatusChanged is successful
    Debug.Log("Friend " + result.Value.userID + ", Activity: " + result.Value.activity + " | Availability: " + result.Value.availability);
};

// Create/Change Status
string userActivity = "Playing Game";
AccelByteSDK.GetClientRegistry().GetApi().GetLobby().SetUserStatus(
    UserStatus.Busy,
    userActivity,
    result =>
    {
        if (result.IsError)
        {
            // Do something when SetUserStatus is failed
            Debug.Log(result.Error.Message);
            return;
        }

        // Do something when the SetUserStatus is successful
        Debug.Log("User Status Changed!");
    }
);

Get a List of Friends' Statuses

Players can also see a list of all of their friends' statuses.

Unreal Engine

AccelByte::FRegistry::Lobby.SetGetAllUserPresenceResponseDelegate(Api::Lobby::FGetAllFriendsStatusResponse::CreateLambda([](FAccelByteModelsGetOnlineUsersResponse result)
{
    for(int i = 0; i < Result.friendId.Num(); i++)
    {
        UE_LOG(LogTemp, Log, TEXT("Friend %s, Activity: %s | Availability: %s "), Result.friendId[i], Result.Activity[i], Result.Availability[i]);
    }
}));
AccelByte::FRegistry::Lobby.SendGetOnlineUsersRequest();

OSS

This feature is not available in OSS.

Unity

AccelByteSDK.GetClientRegistry().GetApi().GetLobby().ListFriendsStatus(result =>
{
    if (result.IsError)
    {
        // Do something when ListFriendsStatus is failed
        Debug.Log(result.Error.Message);
        return;
    }

    // Do something when the ListFriendsStatus is successful
    for (int i = 0; i < result.Value.friendsId.Length; i++)
    {
        Debug.Log("Friend " + result.Value.friendsId[i] + ", Activity: " + result.Value.activity[i] + " | Availability: " + result.Value.availability[i]);
    }
});

note

It may not return all of the friends' statuses. If there are missing friends' statuses, you need to set that availability to offline in the game implementation.

Bulk Friends Presence

You can retrieve all players' presence information in bulk. This will also count the number of users based on their presence status (such as online, busy, invisible, or offline). You can also set the countOnly parameter to true to fetch the count without fetching the users' account data.

OSS

OnlineSubsystem = static_cast<FOnlineSubsystemAccelByte*>(IOnlineSubsystem::Get(ACCELBYTE_SUBSYSTEM));
PresenceInterface = OnlineSubsystem->GetPresenceInterface();

auto OnPresenceReceived = PresenceInterface->AddOnPresenceReceivedDelegate_Handle(FOnPresenceReceivedDelegate::CreateLambda([](const class FUniqueNetId& UserId, const TSharedRef<FOnlineUserPresence>& Presence)
  {
     // do something when query user Presence done
  }));
PresenceInterface->QueryPresence(UserId);

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 been successful
}), 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

var userIds = new List<string>();
userIds.Add("123456789");
userIds.Add("987654321");
bool countOnly = false;

AccelByteSDK.GetClientRegistry().GetApi().GetLobby().BulkGetUserPresence(userIds.ToArray(), result =>
{
    if (result.IsError)
    {
        // Do something when BulkGetUserPresence is failed
        Debug.Log("Error: " + result.Error.Code + " | Message: " + result.Error.Message);

        return;
    }

    // Do something when the BulkGetUserPresence is successful

    foreach (var user in result.Value.data)
    {
        Debug.Log("UserId: " + user.userID + " | Availability: " + user.availability.ToString());
    }
    Debug.Log("User's status count. Online: " + result.Value.online + " | Busy:" + result.Value.busy + " | Invisible:" + result.Value.invisible + " | Offline:" + result.Value.offline);

}, countOnly);

Notifications

There are several tasks involving notifications:

Sending Freeform Notifications

1. Call the notification REST API endpoint, to send any text notification messages.
2. The notification clients listen for new notifications.

Sending Templated Notifications

1. An admin will create notification templates with a template slug (identifier), context (template values to be replaced), and template language.
2. An admin will publish the template.
3. The template slug, context, and language are sent to the service consumer (admin user or other service).
4. The service consumer calls the notification REST API endpoint, specifying the template slug, language, and the value of template context.
5. The notification clients listen for new notifications.

Sending Asynchronous Notifications

1. Follow the workflow of freeform or templated notifications.
2. When calling the REST API endpoint, specify the query parameter as asynchronous..
3. A message will be immediately sent if the player is online.
4. A message will be stored if the player is offline.

Get Stored Notifications

1. A player connects to the Lobby server.
2. A notification can be sent to a player.

All notifications sent to users are in a general format. Clients could decide where to display/put the notification based on the topic set on the notification. For example, game update notifications are displayed as a pop up, game server notifications are displayed in the "system" chat box, etc.

Websocket Notification Format

A Notification message:

type: messageNotif
topic: updateNotification
from: system
to: user123
payload: message content 123
sentAt: 2018-11-25T23:45:05Z

Retrieving Notifications from the SDK

Notifications can be retrieved either synchronously or asynchronously.

Get Synchronous Notifications

To retrieve a synchronous notification using the SDK, you need to add the notification delegate.

Unreal Engine

const auto NotificationDelegate = AccelByte::Api::Lobby::FMessageNotif::CreateLambda([](const FAccelByteModelsNotificationMessage& Result)
{
UE_LOG(LogTemp, Log, TEXT("There is an incoming notification."));
UE_LOG(LogTemp, Log, TEXT("From: %s \nTo: %s\nTopic: %s"), *Result.From, *Result.To, *Result.Topic);
UE_LOG(LogTemp, Log, TEXT("Notification: %s"), *Result.Payload);
});

AccelByte::FRegistry::Lobby.SetMessageNotifDelegate(NotificationDelegate);
AccelByte::FRegistry::Lobby.Connect();

OSS

This feature is not available in OSS

Unity

public static void OnReceiveNotification(Result<Models.Notification> result)
{
    if (result.IsError)
    {
        // Do something when receiving OnReceiveNotification is failed
        Debug.Log(result.Error.Message);
        return;
    }

    // Do something when receiving OnReceiveNotification is successful
    Debug.Log(result.IsError);
    Debug.Log("There is an incoming notification.");
    Debug.Log(result.Value.payload);
}

public static void Main(string[] args)
{
    var lobby = AccelByteSDK.GetClientRegistry().GetApi().GetLobby();
    lobby.OnNotification += OnReceiveNotification;
    lobby.Connect();
}

You can also filter notifications by topic:

Unreal Engine

const auto NotificationDelegate = AccelByte::Api::Lobby::FMessageNotif::CreateLambda([](const FAccelByteModelsNotificationMessage& Result)
{
    UE_LOG(LogTemp, Log, TEXT("There is an incoming notification."));
    if(Result.Topic == “INGAME”)
    {
        UE_LOG(LogTemp, Log, TEXT("Game notification: %s"), *result.Payload);
    }
    Else if(Result.Topic == “EVENT”)
    {
        UE_LOG(LogTemp, Log, TEXT("Event notification: %s"), *result.Payload);
    }
});

OSS

This feature is not available in OSS

Unity

public static void OnReceiveNotification(Result<Models.Notification> result)
{
    if (result.IsError)
    {
        // Do something when receiving OnReceiveNotification is failed
        Debug.Log(result.Error.Message);
        return;
    }

    // Do something when receiving OnReceiveNotification is successful
    Debug.Log("There is an incoming notification.");
    switch (result.Value.topic)
    {
        case "INGAME" : Debug.Log("Game notification: " +result.Value.payload); break;
        case "EVENT" : Debug.Log("Event notification: " +result.Value.payload); break;
    }
}