Instant Games Quick Start

Create your game client

Now that your app is setup, you need to start creating your game client. The game client needs to have an index.html file in the root directory. Start by importing the Instant Games SDK by adding this line.

<script src="https://connect.facebook.net/en_US/fbinstant.6.3.js"></script>

Our SDK makes extensive use of Promises for asynchronous functionality. You'll only be able to interact with the loading UI after FBInstant.initializeAsync() resolves.

FBInstant.initializeAsync() 
  .then(function() {
  // Start loading game assets here
});

Our game client will not download your bundle (.zip file) all at once. Instead it will search the root for configuration (fbapp-config.json) and the main file (index.html). It will then start executing the logic contained in the main file, and will start downloading assets from there. As a developer you have full control of the order and time in which your assets are loaded.

Once you start downloading the necessary assets for initializing the game, you need to inform the SDK about the loading progress in order for us to display the loading ring to players.

var images = ['sprite1', 'sprite2', ...];
for (var i=0; i < images.length; i++) {
  var assetName = images[i];  
  var progress = ((i+1)/images.length) * 100;  
  game.load.image(assetName);

  // Informs the SDK of loading progress
  FBInstant.setLoadingProgress(progress);
}

// Once all assets are loaded, tells the SDK 
// to end loading view and start the game
FBInstant.startGameAsync()
  .then(function() {
  // Retrieving context and player information can only be done
  // once startGameAsync() resolves
  var contextId = FBInstant.context.getID();
  var contextType = FBInstant.context.getType();

  var playerName = FBInstant.player.getName();
  var playerPic = FBInstant.player.getPhoto();
  var playerId = FBInstant.player.getID();

  // Once startGameAsync() resolves it also means the loading view has 
  // been removed and the user can see the game viewport

  game.start();
});

For more information about the initializeAsync(), setLoadingProgress() and startGameAsync() methods, see the SDK Reference.

Instant Games content is hosted on Facebook infrastructure, so you don't need to host the game content on your own or use third-party services. Once the game is ready for testing, package all game files into a single .zip file.

Note: the index.html file should be in the root of this archive and not in any sub-folders.

To upload the .zip file:

1. From the app's dashboard, click the Web Hosting tab
2. Select Instant Game from the dropdown menu, click +Upload Version to upload the .zip file to Facebook's hosting service.
3. Choose the .zip file, add details about the version changes, and click Upload
4. It should only take a few seconds to process the .zip file. When the state changes to Standby, click "★" to push the build to production

You can now test the build on your mobile device. The published build will be visible to you in the games list in Messenger, under a section called In Development.

To speed up the development process, you can upload your build from the command line via the Graph API, or test directly from your development server. Learn more about Testing, Publishing and Sharing your Instant Game.

Context defines any environment in which a game can be played. Commonly, the context identifies things like a Facebook post or group.

The example below shows how to send a context update and how it will look in a Messenger conversation.

Step 1: Declare templates on a configuration file

To declare your custom updates, you need to create a configuration file called fbapp-config.json and place it in the root of your bundle, together with your index.html file.

For more information on the supported configurations, please refer to the Bundle-based configuration section. For this demo, the file contents should be as follows:

{
  "instant_games": {
    "platform_version": "RICH_GAMEPLAY",
    "custom_update_templates": {
      "play_turn": {
        "example": "Edgar played their move"
      }
    }
  }
}

Step 2: Send a custom update with updateAsync

Once your template has been declared in your configuration file, you can use it to populate the mandatory template field in FBInstant.updateAsync. Here's how the call is used in Tic-Tac-Toe to tell the opponent that it's their turn.

// This will post a custom update. If the game is played in a messenger
// chat thread, this will post a message into the thread with the specified
// image and text message. And when people launch the game from this
// message, those game sessions will be able to access the specified blob
// of data through FBInstant.getEntryPointData().
FBInstant.updateAsync({
  action: 'CUSTOM',
  cta: 'Play',
  image: base64Picture,
  text: {
    default: 'Edgar played their move',
    localizations: {
      en_US: 'Edgar played their move',
      es_LA: '\u00A1Edgar jug\u00F3 su jugada!'
    }
  }
  template: 'play_turn',
  data: { myReplayData: '...' },
  strategy: 'IMMEDIATE',
  notification: 'NO_PUSH'
}).then(function() {
  // Closes the game after the update is posted.
  FBInstant.quit();
});

Here is how the message will look like:

For more information on custom context updates, review our Instant Games SDK Reference.

For best practices, including when to message other players, when to notify them and what content to include in these updates, refer to our Best Practices guide.

Note: context updates are not sent outside Messenger. It can be useful to tailor your experience by using the context.getType() method, and detecting THREAD. You can switch to a more appropriate context using context.switchAsync, context.chooseAsync or context.createAsync.