Last Updated: 10/27/2021, 12:49:47 PM

# Cloud Save

# Overview

Cloud Save is a service that stores arbitrary data in JSON format. With Cloud Save, you can store, retrieve, update, and delete any data from your game. The game data can be stored in one of two types of records:

  • Game Records store game data such as event configurations and themes.
  • Player Records stores player records such as saved game data.

# Prerequisites

# Permissions

Permissions are used to grant access to specific resources within our services. 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 management, see the Profile, Stats & Cloud Save tab of the permissions reference.

Usage Resource Action
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 or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

# Managing Your Game with Cloud Save in the Admin Portal

The Admin Portal gives community managers and game admins an easy way to manage and integrate Cloud Save.

# Create a New Game Record

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

    cloud-save

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

    cloud-save

  3. Input the required information into the form below.

    cloud-save

    • Input the Game Record Key using the appropriate format.
    • Input the JSON Configuration.
  4. When you’re done, click Add. The new record will be added to the list.

# Update a Game Record

  1. In the Admin Portal, go to the Cloud Save page and choose the record you want to update.

    cloud-save

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

    cloud-save

  3. Input the updated record information and click Save.

    cloud-save

# Update Player Records

  1. In the Admin Portal, open the Player Records page from the Cloud Save menu on the left sidebar. Click View on the player record you want to update.

    cloud-save

  2. In the Record Detail page, go to the JSON Configuration section and click Edit.

    cloud-save

  3. Input the updated record information and click Save to continue.

    cloud-save

  4. A confirmation modal will appear. Click Save to complete your update.

    cloud-save

# Delete a Game Record

  1. In the Admin Portal, go to the Cloud Save page and choose the record you want to delete by clicking the Delete button in the Action column of that record.

    cloud-save

  2. Confirm that you want to delete the record in the form that appears.

# Search for a Player Record

  1. In the Cloud Save menu of the Admin Portal, click Player Records. In the search box above, you can search for a player record by either typing the User ID or Key and pressing Enter.

    cloud-save

  2. The related records will appear. In the example below, we’ve searched for a record by its Key.

    cloud-save

# Retrieve a Game Record

  1. In the Admin Portal, go to the Cloud Save page and open the record you want to view by clicking the View button in the Action column.

    cloud-save

  2. The Record Detail page will open.

    cloud-save

# Retrieve a Player Record

  1. In the Cloud Save menu of the Admin Portal, click Player Records and open the record you want to view by clicking the View button in the Action column.

    cloud-save

  2. The Record Detail page will open.

# Integrating Your Game with Cloud Save Using SDK

You can use our SDK to manage and Integrate your game with Cloud Save.

# Integrating Your Game with Cloud Save at the User Level

To start integrating your game with Cloud Save, make sure you have configured the AccelByte SDK then follow the steps below. After that, you have to set the Cloud Save URL in the Assets/Resources/AccelByteSDKConfig.json file if you’re using Unity SDK, and in the DefaultEngine.ini file if you're using UE4 SDK.

# Create a New Record

This example shows you how to store user data inside the UserXyzAbGame 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.

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

To ensure that edits to user records made concurrently aren’t overwritten, this feature will cause an error to appear if a client tries to submit changes to a user record that has already been changed at the same time by another client. 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 UE4 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.

# Integrating Your Game with Cloud Save at the Namespace Level

# Create a New Record

To create a new record, use the SaveGameRecord() function. Please note that if the key already exists, the new record will be appended to the existing record.

# Retrieve Game Data

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

# Replace Game Data

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.

# Replace Game Record Concurrently

Just like 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 UE4 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 Data

Use the DeleteGameRecord() function to delete game data.

# Integrating Your Game Server with Cloud Save

This API grants your game server the ability to modify users’ records. After that, you have to set the Cloud Save URL in the Assets/Resources/AccelByteSDKConfig.json file if you’re using Unity SDK.

# Create a User Record

Create a new record for the targeted user. 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.

# Retrieve a User Record

Retrieve the specified user’s record.

# Replace a User Record

This function can overwrite an existing user’s record if it exists. If the record does not exist, it will create a new record.

# Delete a User Record

This function can erase the specified user’s record.

# Managing Cloud Save Using the API

You can also use our API endpoints to manage and integrate with Cloud Save.

# Create a New Game Record

You can create a game record using API. To do so, follow steps below:

  1. Use the Save Namespace Level Record: POST - /cloudsave/v1/admin/namespaces/{namespace}/records/{key} endpoint.
  2. Fill out the Namespace with Game Namespace.
  3. Fill out the Key of the record.
  4. Fill out the Request Body with the record information.

Upon successful request, the new game record will be created. Upon successful request, the new game record will be created. A successful request returns Code 201 Created (opens new window), which indicates that the request was successful.

# Update a Game Record

You can update or replace a game record using API. To do so, follow steps below:

  1. Use the Save or Replace Game Record: PUT - /cloudsave/v1/admin/namespaces/{namespace}/records/{key} endpoint.
  2. Fill out the Namespace with Game Namespace.
  3. Fill out the Key of the record.
  4. Fill out the Request Body with the record information.

Upon successful request, the game record will be updated or replaced. Upon successful request, the game record will be updated or replaced. A successful request returns Code 200 OK which indicates that the request was successful.

# Delete a Game Record

You can delete a game record using API. To do so, follow steps below:

  1. Use the Purge all records under the given key: DELETE - /cloudsave/v1/admin/namespaces/{namespace}/records/{key} endpoint.
  2. Fill out the Namespace with Game Namespace.
  3. Fill out the Key of the record.

Upon successful request, the game record will be deleted. Upon successful request, the game record will be deleted. A successful request returns Code 204 No Content which indicates that the request was successful.

# Retrieve a List of Records in a Namespace

You can retrieve records in a specific game namespace using API. To do so, follow steps below:

  1. Use the Retrieve list of records key by namespace: GET /cloudsave/v1/admin/namespaces/{namespace}/records endpoint.
  2. Fill out the Namespace with Game Namespace.
  3. Fill out the Offset and Limit if you want to paginate the results. If you want to retrieve the complete list, you can leave these fields blank.

Upon successful request, records from a specific game namespace will be retrieved. Here is an example of a response to a successful request:

# Retrieve a Game Record

You can retrieve a game record using API. To do so, follow steps below:

  1. Use the Retrieve a record value by its key: GET /cloudsave/v1/admin/namespaces/{namespace}/records/{key} endpoint.
  2. Fill out the Namespace with Game Namespace.
  3. Fill out the Key of the record.

Upon successful request, the game record will be retrieved. Here is an example of a response to a successful request:

# Retrieve a Player Record

You can retrieve a player record using API. To do so, follow steps below:

  1. Use the Retrieve a record value by its key: GET /cloudsave/v1/admin/namespaces/{namespace}/users/{userID}/records/{key} endpoint.
  2. Fill out the Namespace with Game Namespace.
  3. Fill out the Key of the record.

Upon successful request, the player record will be retrieved. Here is an example of a response to a successful request: