Cloud Saves
Let's see how to add cloud saves to your game through GamePush.
Concept
You can save player data in the GamePush cloud at any time. Saving works even for non-authorized players.
How cloud saves work:
- When the game is opened, the SDK requests the latest player data from the server:
- Using platform authentication data - if the player is authenticated on the platform;
- Or using a secret code if the player is a guest;
- If the profile doesn't exist on the server, it will be created.
- Progress will automatically be linked to the platform profile.
- Empty progress will be created based on default field values in the control panel.
- After loading, the SDK provides access to the latest player data obtained from the cloud (local if local saves are used);
- Player data can be modified using the
gp.player.set
method;- Only fields explicitly set in the control panel can be modified/saved.
- Any changes to player data need to be confirmed by triggering synchronization (
gp.player.sync
); - During synchronization/initial loading on the server, the following actions are performed:
- Comparing player profiles on the server and client;
- Comparison may lead to conflict when a player was a guest and now logs in with existing progress in the account. In this case, the player is offered to choose which data to keep in the account, or profiles are separated depending on the platform's ideology.
- Updating playtime statistics;
- Calculating energy;
- Checking avatar links - only allowed avatar links can be saved if this option is enabled in the control panel;
- Forbidden links will be replaced with a blank avatar.
- Saving data to the database;
- Updating global leaderboard records;
- Checking/activating triggers;
- Checking/distributing A/B experiments;
- Checking/updating segments;
- Checking/updating event lists;
- Checking/updating daily rewards;
- Rewarding achievements/purchases;
- Retrieving a list of unspent purchases;
- Every time on the first request:
- Sending "Login Notifications" to all open tabs with the game under this player profile. This way, you can track whether the player has opened a second tab with the game or played on another device.
- Comparing player profiles on the server and client;
- Upon completing synchronization, the data becomes current both on the server and in the SDK.
- On average, synchronization takes 7 ms.
- Depends on the volume of saved data.
- Permissible total profile data size - less than 1 MB.
- Recommended total profile data size - less than 10 KB (gzip).
Introduction
To save in the cloud, you will need:
- Create player fields for storage in the control panel.
- For more information on working with player fields, you can read here.
- Modify the value of the necessary player fields in the SDK.
- For more information on working with player data, you can read here.
- Confirm the changes by calling the synchronization method.
- For more information on managing player synchronization, you can read here.
For example, let's create several fields:
- Level: We will save the last completed level in the game.
- Character: We will save the last selected character in the game.
- Sound Off: We will save the value of sound on/off in the game.
- Progress: We will save JSON game progress data.
Save a Numeric Field
Using the "Level" field as an example.
- Go to the Players section of your project in the control panel.
- In the "Player Fields" section, click "Add Field".
- Fill in as shown in the image:
You have added the "Level" field, accessible in the SDK by the key level
.
Code to use the field:
// Get the field value
const level = gp.player.get('level');
// Update the field value
gp.player.set('level', level + 1);
// Confirm the changes - save to the cloud
gp.player.sync();
Save a String Field
Using the "Character" field as an example.
- Go to the Players section of your project in the control panel.
- In the "Player Fields" section, click "Add Field".
- Fill in as shown in the image:
- Enumerated values are not mandatory. They are used to restrict valid values and display the translation of that value to the player's language.
You have added the "Character" field, accessible in the SDK by the key character
.
Code to use the field:
// Get the field value
const character = gp.player.get('character');
// Update the field value
gp.player.set('character', 'cat');
// Confirm the changes - save to the cloud
gp.player.sync();
Save a Boolean Field
Using the "Sound Off" field as an example.
- Go to the Players section of your project in the control panel.
- In the "Player Fields" section, click "Add Field".
- Fill in as shown in the image:
You have added the "Sound Off" field, accessible in the SDK by the key sound-off
.
Code to use the field:
// Get the field value
const isSoundOff = gp.player.get('sound-off');
// Update the field value
gp.player.set('sound-off', true);
// Toggle the field value
gp.player.toggle('sound-off');
// Same as above line
gp.player.set('sound-off', !isSoundOff);
// Confirm the changes - save to the cloud
gp.player.sync();
Save a JSON Field
Using the "Progress" field as an example.
- Go to the Players section of your project in the control panel.
- In the "Player Fields" section, click "Add Field".
- Fill in as shown in the image:
You have added the "Progress" field, accessible in the SDK by the key progress
.
Code to use the field:
// Get the field value
let progress;
try {
// Parse progress from JSON string
progress = JSON.parse(gp.player.get('progress'));
} catch (err) {
// Failed to parse progress (missing, corrupted)
// Create a default value
progress = {
level: 1,
hp: 100,
maxHp: 100,
};
}
// Update the field value
progress.level = 2;
progress.hp = 120;
progress.maxHp = 120;
gp.player.set('progress', JSON.stringify(progress));
// Confirm the changes - save to the cloud
gp.player.sync();
Saving Data to the Cloud
After making changes to the player, you can send them to the server and save them locally on the device. It's recommended to save player data after completing a level, receiving rewards, and immediately after important actions like purchasing an item.
Avoid saving when opening the game menu/main screen. It's better to save data after completing an action.
Action algorithm:
- Update player data in the SDK;
- Confirm the changes by calling the synchronization method.
// Update the numeric field value
gp.player.set('level', 2);
// Update the string field value
gp.player.set('character', 'cat');
// Update the boolean field value
gp.player.set('sound-off', true);
// Update the JSON field value
gp.player.set(
'progress',
JSON.stringify({
level: 2,
hp: 120,
maxHp: 120,
})
);
// Synchronize, returns a promise to await completion
await gp.player.sync();
// Data saved
Loading Data from the Cloud
Data is loaded automatically when the game is launched. No additional action is required. Once the SDK is initialized, you can start using the data.
// Get the numeric field value
const level = gp.player.get('level');
// Get the string field value
const character = gp.player.get('character');
// Get the boolean field value
const isSoundOff = gp.player.get('sound-off');
What's Next
- Learn how to authenticate via SDK;
- Learn how to authenticate via SDK using anonymous login;
- Learn more about player fields;
- Learn more about player data;
- Learn to use automatically replenished fields like Energy, Lives, time-based chests - learn more about Energy.
Stay in Touch
Other documents of this chapter available Here. To get started, welcome to the Tutorials chapter.
GamePush Community Telegram
: @gs_community.
For your suggestions e-mail
: [email protected]
We Wish you Success!