Getting started

This step is easy. Sign up here and choose the authentication provider you like to sign up with Cloudonaut.

Applications

An app is your basic starting point to use Cloudonaut. Each app has its cloud data, leaderboards, players, characters, etc...
Cloudonaut does not limit the number of apps you can have. Even in the free tier, you can have as many apps as you want.
Just remember that you have 1000 free calls each month shared between apps.

Create an application

After you logged in to your Cloudonaut dashboard, in the left side menu you see a + icon next to Your applications.
To create a new app click on that + sign.
Give your app a name and click on create.
The app will be created and you will see the applications name in the left side menu.

The app ID

To get your app ID you can click on the application name and then settings in the left side menu.
The number next to "Your appID:" is your application ID.
You will need this ID to identify your app later on.

The app secret

The app secret is auto-generated. To reveal your app secret follow these steps:
Click on the application name and then settings in the left side menu.
Click on the text: *** Click to reveal your app secret ***

Read about App security in the next section for more info.

App security

For compiled games, you can use the app secret key.
The backend API will check the combination of appID with the app secret to identify every call you make.
For web games, we strongly suggest you whitelist your URL for your app and do not use the app secret key.
As an alternative, you can set up a backend script as a router. This router script can use the app secret key.

Whitelist a URL

To whitelist an URL follow the following steps:
Click on the application name and then settings in the left side menu.
Type your domain name in the Url list field and press the update button.
You do not need to specify subdomains. Just use something like "example.com".
To add multiple domains you can an "," to separate domains.

Using a Router script

A router will make it possible to manipulate calls on your backend before passing them on to the Cloudonaut API.
A simple example is adding the app secret to the call instead of whitelisting URLs in your app.
Another example could be to create your anti-cheating mechanisms and check a score before submitting it.

Here is a very basic example router written in PHP.

$rawData = file_get_contents("php://input");
$request = json_decode(urldecode($rawData));
$request->appSecret = <your app secret>;

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api01.cloudonaut.com',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode($request),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Facebook integration

If you want to integrate Facebook to authenticate your players you need to provide us the Facebook App ID and the Facebook App Secret. To get these you need a Facebook developer account and create a Facebook app first. To do this you can find their documentation here.

To enter the facebook app ID and Secret follow the following steps:
Click on the application name and then settings in the left side menu.
Fill in the Facebook App ID and Facebook App Secret and click on the update button.

Firebase integration

Firebase can be used to authenticate using lots of auth providers. Including Facebook, Gmail, Microsoft, Apple, etc... You can use Firebase auth to identify your players. To do that, you need to provide us a service account. You can do that in the project settings of your Firebase project. When you generate a new key you will be able to download a JSON file. Copy the complete contents of this JSON.

To store this json contents go to your Cloudonaut dashboard.
Click on the application name and then settings in the left side menu.
Paste the contents in the field Firebase Service Account and click the update button.

Cloud Data

Cloud data is a key-value store to store player, character, and even app data.

For player data, the player can write and read to his data by default and can be read by other players of the same app.
You can change this behavior with the privacy field.
Each player can also create specific character data. So you can store character abilities or levels for each character as an example.

App data are key values that can be read by all players and characters.
You can use this to store texts or game settings that need to be synchronized to all players without republishing your game.
We strongly advise using the Cloudonaut dashboard to fill-in app data and only retrieve the app data with the API in your game/app or website. In this case, the default privacy setting is set to read-only for players. Using the API to write app data means you are writing data as a player. The privacy setting will be set as read and writable for all players.
We do not recommend this. Use it with care if you have an edge case for this.

Privacy

The privacy field for player/character data can be 0,1 or 2.
0 = Everybody can read and write to this data of the player. (not recommended)
1 = Everybody can read the data but only the logged-in player can write. (default)
2 = Only the logged-in player can read and write to this data.

Notice that when you set privacy to 0. Other players could write to your data. There is no API call for the other player to do that at this moment but there might be one in the future. So take care of the player's data and set the privacy to 1 or 2 to be future proof.

For application data, you can set the privacy to 0,1 or 2.
0 = Everybody can read and write this data. (Not recommended, only for edge cases)
1 = Everybody can read this data but the data can only be set through the Cloudonaut dashboard. (Maybe a back-end API in the future)
2 = Only readable and writeable through the Cloudonaut dashboard.

When a player tries to write to app data that does not have privacy of 0, the following will be returned.

{
  "success":false,
  "error":"Wrong permission to write to this data.",
  "errorId":2
}

All other cases with permission problems will return the following object:

{
  "success":false
}

Write-lock

If 2 users get the same read and writable key what happens when they both save a change?
Without write locks the last one to press save will win. His value will overwrite the other user's value.
If you want to prevent this you can use write locks. Again, when 2 users get the same key they now get the same write lock.
But you can only save data if you have the write lock that matches the write lock value on the server.
In this case, user A saves first. The write lock on the server will be incremented.
If user B saves his data now, it will fail because he used an old write lock.

For app data, the write-lock is always enabled.
For player data, it is disabled by default. As long as you do not set the value of the write-lock it won't be used. If you want to use it for player data, set the write lock to 1 or above. From that moment the write lock is used and can't be undone.

Response after writing with the wrong write lock:

{
  "success":false,
  "error":"Wrong writelock provided",
  "errorId":1
}

Create App data

To create application level key value pairs you will need login to the Cloudonaut dashboard.
On the left side menu click on your app and choose App data.
Click on the Add key button.
Fill in the Key wich has to be unique for this app. (If you try to create a duplicate key you will be prompted that there is a failed API call.)
Set the privacy. Default it is Everybody can read.
Last but not least, fill in a value for the key. This can be any string. Even Json is possible.
Click on Create.

Modify App data

To modify a key follow these steps:
On the left side menu click on your app and choose App data. Click on the Edit button of the key you want to modify.
You can change the value, privacy and the writeLock.
The writeLock should be kept as is. Only in some special occasion you can change it here. Remember that it needs to be a higher number than before.

Quickstart

Lets create a game!

API reference

Cloudonaut can be used completely as an API from any project/app that can make a post call.
In this section we will describe all the calls that can be made. You can even test these with postman or another tool.

So if you are writing C code, Native apps, etc.. You can use this reference to build your integration.

Authentication

For user authentication, you can use our anonymous system or use an existing authentication provider. We integrate with Firebase and Facebook. We did not develop our own email/username/password system because there are already so many providers and security is a huge thing. That is why we recommend using Firebase or Facebook to allow players to play on different devices. Firebase can be used to login with lots of different providers (Game Center, Play games, Google, Apple, ...) and has a free tier.

Anonymous

Anonymous authentication uses a single unique string to identify the player. We call this the provider UID. For Facebook and Firebase, the provider UID will be the UID of that platform. For anonymous authentication, we recommend using the device ID. If you are using a browser application or a platform without a device ID you can generate a unique ID with the Cloudonaut Function Get GUID or Get Random String. Store that string in a browser cookie or local storage to remember the device/player and use it as the provider UID.

Remember that once the provider UID is lost by the player he can't recover his account anymore. (Apple devices have a unique ID for each app. If the player uninstalls the app and reinstalls it again the unique ID will not be the same.) If you need users to have more secured accounts use Firebase or Facebook instead.

However, you should use anonymous authentication to start with. So a player can use all features of your game or app. Including leaderboards and cloud data. If a user logs in with Firebase or Facebook, you can merge the current anonymous user with the social user.

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
"appID":<your appID>,
"appSecret":<your appSecret>,
"controller":"Auth",
"action":"Authenticate",
"provider":0,
"providerUID":<unique ID>,
"displayName":"",
"displayNameExtra":""
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Auth"	Yes
action	string	Set to "Authenticate"	Yes
provider	int	0 = Anonymous authentication, 1 = Facebook authentication, 2 = Firebase authentication	Yes
providerUID	string	Pass the device ID or a generated unique string that can identify the users device / browser	Yes
displayName	string	The display name for the player. If not provided a random name will be used	No
displayNameExtra	string	A extra addition to the name. If not provided a random name will be used	No

The data object looks like this:

{
  "success":<bool>,
  "player":
  {
    "playerID":<int>,
    "playerSecret":<string>,
    "displayName":<string>,
    "displayNameExtra":<string>,
    "providerUID":<string>
  }
}

Use the givven playerSecret for all other calls to identify the player.

Authenticate with Facebook

To use Facebook authentication you need to create a Facebook app on their developer site.
Once you have created an app get the app ID and Facebook app secret.
In the Cloudonaut App Dashboard, you can edit your Cloudonaut app and fill in the Facebook app ID and app secret.
Now your app can connect with Facebook.

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
"appID":<your appID>,
"appSecret":<your appSecret>,
"controller":"Auth",
"action":"Authenticate",
"provider":1,
"playerID":<ID of the anonymoususer you want to merge>,
"providerUID":<unique ID of anonymous user you want to merge>,
"playerSecret":"<The Facebook token>"
"displayName":"",
"displayNameExtra":""
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Auth"	Yes
action	string	Set to "Authenticate"	Yes
provider	int	0 = Anonymous authentication, 1 = Facebook authentication, 2 = Firebase authentication	Yes
playerID	string	The ID of the current logged in anonymous account. Only needed to merge the anonymous account into the new social account	No
providerUID	string	the providerUID of the current logged in anonymous account. Only needed to merge the anonymous account into the new social account	No
playerSecret	string	The facebook token you got from the facebook SDK	Yes
displayName	string	The display name for the player. If not provided the name will be filled with the facebook name	No
displayNameExtra	string	A extra addition to the name. If not provided the name will be filled with the facebook name	No

The data object looks like this:

{
  "success":<bool>,
  "player":
  {
    "playerID":<int>,
    "playerSecret":<string>,
    "displayName":<string>,
    "displayNameExtra":<string>,
    "providerUID":<string>,
    "merged":<bool>
  }
}

Use the givven playerSecret for all other calls to identify the player from now on.

Authenticate with Firebase

Firebase contains a huge amount of authentication providers. From Gmail to Apple Game center and Android Play games. Currently, we did not implement these auth providers on our own. But you can use them through Firebase. (Why reinvent the wheel?)

If you do not have a Firebase application yet you should create one. (Follow their instructions) In the Firebase console, you can generate a service account. It will generate a JSON file. You need this to connect Cloudonaut to Firebase. In the Cloudonaut app dashboard, edit the app you want to use firebase authentication with. Paste the Contents of the JSON file into the Firebase Service Account field.

Now we can connect with Firebase.

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
"appID":<your appID>,
"appSecret":<your appSecret>,
"controller":"Auth",
"action":"Authenticate",
"provider":2,
"playerID":<ID of the anonymoususer you want to merge>,
"providerUID":<unique ID of anonymous user you want to merge>,
"playerSecret":"<The Firebase token>"
"displayName":"",
"displayNameExtra":""
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Auth"	Yes
action	string	Set to "Authenticate"	Yes
provider	int	0 = Anonymous authentication, 1 = Facebook authentication, 2 = Firebase authentication	Yes
playerID	string	The ID of the current logged in anonymous account. Only needed to merge the anonymous account into the new social account	No
providerUID	string	the providerUID of the current logged in anonymous account. Only needed to merge the anonymous account into the new social account	No
playerSecret	string	The Firebase token you got from the firebase SDK	Yes
displayName	string	The display name for the player. If not provided the name will be randomly generated	No
displayNameExtra	string	A extra addition to the name. If not provided the name will be randomly generated	No

The data object looks like this:

{
  "success":<bool>,
  "player":
  {
    "playerID":<int>,
    "playerSecret":<string>,
    "displayName":<string>,
    "displayNameExtra":<string>,
    "providerUID":<string>,
    "merged":<bool>
  }
}

Use the givven playerSecret for all other calls to identify the player from now on.

Cloudonaut Functions

Cloudonaut Functions are a set of helper functions to make your life easier.

Get Distance

Get the distance between 2 geo points in km, miles, or nautical miles. You can send the longitude-latitude points as a decimal or in the degree, minute, and second format.

To define these geo points we created an object GeoPoint.
You can choose which unit of measurement you want to use.
km = kilometer
mi = miles
nmi or nm = nautical miles

POST / HTTP/1.1
Host: localhost:3000
Content-Type: application/json
Content-Length: 233

{
	"appID":<Your appID>,
	"appSecret":<Your appSecret>,
	"controller":"CF",
	"action":"GetDistance",
    "latitude1":"51.2194475",
    "longitude1":"4.4024643",
    "latitude2":"50°51'1.224\"",
    "longitude2":"4°21'6.156\"",
    "unit":"km"
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "CF"	Yes
action	string	Set to "GetDistance"	Yes
longitude1	string	Longitude of point 1 in DMS or Decimal format	Yes
latitude1	string	Latitude of point 1 in DMS or Decimal format	Yes
longitude2	string	Longitude of point 2 in DMS or Decimal format	Yes
latitude2	string	Latitude of point 2 in DMS or Decimal format	Yes
unit	string	The unit you want the distance be calculated in. km = kilometer, mi = miles, nmi or nm = nautical miles	No

The data object looks like this:

{
  "success":<bool>,
  "latitude1": "51.2194475",
  "latitude2": "50.85034",
  "longitude1": "4.4024643",
  "longitude2": "4.35171",
  "distance":"41.19405040417068",
  "unit":"km"
}

Get Random String

Generate a unique string.

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"CF",
  "action":"GetRandomString"
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "CF"	Yes
action	string	Set to "GetRandomString"	Yes

The response object looks like this:

{
    "success": true,
    "randomString": "196069d18d8aea4CRS6069d18d8aea64.49739688"
}

Get GUID

Generate a version 4 GUID.

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"CF",
  "action":"GetGUID"
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "CF"	Yes
action	string	Set to "GetGUID"	Yes

The response object looks like this:

{
    "success": true,
    "GUID": "eb3a4d22-1df8-469a-ab6f-353f6d912152",
    "GUIDVersion": 4
}

Characters

Each player can have multiple characters. Characters will have a character ID.
If you want your game our app to make use of this possibility you can pass this character ID along with the player ID to most of our API functions.
Examples are leaderboards. Add a score for a player. Or for a player character combination.
Cloud data can be stored for a player but also a player character combination.
It is not necessary to use characters if you do not need multiple characters per player.

Add character

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Character",
  "action":"Add",
  "playerID":<playerID>,
	"playerSecret":<Token>,
	"characterName": <The name of the character>,
	"characterNameExtra": <Aditional name for the character>,
	"characterAvatar": <Link to avatar>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Character"	Yes
action	string	Set to "Add"	Yes
playerID	string	Set this ID to match the currently logged in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player	Yes
characterName	string	If not provided a random name will be used	Yes
characterNameExtra	string	A extra addition to the name. If not provided a random name will be used	Yes
characterAvatar	string	Provide this field with any text you want to identify a avatar for this character. You add a link here, a name of a asset in the game you use for characters etc.. It is up to you to use this code and display a Avatar.	Yes

The response object looks like this:

{
    "success": <bool>,
    "characterID": "<int>"
}

Update character

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Character",
  "action":"Update",
  "playerID":<playerID>,
  "playerSecret":<Token>,
  "characterID":<characterID>,
  "characterName": <The name of the character or empty to leave as is>,
  "characterNameExtra": <Aditional name for the character or empty to leave as is>,
  "characterAvatar": <Link to avatar or empty to leave as is>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Character"	Yes
action	string	Set to "Update"	Yes
playerID	string	Set this ID to match the currently logged in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player	Yes
characterID	string	The character ID of the character you want to change	Yes
characterName	string	If not provided a random name will be used	Yes
characterNameExtra	string	A extra addition to the name. If not provided a random name will be used	Yes
characterAvatar	string	Provide this field with any text you want to identify a avatar for this character. You add a link here, a name of a asset in the game you use for characters etc.. It is up to you to use this code and display a Avatar.	Yes

The response object looks like this:

{
    "success": <bool>
}

Get character

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Character",
  "action":"Get",
  "playerID":<playerID>,
  "characterID":<characterID>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Character"	Yes
action	string	Set to "Get"	Yes
playerID	string	Set this ID to any player in your game	Yes
characterID	string	The character ID of the character you want to get	Yes

The response object looks like this:

{
    "success": <bool>,
    "character": {
        "characterID": "<int>",
        "playerID": "<int>",
        "characterAvatar": "<string>",
        "characterName": "<string>",
        "characterNameExtra": "<string>",
        "created": "<datetime>"
    }
}

List characters

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Character",
  "action":"List",
  "playerID":<playerID>,
  "limit":<number>,
  "page":<number>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Character"	Yes
action	string	Set to "List"	Yes
playerID	string	Set this ID to any player in your game to get all his characters	Yes
limit	number	Limits the number of records returned	No
page	number	When you use limit you can use this parameter to get the next page of records	Yes

The response object looks like this:

{
    "success": <bool>,
    "characterList": [
        {
            "characterID": "<int>",
            "playerID": "<int>",
            "characterAvatar": "<string>",
            "characterName": "<string>",
            "characterNameExtra": "<string>",
            "created": "<datetime>"
        },
        ...
    ]
}

Count characters

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Character",
  "action":"Count",
  "playerID":<playerID>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Character"	Yes
action	string	Set to "Count"	Yes
playerID	string	Set this ID to any player in your game to get all his characters	Yes

The response object looks like this:

{
    "success": true,
    "listCount": "<int>"
}

Cloud Data

Cloud data is a key-value store to store player, character, and even app data.

For player data, the player can write and read to his data by default and can be read by other players of the same app.
You can change this behavior with the privacy field.
Each player can also create specific character data. So you can store character abilities or levels for each character as an example.

App data are key values that can be read by all players and characters.
You can use this to store texts or game settings that need to be synchronized to all players without republishing your game.
We strongly advise using the Cloudonaut dashboard to fill-in app data and only retrieve the app data with the API in your game/app or website. In this case, the default privacy setting is set to read-only for players. Using the API to write app data means you are writing data as a player. The privacy setting will be set as read and writable for all players.
We do not recommend this. Use it with care if you have an edge case for this.

Set application data

This will modify an existing key that can be read or written to by all players.
Normally you will not use this function because this will modify a key-value pair on the application level.
But if you have an edge case, please continue.

To create application key's you need to use the cloudonaut dashboard! We will not allow the creation of application level data from this SDK.

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"CloudData",
  "action":"SetAppData",
  "dataKey":<string>,
  "value":<string/json>,
  "privacy":<int>,
  "writeLock":<int>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "CloudData"	Yes
action	string	Set to "SetAppData"	Yes
dataKey	string	Provide the key of the key/value pair	Yes
value	string	Provide a string or json data	Yes
writeLock	int	To write to AppData you need the correct writeLock to prevent data overwrites more info	Yes

The response object looks like this:

{
    "success": <bool>
}

Get application data

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"CloudData",
  "action":"GetAppData",
  "dataKey":<string>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "CloudData"	Yes
action	string	Set to "GetAppData"	Yes
dataKey	string	Provide the key of the key/value pair	Yes

The response object looks like this:

{
    "success": <bool>,
    "cloudData": {
        "dataKey": "<string>",
        "value": "<string>",
        "writeLock": "<int>",
        "created": "<datetime>",
        "modified": "<datetime>"
    }
}

Set Player data

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"CloudData",
  "action":"SetPlayerData",
  "playerID":<int>,
  "playerSecret":<Token>,
  "characterID":<int>,
  "dataKey":<string>,
  "value":<string/json>,
  "privacy":<int>,
  "writeLock":<int>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "CloudData"	Yes
action	string	Set to "SetPlayerData"	Yes
playerID	string	Set this ID to match the currently logged in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player	Yes
characterID	string	The character ID if you want to bind this key to a specific character. Leave empty or 0 to bind the key to the player ID	No
dataKey	string	Provide the key of the key/value pair	Yes
value	string	Provide a string or json data	Yes
privacy	int	0=Everybody can read and write, 1=Everybody can read and only the logged on player can write, 2=Only the logged on player can read and write more info	Yes
writeLock	int	For player data this is optional. Used to prevent data overwrites more info	No

The response object looks like this:

{
    "success":<bool>,
    "inserted":<bool>
}

If inserted is true, it means that the key did not exist and is inserted.

Get Player data

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"CloudData",
  "action":"GetPlayerData",
  "playerID":<int>,
  "playerSecret":<Token>,
  "characterID":<int>,
  "dataKey":<string>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "CloudData"	Yes
action	string	Set to "GetPlayerData"	Yes
playerID	string	Set this ID to match the currently logged in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player	Yes
characterID	string	The character ID if you want to get the data of a specific character. Leave empty or 0 to get the data of the player	No
dataKey	string	Provide the key of the key/value pair	Yes

The response object looks like this:

{
    "success": <bool>,
    "cloudData": {
        "playerID": "<int>",
        "characterID": "<int>",
        "dataKey": "<string>",
        "value": "<string>",
        "writeLock": "<int>",
        "created": "<datetime>",
        "modified": "<datetime>"
    }
}

Get Player data by ID

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"CloudData",
  "action":"GetPlayerDataByID",
  "playerID":<int>,
  "characterID":<int>,
  "dataKey":<string>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "CloudData"	Yes
action	string	Set to "GetPlayerDataByID"	Yes
playerID	string	Set this to match the player ID you want to get data from	Yes
characterID	string	The character ID if you want to get the data of a specific character. Leave empty or 0 to get the data of the player	No
dataKey	string	Provide the key of the key/value pair	Yes

The response object looks like this:

{
    "success": <bool>,
    "cloudData": {
        "playerID": "<int>",
        "characterID": "<int>",
        "dataKey": "<string>",
        "value": "<string>",
        "writeLock": "<int>",
        "created": "<datetime>",
        "modified": "<datetime>"
    }
}

Friends

Players can add each other as friends.
We do not prevent users from becoming friends. Becoming friends is never 2 ways.
Each player can add his friends. So if player A adds player B as a friend. Player A can see player B's score on the friend's leaderboard. Player A on the other hand does not see player B. Player A needs to add player B as a friend.
This way we do not use friend requests and approves because we do not share private data between players.

Add friend

Add a friend to the logged-in players friend list.

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Friends",
  "action":"Add",
  "playerID":<int>,
  "playerSecret":<Token>,
  "friendID": <int>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Friends"	Yes
action	string	Set to "Add"	Yes
playerID	string	Set this ID to match the currently logged in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player	Yes
friendID	int	Provide the playerID of the player to add as a friend	Yes

The response object looks like this:

{
    "success":<bool>
}

Remove friend

Remove a friend from the players friend list.

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Friends",
  "action":"Remove",
  "playerID":<int>,
  "playerSecret":<Token>,
  "friendID": <int>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Friends"	Yes
action	string	Set to "Remove"	Yes
playerID	string	Set this ID to match the currently logged in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player	Yes
friendID	int	Provide the playerID of the player to remove from the friends list	Yes

The response object looks like this:

{
    "success":<bool>
}

Add friends from facebook

Provide a list containing the facebook UID of the facebook friends of the logged-in player.
This only works if the player is authenticated with Facebook or Firebases Facebook implementation.
You can get this list with the Facebook API if you ask for the friends permission.
Facebook needs to review your app before you can use the friends permission.

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Friends",
  "action":"AddFacebookFriends",
  "playerID":<int>,
  "playerSecret":<Token>,
  "friendList":[<Array of facebook UIDs>]
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Friends"	Yes
action	string	Set to "AddFacebookFriends"	Yes
playerID	string	Set this ID to match the currently logged in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player (For facebook or firebase it matches the token)	Yes
friendList	array	A array of facebook UID's. You can get these from the facebooks friends API.	Yes

The response object looks like this:

{
    "success":<bool>
}

List friends

Get a list of all the friends of the logged-in player.

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Friends",
  "action":"List",
  "playerID":<int>,
  "playerSecret":<Token>,
  "limit":<number>,
  "page":<number>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Friends"	Yes
action	string	Set to "List"	Yes
playerID	string	Set this ID to match the currently logged in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player	Yes
limit	number	Limits the number of records returned	No
page	number	When you use limit you can use this parameter to get the next page of records	Yes

The response object looks like this:

{
    "success":<bool>,
    "friendList": [
        "<friends player ID>",
          ...
    ]
}

Count

Returns the number of friends of the logged-in player.

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Friends",
  "action":"Count",
  "playerID":<int>,
  "playerSecret":<Token>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Friends"	Yes
action	string	Set to "List"	Yes
playerID	string	Set this ID to match the currently logged in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player	Yes

The response object looks like this:

{
    "success":<bool>,
    "listCount":<int>
}

Player Profile

Each player has a player profile. Scores, characters, Cloud data and friends are linked to a player profile.
You can see the player profile as character number zero. If a player only has a single profile in your game then you do not need to use characters.

Update Player Profile

Updates a character of the currently logged-in player.

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"PlayerProfile",
  "action":"Update",
  "playerID":<playerID>,
  "playerSecret":<Token>,
  "displayName": <The name of the player or empty to leave as is>,
  "displayNameExtra": <Aditional name for the player or empty to leave as is>,
  "avatar": <Link to avatar or empty to leave as is>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "PlayerProfile"	Yes
action	string	Set to "Update"	Yes
playerID	string	Set this ID to match the currently logged in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player (For facebook or firebase it matches the token)	Yes
displayName	string	Leave empty to keep the name as is	Yes
displayNameExtra	string	A extra addition to the name. Leave empty to keep it as is	Yes
avatar	string	Provide this field with any text you want to identify a avatar. You can add a link here, a name of a asset in the game you use for players etc.. It is up to you to use this code and display a Avatar.	Yes

The response object looks like this:

{
    "success":<bool>
}

Get Player Profile

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"PlayerProfile",
  "action":"Get",
  "playerID":<playerID>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "PlayerProfile"	Yes
action	string	Set to "Get"	Yes
playerID	string	Set this field to the ID of the player from who you want to get the player profile	Yes

The response object looks like this:

{
    "success":<bool>,
    "playerProfile": {
        "playerID": "<int>",
        "displayName": "<string>",
        "displayNameExtra": "<string>",
        "avatar": "<string>"
    }
}

List Player Profiles

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"PlayerProfile",
  "action":"List",
  "playerList":[<Array of playerIDs>],
  "limit":<number>,
  "page":<number>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "PlayerProfile"	Yes
action	string	Set to "List"	Yes
playerList	array	Get the player profiles of a list of playerIDs	Yes
limit	number	Limits the number of records returned	No
page	number	When you use limit you can use this parameter to get the next page of records	Yes

The response object looks like this:

{
    "success":<bool>,
    "playerProfileList": [
      {
        "playerID": "<int>",
        "displayName": "<string>",
        "displayNameExtra": "<string>",
        "avatar": "<string>"
      },
      ...
    ]
}

Search Player Profiles

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"PlayerProfile",
  "action":"Search",
  "search":<string>,
  "limit":<number>,
  "page":<number>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "PlayerProfile"	Yes
action	string	Set to "Search"	Yes
search	string	string that contains part of the player name, name extra or the full playerID	Yes
limit	number	Limits the number of records returned	No
page	number	When you use limit you can use this parameter to get the next page of records	Yes

The response object looks like this:

{
    "success":<bool>,
    "playerProfileList": [
      {
        "playerID": "<int>",
        "displayName": "<string>",
        "displayNameExtra": "<string>",
        "avatar": "<string>"
      },
      ...
    ]
}

Score / Leaderboard

The leaderboard and scores service manage a huge list of posted scores to the backend per App.
We have build a verry flexible way on how to get this leaderboard back from the server.
This way you can build daily boards, monthly boards, high scores, lowest score first etc...

Each app can also contain multiple leaderboards and multiple levels.
A leaderboard conntains an ID and a level parameter so that each app can contain multiple leaderboards (Different game modes is a great example for using multiple leaderboard ID's) and multiple levels (The same leanderboard ID is used but for every level you increase the level proprery).

Ranking

You can configure a function and a sort order on how to calculate which score is the best score.
The default function and sort order are MAX and DESC. (Higher is better)

Here are some common use scenarios.

Function	Sort	Description	Extra
MAX	DESC	Gets the highest score and ranks from high to low	If the function is MAX the sort will default to DESC
MIN	ASC	Gets the lowest score and ranks from low to hight	If the function is MIN the sort will default to ASC
AVG	DESC	Gets the avarage score and ranks from high to low	For AVG the default sort is DESC

There are 2 more functions that can be used:

Function	Description	Use case example
COUNT	Counts the number of scores the player / character has submitted	Most effort in the game/app
SUM	Sums up the scores of each player / character	Most effort combined with high scores.

For each function you can swap the sort order. So if you want the avarage score of each player but sorted lowest first you can do:

Function	Sort
AVG	ASC

Periodicity

All scores are timestampt in the background. That makes it posible to get scores using time frames.
You can do this by using a start and end date or a Periodicity parameter.

Please not that you can't combine start, end date with the periodicity parameter. The periodicity parameter will win over the start, end date.

When using this time frame the function and sort will be applied to all scores in this time range. This way you can create daily boards for example.

The start and end date should be in YYYY-mm-dd hh:mm:ss (24 hour) format.
Example:
2021-01-05 13:30:00
For the fifth of januari 2021 at half past one in the afternoon. (This is always server time).

To make things easier for more common use cases you can use the periodicity parameter.

Value	Description
DAILY	All the scores of past 24 hours
WEEKLY	All the scores of the past 7 days
MONTHLY	All the scores of the past month

List Scores

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Leaderboard",
  "action":"List",
  "leaderboardID": <int>,
  "level": <int>,
  "function": <string>,
  "sort": <string>,
  "startDate": <datetime>,
  "endDate": <datetime>,
  "periodicity": <string>,
  "limit": <int>,
  "page": <int>,
  "playerID": <int>,
  "characterID": <int>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Leaderboard"	Yes
action	string	Set to "List"	Yes
leaderboardID	int	The ID of the leaderboard.	Yes
level	int	Used when you splitted the leaderboard using levels.	No
function	string	Choose a function to calculate the ranking more info	No
sort	string	Sort the ranking Ascending or Descending more info	No
startDate	datetime	The startDate should be in YYYY-mm-dd hh:mm:ss (24 hour) format. more info	No
endDate	datetime	The endDate should be in YYYY-mm-dd hh:mm:ss (24 hour) format. more info	No
periodicity	string	DAILY, WEEKLY or MONTHLY more info	No
limit	number	Limits the number of records returned	No
page	number	When you use limit you can use this parameter to get the next page of records	No
playerID	string	Set this ID to get a scoreboard arround this player	No
characterID	string	Set this ID to get a scoreboard arround this character	No

The response object looks like this:

{
    "success":<bool>,
    "limit": <int>,
    "leaderboard": [
        {
            "playerID": "<int>",
            "displayName": "<string>",
            "displayNameExtra": "<string>",
            "avatar": "<string>",
            "providerUID": "<string>",
            "provider": "<int>",
            "characterID": "<int>",
            "characterName": "<string>",
            "characterNameExtra": "<string>",
            "characterAvatar": "<string>",
            "score": "<double>",
            "rank": "<int>",
            "rowNumber": "<int>"
        },
      ...
    ]
}

The difference between rank and rowNumber is that when 2 users have the same score. They share the same rank but have a different rowNumber.
The providerUID will be empty for anonymous users.

Count Scores

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Leaderboard",
  "action":"Count",
  "leaderboardID": <int>,
  "level": <int>,
  "function": <string>,
  "sort": <string>,
  "startDate": <datetime>,
  "endDate": <datetime>,
  "periodicity": <string>,
  "playerID": <int>,
  "characterID": <int>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Leaderboard"	Yes
action	string	Set to "Count"	Yes
leaderboardID	int	The ID of the leaderboard.	Yes
level	int	Used when you splitted the leaderboard using levels.	No
function	string	Choose a function to calculate the ranking more info	No
sort	string	Sort the ranking Ascending or Descending more info	No
startDate	datetime	The startDate should be in YYYY-mm-dd hh:mm:ss (24 hour) format. more info	No
endDate	datetime	The endDate should be in YYYY-mm-dd hh:mm:ss (24 hour) format. more info	No
periodicity	string	DAILY, WEEKLY or MONTHLY more info	No
playerID	string	Set this ID to get a scoreboard arround this player	No
characterID	string	Set this ID to get a scoreboard arround this character	No

The response object looks like this:

{
    "success":<bool>,
    "listCount":<int>
}

List Friends Scores

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Leaderboard",
  "action":"ListFriends",
  "playerID": <int>,
  "playerSecret": <Token>,
  "leaderboardID": <int>,
  "level": <int>,
  "function": <string>,
  "sort": <string>,
  "startDate": <datetime>,
  "endDate": <datetime>,
  "periodicity": <string>,
  "limit": <int>,
  "page": <int>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Leaderboard"	Yes
action	string	Set to "ListFriends"	Yes
playerID	string	The logged-in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player	Yes
leaderboardID	int	The ID of the leaderboard.	Yes
level	int	Used when you splitted the leaderboard using levels.	No
function	string	Choose a function to calculate the ranking more info	No
sort	string	Sort the ranking Ascending or Descending more info	No
startDate	datetime	The startDate should be in YYYY-mm-dd hh:mm:ss (24 hour) format. more info	No
endDate	datetime	The endDate should be in YYYY-mm-dd hh:mm:ss (24 hour) format. more info	No
periodicity	string	DAILY, WEEKLY or MONTHLY more info	No
limit	number	Limits the number of records returned	No
page	number	When you use limit you can use this parameter to get the next page of records	No

The response object looks like this:

{
    "success":<bool>,
    "limit": <int>,
    "leaderboard": [
        {
            "playerID": "<int>",
            "displayName": "<string>",
            "displayNameExtra": "<string>",
            "avatar": "<string>",
            "providerUID": "<string>",
            "provider": "<int>",
            "characterID": "<int>",
            "characterName": "<string>",
            "characterNameExtra": "<string>",
            "characterAvatar": "<string>",
            "score": "<double>",
            "rank": "<int>",
            "rowNumber": "<int>"
        },
      ...
    ]
}

The difference between rank and rowNumber is that when 2 users have the same score. They share the same rank but have a different rowNumber.
The providerUID will be empty for anonymous users.

Count Friends Scores

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Leaderboard",
  "action":"ListFriends",
  "playerID": <int>,
  "playerSecret": <Token>,
  "leaderboardID": <int>,
  "level": <int>,
  "function": <string>,
  "sort": <string>,
  "startDate": <datetime>,
  "endDate": <datetime>,
  "periodicity": <string>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Leaderboard"	Yes
action	string	Set to "CountFriends"	Yes
playerID	string	The logged-in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player	Yes
leaderboardID	int	The ID of the leaderboard.	Yes
level	int	Used when you splitted the leaderboard using levels.	No
function	string	Choose a function to calculate the ranking more info	No
sort	string	Sort the ranking Ascending or Descending more info	No
startDate	datetime	The startDate should be in YYYY-mm-dd hh:mm:ss (24 hour) format. more info	No
endDate	datetime	The endDate should be in YYYY-mm-dd hh:mm:ss (24 hour) format. more info	No
periodicity	string	DAILY, WEEKLY or MONTHLY more info	No

The response object looks like this:

{
    "success":<bool>,
    "listCount":<int>
}

Get Score

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Leaderboard",
  "action":"Get",
  "leaderboardID": <int>,
  "level": <int>,
  "function": <string>,
  "sort": <string>,
  "startDate": <datetime>,
  "endDate": <datetime>,
  "periodicity": <string>,
  "playerID": <int>,
  "characterID": <int>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Leaderboard"	Yes
action	string	Set to "Get"	Yes
leaderboardID	int	The ID of the leaderboard.	Yes
level	int	Used when you splitted the leaderboard using levels.	No
function	string	Choose a function to calculate the ranking more info	No
sort	string	Sort the ranking Ascending or Descending more info	No
startDate	datetime	The startDate should be in YYYY-mm-dd hh:mm:ss (24 hour) format. more info	No
endDate	datetime	The endDate should be in YYYY-mm-dd hh:mm:ss (24 hour) format. more info	No
periodicity	string	DAILY, WEEKLY or MONTHLY more info	No
playerID	string	The Id of the player you want the score from	No
characterID	string	The Id of the character you want the score from	No

The response object looks like this:

{
    "success":<bool>,
    "score": "<double>",
    "rank": "<int>"
}

Add Score

POST / HTTP/1.1
Host: https://api01.cloudonaut.com
Content-Type: application/json

{
  "appID":<your appID>,
  "appSecret":<your appSecret>,
  "controller":"Leaderboard",
  "action":"Add",
  "playerID":<int>,
  "playerSecret":<Token>,
  "characterID":<int>,
  "leaderboardID": <int>,
  "level": <int>,
  "score": <decimal>
}

Field	Type	Description	Required
appID	number	The application ID	Yes
appSecret	string	The application secret. Can be blank if you use url's to protect your app	No
controller	string	Set to "Leaderboard"	Yes
action	string	Set to "Add"	Yes
playerID	int	Set this ID to match the currently logged in player ID	Yes
playerSecret	string	The secret can be obtained after you authenticated the player	Yes
characterID	int	The character ID if you want to post a score of a certain player character. Leave empty or 0 to post the score for the player	No
leaderboardID	int	The ID of the leaderboard.	Yes
level	int	Used when you splitted the leaderboard using levels.	No
score	decimal	The players score.	Yes

The response object looks like this:

{
    "success":<bool>
}