Build

Hosting Games on Facebook

The Web Games on Facebook and Facebook Gameroom platforms are no longer available for new submissions. This documentation is intended solely for developers with existing games. To learn more, read our blog post.

Games on Facebook are hosted as a portal, the actual game content is hosted from your own web server. By configuring your Facebook Web Games URL, you can make your game available on Facebook.com, where it will appear within an iframe. On Facebook, you can make the most of App Center and game recommendations to provide discoverability for your content, and use the social features of the Facebook platform to make your game more social.

How games appear on Facebook

In your app settings, there's a field for Facebook Web Games URL. This field configures the iframe that loads when a player loads your game. This puts you in complete control your game, and you're free to update versions and content at your own release cycle. See your App Settings here.

When a player on Facebook.com loads your game, Facebook will make an HTTP POST request to the Facebook Web Games URL provided under App Settings. The response to this request should be a full HTML response that contains your game client. You can use the Facebook SDK for JavaScript to authenticate users, interact with the frame, and to access dialogs in-game, so be sure to include that in your game's HTML. See here for more information on Login for Games On Facebook.

The iframe where your game appears on Facebook.com

The HTTP POST request made to your Fcaebook Web Games URL will contain additional parameters, including a signed_request parameter that contains the player's Facebook identity if they've granted basic permissions to your app. If a player is new, the signed_request parameter value will be useful to validate that this request did indeed come from Facebook. Read more about signed requests in the Login for Games on Facebook guide.

Domains and SSL Requirements

HTTPS is required when browsing Facebook.com, and this requirement also applies to game content. Therefore a valid SSL certificate is required when serving your game content. When you configure your web server to host your game, you'll need to make sure it's on a valid domain that you own, and that you have a valid SSL certificate for this domain.

Inbound links

It's possible to pass your own custom parameters to the game launch query. This is useful for tracking the performance of OG Stories, referral sites, or for tracking shared link performance.

There are two ways to accomplish this:

  1. Append query params to the end of your shared link
  2. Add relative links on the game's URL path

Query Params

The URL for your Facebook game will always be https://apps.facebook.com/{namespace}/ . When provide promotion links, either from your App Page or other places on the internet, you can append query params here. For example

https://apps.facebook.com/{namespace}/?source=mysourceid

These query params will be preserved on game launch, and passed to your server in addition to the signed_request.

You can also share links that take players directly to portions of your game. If you are using PHP or have launch scripts, this can be helpful to start players into areas of the game outside of the standard flows. The full path will be preserved in the request to your server. For example, if you share a link to

https://apps.facebook.com/{namespace}/special_launch.php

Facebook will make a request to

https://{your_web_games_url}/special_launch.php

when loading the iframe for your game.

Understanding Game Launch

When players launch your game on Facebook, a query parameter signed_request is added to the HTTP request to your server. This signed_request can be decoded to provide user information, and a signature to verify the security and authenticity of this data. You can parse this parameter like this:

  1. Split the signed request into two parts delineated by a '.' character (eg. 238fsdfsd.oijdoifjsidf899)
  2. Decode the first part - the encoded signature - from base64url
  3. Decode the second part - the payload - from base64url and then decode the resultant JSON object

If no user_id field is present, then the player has not given public_profile permissions to your game yet.

New User Flow

If you parse the signed_request and discover the player is new and has not granted basic permissions to your game, you can ask for these permissions on load, via the Javascript SDK.

FB.login(function(response){
  // Handle the response
});

You can optionally ask for more permissions, such as email, by adding them as a second parameter.

FB.login(function(response) {
  // Handle the response
}, {scope: 'email'});

Other important information in this payload will be age settings and locale preferences for the player. See Login for Games on Facebook for more information.

Best Practices

Developing on a local machine

While you're developing your game, you'll probably want to host it on a web server running on your local machine to speed up your edit-compile-test cycle. The most common way to do that is to set up a server stack like XAMPP. You will also need to create and install a local SSL certificate so that this server supports HTTPS.

Moving to a production server

Once you're ready to take your game live to the world, you'll have to arrange for hosting on a public-facing web server.

Improving hosting performance with a CDN

As your traffic grows, you may want to consider using a content delivery network (CDN) such as Akamai or CDNetworks to reduce your hosting costs and improve performance. A CDN works by caching your game's content at various locations on the internet. This means players will have game assets delivered to their client from a closer location. Your players get a quicker loading game, and your server is protected from excessive traffic.