High Score API

In this article we'll show you how easy it is to integrate Platogo high scores into your games. Platogo tracks the all-time best scores, as well as the best scores in daily, weekly and monthly intervals for your games. Submitting scores is restricted to logged in users, and only the best score of each user is taken into account.

Game settings

Before scores can be submitted, one or more scoreboards have to be added to your game. To do so, use the Edit Game page in your developer dashboard. Under the menu item Highscores you can add new scoreboards or edit existing ones. As long as the game has not yet been published, you can also delete scoreboards. But be careful, as all scoreboard entries will be gone too. Score entries can be deliberately cleared on the page if the need arises (this also only works as long as the game has not been published.)

Scoreboard definition

A game scoreboard has the following properties:

• name
• key
• label
• type
• sort order

The name is the title of your scoreboard and is displayed in the scoreboard section of the game page on Platogo.

Each game scoreboard is uniquely identified by its key property. When submitting a score value, you address the desired scoreboard 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 track the number of puzzles a user has solved so far and so decided upon the key "puzzlesSolved".

A scoreboard's label puts the score value into context. On the website, it is displayed above the score value column. If a scoreboard is being used to track the number of gems collected, an appropriate description could be "Number of Gems collected". In our Picross example, we decided upon "Puzzles solved".

The values in Platogo high scores can be interpreted as either number values or as time values. Numbers are simply signed integer values. Time values, on the other hand, are submitted in milliseconds and formatted as a time string on the website (60000 milliseconds become 1:00.) Furthermore, the values can be submitted as either relative or absolute values. Absolute values overwrite the existing value of a user in the scoreboard table as long as the new value is better than the existing one. If the scoreboard is set to relative, each submitted score value is added to the existing one. This behaviour is depicted by the type property.

With sort order you can specify whether bigger values are better or worse.

All these properties can be retrieved at runtime using PlatogoAPI.gameInformation.getGameScoreboardDefinition( scoreboardKey ) and PlatogoAPI.gameInformation.levelScoreboardDefinition respectively.

Game scoreboards vs Level scoreboards

You can create up to 10 scoreboards in your game with the properties described above (please tell us if you need more scoreboards – we're considering raising the limit.)

Platogo also provides a Content API that allows users to create levels in your games. In addition to the game scoreboards, you can specify a level scoreboard for keeping track of scores for each individual level. Although each level has its own scoreboard, they all share the same definition. Since there can only be one scoreboard per level, a level scoreboard does not have name & key properties. The other properties stay the same and work as expected.

Game and level scoreboards can peacefully co-exist, and it is often useful to use them in tandem. For example, in our game Picross, we use the level scoreboard to track the times that users have taken to solve a puzzle. We also have a separate game scoreboard that shows the users who have solved the most puzzles so far.

Submitting scores

We've tried making the API as simple as possible while still keeping it powerful enough to use it in interesting ways. Most score communication can be achieved by writing a single line of code. Full documentation for all functions of the score service can be found in the High Score API documentation.

Submitting game scores

The following code shows how to submit a score of "123456" for the user currently playing to a game scoreboard with the key "exampleScoreboard".

PlatogoAPI.highscoreService.submitGameScore( "exampleScoreboard", 123456, submitGameScoreHandler );

function submitGameScoreHandler( response : PlatogoResponse ) : void
{
    switch( response.status )
 	{
        case PlatogoStatus.OK:
            trace( "The user was logged in and the score has been successfully submitted." );
            break;

        case PlatogoStatus.NOT_LOGGED_IN:
            trace( "The user was not logged in, therefore no score has been submitted." );
            break;

        case PlatogoStatus.ERROR:
            trace( "Something went wrong. This should never happen." );
            break;
    }
}

While we encourage you to check and react upon the response of service calls, you might get away with a fire-and-forget approach. If you drop the callback function, the scores will be submitted anyway; in case something goes wrong (maybe the user is not logged in) you simply won't notice. It's not the clean way to handle these things but, for high scores and achievements, we sometimes also do it the easy way (psst, just don't tell anyone!) If you decide to live dangerously, the code is reduced to a single line:

PlatogoAPI.highscoreService.submitGameScore( "exampleScoreboard", 123456 );

Submitting level score

Submitting a level score works like submitting a game score but, instead of providing a scoreboard key, you have to pass an instance of the Level interface implementation:

PlatogoAPI.highscoreService.submitLevelScore( level, 123456 );

Read the Content API article or look at LevelService for more information about levels.

Displaying scores

We provide detailed examples on how to display the entries of game or level scoreboards in the API documentation. You can find them under PlatogoAPI.highscoreService.getGameScoreTable() and PlatogoAPI.highscoreService.getLevelScoreTable() respectively.

Since displaying scores can be a bit of a pain – switching between all-time, monthly, weekly & daily scores, displaying avatars, paging the results and more – we created a component that takes care of all the hard work. It requires no code whatsoever and can easily be skinned to make it match the look and feel of your game. The component is open source and is an ideal starting point for your own implementation if the need ever arises.

To display a game scoreboard, you simply have to drop the component onto the stage and use the component inspector to set the key of the desired scoreboard. The rest is done automatically by the component. More information on the component can be found in our Components article.

Game Scoreboards 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 (game) scoreboards of a game. That way, a user will always see the ranking of his friends at a glance. Ambitious gamers can also switch to view the global highscore.

So there isn't a need for you to display a custom scorboard the game as this is conveniently handeled by our wrapper. But of course you can still do so, if you want to.

Things to consider before publishing

Score clearing

At the point of publishing, all score entries will be deleted to even the odds for everyone. Please note that the entries of all game and level scoreboards will be removed as well.

Before publishing you could remove game scoreboards and clear the scores of each scoreboard yourself. This functionality is locked as soon as the game has been published to prevent developers from making changes that would be unfair to users that already have a high score. If you ever run into a problem with the high scores, just contact us and we'll help you sort things out.

Prevent cheating

Unfortunately there are lots of ways users can try to cheat in Flash games. We're trying our best to keep the bad guys out by implementing strict security measures behind the scenes. However, some things are beyond our control. One possible vulnerability is memory inspection, which basically means that the attacker is peeking into your game while it is being played. When he finds something of interest like the number of lives left or the current score he can change this value in his favor.

Don't worry though, we're here to help you. The Platogo API provides DataVault, a helper class that encrypts your important values, thereby making them hard to find by memory inspectors. It is easy to use: simply store a value with PlatogoAPI.dataVault.setValue() and access it with PlatogoAPI.dataVault.getValue(). We highly recommend that you make use of DataVault.

This work is licensed under a Creative Commons License.