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 at
http://developers.facebook.com/anatomy.php.
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 can not
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.
IFrame canvas
pages are pretty straightforward. When the user loads your
application's canvas page on Facebook (say
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. 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:

FBML canvas pages are a little bit different but are still pretty straightforward. When the user requests your canvas page (say 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.
