Cloud Save

Last updated on 15 July, 2022 1:44 AM

Overview

AccelByte Cloud's Cloud Save service stores arbitrary data in JSON format. With Cloud Save, you can store, retrieve, update, and delete any data from your game. Game data can be stored in one of two types of records:

Game Records which store game data such as event configurations and themes.
Player Records which store player records such as saved game data.

Permissions

Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage cloud save in the Admin Portal. For a full list of permissions that impact Cloud Save, see the Profile, Stats & Cloud Save tab of the permissions reference.

Usage	Resource	Action
Save namespace level record	ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD	Create
Save or replace game record	ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD	Update
Purge all records under the given key	ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD	Create, Delete
Retrieve list of records key by namespace	ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD	Read
Retrieve a record value by its key	ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD	Read
Save or modify public player records	ADMIN:NAMESPACE:{namespace}:USER:*:PUBLIC:CLOUDSAVE:RECORD	Update
Save or modify private player records	NAMESPACE:{namespace}:USER:{userId}:CLOUDSAVE:RECORD	Update

Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

Metadata

Metadata allows admins and players to define the behavior of the Cloud Save records. Record metadata is defined in the request body with the field name __META. Metadata is assigned with a default value if not otherwise defined.

Write Permission (set_by)
This metadata indicates which party modified the record. This metadata is available in the admin endpoint only. The value options are:
- Server: the record can only be modified by the server.
- Client: the record can be modified by both clients and the server. This is the default value.
  Write permission behavior metrics on the Game Record:
  Admin Player
  Server Modify, Read Read
  Client Modify, Read Modify, Read
  Write permission behavior metrics on the Player Record:
  Admin Player
  Record Owner Other Players
  Server Modify - -
  Client Modify Modify -
Is Public Record (is_public)
This metadata indicates whether the record is public or not and is available in both admin and public endpoints. The value options are:
- True: meaning that the record is a public record.
- False: meaning that the record is a private record. This is the default value.
  Is Public Record behavior metrics on the Player Record:
  Admin Player
  Record Owner Other Players
  False Read Read -
  True Read Read Read

	Admin	Player
Server	Modify, Read	Read
Client	Modify, Read	Modify, Read

	Admin	Player
Server	Modify	-	-
Client	Modify	Modify	-

	Admin	Player
False	Read	Read	-
True	Read	Read	Read

Manage Cloud Saves in the Admin Portal

Create a New Game Record

In the Game Management section of the Admin Portal, go to the Cloud Save menu and select Game Records.
On the Cloud Save page, click the Create Game Record button.
The Add Record form will appear. Fill in the required fields.
- Input the Game Record Key using the appropriate format.
- Select the Write Permission from the dropdown menu. See Metadata for a full list of the available options.
- Input the JSON Configuration.
Once completed, click the Add button and the new record will be added to the list.

Update a Record

Game Record

To update a Game Record, go to the Game Records page, choose the record you want to update, and select View.

In the Record Detail window, go to the JSON Configuration section and click Edit. Input the updated record information and click Save.

Player Record

To update a Player Record, go to the Player Record page, choose the record you want to update, and select View.

In the Record Detail window, go to the JSON Configuration section and click Edit. Input the updated record information and click Save.

A confirmation will appear. Click Save to complete your update.

Integrate Your Game with Cloud Save at the User Level

Create a New Record

This example shows you how to store user data inside the graphicQuality key using the SaveUserRecord() function. Please note that if the key already exists, the new record will be appended to the existing record.

Unreal Engine
Unity

FString Key = FString("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);

FRegistry::CloudSave.SaveUserRecord(Key, *RecordRequest, false, FVoidHandler::CreateLambda([]()
{
    // Do something if SaveUserRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString ErrorMessage)
{
    // Do something if SaveUserRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error SaveUserRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string key = "graphicQuality";

        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 }
        };

        AccelBytePlugin.GetCloudSave().SaveUserRecord(key, recordRequest, false, 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 has been successful
            }
        });

Retrieve a User Record

User data stored in a private record can be retrieved using the GetUserRecord() function.

Unreal Engine
Unity

FString Key = FString("graphicQuality");

FRegistry::CloudSave.GetUserRecord(Key, THandler<FAccelByteModelsUserRecord>::CreateLambda([](const FAccelByteModelsUserRecord& Result)
{
    // Do something if GetUserRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetUserRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetUserRecord, Error Code: %d Error Message %s"), ErrorCode, *ErrorMessage);
}));

string key = "graphicQuality";

        AccelBytePlugin.GetCloudSave().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}");
            }
            else
            {
                // Do something if GetUserRecord has been successful
            }
        });

Retrieve a Public User Record

A public user record can be retrieved by another user. To get another user's public records, you can use the GetPublicUserRecord() function.

Unreal Engine
Unity

FString Key = FString("playerStatus");
FString UserId = FString("SomeUserId");

FRegistry::CloudSave.GetPublicUserRecord(Key, UserId, THandler<FAccelByteModelsUserRecord>::CreateLambda([](const FAccelByteModelsUserRecord& Result)
{
    // Do something if GetPublicUserRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetPublicUserRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetPublicUserRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string key = "playerStatus";
        string userId = "SomeUserId";

        AccelBytePlugin.GetCloudSave().GetPublicUserRecord(key, userid, result =>
        {
            if (result.IsError)
            {
                // Do something if GetPublicUserRecord has an error
                Debug.Log($"Error GetPublicUserRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if GetPublicUserRecord has been successful
            }
        });

Replace a User Record

You can update data using the ReplaceUserRecord() function, even when the data does not exist. If the data does not exist, it will be created based on the data in the update. This data can be stored either publicly or privately.

Unreal Engine
Unity

FString Key = FString("graphicQuality");

TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetNumberField(FString("textures"), 2);
RecordRequest->SetNumberField(FString("shadow"), 1);
RecordRequest->SetNumberField(FString("lighting"), 0);
RecordRequest->SetNumberField(FString("post-processing"), 1);

FRegistry::CloudSave.ReplaceUserRecord(Key, *RecordRequest, false, FVoidHandler::CreateLambda([]()
{
    // Do something if ReplaceUserRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if ReplaceUserRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error ReplaceUserRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string key = "graphicQuality";

        Dictionary<string, object> recordRequest = new Dictionary<string, object>
        {
            { "textures", 50 },
            { "shaodw", 25 },
            { "lighting", 20 },
            { "post-processing", 15 }
        };

        AccelBytePlugin.GetCloudSave().ReplaceUserRecord(key, recordRequest, false, result =>
        {
            if (result.IsError)
            {
                // Do somtehing if ReplaceUserRecord has an error
                Debug.Log($"Error ReplaceUserRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if ReplaceUserRecord has been successful
            }
        });

Replace User Records Concurrently

This feature will send an error message when a client tries to submit changes to a user record that has been changed at the same time by another client to ensure that edits to user records made concurrently aren't overwritten. There are two possible implementations of this feature: Manual and Automatic:

Manual

The manual implementation will return the error ErrorCode.PlayerRecordPreconditionFailed in Unity or ErrorCodes::PlayerRecordPreconditionFailedException in Unreal Engine if the record has been changed since it was retrieved by the client. You'll need to input the last updated time of the record, which can be found using the GetUserRecord function.

Unreal Engine
Unity

FString Key = FString("playerEquipments");

FRegistry::CloudSave.GetUserRecord(Key, THandler<FAccelByteModelsUserRecord>::CreateLambda([&](const FAccelByteModelsUserRecord& Result)
{
    TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
    RecordRequest->SetNumberField(FString("armor"), 3);
    RecordRequest->SetNumberField(FString("weapon"), 4);
    RecordRequest->SetNumberField(FString("ring"), 2);
    RecordRequest->SetNumberField(FString("wing"), 1);
    RecordRequest->SetNumberField(FString("mount"), 3);

    FRegistry::CloudSave.ReplaceUserRecordCheckLatest(Key, Result.UpdatedAt, *RecordRequest, FVoidHandler::CreateLambda([]()
    {
        // Do something if ReplaceUserRecordCheckLatest has been successful
    }), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if ReplaceUserRecordCheckLatest has an error
        UE_LOG(LogTemp, Log, TEXT("Error ReplaceUserRecordCheckLatest, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
    }));
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetUserRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetUserRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string key = "playerEquipments";

        AccelBytePlugin.GetCloudSave().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}");
            }
            else
            {
                Dictionary<string, object> recordRequest = new Dictionary<string, object>
                {
                    { "armor", 4 },
                    { "weapon", 3 },
                    { "ring", 2 },
                    { "wing", 3 },
                    { "mount", 2 }
                };
                AccelBytePlugin.GetCloudSave().ReplaceUserRecordCheckLatest(key, result.Value.updated_at, recordRequest, result =>
                {
                    if (result.IsError)
                    {
                        // Do something if ReplaceUserRecordCheckLatest has an error
                        Debug.Log($"Error ReplaceUserRecordCheckLatest, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
                    }
                    else
                    {
                        // Do something if ReplaceUserRecordCheckLatest has been successful
                    }
                });
            }
        });

Automatic

The automatic implementation will retrieve the latest update for you. You can set it as your custom modifier, which compares records that are submitted at almost the same time. When the request is submitted again, the new custom modifier will decide which record will be submitted and which record will need to be reviewed and submitted again.

Unreal Engine
Unity

int32 TryAttempt = 7;
FString Key = FString("playerEquipments");
TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetNumberField(FString("armor"), 4);
RecordRequest->SetNumberField(FString("weapon"), 2);
RecordRequest->SetNumberField(FString("ring"), 1);
RecordRequest->SetNumberField(FString("wing"), 3);
RecordRequest->SetNumberField(FString("mount"), 2);

TBaseDelegate<FJsonObject, FJsonObject> PayloadModifier = TBaseDelegate<FJsonObject, FJsonObject>::CreateLambda([RecordRequest](FJsonObject LatestRecord)
{
    for (auto Item : RecordRequest->Values)
    {
        FString Value;
        if (Item.Value->TryGetString(Value))
        {
            LatestRecord.SetStringField(Item.Key, Value);
        }
    }
    return LatestRecord;
});

FRegistry::CloudSave.ReplaceUserRecordCheckLatest(TryAttempt, Key, *RecordRequest, PayloadModifier, FVoidHandler::CreateLambda([]()
{
    // Do something if ReplaceUserRecordCheckLatest has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if ReplaceUserRecordCheckLatest has an error
    UE_LOG(LogTemp, Log, TEXT("Error ReplaceUserRecordCheckLatest, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

int tryAttempt = 7;
        string key = "playerEquipments";
        Dictionary<string, object> recordRequest = new Dictionary<string, object>
        {
            { "armor", 4 },
            { "weapon", 2 },
            { "ring", 3 },
            { "wing", 2 },
            { "mount", 5 }
        };

        Dictionary<string, object> payloadModifier(Dictionary<string, object> latestRecord)
        {
            foreach (var item in recordRequest)
            {
                latestRecord.Add(item.Key, item.Value);
            }
            return latestRecord;
        };

        AccelBytePlugin.GetCloudSave().ReplaceUserRecordCheckLatest(tryAttempt, key, recordRequest, result =>
        {
            if (result.IsError)
            {
                // Do something if ReplaceUserRecordCheckLatest has an error
                Debug.Log($"Error ReplaceUserRecordCheckLatest, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if ReplaceUserRecordCheckLatest has been successful
            }
        }, payloadModifier);

Delete a User Record

Use the DeleteUserRecord() function to delete a record.

Unreal Engine
Unity

FString Key = FString("graphicQuality");

FRegistry::CloudSave.DeleteUserRecord(Key, FVoidHandler::CreateLambda([]()
{
    // Do something if DeleteUserRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if DeleteUserRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error DeleteUserRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string key = "graphicQuality";

        AccelBytePlugin.GetCloudSave().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}");
            }
            else
            {
                // Do something if DeleteUserRecord has been successful
            }
        });

Integrate Your Game with Cloud Save at the Namespace Level

Create a New Game Record

To create a new record, use the SaveGameRecord() function. Please note that if the key already exists, the new record will be appended to the existing record.

Unreal Engine
Unity

FString Key = FString("gameMode");
TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetNumberField(FString("1v1"), 0);
RecordRequest->SetNumberField(FString("2v2"), 1);
RecordRequest->SetNumberField(FString("3v3"), 2);
RecordRequest->SetNumberField(FString("4v4"), 3);

FRegistry::CloudSave.SaveGameRecord(Key, *RecordRequest, FVoidHandler::CreateLambda([]()
{
    // Do something if SaveGameRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if SaveGameRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error SaveGameRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string key = "gameMode";
        Dictionary<string, object> recordRequest = new Dictionary<string, object>
        {
            { "1v1", 0 },
            { "2v2", 1 },
            { "3v3", 2 },
            { "4v4", 3 }
        };

        AccelBytePlugin.GetCloudSave().SaveGameRecord(key, recordRequest, result =>
        {
            if (result.IsError)
            {
                // Do something if SaveGameRecord has an error
                Debug.Log($"Error SaveGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if SaveGameRecord has been successful
            }
        });

Retrieve Game Record

Game data can be retrieved using the GetGameRecord() function.

Unreal Engine
Unity

FString Key = FString("gameMode");

FRegistry::CloudSave.GetGameRecord(Key, THandler<FAccelByteModelsGameRecord>::CreateLambda([](const FAccelByteModelsGameRecord& Result)
{
    // Do something if GetGameRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetGameRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetGameRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string key = "gameMode";

        AccelBytePlugin.GetCloudSave().GetGameRecord(key, result =>
        {
            if (result.IsError)
            {
                // Do something if GetGameRecord has an error
                Debug.Log($"Error GetGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if GetGameRecord has been successful
            }
        });

Replace a Game Record

You can update game data using the ReplaceGameRecord() function, even when the data does not exist. If the data does not exist, it will be created based on the data in the update. And if the data exists, it will replace all the data in the update.

Unreal Engine
Unity

FString Key = FString("gameMode");
TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetNumberField(FString("1v1"), 0);
RecordRequest->SetNumberField(FString("2v2"), 1);
RecordRequest->SetNumberField(FString("3v3"), 2);
RecordRequest->SetNumberField(FString("4v4"), 3);

FRegistry::CloudSave.ReplaceGameRecord(Key, *RecordRequest, FVoidHandler::CreateLambda([]()
{
    // Do something if ReplaceGameRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if ReplaceGameRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error ReplaceGameRecord, Error Code: %d, Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string key = "gameMode";
        Dictionary<string, object> recordRequest = new Dictionary<string, object>
        {
            { "1v1", 0 },
            { "2v2", 1 },
            { "3v3", 2 },
            { "4v4", 3 }
        };

        AccelBytePlugin.GetCloudSave().ReplaceGameRecord(key, recordRequest, result =>
        {
            if (result.IsError)
            {
                // Do something if ReplaceGameRecord has an error
                Debug.Log($"Error ReplaceGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if ReplaceGameRecord has been successful
            }
        });

Replace Game Records Concurrently

Just like user records, you can use this function to avoid overwriting the changes made by other users in the middle of your changes. There are both manual and automatic methods to replace game records concurrently.

Manual

The manual method will be successful only if there are no other updates on record, but will return an ErrorCode.GameRecordPreconditionFailed in Unity or ErrorCodes::PlayerRecordPreconditionFailedException error for Unreal Engine when the record has been changed since you retrieved it. You'll need to input the timestamp of the record's last update, which you can get from GetGameRecord.

Unreal Engine
Unity

FString Key = FString("gameMode");

FRegistry::CloudSave.GetGameRecord(Key, THandler<FAccelByteModelsGameRecord>::CreateLambda([&](const FAccelByteModelsGameRecord& Result)
{
    TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
    RecordRequest->SetNumberField(FString("1v1"), 4);
    RecordRequest->SetNumberField(FString("2v2"), 3);
    RecordRequest->SetNumberField(FString("3v3"), 2);
    RecordRequest->SetNumberField(FString("4v4"), 1);
    RecordRequest->SetNumberField(FString("5v5"), 0);
  
    FRegistry::CloudSave.ReplaceGameRecordCheckLatest(Key, Result.UpdatedAt, *RecordRequest, FVoidHandler::CreateLambda([]()
    {
        // Do something if ReplaceGameRecordCheckLatest has been successful
    }), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if ReplaceGameRecordCheckLatest has an error
        UE_LOG(LogTemp, Log, TEXT("Error ReplaceGameRecordCheckLatest, Error Code: %d, Error Message: %s"), ErrorCode, *ErrorMessage);
    }));
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetGameRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetGameRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string key = "gameMode";

        AccelBytePlugin.GetCloudSave().GetGameRecord(key, result =>
        {
            if (result.IsError)
            {
                // Do something if GetGameRecord has an error
                Debug.Log($"Error GetGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                Dictionary<string, object> recordRequest = new Dictionary<string, object>
                {
                    { "1v1", 4 },
                    { "2v2", 3 },
                    { "3v3", 2 },
                    { "2v2", 1 },
                    { "1v1", 0 }
                };
                AccelBytePlugin.GetCloudSave().ReplaceGameRecordCheckLatest(key, result.Value.updated_at, recordRequest, result =>
                {
                    if (result.IsError)
                    {
                        // Do something if ReplaceGameRecordCheckLatest has an error
                        Debug.Log($"Error ReplaceGameRecordCheckLatest, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
                    }
                    else
                    {
                        // Do something if ReplaceGAmeRecordCheckLatest has been successful
                    }
                });
            }
        });

Automatic

The automatic method will get the latest update for you, put it on your custom modifier, and then make the request again. In the custom modifier, you can compare the latest record with your local record to see what changes have been made.

Unreal Engine
Unity

int32 TryAttempt = 7;
FString Key = FString("gameMode");
TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetNumberField(FString("1v1"), 0);
RecordRequest->SetNumberField(FString("2v2"), 1);
RecordRequest->SetNumberField(FString("3v3"), 2);
RecordRequest->SetNumberField(FString("4v4"), 3);
RecordRequest->SetNumberField(FString("5v5"), 4);

TBaseDelegate<FJsonObject, FJsonObject> PayloadModifier = TBaseDelegate<FJsonObject, FJsonObject>::CreateLambda([RecordRequest](FJsonObject LatestRecord)
{
    for (auto Item : RecordRequest->Values)
    {
        FString Value;
        if (Item.Value->TryGetString(Value))
        {
            LatestRecord.SetStringField(Item.Key, Value);
        }
    }
    return LatestRecord;
});

FRegistry::CloudSave.ReplaceGameRecordCheckLatest(TryAttempt, Key, *RecordRequest, PayloadModifier, FVoidHandler::CreateLambda([]()
{
    // Do something if ReplaceGameRecordCheckLatest has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if ReplaceGameRecordCheckLatest has an error
    UE_LOG(LogTemp, Log, TEXT("Error ReplaceGameRecordCheckLatest, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));
;

int tryAttempt = 7;
        string key = "gameMode";
        Dictionary<string, object> recordRequest = new Dictionary<string, object>
        {
            { "1v1", 1 },
            { "2v2", 2 },
            { "3v3", 3 },
            { "4v4", 4 },
            { "5v5", 5 }
        };

        Dictionary<string, object> payloadModifier(Dictionary<string, object> latestRecord)
        {
            foreach (var item in recordRequest)
            {
                latestRecord.Add(item.Key, item.Value);
            }
            return latestRecord;
        };

        AccelBytePlugin.GetCloudSave().ReplaceGameRecordCheckLatest(tryAttempt, key, recordRequest, result =>
        {
            if (result.IsError)
            {
                // Do something if ReplaceGameRecordCheckLatest has an error
                Debug.Log($"Error ReplaceGameRecordCheckLatest, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if ReplaceGameRecordCheckLatest has been successful
            }
        }, payloadModifier);

Delete a Game Record

Use the DeleteGameRecord() function to delete game data.

Unreal Engine
Unity

FString Key = FString("gameMode");

FRegistry::CloudSave.DeleteGameRecord(Key, FVoidHandler::CreateLambda([]()
{
    // Do something if DeleteGameRecord has been successuful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if DeleteGameRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error DeleteGameRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string key = "gameMode";

        AccelBytePlugin.GetCloudSave().DeleteGameRecord(key, result =>
        {
            if (result.IsError)
            {
                // Do something if DeleteGameRecord has an error
                Debug.Log($"Error DeleteGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if DeleteGameRecord has been successful
            }
        });

Integrate Your Game Server with Cloud Save

In this section, you will learn how to modify games and user records in the Game Server.

Create a User Record

You can create a record for the targeted user or game configuration. If the record already exists, this action will merge the records with the following conditions:

If the field name already exists, the value will be replaced.
If the field name does not exist, it will append the field and its value.

User Record

You can create a user record using the following function.

Unreal Engine
Unity

FString Key = FString("playerEqupments");
FString UserId = FString("SomeUserId");
TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetNumberField(FString("armor"), 1);
RecordRequest->SetNumberField(FString("weapon"), 2);
RecordRequest->SetNumberField(FString("ring"), 3);
RecordRequest->SetNumberField(FString("wing"), 1);
RecordRequest->SetNumberField(FString("mount"), 2);
  
FRegistry::ServerCloudSave.SaveUserRecord(Key, UserId, *RecordRequest, false, FVoidHandler::CreateLambda([]()
{
    // Do something if SaveUserRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if SaveUserRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error SaveUserRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string userId = "SomeUserId";
        string key = "playerEquipments";
        Dictionary<string, object> recordRequest = new Dictionary<string, object>
        {
            { "armor", 2 },
            { "weapon", 1 },
            { "ring", 3 },
            { "wing", 2 },
            { "mount", 5 }
        };

        AccelByteServerPlugin.GetCloudSave().SaveUserRecord(userId, 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}");
            }
            else
            {
                // Do something if SaveUserRecord has been successful
            }
        });

Game Record

You can create a game record using the following function.

Unreal Engine

FString Key = FString("npcLocation");
TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetStringField(FString("npc1"), FString("X=125;Y=256;Z=125"));
RecordRequest->SetStringField(FString("npc2"), FString("X=115,Y=225,Z=120"));
  
FRegistry::ServerCloudSave.SaveGameRecord(Key, *RecordRequest, FVoidHandler::CreateLambda([]()
{
    // Do something if SaveGameRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if SaveGameRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error SaveGameRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Retrieve a Record

You can retrieve a specific game or user record.

User Record

You can retrieve a user record using the following function.

Unreal Engine
Unity

FString UserId = FString("SomeUserId");
FString Key = FString("playerEquipments");

FRegistry::ServerCloudSave.GetUserRecord(UserId, Key, THandler<FAccelByteModelsUserRecord>::CreateLambda([](const FAccelByteModelsUserRecord& Result)
{
    // Do something if GetUserRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetUserRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetUserRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string userId = "SomeUserId";
        string key = "playerEquipments";

        AccelByteServerPlugin.GetCloudSave().GetUserRecord(userid, 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}");
            }
            else
            {
                // Do something if GetUserRecord has been successful
            }
        });

Game Record

You can retrieve a game record using the following function.

Unreal Engine

FString Key = FString("npcLocation");
  
FRegistry::ServerCloudSave.GetGameRecord(Key, THandler<FAccelByteModelsGameRecord>::CreateLambda([](const FAccelByteModelsGameRecord& Result)
{
    // Do something if GetGameRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetGameRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetGameRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Retrieve a Public User Record

Retrieve the specified public user's record. You need to input a User ID to get the specific public user record.

Unreal Engine

FString Key = FString("playerEquipments");
FString UserId = FString("SomeUserId");
  
FRegistry::ServerCloudSave.GetPublicUserRecord(Key, UserId, THandler<FAccelByteModelsUserRecord>::CreateLambda([](const FAccelByteModelsUserRecord& Result)
{
    // Do something if GetPublicUserRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetPublicUserRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetPublicUserRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Retrieve All Game Records

You can retrieve all the list of game records using the following function.

Unreal Engine

FRegistry::ServerCloudSave.RetrieveGameRecordsKey(THandler<FAccelByteModelsPaginatedRecordsKey>::CreateLambda([](const FAccelByteModelsPaginatedRecordsKey& Result)
{
    // Do something if RetrieveGameRecordsKey has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if RetrieveGameRecordsKey has an error
    UE_LOG(LogTemp, Log, TEXT("Error RetrieveGameRecordsKey, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Replace a Record

This function can overwrite an existing user's or game record if it exists. If the record does not exist, it will create a new record.

User Record

You can replace a user record using the following function.

Unreal Engine
Unity

FString UserId = FString("SomeUserId");
FString Key = FString ("playerEquipments");
TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetNumberField(FString("armor"), 5);
RecordRequest->SetNumberField(FString("weapon"), 2);
RecordRequest->SetNumberField(FString("ring"), 1);
RecordRequest->SetNumberField(FString("wing"), 3);
RecordRequest->SetNumberField(FString("mount"), 2);
  
FRegistry::ServerCloudSave.ReplaceUserRecord(UserId, Key, *RecordRequest, false, FVoidHandler::CreateLambda([]()
{
    // Do something if ReplaceUserRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if ReplaceUserRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error ReplaceUserRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string userId = "SomeUserId";
        string key = "playerEquipments";
        Dictionary<string, object> recordRequest = new Dictionary<string, object>
        {
            { "armor", 2 },
            { "weapon", 1 },
            { "ring", 5 },
            { "wing", 2 },
            { "mount", 1 }
        };

        AccelByteServerPlugin.GetCloudSave().ReplaceUserRecord(userid, key, 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}");
            }
            else
            {
                // Do something if ReplaceUserRecord has been successful
            }
        });

Game Record

You can replace a game record using the following function.

Unreal Engine

FString Key = FString("npcLocation");
TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetStringField(FString("npc1"), FString("X=125;Y=120;Z=100"));
RecordRequest->SetStringField(FString("npc2"), FString("X=75;Y=175;Z=225"));

FRegistry::ServerCloudSave.ReplaceGameRecord(Key, *RecordRequest, FVoidHandler::CreateLambda([]()
{
    // Do something if ReplaceGameRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if ReplaceGameRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error ReplaceGameRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Delete a Record

This function can erase the specified record.User Record

You can delete a user record using the following function.

Unreal Engine
Unity

FString UserId = FString("SomeUserId");
FString Key = FString("playerEquipments");
  
FRegistry::ServerCloudSave.DeleteUserRecord(Key, UserId, false, FVoidHandler::CreateLambda([]()
{
    // Do something if DeleteUserRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if DeleteUserRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error DeleteUserRecord, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string userId = "SomeUserId";
        string key = "playerEquipments";

        AccelByteServerPlugin.GetCloudSave().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}");
            }
            else
            {
                // Do something if DeleteUserRecord has been successful
            }
        });

Game Record

You can delete a game record using the following function.

Unreal Engine

FString Key = FString("npcLocation");
  
FRegistry::ServerCloudSave.DeleteGameRecord(Key, FVoidHandler::CreateLambda([]()
{
    // Do something if DeleteGameRecord has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if DeleteGameRecord has an error
    UE_LOG(LogTemp, Log, TEXT("Error DeleteGameRecord, Error Code: %d Error Message: %s"), ErrorMessage, *ErrorMessage);
}));

Connect Custom Services to Cloud Save using the Server SDKs

SDK Initialization

Before using the Cloud Save service from the SDK, you will need to initialize your server-side SDK to ensure you are authorized and able to perform create, read, update, and delete actions.

Golang SDK Initialization

Before using the Cloud Save service from the Golang SDK, you will need to initialize the SDK by following the steps below:

Create your OAuth Client and assign the necessary permissions to access the Cloud Save service.
Log in as a Client using the SDK.
Initialize the Cloud Save service using the following function:

Golang

cloudsaveService := &cloudsave.CloudsaveService{
    Client:         factory.NewCloudsaveClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}

Once completed, you can use the Golang SDK to create, read, update, or delete Cloud Saves from your serverless app.

Python SDK Initialization

Before using the Cloud Save service from the Python SDK, you will need to initialize the SDK by following the steps below:

Create your OAuth Client and assign the necessary permissions to access the Cloud Save service.
Log in as a Client using the SDK.

Once completed, you can use the Python SDK to create, read, update, or delete Cloud Saves from your serverless app.

.NET (C#) SDK Initialization

Before using the Cloud Save service, you will need to set some permissions. Use the following .NET namespaces:

using AccelByte.Sdk.Api.Cloudsave.Model;
using AccelByte.Sdk.Api.Cloudsave.Operation;
using AccelByte.Sdk.Api.Cloudsave.Wrapper;

Java SDK Initialization

Before using the Cloud Save service, you will need to set some permissions. Initialize the PublicGameRecord wrapper from the Cloud Save service using the following code:

PublicGameRecord wPublicGameRecord = new PublicGameRecord(sdk);

Once completed, you can use the SDK to create, read, update, or delete cloud saves.

Create a Game Record

Use the following function to create a game record:

Golang
Python
C#
Java

err := cloudsaveService.PostGameRecordHandlerV1(input)
if err != nil {
  return err
}
return nil

from accelbyte_py_sdk.api.cloudsave import post_game_record_handler_v1
from accelbyte_py_sdk.api.cloudsave.models import ModelsGameRecordRequest

result, error = post_game_record_handler_v1(
   body=ModelsGameRecordRequest.create(dict_={"foo": "bar"}),
   key="<your-key>"
)
if error:
   print(error)

PublicGameRecord wPublicGameRecord = new PublicGameRecord(_Sdk);

ModelsGameRecordRequestForTest gameRecord = new ModelsGameRecordRequestForTest()
{
    Foo = "bar",
    FooBar = "foo",
    FooValue = 4893
};

wPublicGameRecord.PostGameRecordHandlerV1(PostGameRecordHandlerV1.Builder
    .Build(gameRecord, "foo_bar_record", _Sdk.Namespace));

TestModelsGameRecordRequest gameRecord = TestModelsGameRecordRequest.builder()
                .Foo(gameRecordFoo)
                .FooBar(gameRecordFooBar)
                .FooValue(gameRecordFooValue)
                .build();

wPublicGameRecord.postGameRecordHandlerV1(PostGameRecordHandlerV1.builder()
                .namespace(namespace)
                .key(gameRecordKey)
                .body(gameRecord)
                .build());

Update a Game Record

Use the following function to update a game record:

Golang
Python
C#
Java

err := cloudsaveService.GetGameRecordHandlerV1(input)
if err != nil {
  return err
}
return nil

from accelbyte_py_sdk.api.cloudsave import put_game_record_handler_v1
from accelbyte_py_sdk.api.cloudsave.models import ModelsGameRecordRequest

result, error = put_game_record_handler_v1(
   body=ModelsGameRecordRequest.create(dict_={"foo": "bar"}),
   key="<your-key>"
)
if error:
   print(error)

PublicGameRecord wPublicGameRecord = new PublicGameRecord(_Sdk);

ModelsGameRecordRequestForTest updateRecord = new ModelsGameRecordRequestForTest()
{
    Foo = "bar",
    FooBar = "update",
    FooValue = 4893
};

wPublicGameRecord.PutGameRecordHandlerV1(PutGameRecordHandlerV1.Builder
    .Build(updateRecord, "foo_bar_record", _Sdk.Namespace));

TestModelsGameRecordRequest updateRecord = TestModelsGameRecordRequest.builder()
                .Foo(gameRecordFoo)
                .FooBar(gameRecordFooBar + "update")
                .FooValue(gameRecordFooValue)
                .build();

wPublicGameRecord.putGameRecordHandlerV1(PutGameRecordHandlerV1.builder()
                .namespace(namespace)
                .key(gameRecordKey)
                .body(updateRecord)
                .build());

Delete a Game Record

Use the following function to delete a game record:

Golang
Python
C#
Java

err := cloudsaveService.DeleteGameRecordHandlerV1(input)
if err != nil {
  return err
}
return nil

from accelbyte_py_sdk.api.cloudsave import delete_game_record_handler_v1

result, error = delete_game_record_handler_v1(
   key="<your-key>"
)
if error:
   print(error)

PublicGameRecord wPublicGameRecord = new PublicGameRecord(_Sdk);

wPublicGameRecord.DeleteGameRecordHandlerV1(DeleteGameRecordHandlerV1.Builder
    .Build("foo_bar_record", _Sdk.Namespace));

wPublicGameRecord.deleteGameRecordHandlerV1(DeleteGameRecordHandlerV1.builder()
                                .namespace(namespace)
                                .key(gameRecordKey)
                                .build());

Retrieve a Game Record

Use the following function to retrieve a game record:

Golang
Python
C#
Java

gameRecords, err := cloudsaveService.GetGameRecordHandlerV1(input)
if err != nil {
  return err
}
return nil

from accelbyte_py_sdk.api.cloudsave import get_game_record_handler_v1

result, error = get_game_record_handler_v1(
   key="<your-key>"
)
if error:
   print(error)

PublicGameRecord wPublicGameRecord = new PublicGameRecord(_Sdk);

ModelsGameRecord? gRecord = wPublicGameRecord.GetGameRecordHandlerV1(GetGameRecordHandlerV1.Builder
    .Build("foo_bar_record", _Sdk.Namespace));

ModelsGameRecordResponse gRecord = wPublicGameRecord.getGameRecordHandlerV1(GetGameRecordHandlerV1.builder()
                                .namespace(namespace)
                                .key(gameRecordKey)
                                .build());

	Admin	Player
	Admin	Record Owner	Other Players
Server	Modify	-	-
Client	Modify	Modify	-

Overview​

Permissions​

Metadata​

Manage Cloud Saves in the Admin Portal​

Create a New Game Record​

Update a Record​

Game Record​

Player Record​

Integrate Your Game with Cloud Save at the User Level​

Create a New Record​

Retrieve a User Record​

Retrieve a Public User Record​

Replace a User Record​

Replace User Records Concurrently​

Manual​

Automatic​

Delete a User Record​

Integrate Your Game with Cloud Save at the Namespace Level​

Create a New Game Record​

Retrieve Game Record​

Replace a Game Record​

Replace Game Records Concurrently​

Manual​

Automatic​

Delete a Game Record​

Integrate Your Game Server with Cloud Save​

Create a User Record​

User Record​

Game Record​

Retrieve a Record​

User Record​

Game Record​

Retrieve a Public User Record​

Retrieve All Game Records​

Replace a Record​

User Record​

Game Record​

Delete a Record​

This function can erase the specified record.User Record​

Game Record​

Connect Custom Services to Cloud Save using the Server SDKs​

SDK Initialization​

Golang SDK Initialization​

Python SDK Initialization​

.NET (C#) SDK Initialization​

Java SDK Initialization​

Create a Game Record​

Update a Game Record​

Delete a Game Record​

Retrieve a Game Record​

Related Concepts​

Overview

Permissions

Metadata

Manage Cloud Saves in the Admin Portal

Create a New Game Record

Update a Record

Game Record

Player Record

Integrate Your Game with Cloud Save at the User Level

Create a New Record

Retrieve a User Record

Retrieve a Public User Record

Replace a User Record

Replace User Records Concurrently

Manual

Automatic

Delete a User Record

Integrate Your Game with Cloud Save at the Namespace Level

Create a New Game Record

Retrieve Game Record

Replace a Game Record

Replace Game Records Concurrently

Manual

Automatic

Delete a Game Record

Integrate Your Game Server with Cloud Save

Create a User Record

User Record

Game Record

Retrieve a Record

User Record

Game Record

Retrieve a Public User Record

Retrieve All Game Records

Replace a Record

User Record

Game Record

Delete a Record

This function can erase the specified record.User Record

Game Record

Connect Custom Services to Cloud Save using the Server SDKs

SDK Initialization

Golang SDK Initialization

Python SDK Initialization

.NET (C#) SDK Initialization

Java SDK Initialization

Create a Game Record

Update a Game Record

Delete a Game Record

Retrieve a Game Record

Related Concepts