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 storing high scores to store a high score of a player you can call airconsole storehighscore( ) 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 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 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 airconsole storehighscore("single player", "version 1 0", 14, controller uid); requesting high scores to request high scores from players you can call airconsole requesthighscores( ) airconsole requesthighscores( ) this will invoke airconsole onhighscores 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"] \["world", "country", "region", "city", "friends", "partner"] an example response in onhighscores would look like this \[ { "data" { "time" 25, "points" 14 }, "level name" "single player", "level version" "version 1 0", "location country code" "ch", "location country name" "switzerland", "location region code" "zh", "location region name" "zurich", "location city name" "zurich city", "nicknames" \["mandrooooo"], "ranks" { "world" 7, "country" 3, "city" 2, "friends" 6 }, "relationship" "facebook", "score" 14 004, "score string" "14 points in 25s", "share image" "https //www airconsole com/games/image/?id=com airconsole games airshields\&highscore=com airconsole games airshields 1 0 1cd34b9bd6a077678441e0e6db5272cb\&ts=1470666148949", "share url" "https //www airconsole com/play/?id=com airconsole games airshields\&highscore=com airconsole games airshields 1 0 1cd34b9bd6a077678441e0e6db5272cb", "timestamp" 1469645461000, "uids" \["1cd34b9bd6a077678441e0e6db5272cb"] }, ] location location fields are not guaranteed to be returned if you are displaying a global high score board, it is probably a good idea to call airconsole requesthighscores airconsole requesthighscores whenever onhighscorestored gets called and the passed argument is not false airconsole onhighscorestored = function(highscore) { if (highscore) { airconsole requesthighscores( ) } } 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) custom high score data 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 custom data can be tampered with make sure your game does not crash, if someone maliciously inserts fake custom data high scores ranks if you request multiple rank types, not all returned high scores will have all requested rank types set for example, if you request rank types \["world", "country"] \["world", "country"] , there can be high scores returned that only has the world world rank set (if they are not from the same country) some entries may only have the country country rank set, because they are not in the world high scores requested high scores can have a rank value of null null , if they are not ranked in that rank type! rendering 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 world , country country , etc if you are using unity, make use of the airconsole/extras/highscorehelper cs class to group high scores into tables the following code snippet does exactly that in javascript feel free to copy and paste it / converts a list of high scores into rank tables @param {array\<airconsole highscore>} highscores @return {object} the returned object is a dictionary of the following format { "world" { "title" "world", "highscores" \[ array of high scores ] }, "country" { "title" "switzerland", "highscores" \[ array of high scores ] }, } / function converthighscorestotables(highscores) { var tables = {}; for (var i = 0; i < highscores length; ++i) { var highscore = highscores\[i]; for (var rank type in highscore\["ranks"]) { if (!tables\[rank type]) { tables\[rank type] = {"highscores" \[]}; if (rank type == "friends") { tables\[rank type]\["title"] = "friends"; } else if (rank type == "world") { tables\[rank type]\["title"] = "world"; } else if (rank type == "country" || rank type == "region" || rank type == "city") { tables\[rank type]\["title"] = highscore\["location " + rank type + " name"]; } } tables\[rank type]\["highscores"] push(highscore); } } return tables; } if you want to render high scores in javascript/html5, you can also use the airconsole high score renderer library sharing high scores each high score has a share url share url and a share image 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 share image property if you want to implement facebook or twitter sharing of a high score you can use the share url share url property if the share url 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 function shareonfacebook(highscore) { airconsole openexternalurl( "https //www facebook com/dialog/share?display=popup&" + "app id=428783770605591\&href=" + escape(highscore share url)); } function shareontwitter(highscore) { airconsole openexternalurl( "http //aircn sl/airshields/?url=" + escape(highscore share url) + "\&redirect=" + escape("https //twitter com/intent/tweet?text=" + "try%20to%20beat%20my%20highscore%20in%20airshields&" + "hashtags=airconsole,airshields\&url=")); } please make sure you call the shareonfacebook shareonfacebook and shareontwitter shareontwitter in 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 team high scores the high score api supports passing an array of controller uids to the airconsole storehighscore( ) airconsole storehighscore( ) method we do not recommend to pass the uid of the screen to airconsole storehighscore( ) for team high scores screens don't have nicknames or profile pictures, the nicknames property, the share image and the share url wont be useful to you use an array of controller uids instead partner specific high scores available on api 1 9 0 or unity plugin 2 5 0 or higher when including "partner" in the ranks array of airconsole requesthighscores( ) airconsole requesthighscores( ) , the received highscores will contain additional information partner the name of the partner of the partner highscore rank ranks partner the rank for the partner { partner "bmw", ranks { partner 1 }, } all highscores automatically contain information on the partner when storing highscores using airconsole storehighscore( ) airconsole storehighscore( ) , if the screen is running on a system that is supported for partner highscore high scores in development mode / production mode 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 if you want to use a prepopulated database of high score ranks for testing purposes, you can specify com airconsole highscore test com airconsole highscore test as the game id in development mode the prepopulated database includes ranks from various countries you can also prepopulate your development database using the high score generator selecting the best ghosts from a list of high scores 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 we recommend that you set the top top parameter to 0 0 and the ranks ranks to \["world", "friends"] \["world", "friends"] when you call airconsole requesthighscores( ) airconsole requesthighscores( ) else you are competing with the worlds best players and your friends will not be included if you are using unity, make use of the airconsole/extras/highscorehelper cs class to select the best ghosts the following javascript code snippet selects the best ghosts for you / given a list of high scores, returns the best high scores for ghost mode preference in order first ghosts with similar scores then sort them by connected players, friends, city, region, country, world if multiple ghosts have the same preference score, random ones are chosen @param {array\<airconsole highscore>} highscores @param {number} count the numnber of ghosts you would like to get @param {number|undefined} min score factor optional minimum score factor a ghost needs to have compared to the best score of a connected player default is 0 75 @param {number|undefined} min score factor optional maximum score factor a ghost can have compared to the best score of a connected player default is 1 5 @return {array\<airconsole highscore>} / function selectbestghosts(highscores, count, min score factor, max score factor) { if (min score factor == undefined) { min score factor = 0 75; } if (max score factor == undefined) { max score factor = 1 5; } var my score = null; var result = \[]; for (var i = 0; i < highscores length; ++i) { var highscore = highscores\[i]; if (highscore\["relationship"] == "requested") { if (my score == null || my score < highscore\["score"]) { my score = highscore\["score"]; } } result push(highscore); } var preference = { "world" 1, "country" 2, "region" 3, "city" 4, "friends" 5, "similar score" 10, "requested" 20 }; var random uid = (math random() 65536) | 0; var random uid char = (math random() 32) | 0; function sortscore(highscore) { var sort score = 0; for (var rank in highscore\["ranks"]) { sort score = math max(sort score, preference\[rank]); } if (my score != null) { if (highscore\["score"] > my score min score factor && highscore\["score"] < my score max score factor) { sort score += preference\["similar score"]; } if (highscore\["relationship"] == "requested") { sort score += preference\["requested"]; } } var uid = highscore\["uids"]\[random uid % highscore\["uids"] length]; sort score += 1 / uid charcodeat(random uid char % uid length); return sort score } result sort(function (a, b) { return sortscore(b) sortscore(a); }); return result slice(0, math min(result length, count)); } checklist before launch high score responses please make sure that your game does not crash in the following cases if a rank rank is not a number but null { "ranks" { "world" null , "country" 3 }, } if location country code location country code or other location location fields are not present { "location country code" "us" } if there is valid json data in the custom highscore data that is malicious (not what you expect) { "data" { "one of your fields" "malicious data" }, } if there is no custom data present at all { "data" "your data" }