Build

Testing, Publishing, and Sharing an Instant Game

With Instant Games, we've made it really easy for you to test your development version locally, automate publishing, and to share the build with your team. This document will explain these steps in detail.

Testing the game from a local server

A big part of the Instant Games experience comes from the native overlays that are added to the game before and after each play session. In order to facilitate the development and testing workflow, we enable developers to run the game from a local server with a very similar experience to what their players will see on our platform. This is done through our embedded test player, which requires a small amount of configuration.

Enabling SSL via localhost

Since our embedded test player is working under the facebook.com domain, it can only be served through https. In order to embed content in a page served via https, the embedded content also needs to be served via SSL. The next steps will walk you through setting up a localhost server that serves secure content. We are showing one option below, but there are many solutions possible to enable this behavior.

> $ npm install -g http-server
  • 2. Create a private key and a certificate via openssl. This is necessary to run the secure local server.
> $ cd path/to/my/game/
> $ openssl genrsa 2048 > key.pem
> $ openssl req -x509 -days 1000 -new -key key.pem -out cert.pem
# Fill out necessary information
  • 3. Run the game from localhost with SSL. Once the key and certificate are ready, you can serve from localhost using SSL.
# Starts to serve via HTTPS, with cache disabled
> $ http-server --ssl -c-1 -p 8080 -a 127.0.0.1 
Starting up http-server, serving ./ through https
Available on:
https://127.0.0.1:8080
Hit CTRL-C to stop the server
  • 4. After this, pointing your browser to https://localhost:8080 should show you the game running.

Note: You must try to access it at least once, as you might need to approve a security warning from your browser before continuing. If that is the case and you skip this step, your game will not load.

For example, on Chrome you might need to access chrome://flags/#allow-insecure-localhost and enable 'Allow invalid certificates for resources loaded from localhost.' to get rid of the warning.

Running the embedded player from your browser

Now that the game is being served from localhost via a secure connection, you can embed it in our player. Point your browser here:

https://www.facebook.com/embed/instantgames/YOUR_GAME_ID/player?game_url=https://localhost:8080

You should see your game running in the Instant Games Player, like this:

Note: You must have played your game at least once on fb.gg/play/YOUR_GAME_ID for the embedded player to work properly.

At this point you should be able to use all features of the Instant Games SDK, from the game running on your local server.

For security reasons, localhost is the only supported domain for testing with the embedded test player.

Playing from local server in a specific conversation

You can run the game from your local server in a specific context. To do that just use the embedded player as explained above. You can then leverage the FBInstant.context methods (such as switchAsync(), createAsync() and chooseAsync()) to switch to different contexts.

This allows you to effectively play the game from localhost in a conversational context and to test if your context updates are being sent correctly.

Uploading your build

Package your game into a single .zip file

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. Please note that the index.html file must be in the root of this archive and not in any sub-folders. There are two ways to upload your bundle:

1. Upload the .zip file via the developer website

To upload the .zip file, click the Web Hosting tab from the Instant Games product in the App Dashboard. From there, click Upload Version which will allow you to upload the .zip file to Facebook's hosting service.

After that, the build will process the file, which should only take a few seconds. When the state changes to "Standby", the app is ready to be pushed to production!

2. Upload an archive via Graph API

Alternatively, you can upload your bundle via a Graph API call. This is useful if you have an automated deployment system. To do this, you need to request an upload token from the Web Hosting section, by clicking the Get Asset Upload Access Token button on the top.

With the token from the dialog, you can submit the following call to our Graph API to submit your .zip. Note that we are using the video sub-domain, but that's intentional, since that URL is configured to receive larger uploads.

curl -X POST https://graph-video.facebook.com/{App ID}/assets 
  -F 'access_token={ASSET UPLOAD ACCESS TOKEN}' 
  -F 'type=BUNDLE' 
  -F 'asset=@./{YOUR GAME}.zip' 
  -F 'comment=Graph API upload'

After that, your game will show up normally in the list of uploaded bundles. You can use this call to integrate with your existing build system.

Hosting restrictions

Keep in mind Facebook hosting has several restrictions, most importantly:

  • Server-side logic (e.g. php) is not supported.
  • The total size of uploaded files may not exceed 200MB.
  • The number of files inside a single application upload may not exceed 500.

Check Web Hosting documentation for more details.

Testing the uploaded build

Productionize the Build

To test the upload in a production environment, the build must first be staged for production. Click the "★" button to push the build to production.

Note:

Your production build is the build that will be served to every person who plays your game. In order to test your updates in production without affecting your existing playerbase, you can stage a build for testing. This will cause the build to be served only to developers and testers of the app.

Note: Do not create a test app for your game using the "Create Test App" button. To stage a build for testing is the way to go with Instant Games.

Once you have a build in production, always test the production build instead of the build that runs on your local server. You can test the production build using one of the following methods.

1. Play your game on Facebook

To share your game in the Feed, click the Share button in the Share Your Game section. This will allow you to share the game in the Feed and test it from any surface (Desktop, iOS or Android).



2. Play your game on Messenger

In the Instant Games list in Messenger, you and your team (people who are assigned "Admin, "Developer" or "Tester" roles in your app) should have a list of all the games that are under construction. The list is called In development. This helps you test games in Messenger even if they are unpublished.

If you have associated a page with your game, you can also generate a shareable link. This link will take users to a conversation with your bot on Messenger and open the game automatically if you have a bot setup. If not, it will take users to your Page on Facebook and open the game automatically from there. Either way, anyone who clicks the link should be able to play the game right away.

Submit for App Review

Once you're happy with your published version, you need to submit your game to App Review so our team can evaluate it for quality and compliance to our Platform Policies. Make sure to check our Release Checklist before submission and that your game meets all specified criteria. That guide also contains instructions of how to publish your game once it has been reviewed.

Next steps

Now that you know how to test and publish your game, check out our launch checklist before submitting your game: Instant Games Launch Checklist. Also please check our Best Practices section for recommendations on design and updates for your game.