Managing session attribute with SDK

Last updated on November 17, 2023

Overview

This article shows how to store, read, and listen to notifications on session data updates through the Game SDK. Code snippets are provided to show the following:

• Storing session attribute
• Handling update conflicts
• Reading session attribute
• Listening to notifications on session data updates

Manage session attribute in Unity & OSS

Game sessions can contain session attributes that can be used for storing/reading data that is shared across members and dedicated server (DS) used to host the session. All session members and DS has read and write access to this data.

Storing session attribute

Storing session data requires developers to update the session with attributes. Attributes can also be filled on a game session creation.

Unity

string sessionId = "abc123"; // insert session ID here
ApiClient apiClient = MultiRegistry.GetApiClient();

var updateGameSessionRequest = new SessionV2GameSessionUpdateRequest()
{
    version = 1 // Change according to latest version from backend
};
updateGameSessionRequest.attributes.Add("testAttribute", "attributeValue");

apiClient.GetSession().PatchGameSession(sessionId, updateGameSessionRequest, result =>
{
    if (!result.IsError)
    {
        // Do something when update session results in an error
    }
    else
    {
        // Do something when update session completes succesfully
    }
});

Unreal OSS

Session attributes in unreal OSS is stored inside session settings, so you need to set the session attribute in session settings, then call UpdateSession.

FOnlineSubsystemAccelByte* AccelByteOSS = static_cast<FOnlineSubsystemAccelByte*>(IOnlineSubsystem::Get(ACCELBYTE_SUBSYSTEM));
if(AccelByteOSS == nullptr)
{
    // Bail out if AccelByteOSS is not found
    return;
}
FOnlineSessionV2AccelBytePtr SessionInterface = StaticCastSharedPtr<FOnlineSessionV2AccelByte>(AccelByteOSS->GetSessionInterface());

// Grab the local session setting data and update it with an attribute
FOnlineSessionSettings* SessionSettings = SessionInterface->GetSessionSettings(NAME_GameSession);
SessionSettings->Set(FName("attributename"), TEXT("attributeValue"));

// listen to session update session complete delegate
FDelegateHandle UpdateSessionCompleteHandle;
UpdateSessionCompleteHandle = SessionInterface->AddOnUpdateSessionCompleteDelegate_Handle(FOnUpdateSessionCompleteDelegate::CreateLambda(
    [&SessionInterface, &UpdateSessionCompleteHandle](FName SessionName, bool bWasSuccessful)
    {
        // Do something after the update completes here
        // Removing the delegate handler so it doesn't trigger another time
        SessionInterface->ClearOnUpdateSessionCompleteDelegate_Handle(UpdateSessionCompleteHandle);
    }));

SessionInterface->UpdateSession(NAME_GameSession, *SessionSettings);

備考

Attributes will also be filled if a session that is using attributes in the match ticket is created from matchmaking.

Handling update conflicts

Requests to update session data will only be accepted if the update request�s version is equal to the version in backend.

Unity

In Unity, if an update request failed because of old data, it will respond with error code ErrorCode.SessionVersionMismatch.
If you received this error code, you must query the backend first to get the latest session data, then retrythe update with the latest session version.

Unreal OSS

In Unreal OSS, if your update request failed because of a conflicting update, the OSS will refresh the session data and query for the latest backend data. After that, it will trigger delegate set in AddOnSessionUpdateConflictErrorDelegate_Handle while passing in the session setting that failed to update. Then, you can retry the update session call.

SessionInterface->AddOnSessionUpdateConflictErrorDelegate_Handle(FOnSessionUpdateConflictErrorDelegate::CreateLambda(
[](FName SessionName, FOnlineSessionSettings FailedSessionSettings)
{
    // Do something when the update session fails because of update conflict
}));

Reading session attribute

Session attributes will be returned when you request for game session details.

Unity

string sessionId = "abc123"; // Insert session ID here
ApiClient apiClient = MultiRegistry.GetApiClient();
Dictionary<string, object> sessionAttributes;

apiClient.GetSession().GetGameSessionDetailsBySessionId(sessionId, result =>
{
    if (!result.IsError)
    {
        sessionAttributes = result.Value.attributes;
    }
});

Unreal OSS

FOnlineSubsystemAccelByte* AccelByteOSS = static_cast<FOnlineSubsystemAccelByte*>(IOnlineSubsystem::Get(ACCELBYTE_SUBSYSTEM));
if(AccelByteOSS == nullptr)
{
    // Bail out if AccelByteOSS is not found
    return;
}
FOnlineSessionV2AccelBytePtr SessionInterface = StaticCastSharedPtr<FOnlineSessionV2AccelByte>(AccelByteOSS->GetSessionInterface());

// Get the attribute value
FString Attribute{};
SessionInterface->GetSessionSettings(NAME_GameSession)->Get(FName("attributename"), Attribute);

Listening to notifications on session data updates

When there is an update to the session, notifications will be sent to each user in the session. You can add a listener for this notification to know if there is an update.

Unity

ApiClient apiClient = MultiRegistry.GetApiClient();
Dictionary<string, object> sessionAttributes;

apiClient.GetLobby().SessionV2GameSessionUpdated += notif =>
{
    sessionAttributes = notif.Value.attributes;
};

Unreal OSS

FOnlineSubsystemAccelByte* AccelByteOSS = static_cast<FOnlineSubsystemAccelByte*>(IOnlineSubsystem::Get(ACCELBYTE_SUBSYSTEM));
if(AccelByteOSS == nullptr)
{
    // Bail out if AccelByteOSS is not found
    return;
}
FOnlineSessionV2AccelBytePtr SessionInterface = StaticCastSharedPtr<FOnlineSessionV2AccelByte>(AccelByteOSS->GetSessionInterface());

UpdateNotificationHandle = SessionInterface->AddOnSessionUpdateReceivedDelegate_Handle(FOnSessionUpdateReceivedDelegate::CreateLambda(
    [&UpdateNotificationHandle, &SessionInterface_User2](FName SessionName) {
        // do something once we received session update delegate
    }));