Store player data in binary records from game client

Last updated on April 2, 2024

Overview

The Cloud Save service enables you to store your player data in binary format. The stored data will be tied to a specific player. Images and audio files are some of the common examples of data that are typically stored in player binary records.

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

Prerequisites

You will need access to:

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

Store player data in binary record from the Game Client

To store player data in binary records, follow these steps, in this order:

Create player binary record.
Upload binary file
Commit the changes

Create player binary record

In this process, you will get the generated pre pre-sign URL that will be used later to upload the binary file. You can also set the extra read validation to the record you want to create as follows:

Allow only the record owner to access the data.
Allow all player to access the record data.

For more details about extra read validation, see Introduction to Cloud Save.

To create a request, use this function:

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "userInformation";
FString FileType = "bin"; // Valid file types are JPEG, JPG, PNG, BMP, GIF, MP3, WebP, and BIN
bool bIsPublic = true; // Set to true if you want the binary to be public

ApiClient->BinaryCloudSave.SaveUserBinaryRecord(Key
    , FileType
    , bIsPublic
    , FVoidHandler::CreateLambda([]()
    {
        // What to do if SaveUserBinaryRecord is successful
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // What to do if SaveUserBinaryRecord fails
    }));

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

string key = "userInformation";
string fileType = "bin"; // Valid file types are JPEG, JPG, PNG, BMP, GIF, MP3, WebP, and BIN
bool isPublic = true; // Set to true if you want the binary to be public

binaryCloudSave.SaveUserBinaryRecord(key, fileType, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in SaveUserBinaryRecord
        // ...
        Debug.Log(result.Error.Message);

        return;
    }

    // Your logic to run after SaveUserBinaryRecord is successful

}, isPublic);

Upload player binary record file

After creating the user binary record, you can now upload data to it. The needed parameters should be provided in the callbacks from the create player binary record section. You can upload data using this function:

Unity

byte[] yourUserDataToUpload; // Your user binary data
string url; // Retrieved via callback on successful SaveUserBinaryRecord (Value.BinaryInfo.Url)

AccelByteNetUtilities.UploadBinaryTo(binaryInfo.Url, yourUserDataToUpload, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in UploadBinaryTo
        // ...
        Debug.Log(result.Error.Message);

        return;
    }

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

Commit the changes

Once the binary file is uploaded, commit the changes to make sure the new file location is updated. Use this function:

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "userInformation";
FString ContentType = "presignUrlContentType";
FString FileLocation = "presignUrlFileLocation";

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

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

string key = "userInformation";
string contentType; //Retrieved via callback on successful SaveUserBinaryRecord (Value.BinaryInfo.ContentType)
string fileLocation; //Retrieved via callback on successful SaveUserBinaryRecord (Value.BinaryInfo.FileLocation)

binaryCloudSave.UpdateUserBinaryRecordFile(key, contentType, fileLocation, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in UpdateUserBinaryRecordFile
        // ...
        Debug.Log(result.Error.Message);

        return;
    }

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

Retrieve player binary record data from the Game Client

You can retrieve two types of player records based on the record owner, which are as follows:

Own player binary records.
Other user's public binary records.

Retrieve a player's binary records data

Get Single

Use this function to retrieve a specific player's own binary record data by key.

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "userInformation";

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

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

string key = "userInformation";

binaryCloudSave.GetCurrentUserBinaryRecord(key, result =>
{
    if (callback.IsError)
    {
        // Your logic to handle errors in GetCurrentUserBinaryRecord
        // ...
        Debug.Log(result.Error.Message);

        return;
    }

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

Bulk Get

Use this function to get list of binary records owned by the player.

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

TArray<FString> Keys = {"userInformation1", "userInformation2"};

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

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

string[] keys = new string[] {
    "userInformation1",
    "userInformation2"
};

binaryCloudSave.BulkGetCurrentUserBinaryRecords(keys, result =>
{
    if (callback.IsError)
    {
        // Your logic to handle errors in BulkGetCurrentUserBinaryRecords
        // ...
        Debug.Log(result.Error.Message);

        return;
    }

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

Retrieve other user's public binary records data

Get Single

Use this function to retrieve a specific player public binary record data by key.

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "userInformation";
FString UserId = "OtherPlayerUserId";

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

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

string key = "userInformation";
string userId = "otherPlayerUserId";

binaryCloudSave.GetPublicUserBinaryRecord(key, userId, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in GetPublicUserBinaryRecord
        // ...
        Debug.Log(result.Error.Message);

        return;
    }

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

Bulk Get

Use this function to get list of public binary records owned by other player.

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

TArray<FString> Keys = {"userInformation1", "userInformation2"};
FString UserId = "OtherPlayerUserId";

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

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

string[] keys = new string[] {
    "userInformation1",
    "userInformation2"
};
string userId = "otherPlayerUserId";

binaryCloudSave.BulkGetPublicUserBinaryRecords(keys, userId, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in BulkGetPublicUserBinaryRecords
        // ...
        Debug.Log(result.Error.Message);

        return;
    }

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

Modify player binary record from the Game Client

Player binary record data can be modified based on your game use case. You can modify player binary records data in two ways:

Modify via a game client. Use this method if you want to allow your player to modify their player binary records data.
Modify via a game server. Use this method if you only want the game server to be able to modify player binary records data.

For more detail about extra write validation, see Introduction to Cloud Save.

You can also let your players decide what information they want to update: record metadata or binary files.

Modify player binary record metadata

Use this function to only modify the records metadata.

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "userInformation";
FString FileType = "bin"; // Valid file types are JPEG, JPG, PNG, BMP, GIF, MP3, WebP, and BIN
bool bIsPublic = true; // Set to true if you want the binary to be public

ApiClient->BinaryCloudSave.SaveUserBinaryRecord(Key
    , FileType
    , bIsPublic
    , FVoidHandler::CreateLambda([]()
    {
        // What to do if SaveUserBinaryRecord is successful
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // What to do if SaveUserBinaryRecord fails
    }));

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

string key = "userInformation";
bool isPublic = true; // Set to true if you want the binary to be public

binaryCloudSave.UpdateUserBinaryRecordMetadata(key, isPublic, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in UpdateUserBinaryRecordMetadata
        // ...
        Debug.Log(result.Error.Message);

        return;
    }

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

Upload new player binary record file

To upload a new player binary file in a player binary record from the Game Client, follow these steps, in this order:

Request pre-sign URL
Upload binary file
Commit the changes

Request pre-sign URL

You will need a pre-sign URL to upload the updated binary file in the Game Client. To request a pre-sign URL, use the following function:

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "userInformation";
FString FileType = "bin"; // Valid file types are JPEG, JPG, PNG, BMP, GIF, MP3, WebP, and BIN

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

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

string key = "userInformation";
string fileType = "bin"; // Valid file types are JPEG, JPG, PNG, BMP, GIF, MP3, WebP, and BIN

binaryCloudSave.RequestUserBinaryRecordPresignedUrl(key, fileType, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in RequestUserBinaryRecordPresignedUrl
        // ...
        Debug.Log(result.Error.Message);

        return;
    }

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

Upload binary file

Once you have the needed parameter from the Request pre-sign URL section, upload your desired binary data or file. Use the following function:

Unity

byte[] yourUserDataToUpload; // Your user binary data
string url; // Retrieved via callback on successful RequestUserBinaryRecordPresignedUrl (Value.Url)

AccelByteNetUtilities.UploadBinaryTo(binaryInfo.Url, yourUserDataToUpload, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in UploadBinaryTo
        //...
        Debug.Log(result.Error.Message);

        return;
    }

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

Commit the changes

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

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "userInformation";

// The following are taken from RequestUserBinaryRecordPresignedUrl's resulting FAccelByteModelsBinaryInfo
FString ContentType = RequestPresignedUrlResult.Content_Type;
FString FileLocation = RequestPresignedUrlResult.File_Location;

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

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

string key = "userInformation";
string contentType; //Retrieved via callback on successful RequestUserBinaryRecordPresignedUrl (Value.ContentType)
string fileLocation; //Retrieved via callback on successful RequestUserBinaryRecordPresignedUrl (Value.FileLocation)

binaryCloudSave.UpdateUserBinaryRecordFile(key, contentType, fileLocation, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in UpdateUserBinaryRecordFile
        // ...

        return;
    }

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

Delete player binary records from the Game Client

You can only allow your players to remove their own player binary records. To delete a player binary record, use the following function:

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "userInformation";

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

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

string key = "userInformation";

binaryCloudSave.DeleteUserBinaryRecord(key, result =>
{
    if (result.IsError)
    {
        // Your logic to handle errors in DeleteUserBinaryRecord
        // ...
        Debug.Log(result.Error.Message);

        return;
    }

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

Overview​

Prerequisites​

Store player data in binary record from the Game Client​

Create player binary record​

Upload player binary record file​

Commit the changes​

Retrieve player binary record data from the Game Client​

Retrieve a player's binary records data​

Get Single​

Bulk Get​

Retrieve other user's public binary records data​

Get Single​

Bulk Get​

Modify player binary record from the Game Client​

Modify player binary record metadata​

Upload new player binary record file​

Request pre-sign URL​

Upload binary file​

Commit the changes​

Delete player binary records from the Game Client​

On this page

Overview

Prerequisites

Store player data in binary record from the Game Client

Create player binary record

Upload player binary record file

Commit the changes

Retrieve player binary record data from the Game Client

Retrieve a player's binary records data

Get Single

Bulk Get

Retrieve other user's public binary records data

Get Single

Bulk Get

Modify player binary record from the Game Client

Modify player binary record metadata

Upload new player binary record file

Request pre-sign URL

Upload binary file

Commit the changes

Delete player binary records from the Game Client