Store in-game configurations in game records

Last updated on November 20, 2024

Overview

The Cloud Save service enables you to store your game data, for your game use case, in JSON format. The game records stored are for global title uses that are accessible, and in some cases are editable, by the players. Storing, for example:

A game seasonal UI theme configuration
Game event or news information
Players' collective game data such as their clan, area or map

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

Goals

Provide an understanding and overview of game records
Provide an understanding on how to game data in game records
Provide an understanding on how to display game records
Provide an understanding on how to modify game records
Provide an understanding on how to delete game records
Explain how to utilize game 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 data in a new game record

Store data in a new game record via the Admin Portal

Creating game records via the admin portal is suitable if you want to store data that does not need to be modified by the game client, and will only be retrieved by the game client. For example: Seasonal UI theme configuration, Event/News Information, etc.

To create a game record, follow the steps below:

On the Admin Portal sidebar, go to Progression & Inventory > Cloud Save menu and select Game Records.
On the Cloud Save page, open the Game Records tab and click on the Create Game Record button. The Add Record form appears.
Fill in the required information:
- Fill in the Game Record Key using the appropriate format. You can use this as your record title and it can be used as an identifier to retrieve the record from the SDK later.
- You can also add extra validation to make sure that only the game server, or game client, can update the records by selecting your choice in the Write Permission section. See Write Permission for a full list of the available options.
- Add the data you want to store in JSON format.
Click Add. The new record is added to the records list.

Store data in new game records with the SDK

This is suitable if you need game records that are dynamically created after some actions are triggered from the game client. As an example, storing public customizable map data. You store the data by creating a new game record using the following function.

Create a game record via a client

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = FString("map-data");

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"));
                
ApiClient->CloudSave.SaveGameRecord(Key
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if SaveGameRecord succeeds
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if SaveGameRecord fails
    }));

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

string key = "map-data";

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
  {"NPC1", "x:125,y:256,z:125"},
  {"NPC2", "x:115,y:225,z:120"}
};

cloudSave.SaveGameRecord(key, recordRequest, result =>
{
    if (result.IsError)
    {
        // Do something if SaveGameRecord fails
        Debug.Log($"Error SaveGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if SaveGameRecord succeeds
});

Create a game record via a server

Unreal
Unity

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = FString("map-data");

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"));

ServerApiClient->ServerCloudSave.SaveGameRecord(Key
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if SaveGameRecord succeeds
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if SaveGameRecord fails
    }));

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

string key = "map-data";

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
  {"NPC1", "x:125,y:256,z:125"},
  {"NPC2", "x:115,y:225,z:120"}
};

var optionalParams = new GameRecordMetadataOptionalParams()
{
    SetBy = RecordSetBy.CLIENT
};

serverCloudSave.SaveGameRecord(key, recordRequest, optionalParams, result =>
{
    if (result.IsError)
    {
        // Do something if SaveGameRecord fails
        Debug.Log($"Error SaveGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if SaveGameRecord succeeds
});

Create a temporary game record via a server

Unreal
Unity

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = FString("map-data");

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"));

FTTLConfig TTLConfig{};
TTLConfig.Action = EAccelByteTTLConfigAction::DELETE_RECORD;
TTLConfig.Expires_At = FDateTime::UtcNow() + FTimespan(0, 0, 5); // Will delete this record in the next five seconds   

ServerApiClient->ServerCloudSave.SaveGameRecord(Key
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if SaveGameRecord succeeds
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if SaveGameRecord fails
    })
    , TTLConfig);

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

string key = "map-data";

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
  {"NPC1", "x:125,y:256,z:125"},
  {"NPC2", "x:115,y:225,z:120"}
};

var ttlConfig = new TTLConfig()
{
    Action = TTLConfigAction.Delete,
    ExpiresAt = DateTime.Now.AddSeconds(5) // Will delete this record in the next five sceonds
};
var optionalParams = new GameRecordMetadataOptionalParams()
{
    SetBy = RecordSetBy.CLIENT,
    TTLConfig = ttlConfig
};

serverCloudSave.SaveGameRecord(key, recordRequest, optionalParams, result =>
{
    if (result.IsError)
    {
        // Do something if SaveGameRecord fails
        Debug.Log($"Error SaveGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if SaveGameRecord succeeds
});

Remove time to live on a game record via a server

Unreal
Unity

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = FString("map-data");

ServerApiClient->ServerCloudSave.DeleteGameRecordTTLConfig(Key, FVoidHandler::CreateLambda([]()
{
    // Do something if DeleteGameRecordTTLConfig was successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if DeleteGameRecordTTLConfig fails
}));

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

string key = "map-data";

serverCloudSave.DeleteGameRecordTTLConfig(key, result => 
{
    if (result.IsError)
    {
        // Do something if DeleteGameRecordTTLConfig fails
        Debug.Log($"Error DeleteGameRecordTTLConfig, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if DeleteGameRecordTTLConfig succeeds
});

Display game records data

The game records that are stored and created both from your Admin Portal, or game client, can be retrieved by all players. With that data, you can do whatever you want to support your game use cases. As examples, use the data to replace the UI for seasonal themes, display the data to show the updated news or events.

You can retrieve a game record using the following function:

Retrieve a game record via a client

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = FString("inGameNews");        

ApiClient->CloudSave.GetGameRecord(Key
    , THandler<FAccelByteModelsGameRecord>::CreateLambda([](const FAccelByteModelsGameRecord& Result)
    {
        // Do something if GetGameRecord succeeds
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if GetGameRecord fails
    }));

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

string key = "inGameNews";
cloudSave.GetGameRecord(key, result =>
{
    if (result.IsError)
    {
        // Do something if GetGameRecord fails
        Debug.Log($"Error GetGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if GetGameRecord succeeds
});

Retrieve a game record via a server

Unreal
Unity

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = FString("inGameNews");               

ServerApiClient->ServerCloudSave.GetGameRecord(Key
    , THandler<FAccelByteModelsGameRecord>::CreateLambda([](const FAccelByteModelsGameRecord& Result)
    {
        // Do something if GetGameRecord succeeds
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if GetGameRecord fails
    }));

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

string key = "inGameNews";

serverCloudSave.GetGameRecords(key, result =>
{
    if (result.IsError)
    {
        // Do something if DeleteUserRecord fails
        Debug.Log($"Error DeleteUserRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if DeleteUserRecord succeeds
});

Modify game records data

Modify game records via the Admin Portal

Modifying a game record from your Admin Portal is suitable if you want to take manual action to adjust the data. As examples, fixing data, auditing, etc. To update a game record, follow the steps below:

On the Admin Portal sidebar, go to Progression & Inventory > Cloud Save > Game Records.
On the Game Records page, depending on the record type, open the JSON or the Binary tab. From the list, find and view the record you want to update.
On the details page of the record, click on the pencil or edit icon of the fields or sections to update the content.
Save your changes.

Modify new game records with the SDK

This is suitable if your game requires updating the game records data from the game client. The data you store will be replaced with new data, by using the following function:

Modify a game record via a client

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "map-data";

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

ApiClient->CloudSave.ReplaceGameRecord(Key
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if ReplaceGameRecord succeeds
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // Do something if ReplaceGameRecord fails
    }));

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

string key = "map-data";

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
    {"NPC1", "x:100,y:256,z:125"},
    {"NPC2", "x:100,y:225,z:120"}
};

cloudSave.ReplaceGameRecord(key, recordRequest, result =>
{
    if (result.IsError)
    {
        // Do something if ReplaceGameRecord fails
        Debug.Log($"Error ReplaceGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if ReplaceGameRecord succeeds
});

Modify a game record via a server

Unreal
Unity

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = "map-data";

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

ServerApiClient->ServerCloudSave.ReplaceGameRecord(Key
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if ReplaceGameRecord succeeds
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // Do something if ReplaceGameRecord fails
    }));

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

string key = "map-data";

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
  {"NPC1", "x:100,y:256,z:125"},
  {"NPC2", "x:100,y:225,z:120"}
};

var optionalParams = new GameRecordMetadataOptionalParams()
{
    SetBy = RecordSetBy.CLIENT
};

serverCloudSave.ReplaceGameRecord(key, recordRequest, optionalParams, result =>
{
    if (result.IsError)
    {
        // Do something if ReplaceGameRecord fails
        Debug.Log($"Error ReplaceGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if ReplaceGameRecord succeeds
});

Modify a game record to become temporary via a Server

Unreal
Unity

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = "map-data";

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

FTTLConfig TTLConfig{};
TTLConfig.Action = EAccelByteTTLConfigAction::DELETE_RECORD;
TTLConfig.Expires_At = FDateTime::UtcNow() + FTimespan(0, 0, 5); // Will delete this record in the next five seconds

ServerApiClient->ServerCloudSave.ReplaceGameRecord(Key
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if ReplaceGameRecord succeeds
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // Do something if ReplaceGameRecord fails
    })
    , TTLConfig);

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

string key = "map-data";

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
  {"NPC1", "x:100,y:256,z:125"},
  {"NPC2", "x:100,y:225,z:120"}
};

var ttlConfig = new TTLConfig()
{
    Action = TTLConfigAction.Delete,
    ExpiresAt = DateTime.Now.AddSeconds(5) // Will delete this record in the next five sceonds
};
var optionalParams = new GameRecordMetadataOptionalParams()
{
    SetBy = RecordSetBy.CLIENT,
    TTLConfig = ttlConfig
};

serverCloudSave.ReplaceGameRecord(key, recordRequest, optionalParams, result =>
{
    if (result.IsError)
    {
        // Do something if ReplaceGameRecord fails
        Debug.Log($"Error ReplaceGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if ReplaceGameRecord succeeds
});

Delete game record data

Delete new game records via the Admin Portal

To delete a game record, follow these steps:

On the Admin Portal sidebar, go to Progression & Inventory > Cloud Save > Game Records.
On the Game Records page, depending on the record type, open the JSON or the Binary tab. From the list, find the record you want to delete and click on its Delete button under the Action menu.
Click Delete on the confirmation message.

Delete new game records via the SDK

If your game requires you to delete game records from the SDK side, you can delete it using the following function.

Delete a game record via a client

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = FString("map-data");              

ApiClient->CloudSave.DeleteGameRecord(Key
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if DeleteGameRecord succeeds
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if DeleteGameRecord fails
    }));

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

string key = "map-data";

cloudSave.DeleteGameRecord(key, result =>
{
    if (result.IsError)
    {
        // Do something if DeleteGameRecord fails
        Debug.Log($"Error DeleteGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");

    }
    
    // Do something if DeleteGameRecord succeeds
});

Delete a game record via a server

Unreal
Unity

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = FString("map-data");

ServerApiClient->ServerCloudSave.DeleteGameRecord(Key
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if DeleteGameRecord succeeds
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if DeleteGameRecord fails
    }));

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

string key = "map-data";

serverCloudSave.DeleteGameRecord(key, result =>
{
    if (result.IsError)
    {
        // Do something if DeleteGameRecord fails
        Debug.Log($"Error DeleteGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if DeleteGameRecord succeeds
});

Overview​

Goals​

Prerequisites​

Store data in a new game record​

Store data in a new game record via the Admin Portal​

Store data in new game records with the SDK​

Create a game record via a client​

Create a game record via a server​

Create a temporary game record via a server​

Remove time to live on a game record via a server​

Display game records data​

Retrieve a game record via a client​

Retrieve a game record via a server​

Modify game records data​

Modify game records via the Admin Portal​

Modify new game records with the SDK​

Modify a game record via a client​

Modify a game record via a server​

Modify a game record to become temporary via a Server​

Delete game record data​

Delete new game records via the Admin Portal​

Delete new game records via the SDK​

Delete a game record via a client​

Delete a game record via a server​

On this page