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:
| Parameter | Type | Description |
|---|---|---|
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 otherwiseThrows:
INVALID_PARAMINVALID_OPERATIONDUPLICATE_POSTNETWORK_FAILUREOPERATION_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_FAILUREINVALID_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:
| Parameter | Type | Description |
|---|---|---|
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_OPERATIONINVALID_PARAMSAME_CONTEXTNETWORK_FAILUREUSER_INPUTTOURNAMENT_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:
| Parameter | Type | Description |
|---|---|---|
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_PARAMTOURNAMENT_NOT_FOUNDNETWORK_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.'); }); } }
Opens the reshare tournament dialog if the player is currently in a
tournament session.
Parameters:
| Parameter | Type | Description |
|---|---|---|
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_OPERATIONTOURNAMENT_NOT_FOUNDNETWORK_FAILURE
Example:
FBInstant.tournament.shareAsync({ score: 3, data: { myReplayData: '...' } }).then(function() { // continue with the game. });
Types
TournamentArgs
Arguments for creating a Tournament instance.
Properties:
| Property | Type | Description |
|---|---|---|
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:
| Property | Type | Description |
|---|---|---|
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:
| Property | Type | Description |
|---|---|---|
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. |
Represents content used to reshare an instant tournament.
Properties:
| Property | Type | Description |
|---|---|---|
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. |