Configure Lobby with the SDK

Last updated on November 15, 2024

Overview​

AccelByte Gaming Services (AGS) Lobby provides continuous connection between your game and its players by using The WebSocket Protocol. WebSockets ensure reliable, real-time data transfer by allowing two-way communication between the server and clients. Since AGS Lobby is the main hub of your game, it is connected to many of the other AGS features.

This article covers configuring Lobby with the AGS Game SDK.

Goals​

The goals of this article are to show you how to use the AGS Game SDK to:

  • Connect to AGS Lobby.
  • Handle connect and disconnect events.
  • Handle user presence.
  • Listen to notifications.

Prerequisites​

To be able to complete the steps in this article, you will need the following:

  • A familiarity with the Authentication flow that occurs before a player reaches AGS Lobby.
  • Access to the AGS Admin Portal.
  • The AGS Game SDK installed to your Unreal or Unity project and the following credentials for your game client:
    • Client ID
    • Client Secret

Connect to Lobby​

This section will show you how to connect a user to Lobby.

Use the following code to connect a user to Lobby:

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

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

Disconnect from Lobby​

This section explains how to disconnect a user from the Lobby service and best practices for doing so.

Only disconnect a user if they log out or if the game client is exiting or crashing. In these cases, use the following code:

User user = AccelByteSDK.GetClientRegistry().GetApi().GetUser();
Lobby lobby = AccelByteSDK.GetClientRegistry().GetApi().GetLobby();

void Logout()
{
    user.Logout(logoutResult =>
    {
        if (logoutResult.IsError)
        {
            // Handle logout error here
            return;
        }
        
        lobby.Disconnect();
    });
}

void OnApplicationQuit()
{
    lobby.Disconnect();
}

Handle connect and 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 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.

FRegistry::Lobby.Connect();
FRegistry::Lobby.SetConnectSuccessDelegate(AccelByte::Api::Lobby::ConnectSuccess.CreateLambda([]()
{
    // Do something when ConnectSuccessDelegate succeeds
}));
FRegistry::Lobby.SetConnectFailedDelegate(AccelByte::Api::Lobby::ConnectError.CreateLambda([]()
{
    // Do something when ConnectFailedDelegate succeeds
}));
FRegistry::Lobby.SetConnectionClosedDelegate(AccelByte::Api::Lobby::ConnectionClosed.CreateLambda([]()
{
    // Do something when ConnectionClosedDelegate succeeds
}));

Presence​

AGS Presence is part of AGS Social. Presence handles the statuses of user presences (Availability and Activity).

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

AGS Presence flow:

  1. Get all friends' presence statuses after the user initializes a connection with 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 is automatically reset to 0 when the user gets disconnected from the Lobby server.
  5. User activity is 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 by a game, the Player Portal, or a Launcher. This allows the player's friends to see when the player is online and what they are doing.

// View a friend's changed status
```cpp
// 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 or change a 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);

Get a list of friends' statuses​

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

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

Not all of the friends' statuses may return. If there are missing friends' statuses, you need to set the 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.

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 succeeds
}), 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);

Notifications​

There are several tasks involving notifications:

Send freeform notifications​

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

Send 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.

Send 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 can decide where to place the notifications based on the topic set on the notification. For example, game update notifications can be displayed as a pop up, a game server notifications can be displayed in a 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

Retrieve synchronous notifications​

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

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

You can also filter notifications by topic:

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);
    }
});
Last updated on

On this page