Instant Tournaments for Cross-Play Games

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. This is a popular feature is available in both the Instant Games SDK and the Cloud Games SDK, and now available across platforms with Cross Play.

GetTournament

Returns a list of active tournaments that can be surfaced in-game that includes tournaments in which the player has created, the player is participating in, or the player's friends are participating in. This tournament information can be queried via Graph API as follows:

GET /{user-id}/tournaments

To make calling this API easier we provide a high level wrapper in the Android and iOS SDK which will allow you to query tournaments for the player.

TournamentFetcher().fetchTournaments()

TournamentFetcher().fetchTournaments { result in
  switch result {
    case .success(let tournaments):
      // Perform action with tournaments list
    case .failure(let error):
      // Handle errors from the graph API call
  }
}

PostTournamentScore

Updates a player’s score in a tournament. Scores posted using this API should be consistent and comparable across game sessions. This tournament information can be updated via Graph API as follows:

POST /{tournament-id}/score

To make calling this API easier we provide a high level wrapper in the Android and iOS SDK which will allow you to update tournaments for the player. Required fields include tournament ID and the score.

TournamentUpdater().update(tournament: tournament, score: score)

TournamentUpdater().update(tournament: tournament, score: score) { result in
  switch result {
    case .success:
      // The score was updated succesfully
    case .failure(let error):
      // Handle errors from the graph API call
  }
}

CreateTournament

Renders an Instant Tournament creation dialog where a user can create a tournament and share a post to Feed. Required fields include the score and a tournament configuration object. Optional fields include title, endTime, scoreType, sortOrder, payload, and image.

Create a Configuration

Before showing the share dialog to share a new tournament we need to create a configuration for the tournament.

var newTournamentConfig =
  new TournamentConfig.Builder()
    .setTournamentTitle( /* Optional title string*/ ) 
    .setTournamentEndTime( /* java.time.Instant for the endtime */ )
    .setTournamentScoreType( /* Type of score; see TournamentScoreType enum */ )
    .setTournamentSortOrder( /* Sort order for scores; see TournamentSortOrder enum */ )
    .setTournamentPayload( /* Optional string data blob */ )
    .build();

let config = TournamentConfig(
  title: /* Optional title string */
  endTime: /* Optional endTime */
  scoreType: /* Type of score; see TournamentScoreType enum */
  sortOrder: /* Sort order for scores; see TournamentSortOrder enum */
  payload: /* Optional string data blob */
)

Create a Delegate (iOS Only)

On iOS, create a delegate to handle completion, cancellation, and errors of the dialog. Conform any class to the ShareTournamentDialogDelegate and implement the following methods:

class DelegateForShareDialog: ShareTournamentDialogDelegate {

  func didComplete(dialog: ShareTournamentDialog, tournament: Tournament) {
    // Dialog was completed succesfully; do what you want with tournament object
  }

  func didFail(withError error: Error, dialog: ShareTournamentDialog) {
    // Handle the error returned from dialog
  }

  func didCancel(dialog: ShareTournamentDialog) {
    // Dialog cancelled
  }
    
}

Show the Dialog

Once configuration (and the delegate for iOS) is complete, show the share dialog.

This dialog performs an app switch if the Facebook app is installed on the device. For Android, it would try to open the overlay inside of the game app first. If the player does not have the Facebook app installed, the dialog is opened in the mobile browser.

TournamentShareDialog shareDialog = new TournamentShareDialog(getActivity());
shareDialog.registerCallback(
  getCallbackManager(),
  new FacebookCallback<TournamentShareDialog.Result>() {
    @Override
    public void onSuccess(TournamentShareDialog.Result result) {
      result.getTournamentID // Will return the newly created Tournament's ID
    }

    @Override
    public void onCancel() {
      // The user cancelled the dialog without creating and sharing the Tournament
    }

    @Override
    public void onError(FacebookException error) {
      // Handle any dialog errors  
    }
});
      
shareDialog.show(initial_score, newTournamentConfig);

// Creates a new sharedialog with the given delegate
let shareDialog = ShareTournamentDialog(delegate: DelegateForShareDialog())

// Shows the created share dialog with config for the tournament to share and the initial score
shareDialog.show(initialScore: score, config: config)

ShareTournament

Renders an Instant Tournament re-share dialog where a user can post a score to an existing tournament and share a post to Feed. Required fields include the score and tournament.

Similar to tournament creation, this re-share dialog performs an app switch if the Facebook app is installed on the device. For Android, it would try to open the overlay inside of the game app first. If the player does not have the Facebook app installed, the dialog is opened in the mobile browser.

TournamentShareDialog shareDialog = new TournamentShareDialog(getActivity());
shareDialog.registerCallback(
  getCallbackManager(),
  new FacebookCallback<TournamentShareDialog.Result>() {
    @Override
    public void onSuccess(TournamentShareDialog.Result result) {
      result.getTournamentID // Will return the updated tournament's ID
    }

    @Override
    public void onCancel() {
      // The user cancelled the dialog without updating and sharing the Tournament
    }

    @Override
    public void onError(FacebookException error) {
      // Handle any dialog errors  
    }
});
  
shareDialog.show(updateScore, tournament);

// Create a new sharedialog with the specified delegate
let shareDialog = ShareTournamentDialog(delegate: DelegateForShareDialog())

// Show the dialog with the user's score and the tournament to post the given score 
shareDialog.show(score: score, tournament: tournament)