High Scores & Ghost Mode

Starting with AirConsole API 1.5 we are supporting global high scores. This allows players to see how good they are compared to their friends and the rest of the world. This also allows you to implement ghost modes (replay's of previous game runs). An example of a global High Score implementation can be found in the game AirShields.

To store a high score of a player you can call airconsole.storeHighScore(...). This will persistently store the high score for a device on the AirConsole servers. All data is public, so make sure you do not include sensitive data.

In this call you can set how high the score was (the higher the better), which device achieved the high score in which level of your game and you can also attach some custom data. airconsole.onHighScoreStored will be called if the score was higher or equal to the last high score of this device with the new high score data for this device.

If you call airconsole.storeHighScore from the Screen, make sure you pass the UID of the controller that achieved the high score, so the high score is associated with the user and not the screen the user is playing on.

It takes roughly 10 minutes before the high score is globally synced. The high score for connected devices however is always up to date.

An example call to store a high score of 14 points for Level "Single Player" (version 1.0) would look like this:

To request high scores from players you can call airconsole.requestHighScores(...)

This will invoke airconsole.onHighScores with at least 8 high scores, including the high scores of the connected devices. You can specify which kind of ranks you want to receive. Possible values are any combination of ["world", "country", "region", "city", "friends", "partner"].

An example response in onHighScores would look like this:

location_* fields are not guaranteed to be returned.

If you are displaying a global high score board, it is probably a good idea to callairconsole.requestHighScoreswhenever onHighScoreStored gets called and the passed argument is not false:

If you don't do this and just display the newly achieved high score, multiple people might have the same rank in your global high score board (e.g. the player just became World #1 and the previous World #1 should now be World #2).

When storing high scores you can also pass custom data. Custom High Score data can be used for many things. For example to store a replay of the game run and implement a ghost mode. Note that when high scores are returned, the last 10 data entries are returned for every high score so you can add some variety to your ghosts. The last entry is the data that corresponds to the achieved score.

Another use case for custom high score data is signing high scores to verify that they are not fake. This works especially well for Unity games, because they are much harder to disassemble than normal html5 games. An example how to sign a high score would be to take the UID of the device and concatenate it with the high score and a secret string and take the hash from the concatenated string and store it in the custom high score data. When retrieving high scores you can then again concatenate the UID, the score and the secret string and check if the hash is equal to the stored hash in the custom data. Of course this is not completely secure, because the secret string also needs to be stored in the client source code, but it makes it much harder for someone to fake a high score.

For example, if you request rank types ["world", "country"], there can be high scores returned that only has the world rank set (if they are not from the same country). Some entries may only have the country rank set, because they are not in the world high scores.

To render the high scores, you probably want to group them by rank type first, so you can have separate tables for World, Country, etc.

The following code snippet does exactly that in javascript. Feel free to copy and paste it.

If you want to render high scores in Javascript/HTML5, you can also use the AirConsole High Score Renderer Library.

Each high score has a share_url and a share_image property. If you want to display the high score for example on the controller, you can just create an <img> tag and set the source to the share_image property.

If you want to implement facebook or twitter sharing of a high score you can use the share_url property. If the share_url is shared on a social network, an image of the High Score will be displayed. When someone clicks on the post, they will be redirected to your games landing page. Here is an example for the controller:

Please make sure you call theshareOnFacebookandshareOnTwitterin an "onclick" handler on the controller, else iOS devices do not open a new window. Also note that we are using the aircn.sl URL shortener service for twitter, because twitter doesn't like long URLs. You can just replace "airshields" with your game name.

The High Score API supports passing an array of controller UIDs to the airconsole.storeHighScore(...) method.



When including "partner" in the ranks array of airconsole.requestHighScores(...), the received highscores will contain additional information:

All highscores automatically contain information on the partner when storing highscores usingairconsole.storeHighScore(...), if the screen is running on a system that is supported for partner highscore.

You can play with the high score API in development mode. Your high scores will be stored separately from the high scores in production. High Score data in production is shared across all production game versions.

The prepopulated database includes ranks from various countries.

You can also prepopulate your development database using the High Score generator.

As mentioned in the Custom Data section, you can use the data parameter to implement Ghost modes.

Obviously it is more fun to play against Ghosts that you know (Friends) and that have about the same skill level.

The following javascript code snippet selects the best ghosts for you: