Facebook Instant Games Leaderboards

We've covered creating a Leaderboard and saving a score to it. Now it's time to get the entries in a leaderboard, ready for displaying them in our game.

When you create a Leaderboard instance it will automatically populate the entryCount property. This contains the total number of entries in your leaderboard.

To retrieve the scores you need to call the getScores method on the Leaderboard instance. First, we create our leaderboard instance, then we can get the scores from it:

this.facebook.on('getleaderboard', function (leaderboard)
{
    this.leaderboard = leaderboard;

    this.leaderboard.on('getscores', function (scores)
    {
        console.log(scores);

    }, this);

    this.leaderboard.getScores();

}, this);

this.facebook.getLeaderboard('globalscores');

In the above code we create a handler for the getleaderboard event. When this handler is invoked we can create store the leaderboard instance locally, and call getScores on it. Calling that will, in turn, invoke the getscores event handler, upon which we can finally inspect the scores.

The event is passed an array of LeaderboardScore objects. You saw these in the previous part of this tutorial. They are stored in the array in rank order:

0: {
    score: 2650
    scoreFormatted: 2650
    timestamp: 1542029852
    rank: 1
    data: 
    playerName: Richard
    playerPhotoURL: https://platform-lookaside.fbsbx.com/platform/instantgames/profile_pic.jpg?igpid=XXXXXXXXXXXXXXXX&height=256&width=256&ext=XXXXXXXXXX&hash=XXXXXXXXXXXXXXXX
    playerID: XXXXXXXXXXXXXXXX
},
1: {
    score: 2250
    scoreFormatted: 2250
    timestamp: 1542029342
    rank: 2
    data: 
    playerName: Akira
    playerPhotoURL: https://platform-lookaside.fbsbx.com/platform/instantgames/profile_pic.jpg?igpid=XXXXXXXXXXXXXXXX&height=256&width=256&ext=XXXXXXXXXX&hash=XXXXXXXXXXXXXXXX
    playerID: XXXXXXXXXXXXXXXX
},
2: {
    score: 1123
    scoreFormatted: 1123
    timestamp: 1565028572
    rank: 3
    data: 
    playerName: Hashi
    playerPhotoURL: https://platform-lookaside.fbsbx.com/platform/instantgames/profile_pic.jpg?igpid=XXXXXXXXXXXXXXXX&height=256&width=256&ext=XXXXXXXXXX&hash=XXXXXXXXXXXXXXXX
    playerID: XXXXXXXXXXXXXXXX
}

You can iterate through the scores array and display the results as required in your game. How you do this will depend entirely on your game style. You may only care about the player's name and score. You may wish to use the URL of the player photo to display their photo next to their high score. Whatever you wish to do, this is the array of data you do it with.

Score Offset

The getScores method accepts two arguments. The first is the number of leaderboard entries to return. There is an API maximum of 100. If you call the method with no arguments, it will default to 10.

The second argument is the offset. This is the offset from the top of the leaderboard to fetch from. Say that your leaderboard had 80 scores in it. Your game displays 10 scores at a time. You show the first list of scores, then they click 'Next' to view the second set - now you need to call getScores again, but this time you pass in 10 as the offset value, because you want to start getting scores from rank 11 onwards:

this.leaderboard.getScores(10, 10);

And for the next 10:

this.leaderboard.getScores(10, 20);

The offset effectively allows you to handle pagination on your leaderboard.

Again, how you use this will depend on the style of your leaderboard in-game. If you've got a vertically scrolling list of scores, then you could get 100 scores back, and as the player starts to scroll down once they hit a certain distance, you could make an API call for the next 100 and add them to a local array used to display them in-game.

You have to be careful about the network rate limit. If you try and perform too many leaderboard requests it's entirely possible the API call will throw a RATE_LIMITED error and not return anything. So, cache data where possible and don't go too crazy when paging through scores.

For the final part, we'll combine score data and text selection to create a retro arcade style highscore system.