Build

Play Together (Co-play) Requirements

Definitions

  • Rooms: A live video call on Facebook between two or more people. Any member in a Room can start a game activity, which will create a Live Match that other members can join.
  • Live Match: A real-time game between two or more members in a Room. Each Room can only contain one Live Match at a time.
  • Match State: The current status of a Live Match. This will be one of the following values:
    1. PENDING: The Live Match has not yet started. Any member of the Room can join the game.
    2. RUNNING: The Live Match has started. Depending on the type of your game, any members that join the match during this phase should either be allowed to join or placed into a spectator mode.
    3. CONCLUDED: The Live Match has ended. The Room will handle player exit from the Live Match.
    4. ABANDONED: All players in a pending Live Match exited the game before it started.

Integration Requirements

  • Your game must specify the minimum and maximum number of players that the game requires.
  • If your game is new to the Instant Games platform, create a new app by following the instructions in Getting Started with Instant Games.
  • After game setup, follow the Instant Games Quick Start to create a game client. Note that you should use the Beta SDK to access the Rooms APIs below. Then upload a Room version of your game in the Web Hosting tab, and push it to Messenger Rooms, as shown in the screenshot below.
Push your game to Messenger Rooms
  • Load the beta version of the SDK: 
<script src="https://connect.facebook.net/en_US/fbinstant.beta.js"></script>
  • It is important that you have a Production version - currently playing the game from Messenger Rooms will make the game appear in the Recently Played section of Instant Games on Facebook. The Production version should either have gameplay meant to be played outside of Rooms or have messaging to inform players that the game can only be played in Messenger Rooms.
  • After your app has been pushed to Messenger Rooms, your game must go through business verification to get the capability that is required by Rooms.

Learn more about how to Create a Business Manager and how to Verify a Business.

Game Behavior Requirements

When a game is started in a Room, everyone who joins the game expects to be able to play the game together in real- time. Your game must follow the guidelines in this section to provide a consistent experience across all Instant Games.

General

  • Provide a lobby state while waiting for the minimum number of players to join the match. Your game must keep track of how many players are currently in the lobby. As soon as enough players have joined, a player should have the ability to start the match.
  • Provide a valid experience for players who enter the game either after the match has started or after the maximum number of players have joined. If possible, members should be allowed to join the game after the Live Match has started. If your game does not allow members to join mid-match, joining members should be placed in a spectator mode that allows them to follow along with the action in the game.
  • Do not attempt to persist or switch players into a Live Match context after the match ends; the game will always be loaded in a Live Match contexts by the players in the call. A match ends either when your game enters the COMPLETED state or the Room call ends.
  • Provide audio settings so that players can mute the game.
  • Do not place any game UI in the top-right corner of the game. This space is reserved for the quit button.
  • Your game needs to stick with one orientation for mobile experience.

Game Load

At load time, your game should call FBInstant.room.getCurrentMatchAsync and respond as follows:

  • If the API request is rejected, the game is not in a LiveMatch and can behave normally.
  • If the API request resolves with a valid LiveMatch object, the game is now in a LiveMatch and should satisfy the behavioral requirements for a real-time match in a Room.

We do not support the Unity game engine for Play Together. Also refer to Load Times and Performance for more recommendations.

Pre-Game

When your game detects that a Live Match is in progress, you can call LiveMatch.getContextID to get the social context ID associated with the Live Match. The social context ID will match the current context that is returned from the Room environment when you call FBInstant.context.getID.

All players whose Live Match is associated with the same social context ID must be grouped together in a single game match.

When the minimum number of players have joined the match, your game should allow a player to start the match. Your game has a discretion over which players can start the match. For example, you can allow any player to start the match, or allow only the first player to enter the match context (that is, the player who initiated the game in the Room) to start the match.

In-Game

When the match has started in-game, your game server should use the following POST request to signal to the platform that the match has started. This will set the Match Status to RUNNING:

POST https://graph.facebook.com/{live-match-id}/start_match?access_token={APP_ACCESS_TOKEN}

Response
{
    "success": true
}

When the match has ended in-game, the game server should use the following POST request to signal to the platform that the match has ended. This will set the Match Status to CONCLUDED.

POST https://graph.facebook.com/{live-match-id}/end_match?access_token={APP_ACCESS_TOKEN}

Response
{
    "success": true
}

Your game can also access the list of players who are actively in the match by calling LiveMatch.getActiveParticipantsAsync().