Getting Started with the Facebook SDK for Unity on Facebook Canvas

Note: This guide is organized to follow after the shared setup steps for the Facebook SDK for Unity detailed in the Getting Stared guide. If you have not yet completed these steps please do so first.

This document provides an follow up step-by-step guide to get started with the Facebook SDK for Unity on Facebook Canvas. We will build and deploy the sample Unity app bundled with the Unity SDK to allow you to get working on a Facebook integration quickly and effectively. If you're more comfortable working on iOS or Android, you can switch to the Getting Started guides for those platforms.

WebGL vs Unity Web Player

In Unity 5.0, the WebGL deployment target was introduced as a new way to build Web games. Unlike deploying with the Unity Web Player, WebGL has no dependency on a browser plug-in; games will simply run in any modern browser.

An additional motivation for deploying with WebGL is to support browsers where the Unity Web Player is no longer a viable solution. One such browser is Google Chrome, which ended general support for Netscape Plug-in API (NPAPI). Since Unity Web Player is an NPAPI plug-in, these changes make the Unity Web Player unusable in Chrome.

Configure your app for Facebook Canvas

Step 1: Switch to a Web Platform

Go to the Unity Editor. From the menu, choose 'File', 'Build Settings…' In the Build Settings dialog, under 'Platform', select 'WebGL' or 'Web Player' as the target and click 'Switch Platform'. Ensure the sample project scenes have been added to the 'Scenes in Build' as previously described here.

Note: Select 'WebGL' to build with HTML5 technologies or select 'Web Player' to build for the Unity Web Player to target older browsers.

Unity Build Settings

Step 2: Build

With the Build Settings dialog open, click the 'Build' button. When prompted for an output directory name, call it web.

Unity Web Build

See the Building for Web section below for best practices.

Step 3: Deploy the game

Upload the files from the output directory to an SSL/TLS-capable Web server. The game object must be served over HTTPS. During development you will find it easier to serve your game file from a local web server supporting HTTPS. Plenty of solutions exist on the web to help you get started, most of which are free and open source. Check out XAMPP as a starting point.

Step 4: Configure Facebook Canvas App Settings

Navigate to your app's Facebook settings. Go to the 'Facebook Canvas' pane in the Basic tab of your app's 'Settings' page and fill in the 'Secure Canvas URL' field with the URL where you are serving your game. Now save your changes.

When using version 7 or later of the Unity SDK, ensure you leave both 'Legacy Unity Integration' and 'Unity Web Player Install Flow' un-checked. These are legacy settings for usage with older versions of the Unity SDK.

Facebook Canvas App Config

Step 5: Run

Navigate to '[your_app_id]'. The example app should be running in the Facebook canvas.

Unity App running on Canvas

Congratulations, you have setup a basic Unity sample and have it running successfully on!

Building for Web

Building with WebGL requires a special consideration. Take note of the steps outlined below:

  1. Read through the Unity documentation on WebGL before you begin building to the WebGL deployment target. There are a number of limitations in features and in browser compatibility to be aware of such as no support for threading or sockets.

  2. Use the latest Unity 5 Release. There are numerous improvements for WebGL in each Unity 5 release and you should not be building without them.

  3. Refer to the Unity documentation on building a WebGL project for information about optimizing build size and performance.

  4. Learn from the community. Read blogs from developers who detail their transition to WebGL, like Jelly Button and Leviathan Games.

  5. Check out the webinar recording embedded below for details on common challenges with WebGL deployment and best practices for web games.

Hybrid Deployment

Due to the varied levels of support for WebGL across browers it can be desirable to maintain both a WebGL and Web Player deployment of your game.

In order to accomplish this you will need to build and host both versions of your game. Instead of pointing the Secure Canvas URL setting to one of the builds, create a new Pre-Loader that will decide which build to redirect to.

// Simple Pre-Loader Example in Javascript
// Redirects Google Chrome v42 User Agent to WebGL
// Redirects all else to Web Player
<!DOCTYPE html>
var chromeVersion = window.navigator.userAgent.match(/Chrome\/(\d+)\./);
if (chromeVersion && chromeVersion[1]) {
  if (parseInt(chromeVersion[1], 10) >= 42) {
    window.location = "/unity/webgl";
window.location = "/webplayer/webplayer.html";

There are more advanced ways to detect support of the Unity Web Player plugin, but we will not detail those here. Consider starting with UnityObject2.js

WebGL Webinar

Next steps

Feel free to explore the sample app to try out the various features of the SDK. Start by clicking the FB.Init button at the top of the sample, which will enable the other features of the sample. As a next step, modify the code included in the sample and add it to your game project; this will get your Facebook integration off to a flying start.

For more details on integrating the Facebook SDK into your Unity game, check out the SDK reference and SDK Examples. And if you'd like to see how easy it is to deploy to iOS and Android, check out their respective Getting Started guides.