Last Updated: 5/11/2022, 10:38:05 AM

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

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

# 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 modified the record. This metadata is available in the admin endpoint only. The value options are:

    • Server: the record can only be modified by the server.
    • Client: the record can be modified by both clients and the server. This is the default value.
    Write permission behavior metrics on the Game Record:
    Admin Player
    Server Modify, Read Read
    Client Modify, Read Modify, Read
    Write permission behavior metrics 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 value options are:

    • True: meaning that the record is a public record.
    • False: meaning that the record is a private record. This is the default value.
    Is Public Record behavior metrics on the Player Record:
    Admin Player
    Record Owner Other Players
    False Read Read -
    True Read Read Read

# 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 select Game Records.

    cloud-save

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

    cloud-save

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

    cloud-save

    • Input the Game Record Key using the appropriate format.
    • Select Write Permission from the dropdown menu. See Metadata for a full list of the available options.
    • Input the JSON Configuration.

    Once completed, click the Add and the new record will be added to the list.

    cloud-save

# Update a Record

# Game Record

To update a Game Record, go to the Game Records page, choose the record you want to update, and select View.

cloud-save

  • In the Record Detail window, go to the JSON Configuration section and click Edit. Input the updated record information and click Save.

    cloud-save

# Player Records

To update a Player Record, go to the Player Record page, choose the record you want to update, and select View.

cloud-save

  • In the Record Detail window, go to the JSON Configuration section and click Edit. Input the updated record information and click Save.

    cloud-save

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

    cloud-save

# 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

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

# Integrating Your Game with Cloud Save at the Namespace Level

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

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

# Integrating Your Game Server with Cloud Save

# Create a New Record

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

Retrieve the specified game or user’s 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.

# 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 can erase the specified record.

# User Record

You can delete a user record using the following function.

# Game Record

You can delete a game record using the following function.

# Connecting Custom Services to Cloud Save using the Server SDK

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

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:

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. 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. 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):