Integrate session storage

Last updated on April 18, 2024

Introduction

AccelByte Gaming Services (AGS) session storage offers a versatile solution that caters to a wide range of gaming clients. It facilitates seamless loading within the session, 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:

Prerequisites

Game clients must have the followings permissions:

Permissions	Action	Usage
`NAMESPACE:{namespace}:SESSION:STORAGE`	`CREATE`	To insert session storage

How it works

The following diagram shows how session storage will work using AGS.

A player is granted permission to update or insert data into the 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 the session leader storage. This function can only modify the data of session storage for leader.

Unreal
Unity

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

// Get our 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 backend
// Set a bool to indicate we set something as a session leader in local cache
FJsonObjectWrapper LeaderStorage = SessionInfo_User1->GetSessionLeaderStorage();
LeaderStorage.JsonObject->SetBoolField(TEXT("is_something_enabled"), true);

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

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

// Obtained from the result callback of creating game session, joining 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 the session member storage.

note

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

Unreal
Unity

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

// Get our 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 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 listener when update session storage to backend is complete
FOnUpdateSessionMemberStorageCompleteDelegate OnUpdateSessionMemberStorageComplete = FOnUpdateSessionMemberStorageCompleteDelegate::CreateLambda(
    [&](FName SessionName, const FUniqueNetId & UpdatedMemberId, bool bWasSuccessful)
        {
            // Do something after update to backend complete
        });
SessionInterface_User1->AddOnUpdateSessionMemberStorageCompleteDelegate_Handle(OnUpdateSessionMemberStorageComplete);

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

// Obtained from the result callback of creating game session, joining 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 JSON object type in the game session.

Unreal
Unity

Read session leader storage

Get the data of session storage from leader.

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

// Get our 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 members.

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

// Get our 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 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 leader and members.

// Obtained from the result callback of creating game session, joining 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 member.

// Get notified when a session member update 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 our 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 leader or member.

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

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

Introduction​

Prerequisites​

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