Store game-wide data in binary records

Last updated on May 13, 2024

Overview

The AccelByte Gaming Services (AGS) Cloud Save service enables you to store your game data in binary format. The data that is stored is for global title uses that are accessible and, in some cases, editable by the players.

In this article, you will learn how to use binary records to store your player data, retrieve it, and modify it according to your game use case.

Goals

This article gives an overview of game binary records and how to use them with the AGS Game SDK, and shows you how to do the following:

Store game data in binary records
Retrieve game binary records
Modify game binary records
Delete game binary records

Prerequisites

To complete the steps in this article, you will need:

Access to the AGS Admin Portal
The AGS Game SDK for Unreal or Unity installed to your game project with the required permissions:
- Client ID
- Client Secret

Store game data in binary records with the game server

Storing game data in binary records can only be done by the game server, which can be set up by completing the steps in this section.

Create game binary record request

You will first need to create a binary record you wish to store. From this process, you will get the generated presigned URL that will be used later to upload the binary file. You can create the request by using the following function:

Unreal

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = "GameInformation1";
EAccelByteFileType FileType = EAccelByteFileType::BIN; // Valid file types are jpeg, jpg, png, bmp, gif, mp3, webp, and bin
ESetByMetadataRecord SetBy = ESetByMetadataRecord::CLIENT; // Set to client if you want the binary can be managed by Game Client or using Public endpoints

ServerApiClient->ServerBinaryCloudSave.CreateGameBinaryRecord(Key
    , FileType
    , SetBy
    , THandler<FAccelByteModelsBinaryInfo>::CreateLambda([](FAccelByteModelsBinaryInfo Result)
     {
         // Do something if CreateGameBinaryRecord is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if CreateGameBinaryRecord has an error
     }));

Upload binary file

Upload the binary file directly with the presigned URL you have. You can use the following function to upload the binary file:

Unreal

FString Url = "PresignedUrlToUpload";
TArray<uint8> DataUpload = { 106, 35, 171, 106, 138, 197, 77, 94, 182, 18, 99, 9, 245, 110, 45, 197, 22, 35 };

FAccelByteNetUtilities::UploadTo(Url
    , DataUpload
    , FHttpRequestProgressDelegate::CreateLambda([](const FHttpRequestPtr& Request, int32 BytesSent, int32 BytesReceived)
     {
         // Do something if UploadTo still in progress successful
     })
    , FVoidHandler::CreateLambda([]()
     {
         // Do something if UploadTo has is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
     {
         // Do something if UploadTo has an error
     }));

Commit to update the file location

Once the binary file is uploaded, commit the changes to make sure the new file location is updated by using the following function:

Unreal

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = "GameInformation1";
EAccelByteFileType FileType = EAccelByteFileType::BIN; // Valid file types are jpeg, jpg, png, bmp, gif, mp3, webp, and bin
FString FileLocation = "PresignUrlFileLocation";

ServerApiClient->ServerBinaryCloudSave.UpdateGameBinaryRecord(Key
    , FileType
    , FileLocation
    , THandler<FAccelByteModelsGameBinaryRecord>::CreateLambda([](FAccelByteModelsGameBinaryRecord Result)
     {
         // What to do if UpdateGameBinaryRecord is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // What to do if UpdateGameBinaryRecord fails
     }));

Update a game binary record file from the game server

Updating a new binary file in a game binary record has slightly different steps compared to the game binary record creation. Complete the steps in this section to upload a new binary file from the game client.

Request a presigned URL

You will first need to request a presigned URL that you will use to upload the updated binary file. You can use the following function to request one:

Unreal

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = "GameInformation1";
EAccelByteFileType FileType = EAccelByteFileType::BIN; // Valid file types are jpeg, jpg, png, bmp, gif, mp3, webp, and bin

ServerApiClient->ServerBinaryCloudSave.RequestGameBinaryRecordPresignedUrl(Key
    , FileType
    , THandler<FAccelByteModelsBinaryInfo>::CreateLambda([](FAccelByteModelsBinaryInfo Result)
     {
         // What to do if RequestGameBinaryRecordPresignedUrl is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // What to do if RequestGameBinaryRecordPresignedUrl fails
     }));

Upload new binary file

Upload the binary file directly with the presigned URL you have. You can use the following function to upload the binary file:

Unreal

FString Url = "PresignedUrlToUpload";
TArray<uint8> DataUpload = { 106, 35, 171, 106, 138, 197, 77, 94, 182, 18, 99, 9, 245, 110, 45, 197, 22, 35 };

FAccelByteNetUtilities::UploadTo(Url
    , DataUpload
    , FHttpRequestProgressDelegate::CreateLambda([](const FHttpRequestPtr& Request, int32 BytesSent, int32 BytesReceived)
     {
         // Do something if UploadTo still in progress successful
     })
    , FVoidHandler::CreateLambda([]()
     {
         // Do something if UploadTo has is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
     {
         // Do something if UploadTo has an error
     }));

Commit to update the file location again

Once the binary file is uploaded, commit the changes to make sure the new file location is updated using the following function:

Unreal

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = "GameInformation1";
EAccelByteFileType FileType = EAccelByteFileType::BIN; // Valid file types are jpeg, jpg, png, bmp, gif, mp3, webp, and bin
FString FileLocation = "PresignUrlFileLocation";

ServerApiClient->ServerBinaryCloudSave.UpdateGameBinaryRecord(Key
    , FileType
    , FileLocation
    , THandler<FAccelByteModelsGameBinaryRecord>::CreateLambda([](FAccelByteModelsGameBinaryRecord Result)
     {
         // What to do if UpdateGameBinaryRecord is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // What to do if UpdateGameBinaryRecord fails
     }));

Delete game binary records from the game server

Use the following function to delete the game binary record:

Unreal

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = "GameInformation1";

ServerApiClient->ServerBinaryCloudSave.DeleteGameBinaryRecord(Key
    , FVoidHandler::CreateLambda([]()
     {
         // What to do if DeleteGameBinaryRecord is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // What to do if DeleteGameBinaryRecord fails
     }));

Retrieve game binary record data from the game client

After the game binary record data is stored, you can allow your player to retrieve that data.

Get single record

Use the following function to retrieve a specific game binary record data by key:

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "GameInformation1";

ApiClient->BinaryCloudSave.GetGameBinaryRecord(Key
    , THandler<FAccelByteModelsGameBinaryRecord>::CreateLambda([](FAccelByteModelsGameBinaryRecord Result)
     {
         // What to do if GetGameBinaryRecord is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // What to do if GetGameBinaryRecord fails
     }));

BinaryCloudSave binaryCloudSave = AccelByteSDK.GetClientRegistry().GetApi().GetBinaryCloudSave();

string key = "GameInformation1";

binaryCloudSave.GetGameBinaryRecord(key, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in GetGameBinaryRecord
        // ...
        Debug.Log($"Error GetGameBinaryRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Your logic to run after GetGameBinaryRecord is successful
});

Get bulk records

Use the following function to get the list of game binary records:

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

TArray<FString> Keys = { "GameInformation1", "GameInformation2" };

ApiClient->BinaryCloudSave.BulkGetGameBinaryRecords(Keys
    , THandler<FAccelByteModelsListGameBinaryRecords>::CreateLambda([](FAccelByteModelsListGameBinaryRecords Result)
     {
         // What to do if BulkGetGameBinaryRecords is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // What to do if BulkGetGameBinaryRecords fails
     }));

BinaryCloudSave binaryCloudSave = AccelByteSDK.GetClientRegistry().GetApi().GetBinaryCloudSave();

string[] keys = { "GameInformation1", "GameInformation2" };

binaryCloudSave.BulkGetGameBinaryRecords(keys, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in BulkGetGameBinaryRecords
        // ...
        Debug.Log($"Error BulkGetGameBinaryRecords, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Your logic to run after BulkGetGameBinaryRecords is successful
});

Download binary file

Download the binary file directly with the presigned URL you have. You can use the following function to download the binary file:

Unreal
Unity

FString Url = "PresignedUrlToDownload";

FAccelByteNetUtilities::DownloadFrom(Url
    , FHttpRequestProgressDelegate::CreateLambda([](const FHttpRequestPtr& Request, int32 BytesSent, int32 BytesReceived)
      {
          // Do something if DownloadFrom still in progress successful
      })
    , THandler<TArray<uint8>>::CreateLambda([&](const TArray<uint8>& RawData)
      {
          // Do something if DownloadFrom has is successful
      })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
      {
          // Do something if DownloadFrom has an error
      }));

string url = "PresignedUrlToDownload";

AccelByteNetUtilities.DownloadBinaryFrom(url, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in DownloadBinaryFrom
        // ...
        Debug.Log($"Error DownloadBinaryFrom, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Your logic to run after DownloadBinaryFrom is successful
});

Overview​

Goals​

Prerequisites​

Store game data in binary records with the game server​

Create game binary record request​

Upload binary file​

Commit to update the file location​

Update a game binary record file from the game server​

Request a presigned URL​

Upload new binary file​

Commit to update the file location again​

Delete game binary records from the game server​

Retrieve game binary record data from the game client​

Get single record​

Get bulk records​

Download binary file​

On this page