Welcome to the Facebook Instant Games SDK Tutorials. This series of tutorials covers many aspects of using the Facebook Instant Games SDK.

In this tutorial we will take a look at working with scores and leaderboards using the Facebook Instant Games SDK.

What are Leaderboards?

A leaderboard is a large collection of scores usually sorted by value from highest to lowest or lowest to highest. Each unique score belongs to a unique user. They are a great mechanism for encouraging competitive play between different players.

Facebook Instant Games supports two types of leaderboards:

• Contextual leaderboard – These contain scores that relate to the context in which the player is currently playing in. For example if you have 4 people playing in the same Messenger chat group then the leaderboard will only contain the scores of those players.
• Non-contextual leaderboard – This contains scores for all players that player the game regardless of which context the users play in. You can think of these as global leaderboards.

You can create leaderboards in the Leaderboards section of the Instant Games product in the developer dashboard. Note, when you create a leaderboard you need to decide beforehand if it should be contextual or non-contextual.

Setting Leaderboard Scores

You can set a players leaderboard score by calling setScoreAsync() on a specific leaderboard:
[sourcecode language=”js”]
FBInstant.getLeaderboardAsync(leaderboard_name)
.then(function(leaderboard) {
return leaderboard.setScoreAsync(score, meta_data);
}).then(function(entry) {
// Score set
}).catch(function(error) {
// Error setting score
});
[/sourcecode]
The leaderboard name is whatever name you have specified in the Faceboook developer dashboard. Note that for contextual leaderboards you need to append the context ID onto the leaderboard name to access the correct leaderboard. For example “bestscores.context_id1”.

Also note that when you set the players score you can pass along some meta data (for example the level the player obtained the score) that will be saved with the score, You can retrieve this meta data later when you are displaying your leaderboards.

Getting Leaderboard Scores

You can collect the scores for a leaderboard by calling getEntriesAsync() on a specific leaderboard:
[sourcecode language=”js”]
FBInstant.getLeaderboardAsync(leaderboard_name)
.then(function(leaderboard) {
return leaderboard.getEntriesAsync(count, start);
}).then(function(entries) {
// Score entries are returned in the entries array
}).catch(function(error) {
// Error retrieving scores
});
[/sourcecode]
start specifies the first entry that you are requesting and count the total number of entries you are requesting.

Note that if you want to only return friend scores then call getConnectedPlayerEntriesAsync() instead of getEntriesAsync().

Each returned leaderboard entry has the following functions for querying the entry data:

• getScore() – Returns the entry score
• getFormattedScore() – Returns the entry score, formatted with the score format associated with the leaderboard
• getTimestamp() – Gets the timestamp of when this score was last updated
• getRank() – Returns the scores rank in the leaderboarrd
• getExtraData() – Returns the meta data associated with this score
• getPlayer() – Returns the leaderboard player associated with this score

Its important to note that requesting leaderboard entry data uses bandwidth so you should not request the same leaderboard many times in a short period of time. If you do then your app will be rate limited and blocked from collecting leaderboard data again for a short period of time.

Posting Context Leaderboard Updates

You can post a context leaderboard update to a context to show players the current state of the leaderboard using updateAsync() and the LEADERBOARD action:
[sourcecode language=”js”]
FBInstant.updateAsync({
action: "LEADERBOARD",
name: leaderboard_name
})
.then(function(){
// Posted message successfully
}).catch(function(error) {
// Error posting message
});
[/sourcecode]