Apps on Facebook.

com
Getting Started › Apps on Facebook.com
Building an app on Facebook gives you the opportunity to deeply integrate into the core Facebook
experience. Your app can integrate with many aspects of Facebook.com, including the News Feed
and Notifications. All of the core Facebook Platform technologies, such as Social Plugins, the
Graph API and Platform Dialogs are available to Apps on Facebook.com.
This guide highlights how to setup your app to run within Facebook and the use of specific
integration features. The examples in this guide use PHP. These examples are very straightforward
and easily translatable to other languages.
In this document:
• Getting Started
• Authorization
• Social Channels
• Custom Page Tabs

Getting Started
Apps on Facebook.com are web apps that are loaded in the context of Facebook. You can build your
app using any language or tool chain that supports web programming, such as PHP, Python, Java or
C#.
Apps on Facebook.com are loaded into a Canvas Page. A Canvas Page is quite literally a blank
canvas within Facebook on which to run your app. You populate the Canvas Page by providing a
Canvas URL that contains the HTML, JavaScript and CSS that make up your app. When a user
requests the Canvas Page, we load the Canvas URL within an iframe on that page. This results in
your app being displayed within the standard Facebook chrome.
For example, suppose that you have a web app available at
http://www.example.com/canvas. This is your Canvas URL. When you setup your app on
Facebook, you must specify a Canvas Page name that is appended to http://apps.facebook.com/. In
this example, we will use your_app as the Canvas Page name. When the user navigates to
http://apps.facebook.com/your_app in their browser, they will see the contents of
http://www.example.com/canvas loaded inside of Facebook.com.
Note that http://www.example.com/canvas cannot forward to another URL via HTTP
redirect responses, e.g. response code 301, but has to return the response directly.

To set up your Canvas Page and Canvas URL you must first register your Facebook app and enter
in your basic app information. With that complete, click the "Facebook Integration" tab on the left
side of the configuration screen and specify a Canvas Page and Canvas URL:

Because your app is loaded in the context of Facebook, you must be aware of certain size
constraints when designing your user interface. A Canvas Page is limited to a maximum of 760
pixel in width. A Canvas Page can be any height, although you will see scrollbars by default if the
height exceeds the bounds of outer Facebook.com page. You can control this behavior by turning
off scrollbars in the Developer App and using the setSize() function in our JavaScript SDK.

Authorization
In order to create a personalized user experience, Facebook sends your app information about the
user. This information is passed to your Canvas URL using HTTP POST within a single
signed_request parameter which contains a base64url encoded JSON object.
When a user first accesses your app, the signed_request parameter contains a limited amount of user
data:
Name Description
user A JSON array containing the locale string, country string and the age object
(containing the min and max numbers of the age range) for the current user.
algorithm A JSON string containing the mechanism used to sign the request.
issued_at A JSON number containing the Unix timestamp when the request was signed.
In order to gain access to all the user information available to your app by default (like the user's
Facebook ID), the user must authorize your app. We recommend that you use the OAuth Dialog for
Apps on Facebook.com. You invoke this dialog by redirecting the user's browser to the following
URL (replacing the YOUR_APP_ID and YOUR_CANVAS_PAGE with the correct values found in
the Developer App):
https://www.facebook.com/dialog/oauth?
client_id=YOUR_APP_ID&redirect_uri=YOUR_CANVAS_PAGE

Because of the way that we currently load iframes for Apps on Facebook.com, it is important that
you navigate the top window of the user's browser to the OAuth Dialog. Many apps do this by
sending a script fragment to the user's browser setting the top.location.href property to
the dialog URL. Please see the PHP example at the end of this section for an example.
By default, the user is asked to authorize the app to access basic information that is available
publicly or by default on Facebook. If your app needs more than this basic information to function,
you must request specific permissions from the user. This is accomplished by adding a scope
parameter to the OAuth Dialog request followed by comma separated list of the required
permissions. The following example shows how to ask for access to user's email address and their
news feed:
https://www.facebook.com/dialog/oauth?client_id=YOUR_APP_ID
&redirect_uri=YOUR_CANVAS_PAGE&scope=email,read_stream

A full list of permissions is available in our permissions reference. There is a strong inverse
correlation between the number of permissions your app requests and the number of users that will
allow those permissions. The greater the number of permissions you ask for, the lower the number
of users that will grant them; so we recommend that you only request the permissions you
absolutely need for your app.
If the user presses Don't Allow, your app is not authorized. The OAuth Dialog will redirect (via
HTTP 302) the user's browser to the URL you passed in the redirect_uri parameter with the
following error information:
http://YOUR_CANVAS_PAGE?error_reason=user_denied&
error=access_denied&error_description=The+user+denied+your+request.

If the user presses Allow, your app is authorized. The OAuth Dialog will redirect (via HTTP 302)
the user's browser to the URL you passed in the redirect_uri parameter. After the user has
authorized your app, the signed_request parameter will contain the following information on
subsequent requests:
Name Description
A JSON array containing the locale string, country string and the age object
user
(containing the min and max numbers of the age range) for the current user.
algorithm A JSON string containing the mechanism used to sign the request.
issued_at A JSON number containing the Unix timestamp when the request was signed.
user_id A JSON string containing the Facebook user identifier (UID) of the current user.
oauth_toke
n A JSON string that you can pass to the Graph API or the Legacy REST API.
expires A JSON number containing the Unix timestamp when the oauth_token expires.
The following PHP example demonstrates how to access the signed_request parameter and
prompt the user to authorize your app:
<?php

$app_id = "YOUR_APP_ID";

$canvas_page = "YOUR_CANVAS_PAGE_URL";

$auth_url = "http://www.facebook.com/dialog/oauth?client_id="
. $app_id . "&redirect_uri=" . urlencode($canvas_page);

$signed_request = $_REQUEST["signed_request"];

list($encoded_sig, $payload) = explode('.', $signed_request, 2);

$data = json_decode(base64_decode(strtr($payload, '-_', '+/')), true);

if (empty($data["user_id"])) {
echo("<script> top.location.href='" . $auth_url . "'</script>");
} else {
echo ("Welcome User: " . $data["user_id"]);
}
?>

You can learn more about the signed_request parameter including how to validate the
signature in our Signed Request Reference guide. Several of our SDKs, such as the JavaScript SDK
and the PHP SDK make authentication and authorization straightforward.

Social Channels
Facebook Platform provides a number of different ways for users to share with their friends from
your app. We call these Social Channels. Your app can publish directly to a user's News Feed, send
Requests to their friends and leverage our automatic channels.
Automatic Channels
To drive more traffic to your app, we enable some channels automatically as people use your app.
Once a user starts using your app, we create a bookmark to enable users to easily navigate back to
your app from within Facebook. We also publish a usage story to notify their friends that the user
has started to use your app. Lastly, your app is automatically added to the App Dashboard or Game
Dashboard.

Feed
The News Feed is shown immediately to users upon logging into Facebook, making it core to the
Facebook experience. Your app can post to the user's news feed by using the Feed Dialog. The
following example shows how to display this dialog within your canvas page:
<?php

$app_id = "YOUR_APP_ID";

$canvas_page = "YOUR_CANVAS_PAGE_URL";

$message = "Apps on Facebook.com are cool!";

$feed_url = "http://www.facebook.com/dialog/feed?app_id="
. $app_id . "&redirect_uri=" . urlencode($canvas_page)
. "&message=" . $message;

if (empty($_REQUEST["post_id"])) {
echo("<script> top.location.href='" . $feed_url . "'</script>");
} else {
echo ("Feed Post Id: " . $_REQUEST["post_id"]);
}
?>

Requests
Requests are a great way to enable users to invite their friends to your app or to take specific action
like accepting a gift or help complete a task. Your app can send requests by using the Request
Dialog. The following example shows how to display this dialog within your canvas page:
<?php

$app_id = "YOUR_APP_ID";

$canvas_page = "YOUR_CANVAS_PAGE_URL";

$message = "Would you like to join me in this great app?";

$requests_url = "http://www.facebook.com/dialog/apprequests?app_id="
. $app_id . "&redirect_uri=" . urlencode($canvas_page)
. "&message=" . $message;

if (empty($_REQUEST["request_ids"])) {
echo("<script> top.location.href='" . $requests_url . "'</script>");
} else {
echo "Request Ids: ";
print_r($_REQUEST["request_ids"]);
}
?>
For more details about our channels, see our Social Channels core concept document.

Custom Page Tabs

Facebook Pages are a heavily used feature of Facebook. Major brands, celebrities, etc. use
Facebook Pages as their "social home" on the web. One of the most interesting features of Apps on
Facebook.com is the ability for your app to be used within the context of a Facebook Page. You can
find a great example of this kind of integration on the Coca-Cola Page.
In order to enable this feature, you need to specify a Tab Name and a Tab URL (much like you
provided a Canvas Page and Canvas URL previously) that is loaded when the user selects your Tab
on a given Facebook Page. If you support HTTPS traffic, also specify Secure Tab URL. Users
browsing in HTTPS will be unable to use your tab if this URL is empty. You can find these settings
in the "Facebook Integration" section of the Developer App.

Your Tab URL must be relative to your Canvas Page and therefore your Canvas URL. Using our
previous Canvas Page and Canvas URL settings would results in Facebook loading content from
"http://www.example.com/canvas/tab."
As with a Canvas Page, the amount of space available to your app is bounded by the outer context
of Facebook. Since your app is also loaded inside of Facebook Page, the space is smaller (520
pixels) than what is available to on a Canvas Page.

Facebook Page administrators can add your app directly to their Page by navigating to your app's
Profile Page and selecting "Add to my Page".

When a user navigates to the Facebook Page, they will see your Page Tab added in the next
available tab position. Broadly, a Page Tab is loaded in exactly the same way as a Canvas Page.
When a user selects your Page Tab, you will received the signed_request parameter with one
additional parameter, page. This parameter contains a JSON object with an id (the page id of the
current page), admin (if the user is a admin of the page), and liked (if the user has liked the
page). As with a Canvas Page, you will not receive all the user information accessible to your app in
the signed_request until the user authorizes your app.
In addition, your application will also receive a string parameter called app_data as part of
signed_request if an app_data parameter was set in the original query string in the URL your tab is
loaded on. For the Shop Now link above, that could look like this:
"http://www.facebook.com/YourPage?v=app_1234567890&app_data=any_string_here". You can
use that to customize the content you render if you control the generation of the link.
Next Steps
This was a quick survey of the major integration points available to Apps on Facebook.com.
Beyond these features only available to Apps on Facebook.com, you can leverage all the different
pieces of Facebook Platform including Social Plugins and the Graph API within your app.
If you are looking for a real world example to help you get started building Apps on Facebook.com,
please see our Run with Friends sample app. This sample uses most of the pieces of Facebook
Platform and even some advanced features like Real-time Updates.