Facebook-Spiele

Instant Tournaments for Instant Games

FBInstant

Top level namespace for the Instant Games SDK.

postSessionScore( )

Note: this API is deprecated.

Posts a player's score to Facebook. This API should only be called at the end of an activity (example: when the player doesn't have "lives" to continue the game). This API will be rate-limited when called too frequently. Scores posted using this API should be 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, those two scores should be generated from activities where the scores are fair to be compared and ranked against each other.

Parameters

  • score number An integer value representing the player's score at the end of an activity.

Examples

function onScore(score) {
  if (score > bestSessionScore) {
    bestSessionScore = score;
    FBInstant.postSessionScore(bestSessionScore);
  }
}

Returns void

postSessionScoreAsync( )

Posts a player's score to Facebook and resolves when score has been posted. This API should only be called at the end of an activity (example: when the player doesn't have "lives" to continue the game). This API will be rate-limited when called too frequently. Scores posted using this API should be 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, those two scores should be generated from activities where the scores are fair to be compared and ranked against each other.

Parameters

  • score number An integer value representing the player's score at the end of an activity.

Examples

function onScore(score) {
  if (score > bestSessionScore) {
    bestSessionScore = score;
    FBInstant.postSessionScoreAsync(bestSessionScore)
      .then(() => {
        ...
      });
  }
}

Returns Promise A promise that resolves when all platform behavior (such as dialogs) generated from the posted score has completed, and the game should resume. If the behavior resulted in a social context change, that will be reflected by the time the Promise resolves.

Tournament

An instant game tournament.

getID( )

The unique ID that is associated with this instant tournament.

Examples

FBInstant.getTournamentAsync()
  .then(function(tournament) {
    console.log(tournament.getID());
  });

Returns string A unique identifier for the instant tournament.

getContextID( )

The unique context ID that is associated with this instant tournament.

Examples

FBInstant.getTournamentAsync()
  .then(function(tournament) {
    console.log(tournament.getContextID());
  });

Returns string A unique identifier for the game context.

getEndTime( )

Timestamp when the instant tournament ends. If the end time is in the past, then the instant tournament is already finished and has expired.

Examples

FBInstant.getTournamentAsync()
  .then(function(tournament) {
    console.log(tournament.getEndTime());
  });

Returns number A unix timestamp of when the tournament will end.

getTitle( )

Title of the tournament provided upon the creation of the tournament. This is an optional field that can be set by creating the tournament using the FBInstant.tournament.createAsync() API.

Examples

FBInstant.getTournamentAsync()
  .then(function(tournament) {
    console.log(tournament.getTitle());
  })

Returns string?

getPayload( )

Payload of the tournament provided upon the creation of the tournament. This is an optional field that can be set by creating the tournament using the FBInstant.tournament.createAsync() API.

Examples

FBInstant.getTournamentAsync()
  .then(function(tournament) {
    console.log(tournament.getPayload());
  })

Returns string?

getTournamentAsync( )

Fetch the instant tournament out of the current context the user is playing. This will reject if there is no instant tournament link to the current context. The instant tournament returned can be either active or expired (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.

Examples

FBInstant.getTournamentAsync()
  .then(function(tournament) {
     console.log(tournament.getContextID());
     console.log(tournament.getEndTime());
  });
  • Throws PENDING_REQUEST
  • Throws NETWORK_FAILURE
  • Throws INVALID_OPERATION
  • Throws TOURNAMENT_NOT_FOUND

Returns Promise<Tournament>

tournament

Contains functions and properties related to instant tournaments.

CreateTournamentConfig

Represents the configurations used in creating an Instant Tournament.

Type: Object

Properties

  • title (string?) Optional text title for the tournament.
  • image (string?) Optional base64 encoded image that will be associated with the tournament and included in posts sharing the tournament.
  • sortOrder (string?) 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 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 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.

CreateTournamentPayload

Represents settings used for FBInstant.tournament.createAsync.

Type: Object

Properties

  • initialScore (number) An integer value representing the player's score which will be the first score in the tournament.
  • config (CreateTournamentConfig) An object holding optional configurations for the tournament.
  • data (Object)? A blob of data to attach to the update. All game sessions launched from the update will be able to access this blob from the payload on the tournament. Must be less than or equal to 1000 characters when stringified.

createAsync( )

Opens the tournament creation dialog if the player is not currently in a tournament session

Parameters
  • payload CreateTournamentPayload

Examples

FBInstant.tournament.createAsync({
    initialScore: 4,
    data: { tournamentLevel: 'hard' },
    config: {
      title: 'Level X Tournament',
      image: base64Picture,
      sortOrder: 'HIGHER_IS_BETTER',
      scoreFormat: 'NUMERIC',
      endTime: 1515806355,
    },
  })
  .then(function() {
     // user successfully created tournament and switch into tournament context
  });
  • Throws INVALID_PARAM
  • Throws INVALID_OPERATION
  • Throws DUPLICATE_POST
  • Throws NETWORK_FAILURE

Returns Promise<Tournament>

postScoreAsync( )

Posts a player's score to Facebook. This API should only be called within a tournament context at the end of an activity (example: when the player doesn't have "lives" to continue the game). This API will be rate-limited when called too frequently. Scores posted using this API should be 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, those two scores should be generated from activities where the scores are fair to be compared and ranked against each other.

Parameters
  • score number An integer value representing the player's score at the end of an activity.
Examples
function onScore(score) {
  if (score > bestScore) {
    bestScore = score;
    FBInstant.tournament.postScoreAsync(bestScore)
      .then(function() {
        ...
      });
  }
}
  • Throws INVALID_PARAM
  • Throws TOURNAMENT_NOT_FOUND
  • Throws NETWORK_FAILURE

Returns Promise A promise that resolves when the score post is completed.

ShareTournamentPayload

Represents content used to reshare an Instant Tournament.

Type: Object

Properties

  • score (number) An integer value representing the player's latest score.
  • data (Object)? 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.

shareAsync( )

Opens the reshare tournament dialog if the player is currently in a tournament session

Parameters
  • payload ShareTournamentPayload Specifies share content. See example for details.
Examples
FBInstant.tournament.shareAsync({
  score: 3,
  data: { myReplayData: '...' }
}).then(function() {
  // continue with the game.
});
  • Throws INVALID_OPERATION
  • Throws TOURNAMENT_NOT_FOUND
  • Throws NETWORK_FAILURE

Returns Promise A promise that resolves if the tournament is shared, or rejects otherwise.

joinAsync( )

Request 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, this will reject. Otherwise, the promise will resolve when the game has switched into the specified context.

Parameters
  • tournamentID string
  • id string The Tournament ID of the desired context to switch into.
Examples
FBInstant.getTournamentAsync().then((tournament) => {
   console.log(tournament.getID());
});
// 1122334455
FBInstant.tournament
  .joinAsync('1122334455')
  .then(function() {
     // Context switch completed successfully.
  });
  • Throws INVALID_OPERATION
  • Throws INVALID_PARAM
  • Throws SAME_CONTEXT
  • Throws NETWORK_FAILURE
  • Throws USER_INPUT
  • Throws TOURNAMENT_NOT_FOUND

Returns Promise A promise that resolves when the game has switched into the specified tournament context, or rejects otherwise.

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.

Examples
FBInstant.tournament.getTournamentsAsync()
 .then(tournaments => {
   // tournament list
 });
  • Throws NETWORK_FAILURE
  • Throws INVALID_OPERATION

Returns Promise<Array<Tournament>>