Why Build an App on Facebook?

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.

In this document we will explain the following concepts:

Canvas Page: The Page in which your app is loaded.
Social Channels: The key channels that help you grow your user base and re-engage existing users.
Analytics: Accessing analytics for your application.

Canvas Page

Apps on Facebook are web apps that are loaded in the context of Facebook in what we refer to as a Canvas Page. You can build your app using any language or tool chain that supports web programming, such as PHP, Python, Java or C#.

Canvas for your app
Apps on Facebook 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.

The canvas chrome is 760px width by default but you can set it to be a Fluid Canvas so that it is left aligned and takes up the full width and height of the user browser.

Bookmarks for quick re-engagement
Once a user starts using your app, we create a bookmark to enable users to easily navigate back to your app from within Facebook. These Bookmarks are available on the Facebook homepage as well as on the Canvas Page on the top right corner.

These Bookmarks are ordered based on how often and recently the user used your app. The red counters on the bookmarks notify users of outstanding Requests 2.0 related requests for your apps and encourage them to respond.

Real-time social app activity
To drive greater engagement with platform apps, on the upper right side of canvas pages we present a live ticker of app-specific updates from the users'' friends.

When a user first enters an application, we present stories that are most relevant to that app. These stories are about the user and their friends interacting with the app or game currently being used.

As a user continues to use the app, we broaden what is presented to updates from friends using the app that the user both currently uses and has not yet installed.

Note that content in the app ticker is specific to the app context the user is in. So, if the user is playing a game, the messages the user will see will be specific to what their friends are doing in other games only.

Discovery stories
To help users discover new apps and games, Facebook generates ''playing'' and ''using'' stories by default, when friends use an app or play a game respectively. These stories show up in the canvas Ticker in real-time. The user is marked as playing if we have had a ping from them in the last 15 minutes. We ping 5 seconds in, then 5 minutes in, then every 10 minutes. We change the language to ''played'' and ''used'' if the user played or used the app more than 15 minutes ago.

Developers of app associated with more personal behavior such as dating, weight management or pregnancy, can turn these stories off by disabling the social discovery field in the Developer app in the ''On Facebook'' tab under the ''Canvas'' section.

Game stories
Developers of apps categorized as ''Games'' can publish additional stories into the ticker by using the Graph APIs for achievements and scores. These stories are only shown to users, when using an app categorized as ''Games''.

The achievements API allows you to publish stories about the user and their friends achieving a set of achievements you define for your app. The scores API allows you to publish stories about the user and their friends passing each others'' scores in your app. The user needs to grant your app with the publish_actions permission before you can publish a user''s scores and achievements.

User control
On the Application Settings Page users can control the maximum audience each app can share with on their behalf. So if users want people to see that they are playing one game, but not another, they can control that.

They can also control individual stories by x-ing them out real-time from the ticker.

Social Channels

To drive more traffic to apps on Facebook, we enable various channels that enable new users to discover your app as well as existing users to re-engage with your app. Each channel is designed to help engage users and our algorithms help surface the best content for each user. The current channels include:

Bookmarks enable users to easily navigate back to your app from within Facebook. Bookmarks are automatically added for your app after the user engages with your apps. The bookmark will appear on left column of the homepage as well as on the top right of a Canvas Page. Users can add a bookmark to ''favorite'' which pins them to the top. Bookmarks also show a counter next to them which represents the number of outstanding requests for the user for your app. The more link next to the app bookmarks takes the user to the app dashboard which shows the outstanding app requests as well as the full list of apps the user has authenticated.

Notifications on Facebook are meant to provide prominent but lightweight heads-up about interesting changes to content relevant to users. Requests from your app may trigger a notification to users who will find it relevant.

Requests are a great way to enable users to invite their friends to your application. You can also use requests to have a user notify their friends to take a specific action in your app, such as accepting a gift or helping the user complete a quest.

There are two types of requests that can be sent from an app:

User-generated requests: These requests are confirmed by a user''s explicit action on a request dialog. These requests update the bookmark count for the recipient.

App-generated requests: These requests can be initiated and sent only to users who have authorized your app. You should use these requests to update the bookmark count to encourage a user to re-engage in the app (e.g., your friend finished her move in a game and it''s now your turn).

News Feed stories
The News Feed is shown immediately to users upon logging into Facebook, making it core to the Facebook experience.

Discovery stories
Similar to the discovery stories in the Ticker, Facebook also shares stories with friends when a user starts using a new app or first installs a new game. These installation discovery stories show up in friends'' News Feed and enables users to discovery popular apps their friends are using. Similar to the Ticker discovery stories, you can turn these stories off by disabling the social discovery field in the developer app in the ''On Facebook'' tab under the ''Canvas'' section.

Publishing stories
In addition you can publish content to the stream using the Feed Dialog. You can prompt users to publish stories about what they are doing in your app. If a user chooses to publish, the story will appear on the user''s profile and may appear to the user''s friends'' News Feeds. Stories published from your app will include a link to your app, and can optionally include a rich attachment. You can learn more about how to enable users to publish stories from your app in our getting started tutorial.

Each new app has its own App Profiles Page (for example, see Facebook Live ''s page). This Page is similar to other Pages and user profiles on Facebook, and it includes Wall and Info tabs as well as other configurable tabs. When users search for your app, this Page shows up in the search type-ahead or on the search results page. From this Page, users can navigate to your app or Like your Page. You can also choose to update users who have liked your profile Page with news about your app.

You can submit your app to search to ensure that users can find your app in the Facebook search box. Simply go to the Developer App, and go into edit settings. In the left nav under ''Related Links'' you can find and click on ''Submit to Search''.


Use Insights for your app to track how users are interacting with your app to build the best possible experience for your users. For app administrators, Insights includes feedback for stream stories, referral traffic to your app, a breakdown of what user actions contribute to active user count, demographics on authorized users and active users, and the number of times permissions are prompted and granted.

In addition, it provides diagnostics for your app so that you can track API errors as well as get access to allocations and throttling information.

You can access Insights for your app directly through the Insights Dashboard or by selecting your app in the Developer app and clicking the "insights" link.

Developers can also track referral traffic from the Ticker stories via the following ref_params.