Instant Tournaments

Instant Tournaments is a feature that helps Facebook users discover and play games with friends and others through Feed, building connections with each other through lightweight competition. Instant Tournaments are available in both the Instant Games SDK and the Cloud Games SDK.

Instant Tournaments are a great way to acquire new players, and a good way to keep players engaged during the life of the tournament (the default life of a tournament is seven days). Players share a leaderboard to their timeline with a prompt for friends to join the challenge. Feed delivery—combined with re-shares by players who join—enable tournaments to traverse the friends graph rapidly to help the game acquire more players in a short time.

Why Your Game Should Integrate Tournaments

Instant Tournaments primarily help with the acquisition of new players. In addition, tournaments improve retention while the Tournament is running.

Because the posts are displayed in the Feed, Instant Tournaments help surface your game to players who have never seen it before—especially players who don't usually visit the Facebook Gaming tab. Well-trafficked tournaments keep existing players competing for the top spot and bragging rights.

Learn how Supergene saw 200% increase in ARPU with Instant Tournaments

Getting Started

Games that use Instant Games SDK or Cloud Games Facebook SDK can integrate Instant Tournaments with minimal effort by calling one of the following APIs at the end of an activity or round (for example, when the player doesn't have "lives" to continue the game):

• FBInstant.postSessionScoreAsync: Posts a player's score to Facebook and resolves when the score has been posted and all platform dialogs spawned from the posted score have completed. After that, the game should resume.
• FBInstant.postSessionScore: [Deprecation Planned] Released in 6.3, this API will be deprecated in favor of FBInstant.postSessionScoreAsync.

Calling these APIs will post the player’s score to the current context. This means that we'll handle the logic on whether to render a create dialog, or a share dialog for the player, based on whether they were already playing in a Tournament context.

If you want more control over the overall tournament experience for the player, use the following APIs to allow players to create and share tournaments, query and join tournament contexts, and post the player's score from the current game session:

• FBInstant.getTournamentAsync: Retrieves the active or expired Instant Tournament object for the current context the user is playing in, if one exists.
• FBInstant.tournament.createAsync: Posts a player’s score to Facebook, and renders a tournament creation dialog if the player is not currently in a tournament session. The client will attempt to switch into the tournament context, and resolve if successful.
• FBInstant.tournament.postScoreAsync: Posts a player's score to Facebook and resolves when the score has been posted. No platform dialog will be shown.
• FBInstant.tournament.shareAsync: Posts a player’s score to Facebook, and renders a tournament share dialog if the player is currently in a tournament session. The promise will resolve when the user action is completed.
• FBInstant.tournament.getTournamentsAsync: Returns a list of active tournaments that can be surfaced in-game, including:
  • tournaments the player has created.
  • tournaments the player is participating in.
  • tournaments the player's friends (who granted permission) are participating in.
• FBInstant.tournament.joinAsync: Requests a switch into a specific tournament context. The promise will resolve when the game has switched into the specified context.

Example Player Journeys

Reward Players Both for Participating and for Winning

Grow your game organically by offering rewards to the tournament organizer for each new player joining the game through the tournament.

To see how this works, assume that Player A finishes a game round.

Player A then wants to start a new tournament by sharing it to their Feed.

When the play session ends, your game should display the tournament creation dialog as shown in the following code.

FBInstant.tournament.createAsync(initScore, config, {param1: “value”})
  .then(tournament => {
    // Sync Player A's info to the game server here.
})

Next, Player B sees the share in their Feed and clicks on it to open the game session.

Your game should fetch the tournament and sync Player B's information to the game server.

FBInstant.getTournamentAsync.().then(
  // Fetch the tournament in the current context here.
  tournament =>  {
    // Sync Player B's info to the game server here.
})

Player B then accepts your game's Terms of Service and starts playing the game in the same tournament context as Player A.

When each player finishes their session, your game should post the result to the game server.

FBInstant.tournament.postScoreAsync(score).then(
  response => {
    // Sync the score to the game server here.
})

When the tournament is over, compare the posted results from all participants and calculate rewards. Your game should send each participant a custom update with a payload that contains their reward as well as information about the results of the tournament.

FBInstant.updateAsync(payload) 

The next time that Players A and B interact with your game, fetch the reward and tournament results by calling the following API.

FBInstant.getEntrypointData()

Finally, display an in-game button that allows players to create or join a new tournament.

Enable Tournaments for a Specific Level in Your Game

You can enable tournaments for a specific level in your game by passing name-value pairs as parameters to the Tournament APIs.

To see how this works, assume that Player A finishes a level in your game and then wants to start a new tournament for that level. When the play session ends, your game should display the tournament creation dialog and pass information about the level as shown in the following code.

FBInstant.tournament.createAsync(initScore, {tournamentTitle: “Level 1 Championship”}, {level: 1}).then(tournament => {})

When the tournament is shared in the Feed, the game level is distinctly identifiable through a custom image. Player B clicks on the share to start the game session in that level.

When your game opens, it should fetch the game level to load as shown in the following code.

FBInstant.getTournamentAsync.().then(
  tournament =>  {
    tournament.getPayload()[“level”]
})

Additional Features: Page-Hosted Tournaments

Once your game has fully integrated with Instant Tournaments via our in-game APIs, we recommend creating public tournaments from your community page as follows:

1. Navigate to the App Dashboard for your game.
2. In the Instant Games product, open the Instant Tournament page.
3. Fill in the following fields and then click Create:
   • Description of the tournament
   • Page you want to post on
   • Title
   • Image (base64 data URL format, which is same as the tournament 2.0 API)
   • Payload that the game needs to put players in the right place
   • Tournament score sort order ("higher is better" or "lower is better")
   • Score format (Numeric or Time-based)

After the tournament has been created, refresh the page to see the tournament post. The App Dashboard shows a list of the active page-hosted tournaments for your game; the table lists the context ID, tournament ID, creation time, and end time.

Analysis

Gaming Insights in Facebook Business Suite does not yet support reporting metrics for Instant Tournaments. You can assess the impact of using Instant Tournaments in your game by tracking metrics such as:

• Instant Tournament Plays
• Players per Instant Tournament
• New players from Instant Tournaments

Best Practices

• Instant Tournaments are a perfect fit for games that have gameplay loops in which players are trying to achieve the highest score, lowest score, fastest time, or longest survival time.
• For games not built around loops like this, you can add mini-game modes to help new players discover the game through an Instant Tournament. In this case, the game should guide the player to experience the other gameplay after competing in the tournament.
• Entry into the tournament mode should be immediately accessible by all players, including first-time players. That is, it should not be gated by any level blockers or game introductory sections. Anyone should be able to jump into the game or tournament mode from the Feed post and just play.
• Consider rewarding players for participating in the tournament, with additional rewards based on their final position in the table.

Feature FAQ

Documentation Contents

Tournaments in Instant Games Explains how to run a tournament in an Instant Game.	Tournaments in Cloud Games Explains how to run a tournament in a Cloud Game.
Tournaments for Cross-Play Games Explains how to run a tournament that includes participants from different platform builds of your game.

See Also

• Facebook Gaming Support