Store game wide data in binary records from game client
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 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
}));
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
}));
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
}));
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
}));
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
}));
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
}));
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
}));
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
}));
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
}));
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
}));