Facebook Games

Play With Friends for Instant Games

With instant games, there are many ways to enable social interaction between players.

Connected Players

The FBInstant.player.getConnectedPlayersAsync() method retrieves a list of users that are connected to the current player through Messenger. This method will return only connected users that have granted permission for the game to access their information.

Note: The method will not differentiate between players who have or have not been playing in the same context. You can fetch information specific to that context from FBInstant.context.getPlayersAsync().

Fetch Player's Friends

FBInstant.player.getConnectedPlayersAsync()
  .then(function(players) {
    _leaderboard.render(players);
  });

Fetch Context Players

FBInstant.context.getPlayersAsync()
  .then(function(players) {
    _leaderboard.render(players);
  });

Changing Contexts

Instant Games can be played in many different contexts, such as Messenger conversations or Feed stories. With the SDK calls below, you can switch contexts from any session, regardless of its entry point. This means you can allow your players to switch to other conversations without requiring them to quit and re-open the game.

We offer three different context change methods:

  • FBInstant.context.chooseAsync() opens a native dialog that allows the player to select which conversation they want to change to.
  • FBInstant.context.switchAsync(contextId) allows the developer to send the player to a pre-defined context (for instance, to continue a match that has previously started in a different conversation).
  • FBInstant.context.createAsync(playerId) attempts to create a context with the specified player (for example, to start a match between a player and a suggested friend).

Playing with other Players with Matchmaking

We provide tools for your game to bring players into new contexts with our context and matchmaking APIs. We've found that people who play with other players end up retaining better than solo context players. There's a couple reasons for this:

  1. Personalized updates in the context can provide a compelling entry point back into the game
  2. Social play drives retention because people have more fun when they play together!

Meaningful social dynamics in the gameplay itself will make your instant game shine, and excite players enough to share your game with all their friends.

Recommended usage:

  1. Use the matchmaking API to give players the opportunity to have a social play experience independent from friend interactions. This is especially helpful in turn-based games and multiplayer games, but can also benefit other types of games in case players don't have any friends who play a given game, their friends don't play frequently enough, or they just want a different play experience.
  2. Swap in AI players if random opponents quit before match completes

By calling matchPlayerAsync(), your game will attempt to match the current player into a context with another player. We have added an additional parameter to specify whether you want the game to switch into the newly created context right after the player is matched, or wait until the player has clicked Play in the toast.

There are two matching mechanisms:

  1. Synchronous match: Matches the current player with other users looking for people to play with. If successful, a new Messenger group thread will be created containing the matched players and the player will be switched into that thread's context. This will resolve when the player has successfully switched into the newly matched context.
  2. Asynchronous match (learn more): Player starting offline match will be added to a group thread right away with other players who started offline match before, players can leave the game while waiting more players to join. Once matched, the player will be added and switched into that matched thread's context. This will resolve when the player has been successfully added to the group thread and switched into the matched context.

The default minimum and maximum number of players in one matched thread are 2 and 20 respectively, depending on how many players are trying to get matched around the same time. The values can be changed in fbapp-config.json.