Leaderboards

Overview

Leaderboards provide a key retention mechanic for simpler score based games. Instant Games support leaderboards and leaderboard updates besides custom updates.

A leaderboard update in Facebook Messenger.

Example project

Click the button below to download our sample project:

Step 1: Create a Leaderboard

To create a new leaderboard using the developer console, go to the leaderboard sub product under the Instant Games header and fill out the required fields.

Leaderboards are contextual, which means that each Instant Game context will have access to its own distinct instance of the leaderboard. Contextual leaderboards can be updated only from the context they belong to.

The leaderboard creation screen in the developer console.

Step 2: Add Scores to your Leaderboard

To add scores to the leaderboard, use the setScoreAsync method. You can store additional data along with the score itself. Note that for contextual leaderboards, the context must be included in the name of the leaderboard, separated with a dot.

FBInstant
  .getLeaderboardAsync('my_awesome_leaderboard.' + context.getID())
  .then(leaderboard => {
    console.log(leaderboard.getName());
    return leaderboard.setScoreAsync(42, '{race: "elf", level: 3}');
  })
  .then(() => console.log('Score saved'))
  .catch(error => console.error(error));

Step 3: Retrieve Scores from the Leaderboard

You can retrieve scores from the leaderboard using the getEntriesAsync method. This accepts two parameters (a count and an offset) that can be used for pagination.

FBInstant
  .getLeaderboardAsync('my_awesome_leaderboard.' + FBInstant.context.getID())
  .then(leaderboard => leaderboard.getEntriesAsync(10, 0))
  .then(entries => {
    for (var i = 0; i < entries.length; i++) {
      console.log(
        entries[i].getRank() + '. ' +
        entries[i].getPlayer().getName() + ': ' +
        entries[i].getScore()
      );
    }
  }).catch(error => console.error(error));

You can always access the current player's leaderboard entry using getPlayerEntryAsync as follows:

FBInstant
  .getLeaderboardAsync('my_awesome_leaderboard.' + FBInstant.context.getID())
  .then(leaderboard => leaderboard.getPlayerEntryAsync()))
  .then(entry => {
    console.log(
      entries[i].getRank() + '. ' +
      entries[i].getPlayer().getName() + ': ' +
      entries[i].getScore()
    );
  }).catch(error => console.error(error));

Step 4: Post a Leaderboard Update

To post leaderboard updates into a message thread, you can use updateAsync with the LEADERBOARD action as follows:

FBInstant.updateAsync({
  action: 'LEADERBOARD',
  name: 'my_awesome_leaderboard.' + FBInstant.context.getID()
})
  .then(() => console.log('Update Posted'))
  .catch(error => console.error(error));

An update will appear at the end of the game session as follows:

A leaderboard update in Facebook Messenger.