Facebook Instant Games - Getting Started

With the HTML5 export of your game, you have a huge variety of ways that you can publish your game, like publishing it on your own website or going through a third party portal. One of the most popular methods to get your game out there for people to play is to use the Facebook Instant Games API.

In this article we explain how to get a game uploaded and running using this API, but before continuing please make sure that you are a Registered Facebook developer with access to the Instant Games Developer Platform. You can find more information from Facebook here.

 

Get The Facebook Instant Games Extension

Assuming you have a HTML5 game or demo all ready for playing, you then want to add the Facebook Instant Game Extension to the project. This extension has the functions required to communicate with the Facebook Instant Games API and you won't be able to upload a working instant game without it. You can get just the extension file from the following link:

To add this to your project, simply open the project and then drag the downloaded extension from the file explorer onto the IDE. This will show the following prompt:

InstantGames_AddExtension.png

Click the Yes button, and then in the following window choose Add All then Import:

Instant_Games_Import.png

The extension will now be added to the resource tree of your game, ready for use.

 

Create A Custom HTML File

For the extension to communicate with Facebook, we need to set a Custom index.html file as the game launcher. This file will need to include the following line to include the Facebook Instant API:

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

You can find an example HTML file that calls this script here:

Once you have the HTML file ready, it should be added to your project as an Included File. Your resource tree should now look something like this:

InstantGames_ResourceTree.png

We now need to tell GameMaker Studio 2 to use this custom index file instead of the default HTML, so you need to open the HTML5 Game Options and go to the General section. Here you need click the Included file as index.html dropdown and select the custom index html file that you just added. Once that's done, you then need to tell GameMaker that you want to use the Loading Bar extension, so click the Loading bar extension dropdown and select FBIntantGames_LoadingBar:

InstantGames_HTML5Options.png

 

Graphics Game Options

While you are in the HTML5 Game Options, you should take this opportunity to set the Graphics options. For Facebook Instant Games, WebGL is fully supported but if the game is only available in WebGL then it must be set properly in the settings of the application on the dashboard of the FB application. Facebook also recommend that the initial loading of an Instant Game is less than 1MB in size, so if your game does not use the built-in particle sprites, you should also disable Use built-in particles.

 

Initialising Instant Games In Your Project

With all that done, it's time to add some code to initialise the Instant Games API. The following code is the minimum required by Facebook to get your game uploaded and running, and should be added to the Create Event of the first object to be created in the first room of your game (so some controller or init object):

FBInstantGames_SetLoadProgress(<val>);
FBInstantGames_StartGame(<script>, <script>);

The first of these functions is to tell the Instant Games API that the game has loaded and is ready to start and you would normally wish to use 100 here to indicate that the game has loaded 100%. If you have further elements that you wish to load or add (like creating sprites from surfaces, or adding audio, etc...), then you can set this to a value less than 100 and increment it as required.

The second line is to tell the API that your game has started, and it requires you to provide two script names as strings, so for example:

FBInstantGames_StartGame("gmcallback_gamestarted","gmcallback_onpause");

These scripts will be called asynchronously whenever the Instant Games API generates a relevant callback. The first script will be called when the API returns that it is ready and the game can start to be played so you can go ahead and permit player interaction, start music, etc... and the second script will be called whenever the API detects a "pause", enabling you to pause any music and pause any action in your game.

IMPORTANT! You cannot use the GML keywords "other" and "self" as they have no context when checked as part of a callback from the Instant Games functions. Using these keywords in any callback will cause an error, so they must not be used.

Note that the scripts all start with "gmcallback_". All callback scripts must be named with this suffix! In this way, the compiler will know not to obfuscate them and permit the extension to call them when required.

 

Packaging Your Instant Game

Your game now meets the minimum requirements to be permitted onto the Instant Games platform, and so it's time to package it ready for uploading. To start with you simply need to click the Run button in GameMaker Studio 2 (make sure you have the Target Manager set to HTML5) to run the game in your browser:

InstantGames_CreateZip.png

With the game running, browse to the to the folder from where the game is being run. You can find the full path to this folder from the Micro Web Server:

InstantGames_WebRoot.png

In this folder, select the html5game folder and the index.html file and add them to a Zip file:

InstantGames_Files.png

This Zip file will be what we upload to Facebook as our Instant Game.

 

Setting Up The Game On Facebook

Now you have your game file packaged, it's time to set up your Facebook Developer page with the App details. For that you need to go to your Developer Apps dashboard (here) and select "Add a New App". Enter your games title and your contact email in the pop up, before clicking "Create App ID":

FB_CreateAppId.png

From the App dashboard, you need to set up the Instant Games section, and click the button labelled "Setup" then fill in the required information:

FB_InstantGameSetup.png

Once you've saved the changes you will need to click on Web Hosting in the products list on the left tab and click the "Upload Version" button:

FB_WebHosting.png

Now, browse to where you saved the Zip we created previously and select it and click "Upload":

FB_Upload.png

After uploading the status of that build will be set to Processing on the app dashboard. Within a minute or two this should change to Standby. If it doesn't - and it may not the first time as the upload and processing may fail for external reasons - then just upload the same Zip file again as a new version.

Once the status is Standby, hover over the status and a "star" icon labelled "Push to Production" becomes visible. Click this now, but note that this doesn’t publish it publicly - at this stage only developers whose Facebook accounts have been added to the game will be able to play the game.

FB_PushProduction.png

Your uploaded game status should now change to "Production". You now need to go back to Products > Instant Games > Details, and scroll down to the bottom of the page to find the button labelled Share Game.

FB_ShareGame.png

Clicking this will create a generated post for the game to be posted on your own timeline with the visibility set to "Only me":

FB_Post.png

When you go to your own Facebook profile, you should now see the post you just generated, and  clicking on it should launch your game. This should work exactly the same on both mobile devices or desktop/browser Facebook. If you get any errors then check the console output in your browser's Developer Tools and you should be able to see what errors are occurring.

Summary

With that, you have successfully created and uploaded a Facebook Instant Game ready project. As we mentioned at the start of the article, this outlines the absolute minimum requirements to get a game onto Facebook in this way, however there are other more complex things which the Instant Game API can do. For more information, please see the following article:

  

 -

Have more questions? Submit a request

0 Comments

Article is closed for comments.