This tutorial will guide you through building your first Instant Game: a turn-based version of the classic Tic-Tac-Toe. It will use Game Updates and a Game bot. |
After you setup your App, you are ready to take the first steps:
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>
Important notes:
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:
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.
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" } } } }
The custom update template configuration allows us to assign an ID to each specific custom update which results in better analytics. It is mandatory to assign template IDs for all games.
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
.
The Game Bot gives your game a powerful channel for re-engagement - check our Game Bot setup guide to create one.
Now that you know how to build and configure your Instant Game and your Game bot, make sure to check the guides below: