User Data API

Platogo enables game developers to save and load user-specific data for each of their games. In the following paragraphs we'll talk about User Data and how it might be used in games.

User Data vs. cookies

You can think of User Data as being similar to regular HTTP cookies. The main difference and major benefit of User Data is that it is linked to the user's Platogo account. No matter on which computer the user plays a game – whether at school, work or at home – as long as the user is logged in at Platogo, his or her User Data for the game currently being played can be accessed. Furthermore, User Data are not lost if the user decides to clear the cache.

Example usage

There are a lot of different use cases for User Data:

• save game progress (e.g. save game functionality)
• remember user preferences (e.g. user likes the sound to be turned off)
• track statistics (e.g. how often something has happened across all game plays of the user)

These are just some examples to give you an idea on how User Data might be useful for your game. Maybe there are other applications for User Data in your particular game – use this functionality however you see fit.

Saving User Data

There's a single function for saving User Data and it can be found in the User Service (every function that has to communicate with the server is put inside a service class.) Using PlatogoAPI.userService.saveCurrentUserData() you are able to save an infinite number of key/value pairs for the current user. The key as well as the value has to be of the type String and must not be longer than 256 characters. Values other than Strings have to be converted to a String first (e.g. by using toString() on a Number.)

The following example demonstrates how to save the string "Example Data" under the key "exampleKey". Once it's done we retrieve the User Data again to print it to them console output:

PlatogoAPI.userService.saveCurrentUserData( "exampleKey", "Example Data", saveUserDataHandler );

function saveUserDataHandler( response : PlatogoResponse ) : void
{
	switch( response.status )
	{
		case PlatogoStatus.OK:
			trace( "The user was logged in and the data has been successfully saved." );
			trace( PlatogoAPI.currentUser.getData( "Example Key" ) ); // "Example Data"
			break;

		case PlatogoStatus.NOT_LOGGED_IN:
			trace( "The user was not logged and user data is not saved." );
			trace( PlatogoAPI.currentUser.getData( "Example Key" ) ); // null
			break;

 		case PlatogoStatus.ERROR:
			trace( "Something went wrong. This should never happen." );
			trace( PlatogoAPI.currentUser.getData( "Example Key" ) ); // null if user is not logged in & no value was successfully associated before
			break;
    }
}

You don't necessarily have to handle the response: however, it is good practice to check if everything has worked correctly. Furthermore, the data are only guaranteed to be safely accessible after PlatogoAPI.userService.saveCurrentUserData() is finished and has invoked the callback handler. If you decide to ignore the response you can pass null as the last parameter which reduces the example above to a single line:

PlatogoAPI.userService.saveCurrentUserData( "exampleKey", "Example Data", null );

Retrieving User Data

As soon as the game connects to Platogo, the current user and relevant User Data are passed to the game. Saved User Data can be accessed by calling PlatogoAPI.currentUser.getData(). Values are always stored as Strings – if you converted a Number to a String when saving the User Data you have to parse the String value back to a Number again when retrieving the User Data (e.g. by using parseFloat() or parseInt().)

The following example shows how to access previously saved User Data:

PlatogoAPI.currentUser.getData( "exampleKey" ); // "Example Data" if the data has been set using the example above

This work is licensed under a Creative Commons License.