Canvas Applications

What is a Canvas Application?

In addition to standalone  Web and desktop applications, Facebook also supports “Canvas” applications. Canvas applications are integrated directly into the user experience on the facebook.com  Website. Canvas applications have the ability to display information on a user’s profile, publish to a user’s mini-feeds, and spread themselves organically through Facebook’s social network. For more information about building a Facebook Canvas application, read Anatomy of a Facebook Application.

Canvas applications can be one of two types. FBML Canvas applications leverage Facebook Markup Language (FBML) to provide a consistent integrated user experience for Facebook users. FBML canvas applications essentially are constructed by the developer building an FBML “ Web service” that can be called by the Facebook Server and return some FBML. The Facebook server will then translate that FBML into HTML to display on a Facebook-hosted page. The second type of Canvas application is the IFrame Canvas application. In this type of canvas application, the Facebook  Web page will simply show an IFrame linked to application content hosted by the developer’s server. This type of canvas application cannot leverage FBML functionality, but does have the advantage of being a much more typical  Web development experience.

The Facebook Developer Toolkit provides infrastructure for building both types of canvas applications. The facebook. Web assembly contains CanvasFBMLBasePage, CanvasIFrameBasePage, CanvasFBMLMasterPage, and CanvasIFrameMasterPage. You can use the BasePages if you want each of your pages to inherit from that class, or you can use the MasterPages if you would rather create one master page which hosts all of your other pages. No matter which method you choose, these pages take care of all of the plumbing needed to successfully host a canvas application on the Facebook site. See Sections 5.3 and 5.4 below for a detailed walkthrough. In addition, you can see samples of both types of Canvas applications at the below urls. The FBML sample is a reproduction of Facebook’s Smiley application. This shows how to leverage all the various facebook integration points. We also put together a document that walks through and describes all of the code.

How an FBML Canvas Application Works

FBML canvas pages are a little bit different but are still pretty straightforward. When the user requests your canvas page (for example, http://apps.facebook.com/yourapp/canvaspage), Facebook doesn't send back a response immediately; instead, Facebook sends an HTTP POST to a callback URL on your server (as in http://www.yourserver.com/callbackurl/canvaspage). The fb_sig parameters get sent as part of the POST rather than as part of the URL. Facebook then expects your server to return FBML, and then converts that FBML into HTML and sends it back to the user's browser. FBML is like HTML, but it lets you include social content inline in your markup.

So, if you want to show Facebook data like names and pictures in FBML, you don't need to make calls to the Facebook API; you can just use tags like fb:name and fb:profile-pic to reference the data directly. If you want to use data like birthdays, then you'll still need to use the API, just as you would on an IFrame page.

Here's a diagram of how an FBML canvas page works. Most of the time, you won't need to make any API calls, so those arrows are dotted in the diagram.

How an IFrame Canvas Application Works

IFrame canvas pages are pretty straightforward. When the user loads your application's canvas page on Facebook (for example, http://apps.facebook.com/yourapp/somepage), Facebook renders a Web page that contains the Facebook chrome surrounding your IFrame. The IFrame has a URL to your callback URL, and Facebook appends a number of parameters, like http://www.yourdomain.com/callbackurl/somepage?fb_sig_in_iframe=1&fb_sig_locale=en_US&fb_sig_time=1221720862.9318&fb_
sig_api_key=48102584111d14a9c2e41dd28ea637d7&fb_sig=
e656792696ae913c1fc34eeff2d79f75

The fb_sig parameters give more information about which user is logged into your application, let you verify that the request is indeed coming through Facebook, and so forth. (For a description of the parameters, see Authorizing Applications.) You can put whatever content you want into the IFrame and it will be rendered inside.

To make your Facebook application a richer social experience, you'll want to include some social content like names and profile pictures, and sometimes you'll want to get some data from the Facebook API to determine which content to show. To show this content without using FBML, you need to use the Platform API and render it yourself.

Here's a simple diagram of how all this works: