Integrate session storage

Last updated on October 24, 2024

Introduction

AccelByte Gaming Services (AGS) Session has storage capability that offers a versatile solution that caters to a wide range of gaming clients. It facilitates seamless loading within sessions, while providing distinct permissions for leader and public data. Public data will be accessible for reading but can only be modified by its owner. This functionality streamlines the storage of session data for game developers, enhancing overall efficiency.

This article contains code snippets for the following functions:

How it works

The diagram below shows how session storage works using AGS.

A player is granted permission to update or insert data into session storage if they are both registered and active in the game session. Access is restricted to players who have joined and connected to the respective game session. Players who already left or disconnected from a session will not be allowed to update the session storage.

Update session storage

If there's no data in the session storage, create it. If there's already data, update it in the game session.

Update session leader storage

Modify the data for session leader storage. This function can only modify the data of session storage for leader.

Unreal
Unity

// Get the named session object
const FNamedOnlineSession* TestGameSession_User1 = SessionInterface_User1->GetNamedSession(NAME_GameSession);
if (TestGameSession_User1 == nullptr)
{
    return;
}

// Get the named game session's info object and cast it to FOnlineSessionInfoAccelByteV2
TSharedPtr<FOnlineSessionInfoAccelByteV2> SessionInfo_User1 = StaticCastSharedPtr<FOnlineSessionInfoAccelByteV2>(TestGameSession_User1->SessionInfo);
if (!SessionInfo_User1.IsValid())
{
    return;
}

// Set and update leader data to the backend
// Set a bool to indicate something was set as a session leader in a local cache
FJsonObjectWrapper LeaderStorage = SessionInfo_User1->GetSessionLeaderStorage();
LeaderStorage.JsonObject->SetBoolField(TEXT("is_something_enabled"), true);

// Set a listener when the update session leader storage to backend completes
FOnUpdateSessionLeaderStorageCompleteDelegate OnUpdateLeaderStorageComplete = FOnUpdateSessionLeaderStorageCompleteDelegate::CreateLambda(
    [&] (FName SessionName, bool bWasSuccessful)
    {
        if (bWasSuccessful)
        {
            // Do something after updating leader storage completes
        }
    });
SessionInterface_User1->AddOnUpdateSessionLeaderStorageCompleteDelegate_Handle(OnUpdateLeaderStorageComplete);

// Execute updating session leader storage to the backend
SessionInterface_User1->UpdateSessionLeaderStorage(LocalUserId1.ToSharedRef().Get(), NAME_GameSession);

// Obtained from the result callback of creating a game session, joining a game session, etc.
string sessionId = "<game-session-id>";
var data = new SessionStorageTestData
{
    StringField = "This is a string value",
    IntegerField = 99,
    BooleanField = true,
    FloatField = 3.14f,
    DoubleField = 2.718,
    ArrayOfIntegerField = new int[] { 1, 1, 2, 3, 5, 8 }
};
var jData = JObject.FromObject(data);

AccelByteSDK.GetClientRegistry().GetApi().GetSession().UpdateLeaderStorage(sessionId, jData, result => 
{
    if (result.IsError)
    {
        // Handle the error
        Debug.Log(result.Error.Message);
        return;
    }
    // Do something
});

Update session member storage

Modify the data for session member storage. This function can only modify the data of session storage for members (non-leaders).

Unreal
Unity

// Get the named session object
const FNamedOnlineSession* TestGameSession_User1 = SessionInterface_User1->GetNamedSession(NAME_GameSession);
if (TestGameSession_User1 == nullptr)
{
    return;
}

// Get the named game session's info object and cast it to FOnlineSessionInfoAccelByteV2
TSharedPtr<FOnlineSessionInfoAccelByteV2> SessionInfo_User1 = StaticCastSharedPtr<FOnlineSessionInfoAccelByteV2>(TestGameSession_User1->SessionInfo);
if (!SessionInfo_User1.IsValid())
{
    return;
}

// Get the current logged in session member's storage, then update it locally.
FJsonObjectWrapper CurrentMemberStorage = SessionInfo_User1->GetCurrentUserSessionMemberStorage();
CurrentMemberStorage.JsonObject->SetStringField(TEXT("weapon"), TEXT("AK-74"));

// Set the listener when update session storage to the backend completes
FOnUpdateSessionMemberStorageCompleteDelegate OnUpdateSessionMemberStorageComplete = FOnUpdateSessionMemberStorageCompleteDelegate::CreateLambda(
    [&](FName SessionName, const FUniqueNetId & UpdatedMemberId, bool bWasSuccessful)
        {
            // Do something after the update to the backend completes
        });
SessionInterface_User1->AddOnUpdateSessionMemberStorageCompleteDelegate_Handle(OnUpdateSessionMemberStorageComplete);

// Execute updating session member to the backend
SessionInterface_User1->UpdateSessionMemberStorage(LocalUserId1.ToSharedRef().Get(), NAME_GameSession);

// Obtained from the result callback of creating a game session, joining a game session, etc
string sessionId = "<game-session-id>";
var data = new SessionStorageTestData
{
    StringField = "This is a string value",
    IntegerField = 99,
    BooleanField = true,
    FloatField = 3.14f,
    DoubleField = 2.718,
    ArrayOfIntegerField = new int[] { 1, 1, 2, 3, 5, 8 }
};
var jData = JObject.FromObject(data);

AccelByteSDK.GetClientRegistry().GetApi().GetSession().UpdateMemberStorage(sessionId, 
    jData, 
    result => 
    {
        if (result.IsError)
        {
            // Handle the error
            Debug.Log(result.Error.Message);
            return;
        }
        // Do something
    }); 

Read session storage

Get the data of session storage with a JSON object type in the game session.

Unreal
Unity

Read session leader storage

Get the data of session storage from the leader.

// Get the named session object
const FNamedOnlineSession* TestGameSession_User1 = SessionInterface_User1->GetNamedSession(NAME_GameSession);
if (TestGameSession_User1 == nullptr)
{
    return;
}

// Get the named game session's info object and cast it to FOnlineSessionInfoAccelByteV2
TSharedPtr<FOnlineSessionInfoAccelByteV2> SessionInfo_User1 = StaticCastSharedPtr<FOnlineSessionInfoAccelByteV2>(TestGameSession_User1->SessionInfo);
if (!SessionInfo_User1.IsValid())
{
    return;
}

// Get session leader storage data
FJsonObjectWrapper LeaderStorage = SessionInfo_User1->GetSessionLeaderStorage();
if (LeaderStorage.JsonObject->GetBoolField(TEXT("is_something_enabled")))
{
    // Do something
};

Read session member storage

Get the data of session storage from the members.

// Get the named session object
const FNamedOnlineSession* TestGameSession_User1 = SessionInterface_User1->GetNamedSession(NAME_GameSession);
if (TestGameSession_User1 == nullptr)
{
    return;
}

// Get the named game session's info object and cast it to FOnlineSessionInfoAccelByteV2
TSharedPtr<FOnlineSessionInfoAccelByteV2> SessionInfo_User1 = StaticCastSharedPtr<FOnlineSessionInfoAccelByteV2>(TestGameSession_User1->SessionInfo);
if (!SessionInfo_User1.IsValid())
{
    return;
}

// Read all of the session's member storage
for (TPair<FUniqueNetIdRef, FJsonObjectWrapper> MemberStorage : SessionInfo_User1->GetAllSessionMemberStorage())
{
    // Do something by looping through all member storage
}

Get the data of session storage from the leader and members.

// Obtained from the result callback of creating a game session, joining a game session, etc
string sessionId = "<game-session-id>";
AccelByteSDK.GetClientRegistry().GetApi().GetSession().GetGameSessionDetailsBySessionId(sessionId, result =>
{
    if (result.IsError)
    {
        // Handle the error
        Debug.Log(result.Error.Message);
        return;
    }

    var sessionStorage = result.Value.Storage;
    // Do something
});

Listen to session storage updated event

An event that will be sent to all users in the same game session when there is a session storage update. This event is sent through a WebSocket connection to ensure that they've been received in real time.

Unreal
Unity

Session leader storage updated event

Received when there is a session storage update from leader.

// Get Notified when there is an update to session leader storage from backend
FOnSessionLeaderStorageUpdateReceivedDelegate OnSessionLeaderStorageUpdated = FOnSessionLeaderStorageUpdateReceivedDelegate::CreateLambda(
    [&](FName SessionName)
    {
        ///
        // Do something when we received an update to session leader storage
        ///
    });
SessionInterface_User1->AddOnSessionLeaderStorageUpdateReceivedDelegate_Handle(OnSessionLeaderStorageUpdated);

Session member storage updated event

Received when there is a session storage update from a member.

// Get notified when a session member updates their storage
FOnSessionMemberStorageUpdateReceivedDelegate OnSessionMemberStorageUpdated = FOnSessionMemberStorageUpdateReceivedDelegate::CreateLambda(
    [&](FName SessionName, const FUniqueNetId & UpdatedMemberId)
    {
        // Get our named session object
        const FNamedOnlineSession * TestGameSession_User1 = SessionInterface_User1->GetNamedSession(SessionName);
        if (TestGameSession_User1 == nullptr)
        {
            return;
        }

        // Get the named game session's info object and cast it to FOnlineSessionInfoAccelByteV2
        TSharedPtr<FOnlineSessionInfoAccelByteV2> SessionInfo_User1 = StaticCastSharedPtr<FOnlineSessionInfoAccelByteV2>(TestGameSession_User1->SessionInfo);
        if (!SessionInfo_User1.IsValid())
        {
            return;
        }

        // Get the changed member storage
        FJsonObjectWrapper UpdatedSessionMemberStorage = SessionInfo_User1->GetSessionMemberStorage(UpdatedMemberId.AsShared());

        // Do something with the updated storage
        // ...
        // ...
    });
SessionInterface_User1->AddOnSessionMemberStorageUpdateReceivedDelegate_Handle(OnSessionMemberStorageUpdated);

Received when there is a session storage update from the leader or a member.

AccelByteSDK.GetClientRegistry().GetApi().GetLobby().SessionV2StorageChanged += result =>
{
    if (result.IsError)
    {
        // Handle the error
        Debug.Log(result.Error.Message);
        return;
    }

    // Do something when receiving an update to session leader or member storage
};

Introduction​

How it works​

Update session storage​

Update session leader storage​

Update session member storage​

Read session storage​

Read session leader storage​

Read session member storage​

Listen to session storage updated event​

Session leader storage updated event​

Session member storage updated event​

On this page