Using 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:

Download Leaderboards Demo (.zip)

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.

A contextual leaderboard will be different in each Instant Game context, whereas a non-contextual leaderboard is global. Contextual leaderboards can only be updated from the context they belong to.

The leaderboard creation screen in the developer console.

Leaderboards can also be created using the Graph API using the Leaderboard Create endpoint.

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 as follows:

A leaderboard update in Facebook Messenger.

Resetting Leaderboards

Leaderboards can be reset using the Facebook Graph API.