Once you are done with Setup on both iOS and Android, you can start implementing cloud services in your application. Cloud services allows you to store your game data on cloud so that your users can access their progress from anywhere.

How the data sync works

There are two kinds of data copies based on where they are available.

• ​Cloud Copy​

• ​Local Copy​

Cloud Copy always stays remotely on cloud servers. Where as Local Copy is "nearly the latest" copy downloaded on the user's device.

When you try to sync data with cloud, as soon as user's device connects to the cloud servers (When you call Syncronize for the first time), plugin communicates with the cloud servers and fetches the latest copy available on server and this is our Local Copy.

For the first time, if there is no Local Copy available on device, plugin replaces the Local Copy with the latest Cloud Copy just downloaded and fires CloudServices.OnSavedDataChange event with InitialSyncChange as the reason along with the changed keys(available in cloud copy).

Irrespective of data differences between "Cloud Copy" and "Local Copy", always plugin "overwrites" your device's "Local Copy" with the latest downloaded "Cloud Copy" on Syncronize.

Once after overwriting, it fires the event with the changed keys with the related reason.

Once you get OnSavedDataChange with the list of changed keys, you need to update the data of the Local Copy with the setter functions if you have any updated data in your cache.

Once you update the correct data with setters in the OnSavedDataChange callback, this data will be pushed to the cloud servers in the next Syncronize call.

You can call Syncronize any time to initiate a sync between Cloud and Local copies. However, plugin provides an option to set the Sync Interval to do this sync automatically. You just need to call Syncronize only once at start to initiate the first sync.

​

​

Import Namespace

Before using Cloud Services feature, you need to import the namespace.

using VoxelBusters.EssentialKit;

Including the above namespace gives access to CloudServices class which is the class responsible for providing cloud services features.

Register for Events

For getting the callbacks, you need to first register the events in OnEnable of your MonoBehaviour.

private void OnEnable()
{
    // register for events
    CloudServices.OnUserChange              += OnUserChange;
    CloudServices.OnSavedDataChange         += OnSavedDataChange;
    CloudServices.OnSynchronizeComplete     += OnSynchronizeComplete;
}
​
private void OnDisable()
{
    // unregister from events
    CloudServices.OnUserChange              -= OnUserChange;
    CloudServices.OnSavedDataChange         -= OnSavedDataChange;
    CloudServices.OnSynchronizeComplete     -= OnSynchronizeComplete;
}

Syncronize

Syncronize initiates authentication login prompt for the user if required and downloads the latest copy from cloud servers.

This is required as the initial step as once a user installs the app freshly or once user is back to the app after sometime, we need to make sure he/she has the latest data to proceed.

So, call this method in the main menu or at the time of loading so that you will be ready with the data once your user starts the game. Note that the first call to Syncronize may show up a pop up on android for google play services login.

CloudServices.Syncronize();

This call triggers a callback CloudServices.OnSyncronizeComplete and it returns success flag as true if syncronize succeds. If will be false if user deny the authentication or due to network error.

// Register for the CloudServices.OnSyncronizeComplete event
// ...
private void OnSynchronizeComplete(CloudServicesSynchronizeResult result)
{
    Debug.Log("Received synchronize finish callback.");
    Debug.Log("Status: " + result.Success);
    // By this time, you have the latest data from cloud and you can start reading.
}

Store and Retrieve Data

Plugin offers to save your data in the form of Key-Value pairs. So, for each data item you want to store on cloud, you need to set a unique key. Currently, we support all commonly used data types to save on cloud.

• Bool

• Long

• Double

• String

Here are some examples on how to set and get different data types.

Saving and reading a bool value

bool boolValue;
// ... Update the boolValue as per your code
// Start saving it to cloud
CloudServices.SetBool("bool-unique-key", boolValue);
​
// ....
// Get the value of the above saved bool value later
bool boolValueFromCloud = CloudServices.GetBool("bool-unique-key");

Saving and reading a long value

long longValue;
​
// Start saving it to cloud
CloudServices.SetLong("long-unique-key", longValue);
​
// ....
// Get the value of the above saved long value later
long longValueFromCloud = CloudServices.GetLong("long-unique-key");

Saving and reading a string value

string stringValue;
​
// Start saving it to cloud
CloudServices.SetString("string-unique-key", stringValue);
​
// ....
// Get the value of the above saved string value later
string stringValueFromCloud = CloudServices.GetString("string-unique-key");

Saving a reading a Dictionary value When saving Dictionary or List kind of containers, you can just convert to json string and use SetString method.

Dictionary<string, string> dictionaryValue;
​
// Convert to json (you can make use of our Json service provider available in VoxelBusters.EssentialKit or use your own serializer)
IJsonServiceProvider serializer = new DefaultJsonServiceProvider();
string json = serializer.ToJson(dictionaryValue);
​
// Start saving it to cloud
CloudServices.SetString("dictionary-unique-key", json);
​
// ....
// Get the value of the above saved string value later
string stringValueFromCloud = CloudServices.GetString("string-unique-key");
// Convert the jsonString back to dictionary
IJsonServiceProvider serializer = new DefaultJsonServiceProvider();
object dictObject = serializer.FromJson(stringValueFromCloud);

Handling data consistency and external data changes

If the user plays your game on different devices, there is a possibility to shift from one device to another during the game play progress. They do expect the latest data on the current device they are on. To handle these kind of situations, we provide CloudServices.OnSavedDataChange which informs the data changes if any with a reason and changed keys.

CloudServices.OnSavedDataChange event is triggered when ever there is a change in the data that is accessed by Getter functions (GetBool, GetString etc..). This callback gives you the required information to handle the data state. It gives a reason (CloudSavedDataChangeReasonCode) and also the changedKeys array to find out the keys that got changed from the current copy.

CloudServices.OnSavedDataChange event gets fired for the following reasons:

​