This guide describes creating a web app directly within the core Facebook experience. See the Facebook for Websites guide if you instead want to add Facebook capabilities to an external website.
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:
If you wish to start building an App on Facebook now, please refer to our getting started tutorial. If you want to build an app to add to the tab of a Facebook Page then you should refer to Page Tabs.
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#.
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.
If you want to get started with building an App on Facebook right away, please read the getting started tutorial.
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.
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. You can send notifications via the Notifications API or via requests.
The Notifications API allows you to send free-form text messages to any user of your application. It's the most effective way to reengage active users, informing them of important events, invites from friends, or actions they need to take the game. Learn more about this API in the reference guide.
Requests enable users to invite their friends to your application. Although requests can be sent to any user on Facebook, their appearance in the notifications pane and elsewhere on Facebook is more restricted, so it is best to use requests primarily to invite new users.
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).
You can learn more about how to enable users to send request from your app in our getting started tutorial
The News Feed is shown immediately to users upon logging into Facebook, making it core to the Facebook experience.
Facebook 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.
In addition, Facebook also generates aggregated ‘playing’ stories by default. These stories show up in friends' News feed. Gamers and non-gamers alike will see stories that list games their friends are playing the most. These stories are designed to bring new users and significant re-engagement to games by encouraging users to discover games their friends are playing.
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 App Dashboard in the ‘On Facebook’ tab under the ‘Canvas’ section.
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.
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.
The user's Timeline deeply integrates a user's top game activity over a given period of time. This Games Timeline unit highlights the games users play the most, as well as top scores and achievements, allowing for quick re-engagement for the user and discovery among friends.
Developers of apps categorized as 'Games' can publish stories by using the Open Graph built-ins 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 as well as High Score stories when the user earns a new high score. The user needs to grant your app with the
publish_actions permission before you can publish a user's scores and achievements.
In addition the Timeline also showcases recent game activity for the user.
When your App reaches 10 monthly active users it will be automatically queued to be included in the search index the next time we rebuild our search index (we rebuild every 2-4 weeks). After the index is rebuilt your app will be discoverable via Search.
Additionally, you can create a Facebook Page for your App from the App Dashboard. Simply visit the Contact Info section in the App Details tab of the App Dashboard, and click on the “Create Facebook Page” button to create a new Facebook Page.
Hitting Confirm on the next dialog associates the new Facebook Page with your app.
The Page differs slightly from regular Pages; it will have a "Go To App" or "Play Game" button, as well as the following App-related links:
By default, the Page is titled "[YOUR_APP_NAME] Community". You can modify this name at any time subject to the same rules that govern all Pages.
Facebook has a Games and Apps Dashboard that allows users to see outstanding requests as well as recommended Apps and Games to enable them to discover new games as well as re-engage with existing games.
Users can also access all their apps and games feed in one place here.
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.