Achievement API

In this article we'll help you to quickly get up and running with Platogo Achievements. Achievements are a way to reward users for completing game-specific challenges. Once a user has been awarded an achievement, it is proudly displayed on his or her user profile (and in the Social Bar) and Achievement Points are added to the user's gaming score. Achievements can only be awarded to logged in users.

Game settings

Before they can be awarded, one or more achievements have to be added to your game. To do so, go to the Edit Game page in your developer dashboard. You can add new achievements or edit existing ones under the menu item Achievements. A game can have up to 10 achievements. As long as the game has not yet been published, you can also delete achievements.

Achievement definition

An achievement has the following properties:

• name
• key
• points
• image
• description

The name is the name of the achievement (this is hopefully pretty self-explanatory.)

Each achievement is uniquely identified by its key property. When awarding an achievement, you address the desired achievement in your code via its key. You can choose the key yourself to make sure it is meaningful and memorable for you. For example, in Picross we award the achievement "Puzzle Beginner" when the user solves his or her first puzzle and so decided upon the key "puzzleBeginner".

An achievement is worth a certain amount of points. It is up to you to decide how many points you'd like to assign when the achievement is awarded: however, the sum of the points of all achievements in your game may not surpass 100. You may also create achievements that have no points at all: this might be used to penalize users for being exceptionally bad or doing something extremely stupid (think of it as a negative achievement.)

An achievement can have an icon, and we encourage you to upload an image for each achievement as this makes them easily recognizable on the user profile.

The description is a short text that should explain what the user needs to do in order to be awarded the achievement.

All these properties can be retrieved at runtime using PlatogoAPI.gameInformation.getAchievement( achievementKey ).

Awarding achievements

Rewarding the user with an achievement is a simple process that requires the calling of only one function:

PlatogoAPI.achievementService.awardAchievement( "exampleAchievement", awardAchievementHandler );

function awardAchievementHandler( response : PlatogoResponse ) : void
{
	switch( response.status )
	{
		case PlatogoStatus.OK:
			trace( "The user was logged in and has been successfully awarded the achievement." );
			trace( PlatogoAPI.currentUser.hasAchievement( "exampleAchievement" ) ); // true
			break;

		case PlatogoStatus.NOT_LOGGED_IN:
			trace( "The user was not logged and the achievement has not been awarded." );
			trace( PlatogoAPI.currentUser.hasAchievement( "exampleAchievement" ) ); // false
			break;

		case PlatogoStatus.ERROR:
			trace( "Something went wrong. This should never happen." );
			trace( PlatogoAPI.currentUser.hasAchievement( "exampleAchievement" ) ); // false
			break;
	}
}

As ever, it is not mandatory to provide a callback handler for the function (although it is good form.) Beware, you're living on the edge here since you won't notice any errors:

PlatogoAPI.achievementService.awardAchievement( "exampleAchievement" );

Check for awarded achievement

The following example shows how to check if the user currently playing has already been awarded the "exampleAchievement":

PlatogoAPI.currentUser.hasAchievement( "exampleAchievement" ); // returns true if the specified achievement has been awarded; false otherwise

Achievements in the Social Bar

On Platogo and its partner sites the games are embedded using our Platogo Wrapper. Among other things, it automatically displays all available achievements of a game in a seperate tab. It also shows, which achievements have already been awarded to the current user and his friends. A user can even show off his achievements by posting them to his own wall.

Things to consider before publishing

Adding, editing or removing achievements

At the point of publishing, existing achievements can no longer be removed. Also, the points awarded for the achievements may not be changed: we do not want to allow the changing of achievements that may have already been awarded to users. Developers can add additional achievements as long as the sum of the points of all achievements does not surpass 100.

Deciding upon achievement points

Although you have 100 points with which to reward achievements, it might not always be wise to use them all right away. Be thrifty with the points and distribute them according to the difficulty of the task required to get the achievement. Take a look at what other developers are doing and see how many points they award for their achievements.

If you don't use up all achievement points before publishing your game, you'll still have points left that can be used to add achievements later: maybe if you upload a new version of your game where a new achievement would be appropriate, or if you get suggestions from users for cool achievements. Either way, once a game is published the points of the existing achievements cannot be changed and, by using all points beforehand, you'd be stuck with the initial achievements.

This work is licensed under a Creative Commons License.