Instant Games

Social Features: Global Leaderboards

Note that you can always render an arbitrary player's information. That allows you greater flexibility when it comes to leaderboards as you can create your own systems. The following is an old way of using leaderboards in NEZP. We will be providing less support for this going forwards.

Since Zero Permissions games only have access to a persistent identifier for the current player in a game session, but not friends and other players, games will not be able to display leaderboards containing user data and scores directly. Instead, Meta provides a set of leaderboard APIs to store scores for a player so that they can later be used to render the data inside an overlay view.

Developer Site Setup

To start using leaderboards, the Global Leaderboards use case must first be added to the game on the developers site. The following UI will be how leaderboards can be configured:

After creating the leaderboard, you can then pull the leaderboard’s ID. This ID will be used in the different SDK APIs to set scores in the leaderboard and also to render user data inside an overlay view.

SDK API

The Instant Games SDK has four new leaderboard methods:

  • FBInstant.globalLeaderboards.setScoreAsync(<leaderboardID>, <score>)
    • Set the score of the current player
    • This will only update the player's score if it is set to a better score than what they currently have scored (so if the leaderboard is configured for a Higher is better sort order, then a higher score will need to be set)
  • FBInstant.globalLeaderboards.getScoreAsync(<leaderboardID>)
    • Get the score of the current player
  • FBInstant.globalLeaderboards.getTopEntriesAsync(<leaderboardID>, <limit>)
    • Get the top scoring players in the leaderboard
    • Limit is an optional parameter to just return up to that many results
    • Returns an array of entries, containing player session ID and score
  • FBInstant.globalLeaderboards.getTopFriendEntriesAsync(<leaderboardID>, <limit>)
    • Get the top scoring friends of the current player in the leaderboard
    • Returns an array of entries, containing player session ID and score

The SDK methods return an array of entries containing a player session IDs. These are IDs that are only valid for the player's current session, and can be used to reference the players in a secure overlay view to render the player's data. Here is an example of accessing the player's session ID and score from one of these SDK calls:

const topEntries = await FBInstant.globalLeaderboards.getTopEntriesAsync('123');
const sessionID = topEntries[0].getPlayer().getSessionID();
const score = topEntries[0].getScore();

Note that you can always render an arbitrary player's information. That allows you greater flexibility when it comes to leaderboards as you can create your own systems. The following is an old way of using leaderboards in NEZP. We will be providing less support for this going forwards.

Rendering with Session ID

The session IDs of players returned from getTopEntriesAsync can be used inside an overlay XML to display the player's name, photo, and score like this example XML:

<View>
  <Image src="{{FBInstant.players[{{playerSessionID}}].photo}}" />
  <Text content="{{FBInstant.players[{{playerSessionID}}].name}}" />
  <Text content="{{FBInstant.players[{{playerSessionID}}].score}}" /> 
</View>

using these passed in params: {"playerSessionID":"a46591a3-fe76-425a-9c38-c1b55641f0c5"}

The syntax for rendering players returned from getTopFriendEntriesAsync differs a bit like this:

<View>
  <Image src="{{FBInstant.player.friends[{{playerSessionID}}].photo}}" />
  <Text content="{{FBInstant.player.friends[{{playerSessionID}}].name}}" />
  <Text content="{{FBInstant.player.friends[{{playerSessionID}}].score}}"/>
</View>

Rendering with Data Resolver

In addition to these two methods above using session IDs to render leaderboards, an XML for-loop data resolver can also be used to iterate through top entries like this:

<View>
  <For source="{{FBInstant.globalLeaderboards[{{leaderboardID}}].topPlayers}}" itemName="i" sortKey="name">
    <View style="display: flex;flexDirection: column">
      <Image src="{{i.photo}}" />
      <Text content="{{i.name}}" />
      <Text content="{{i.score}}" />
    </View>
  </For>
</View>

using these passed in params: {"leaderboardID":"901819751533800"}

This method is better for rendering a simple global leaderboard with all entries in a table. For more advanced leaderboard displays, it is recommended to use the session IDs and render each player entry in a separate overlay for more control over how they are shown.