Usage

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 Synchronize 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 Synchronize.
Once after overwriting, it fires the event with the changed keys with the related reason. 
As plugin always overwrites the Local Copy with latest downloaded Cloud Copy, you need to make sure you have a mechanism in your game to recover the overwritten data (by caching the data you are writing to Local copy through Setter functions)

Future Roadmap:
This requirement may change in the future where our plugin sends the overwritten data along with the changed keys and this avoids you to have your own copy.
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. 
Note that by the time you get this callback, Local copy is already overwritten with Cloud copy and all getter functions return latest cloud copy data only but not your earlier local data you set through setter functions.
Once you update the correct data with setters in the OnSavedDataChange callback, this data will be pushed to the cloud servers in the next Synchronize call.
You can call Synchronize 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 Synchronize only once at start to initiate the first sync.
If there are no changes between Cloud Copy and Local Copy, no event will be fired and it means your data is in sync with the cloud servers!
​
TOC
​Import Namespace​
​Register for Events​
​Sync Data​
​Store and Retrieve Data​
​Data Consistency​
​
Import Namespace
Before using Cloud Services feature, you need to import the namespace.
1
using VoxelBusters.CoreLibrary;
2
using VoxelBusters.EssentialKit;
Copied!
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.
1
private void OnEnable()
2
{
3
    // register for events
4
    CloudServices.OnUserChange              += OnUserChange;
5
    CloudServices.OnSavedDataChange         += OnSavedDataChange;
6
    CloudServices.OnSynchronizeComplete     += OnSynchronizeComplete;
7
}
8
​
9
private void OnDisable()
10
{
11
    // unregister from events
12
    CloudServices.OnUserChange              -= OnUserChange;
13
    CloudServices.OnSavedDataChange         -= OnSavedDataChange;
14
    CloudServices.OnSynchronizeComplete     -= OnSynchronizeComplete;
15
}
Copied!
Event Name
Description
CloudServices.OnUserChange
This event gets triggered once if there is a change in the underlying cloud account
CloudServices.OnSavedDataChange
This event gets triggered when there is a change in current cloud data you have access to and provides the reason(CloudSavedDataChangeReasonCode) behind the data change along with the changed keys.
CloudServices.OnSynchronizeComplete
This event gets triggered in response to Synchronize call with CloudServicesSynchronizeResult status.
Synchronize
You need to call Synchronize manually for the first time after the launch of your app (if Synchronize On Load property is off).
Synchronize 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 Synchronize may show up a pop up on android for google play services login.
1
CloudServices.Synchronize();
Copied!
This call triggers a callback CloudServices.OnSynchronizeComplete and it returns success flag as true  if synchronize succeds. If will be false if user deny the authentication or due to network error.
1
// Register for the CloudServices.OnSynchronizeComplete event
2
// ...
3
private void OnSynchronizeComplete(CloudServicesSynchronizeResult result)
4
{
5
    Debug.Log("Received synchronize finish callback.");
6
    Debug.Log("Status: " + result.Success);
7
    // By this time, you have the latest data from cloud and you can start reading.
8
}
Copied!
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
1
bool boolValue;
2
// ... Update the boolValue as per your code
3
// Start saving it to cloud
4
CloudServices.SetBool("bool-unique-key", boolValue);
5
​
6
// ....
7
// Get the value of the above saved bool value later
8
bool boolValueFromCloud = CloudServices.GetBool("bool-unique-key");
Copied!
Saving and reading a long value
1
long longValue;
2
​
3
// Start saving it to cloud
4
CloudServices.SetLong("long-unique-key", longValue);
5
​
6
// ....
7
// Get the value of the above saved long value later
8
long longValueFromCloud = CloudServices.GetLong("long-unique-key");
Copied!
Saving and reading a string value
1
string stringValue;
2
​
3
// Start saving it to cloud
4
CloudServices.SetString("string-unique-key", stringValue);
5
​
6
// ....
7
// Get the value of the above saved string value later
8
string stringValueFromCloud = CloudServices.GetString("string-unique-key");
Copied!
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.
1
Dictionary<string, string> dictionaryValue;
2
​
3
// Convert to json (you can make use of our Json service provider available in VoxelBusters.EssentialKit or use your own serializer)
4
IJsonServiceProvider serializer = new DefaultJsonServiceProvider();
5
string json = serializer.ToJson(dictionaryValue);
6
​
7
// Start saving it to cloud
8
CloudServices.SetString("dictionary-unique-key", json);
9
​
10
// ....
11
// Get the value of the above saved string value later
12
string stringValueFromCloud = CloudServices.GetString("string-unique-key");
13
// Convert the jsonString back to dictionary
14
IJsonServiceProvider serializer = new DefaultJsonServiceProvider();
15
object dictObject = serializer.FromJson(stringValueFromCloud);
Copied!
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:
Reason
Description
CloudSavedDataChangeReasonCode.ServerChange
This reason is returned when there is a difference between the local copy that is currently used and the latest cloud copy on cloud server.
CloudSavedDataChangeReasonCode.InitialSyncChange
This is triggered initially when a new copy is downloaded from the cloud server for the first time.
CloudSavedDataChangeReasonCode.QuotaViolation
This is the reason when excess data is being stored and it resets to the cloud copy available on the server
CloudSavedDataChangeReasonCode.AccountChange
This is the reason when user shifts the account that is being used on the device and as the current data is no more valid, it returns all the key changes.
Sequence of events
1.
Plugin trying to sync the data
2.
Downloaded latest copy from cloud
3.
Finds the keys which got changed from cloud copy by comparing with local copy
4.
Overwrites the complete Local copy with latest Cloud Copy data
5.
If there are any key-value changes in step 3, then fires CloudServices.OnSavedDataChange event with changed the changed keys
6.
In the callback, you need to check the cloud value with Getters and check the values with your cache
7.
If you see the local copy got overwritten with cloud copy and not reflecting your changes, you need to use setters to update it.
8.
Data updated in step 7 will be pushed to cloud on next sync.
​