Instant Games

Instant Games SDK v8.0: FBInstant.tournament

Updated: May 5, 2026
Copy for LLM
See Instant Games SDK v8.0 for the SDK overview, changelog, and root FBInstant reference.

FBInstant.tournament

createAsync()

Opens the tournament creation dialog if the player is not currently in a tournament session.
Parameters:
ParameterTypeDescription
payload
Specifies the payload for the creation of the tournament.
Returns:Promise<Tournament> — A promise that resolves if the tournament creation is a success, or rejects otherwise
Throws:
  • INVALID_PARAM
  • INVALID_OPERATION
  • DUPLICATE_POST
  • NETWORK_FAILURE
  • OPERATION_SUPPRESSED
Example:
FBInstant.tournament.createAsync({
  initialScore: 100,
  config: {
    title: 'Best Score Showdown',
    sortOrder: 'HIGHER_IS_BETTER',
    scoreFormat: 'NUMERIC',
    // Optional: end the tournament 24 hours from now.
    // Defaults to one week after creation if omitted.
    endTime: Math.floor(Date.now() / 1000) + 24 * 60 * 60,
  },
  data: { level: 1 },
}).then(function(tournament) {
  console.log(tournament.getID());
  console.log(tournament.getContextID());
  // Continue the game in the newly created tournament context.
}).catch(function(error) {
  console.error(error.message);
});

getTournamentsAsync()

Returns a list of eligible tournaments that can be surfaced in-game, including tournaments 1) the player has created; 2) the player is participating in; 3) the player’s friends (who granted permission) are participating in. The instant tournaments returned are active. An instant tournament is expired if its end time is in the past. For each instant tournament, there is only one unique context ID linked to it, and that ID doesn’t change.
Returns:Promise<Array<Tournament>> — A promise that resolves with an array of Tournament objects if the tournaments are fetched, or rejects otherwise.
Throws:
  • NETWORK_FAILURE
  • INVALID_OPERATION
Example:
FBInstant.tournament.getTournamentsAsync()
 .then(tournaments => {
   // tournament list
 });

joinAsync()

Requests a switch into a specific tournament context. If the player is not a participant of the tournament, or there are not any connected players participating in the tournament, the promise rejects. Otherwise, the promise resolves when the game has switched into the specified context.
Parameters:
ParameterTypeDescription
tournamentID
string
The Tournament ID of the desired context to switch into.
Returns:Promise<void> — A promise that resolves when the game has switched into the specified tournament context, or rejects otherwise.
Throws:
  • INVALID_OPERATION
  • INVALID_PARAM
  • SAME_CONTEXT
  • NETWORK_FAILURE
  • USER_INPUT
  • TOURNAMENT_NOT_FOUND
Example:
FBInstant.getTournamentAsync().then((tournament) => {
   console.log(tournament.getID());
});
// 1122334455
FBInstant.tournament
  .joinAsync('1122334455')
  .then(function() {
     // Context switch completed successfully.
  });

postScoreAsync()

Posts a player’s score to Facebook. Call this API only within a tournament context at the end of an activity (example: when the player doesn’t have “lives” to continue the game). Facebook rate-limits this API if you call it too frequently. Post scores that are consistent and comparable across game sessions. For example, if Player A achieves 200 points in a session, and Player B achieves 320 points in a session, generate both scores from activities that can be fairly compared and ranked against each other.
Parameters:
ParameterTypeDescription
score
number
An integer value representing the player’s score at the end of an activity.
Returns:Promise<boolean> — A promise that resolves when the score post is completed.
Throws:
  • INVALID_PARAM
  • TOURNAMENT_NOT_FOUND
  • NETWORK_FAILURE
Example:
let bestScore = 0;

function onScore(score) {
  if (score > bestScore) {
    bestScore = score;
    FBInstant.tournament.postScoreAsync(bestScore)
      .then(function() {
        console.log('Score posted to the tournament leaderboard.');
      });
  }
}

shareAsync()

Opens the reshare tournament dialog if the player is currently in a tournament session.
Parameters:
ParameterTypeDescription
payload
Specifies share content. See example for details.
Returns:Promise<void> — A promise that resolves if the tournament is shared, or rejects otherwise.
Throws:
  • INVALID_OPERATION
  • TOURNAMENT_NOT_FOUND
  • NETWORK_FAILURE
Example:
FBInstant.tournament.shareAsync({
  score: 3,
  data: { myReplayData: '...' }
}).then(function() {
  // continue with the game.
});

Types

TournamentArgs

Arguments for creating a Tournament instance.
Properties:
PropertyTypeDescription
tournamentID
string
The unique identifier for the tournament.
contextID
string
The context ID associated with the tournament.
endTime
number
Timestamp when the tournament ends.
tournamentType
InstantGameTimedLeaderboardTournamentExternalType
The type of tournament.
title
string(optional)
Optional title for the tournament.
payload
string(optional)
Optional data payload for the tournament.

Tournament

An instant game tournament.

CreateTournamentConfig

Represents the configurations used in creating an instant tournament.
Properties:
PropertyTypeDescription
title
string(optional)
Optional text title for the tournament, please do not include user names in title.
forceScoreValidation
boolean(optional)
Optional boolean that specifies if the tournament requires game server validation before a score can be added to or updated on the leaderboard.
image
string(optional)
Optional base64 encoded image that will be associated with the tournament and included in posts sharing the tournament
sortOrder
string(optional)
Optional input for the ordering of which score is best in the tournament. The options are ‘HIGHER_IS_BETTER’ or ‘LOWER_IS_BETTER’. If not specified, the default is ‘HIGHER_IS_BETTER’.
scoreFormat
string(optional)
Optional input for the formatting of the scores in the tournament leaderboard. The options are ‘NUMERIC’ or ‘TIME’. If not specified, the default is ‘NUMERIC’.
endTime
number(optional)
Optional input for setting a custom end time for the tournament. The number passed in represents a unix timestamp. If not specified, the tournament will end one week after creation.
forceScoreRangeValidation
boolean(optional)
Optional boolean that specifies if the tournament should use score range validation. If true, then minimum and/or maximum scores should be provided; scores falling outside the range will be automatically rejected. If either minimum or maximum is null, then that side of the range will be ignored.
minimumScore
number(optional)
Optional input will only be used if forceScoreRangeValidation is true. If it is, scores below this will be automatically rejected. If null or forceScoreRangeValidation is false, no minimum will be used
maximumScore
number(optional)
Optional input will only be used if forceScoreRangeValidation is true. If it is, scores above this will be automatically rejected. If null or forceScoreRangeValidation is false, no maximum will be used
tournamentType
string(optional)
Optional input for tournament type. This can be set to either “COLLABORATIVE” (everyone works together for a goal) or “DEEP” (the standard tournaments). This will default to “DEEP” if no value is provided.
goal
integer(optional)
Input for collaborative tournaments, participants strive to reach this goal to beat the tournament. This input is optional for standard tournaments and required for collaborative tournaments.

CreateTournamentPayload

Represents content used to create an instant tournament.
Properties:
PropertyTypeDescription
initialScore
number
An integer value representing the player’s score which will be the first score in the tournament.
config
An object holding optional configurations for the tournament
data
GamePayload(optional)
A blob of data to attach to the update. All game sessions launched from the update will be able to access this blob through FBInstant.getEntryPointData(). Must be less than or equal to 1000 characters when stringified.

ShareTournamentPayload

Represents content used to reshare an instant tournament.
Properties:
PropertyTypeDescription
score
number(optional)
An optional integer value representing the player’s latest score.
data
GamePayload(optional)
A blob of data to attach to the update. Must be less than or equal to 1000 characters when stringified.