Store player attributes in private records

Last updated on April 4, 2024

Overview

The Cloud Save service enables you to store your players' data privately. Storing privately means players won't be able to read other player's specific data.

The data stored is usually information which is not relevant to other players, or might be sensitive information, and is stored in JSON format. For example, you might store:

Player's personal settings, such as key bindings, graphic quality, audio preference, etc.
Player's specific information for specific use case, such as character last location for RPG games, etc.

In this guide, you will learn how to utilize a store your player's data privately, display it within the game client, and modify it according to your game use case.

Goals

Provide an understanding and overview of private player records
Provide an understanding on how to store private player data in private player records
Provide an understanding on how to display private player records
Provide an understanding on how to modify private player records
Provide an understanding on how to delete private player records
Explain how to utilize private player records using the AccelByte SDK

Prerequisites

You will need access to:

The Admin Portal
The AccelByte Unreal or Unity SDK, including the permissions:
- Client ID
- Client Secret
The AccelByte Cloud Save API documentation

Store User Data in Private Player Records

Storing user data is important for the game because this can make the game experience more enjoyable as players don't need to start over every time they play.

There are two methods to store Cloud Save private player records:

Store via a game client. The data stored can be modified from both a game client or game server.
Store via a game server. The data stored via the game server can only be modified by the game server.

The only difference between the two methods above is the write permission that can be assigned for the record. For more information about record write permissions, check this section.

Storing User Data in Private Player Records via a Game Client

This is suitable for storing player data that is not relevant for other players, and the record owner can modify the data. An example would be storing a player's graphic quality settings, key bindings, etc.

This example shows you how to store user data inside the graphicQuality key, via a game client. Please note that if the key already exists, the new record will be appended to the existing record.

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "graphicQuality";
 
TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
// 0 Low Quality, 1 Medium Quality, 2 High Quality
RecordRequest->SetNumberField(FString("textures"), 2);
RecordRequest->SetNumberField(FString("shadow"), 1);
RecordRequest->SetNumberField(FString("lighting"), 0);
RecordRequest->SetNumberField(FString("post-processing"), 2);

ApiClient->CloudSave.SaveUserRecord(Key
    , *RecordRequest
    , false
    , FVoidHandler::CreateLambda([]()
     {
         // Do something if SaveUserRecord is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if SaveUserRecord has an error
     }));

CloudSave cloudSave = AccelByteSDK.GetClientRegistry().GetApi().GetCloudSave();

bool isPublic = false;
string key = " grapicQuality";

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
    // 0 Low Quality, 1 Medium Quality, 2 High Quality
    { "textures", 0 },
    { "shadow", 2 },
    { "lighting", 1 },
    { "post-processing", 2 }
};

cloudSave.SaveUserRecord(key, recordRequest, result =>
{
    if (result.IsError)
    {
        // Do something if SaveUserRecord has an error
        Debug.Log($"Error SaveUserRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if SaveUserRecord is successful
}
, isPublic);

Storing User Data in Private Player Records via a Game Server

This is suitable for storing player data that is not relevant for other players, and the data is not editable by the record owner. An example would be storing the character's last location before the player exits the game, so that when the player launches the game it will load their last location.

The example below shows you how to store user data inside the characterLocation key, via the game server.

Unreal
Unity

FServerApiClientPtr ApiServer = FMultiRegistry::GetServerApiClient();

FString Key = "characterLocation";
FString UserId = "Player User Id";
ESetByMetadataRecord SetBy = ESetByMetadataRecord::SERVER;

TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetStringField("LastLocation", "x:120,y:200");

ApiServer->ServerCloudSave.SaveUserRecord(Key
    , UserId
    , SetBy
    , false
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
     {
         // Do something if SaveUserRecord is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if SaveUserRecord has an error
     }));

ServerCloudSave serverCloudSave = AccelByteSDK.GetServerRegistry().GetApi().GetCloudSave();

bool isPublic = false;
string key = "characterLocation";
string userId = "Player User Id";
RecordSetBy setBy = RecordSetBy.SERVER;

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
    {"LastLocation", "x:120,y:200"}
};

serverCloudSave.SaveUserRecord(userId, key, recordRequest, setBy, isPublic, result =>
{
    if (result.IsError)
    {
        // Do something if SaveUserRecord has an error
        Debug.Log($"Error SaveUserRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
    }
    else
    {
        // Do something if SaveUserRecord is successful
    }
});

Display Private Player Record Data

The private player records that are stored are only able to be retrieved by the records' owner. After the data is retrieved, you can do whatever you want to support your game use cases. As examples, you can import graphic quality settings, import key binding settings, etc.

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "graphicQuality";

ApiClient->CloudSave.GetUserRecord(Key
    , THandler<FAccelByteModelsUserRecord>::CreateLambda([](FAccelByteModelsUserRecord Result)
     {
         // Do something if GetUserRecord is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if GetUserRecord has an error
     }));

CloudSave cloudSave = AccelByteSDK.GetClientRegistry().GetApi().GetCloudSave();

string key = "graphicQuality";

cloudSave.GetUserRecord(key, result =>
{
    if (result.IsError)
    {
        // Do something if GetUserRecord has an error
        Debug.Log($"Error GetUserRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if GetUserRecord is successful
});

Modify Private Player Record Data

Player record data can be modified based on your game use case. There are two methods to modify cloud save private player records:

Modify via a game client
Modify via a game server

Modify Private Player Record via a Game Client

This is suitable if you want to allow your players to modify their player records. For example: users update their graphics settings.

There are two methods that you can use to modify the private player records:

Replace: is suitable if you want to replace the entire data with new content. If the record does not exist, it will be created based on the new data and if the record already exists it will replace the entire record.
Append: is suitable if you only want to add new keys and values to player records. This process is lighter when compared to Replace.

Replace a User Private Player Record

The example below shows you how to replace user data inside the graphicQuality key.

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "graphicQuality";
 
TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
// 0 Low Quality, 1 Medium Quality, 2 High Quality
RecordRequest->SetNumberField(FString("textures"), 2);
RecordRequest->SetNumberField(FString("shadow"), 2);
RecordRequest->SetNumberField(FString("lighting"), 2);
RecordRequest->SetNumberField(FString("post-processing"), 2);

ApiClient->CloudSave.ReplaceUserRecord(Key
    , false
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
     {
         // Do something if ReplaceUserRecord is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if ReplaceUserRecord has an error
     }));

CloudSave cloudSave = AccelByteSDK.GetClientRegistry().GetApi().GetCloudSave();

bool isPublic = false;
string key = "Your cloud save key";
Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
    // 0 Low Quality, 1 Medium Quality, 2 High Quality
    { "textures", 2 },
    { "shadow", 2 },
    { "lighting", 2 },
    { "post-processing", 2 }
};

cloudSave.ReplaceUserRecord(key, isPublic, recordRequest, result =>
{
    if (result.IsError)
    {
        // Do something if ReplaceUserRecord has an error
        Debug.Log($"Error ReplaceUserRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if ReplaceUserRecord is successful
});

Append a User Private Player Record

The example below shows you how to append user data inside the graphicQuality key.

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "graphicQuality";
 
TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetStringField("blur", "2");

ApiClient->CloudSave.SaveUserRecord(Key
    , *RecordRequest
    , false
    , FVoidHandler::CreateLambda([]()
     {
         // Do something if SaveUserRecord is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if SaveUserRecord has an error
     }));

CloudSave cloudSave = AccelByteSDK.GetClientRegistry().GetApi().GetCloudSave();

bool isPublic = true;
string key = " grapicQuality";

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
    {"LastName", "Doe" }
};

cloudSave.SaveUserRecord(key, recordRequest, result =>
{
    if (result.IsError)
    {
        // Do something if SaveUserRecord has an error
        Debug.Log($"Error SaveUserRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if SaveUserRecord is successful
}
, isPublic);

Modify Private Player Record via a Game Server

A Game server has the most permissions for modifying private player records data. For more information about record write permissions, check this section. This is suitable if you only want the game server to be able to modify player records. As an example, a game server storing a character's last location.

The example below shows you how to modify player record data inside the characterLocation key, via the game server.

Unreal
Unity

FServerApiClientPtr ApiServer = FMultiRegistry::GetServerApiClient();

FString Key = "characterLocation";
FString UserId = "Player User Id";
ESetByMetadataRecord SetBy = ESetByMetadataRecord::SERVER;

TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetStringField("LastLocation", "x:2330,y:8710");

ApiServer->ServerCloudSave.ReplaceUserRecord(Key
    , SetBy
    , false
    , UserId
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
        {
            // Do something if ReplaceUserRecord is successful
        })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
        {
            // Do something if ReplaceUserRecord has an error
        }));

ServerCloudSave serverCloudSave = AccelByteSDK.GetServerRegistry().GetApi().GetCloudSave();

string key = "characterLocation";
string userId = "Player User Id";
RecordSetBy setBy = RecordSetBy.SERVER;

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
    {"LastLocation", "x:2330,y:8710"}
};

serverCloudSave.ReplaceUserRecord(userId, key, recordRequest, setBy, false, result =>
{
    if (result.IsError)
    {
        // Do something if ReplaceUserRecord has an error
        Debug.Log($"Error ReplaceUserRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if ReplaceUserRecord is successful
});

Delete Private Player Records for a Specific User

You can also delete private player record data. Deleting player record data can be done from a game client or game server.

Deleting a User Private Player Record via a Game Client

The example below shows you how to delete user record data with the graphicQuality key, via a game client.

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "graphicQuality";

ApiClient->CloudSave.DeleteUserRecord(Key
    , FVoidHandler::CreateLambda([]()
     {
         // Do something if DeleteUserRecord is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if DeleteUserRecord has an error
     }));

CloudSave cloudSave = AccelByteSDK.GetClientRegistry().GetApi().GetCloudSave();

string key = "graphicQuality";

cloudSave.DeleteUserRecord(key, result =>
{
    if (result.IsError)
    {
        // Do something if DeleteUserRecord has an error
        Debug.Log($"Error DeleteUserRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if DeleteUserRecord is successful
});

Deleting a User Private Player Record via a Game Server

The example below shows you how to delete user record data with the characterLocation key, via a game server.

Unreal
Unity

FServerApiClientPtr ApiServer = FMultiRegistry::GetServerApiClient();

FString Key = "characterLocation";
FString UserId = "Player User Id";

ApiServer->ServerCloudSave.DeleteUserRecord(Key
    , UserId
    , false
    , FVoidHandler::CreateLambda([]()
        {
            // Do something if DeleteUserRecord is successful
        })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
        {
            // Do something if DeleteUserRecord has an error
        }));

ServerCloudSave serverCloudSave = AccelByteSDK.GetServerRegistry().GetApi().GetCloudSave();

string key = "characterLocation";
string userId = "Player User Id";

serverCloudSave.DeleteUserRecord(userId, key, result =>
{
    if (result.IsError)
    {
        // Do something if DeleteUserRecord has an error
        Debug.Log($"Error DeleteUserRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if DeleteUserRecord is successful
});

Overview​

Goals​

Prerequisites​

Store User Data in Private Player Records​

Storing User Data in Private Player Records via a Game Client​

Storing User Data in Private Player Records via a Game Server​

Display Private Player Record Data​

Modify Private Player Record Data​

Modify Private Player Record via a Game Client​

Replace a User Private Player Record​

Append a User Private Player Record​

Modify Private Player Record via a Game Server​

Delete Private Player Records for a Specific User​

Deleting a User Private Player Record via a Game Client​

Deleting a User Private Player Record via a Game Server​

On this page