Cloud Save

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 record:

• 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 (opens new window) are used to grant access to specific resources within our service. 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 (opens new window) tab of the permissions reference.

Usage	Resource	Permission
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 (opens new window) or Roles (opens new window) assigned to users. For more information, read the Authentication and Authorization (opens new window) 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 can modify the record. This metadata is available only in admin endpoints. The possible values are:

• Server: The record can only be modified by the server.
• Client: The record can be modified by either the client or the server. This is the default value.

Write permission behavior on the Game Record:

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

Write permission behavior 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 possible values are:

• Public: The record is accessible to other players. The value displayed in the is_public field is True.
• Private: The record is not accessible to other players. The value displayed in the is_public field is False.

Is Public Record behavior on the Player Record:

	Admin	Player
		Record Owner	Other Players
Private	Read	Read	-
Public	Read	Read	Read

Manage Cloud Saves in the Admin Portal

Create a New Game Record

To create a game record, follow the steps below:

1. In the Game Management section of the Admin Portal, go to the Cloud Save menu and select Game Records.

   

2. On the Cloud Save page, click the Create Game Record button.

   

3. 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 Write Permission for a full list of the available options.
   • Input the JSON Configuration.

4. When you have finished, click the Add button and the new record will be added to the list.

   

Create a New Player Record

To create a game record, follow the steps below:

1. In the Game Management section of the Admin Portal, go to the Cloud Save menu and select Player Records.

   

2. On the Cloud Save page, click the Add Player Record button.

   

3. The Create Player Record form will appear. Fill in the required fields.

   • Input the User ID of the target user within the active namespace.
   • Input the Key field with the Player Record Key using the appropriate format. This will be your players' record identifier.
   • Input the Record Type. See Record Type for a full list of the available options.
   • Choose the Write Permission. See Write Permission for a full list of the available options.

   

4. Click the Create button. The new game record is created and you will be redirected to the Player Record Detail page.

Update a Game Record

To update a game record, follow the steps below:

1. In the Game Management section of the Admin Portal, go to the Cloud Save menu and select Game Records.

   

2. On the Cloud Save page, choose the record you want to update, and select View in the Action menu.

   

3. In the Record Detail window, go to the JSON Configuration section and click Edit.

   

4. Input the updated record information and click Save.

   

Update a Player Record

To update a player record, follow the steps below:

1. In the Game Management section of the Admin Portal, go to the Cloud Save menu and select Player Records.

   

2. On the Cloud Save page, choose the record you want to update, and select View in the Action menu.

   

3. In the Record Detail window, go to the JSON Configuration section and click Edit.

   

4. Input the updated record information and click Save.

   

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

   

Integrating 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.

Retrieve a User Record

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

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.

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.

Replace User Records Concurrently

This feature will send an error message when a client tries to submit changes to a user record that is being edited at the same time by another client. This ensures 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.

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.

Delete a User Record

Use the DeleteUserRecord() function to delete a record.

Integrate Your Game with Cloud Save at the Namespace Level

Create a New Game Record

To create a new record, use the SaveGameRecord() function.

NOTE

If the key already exists, the new record will be appended to the existing record.

Retrieve Game Record

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

Replace 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, all the data in the update will be replaced.

Replace Game Record Concurrently

In the same way as 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.

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.

Delete Game Record

Use the DeleteGameRecord() function to delete game data.

Modify Games and User Records

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

NOTE

You need to use a client token to call a Game Server.

Create a New 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.

Game Record

You can create a game record using the following function.

Retrieve a Record

You can retrieve a specific game or user record.

User Record

You can retrieve a user record using the following function.

Game Record

You can retrieve a game record using the following function.

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.

Retrieve All Game Records

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

Retrieve All Game Records

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

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.

Game Record

You can replace a game record using the following function.

Delete a Record

This function will delete the specified user record.

Game Record

You can delete a game record using the following function.

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:

1. Create your IAM Client (opens new window) and assign the necessary permissions to access the IAM service.
2. Log in as a Client using the SDK (opens new window).
3. Initialize the OAuth 2.0 service using the following function (opens new window):

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:

1. Create your IAM Client (opens new window) and assign the necessary permissions to access the Matchmaking service.
2. Log in as a Client using the SDK (opens new window).

Once completed, you can use the Golang SDK to access Cloud Save (opens new window) services from your serverless app.

.NET (C#) SDK Initialization

Before using the Cloud Save service, you will need to set some permissions (opens new window). 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 Cloudsave service, you will need to set some permissions (opens new window). Initialize the PublicGameRecord wrapper from the Cloudsave service using the following code:

PublicGameRecord wPublicGameRecord = new PublicGameRecord(sdk);

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

Create a Game Record

Use the following function to create a game record (opens new window):

Update a Game Record

Use the following function to update a game record (opens new window):

Delete a Game Record

Use the following function to delete a game record (opens new window):

Retrieve a Game Record

Use the following function to retrieve a game record (opens new window):