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:
- 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
If your app is classified as a game and a user starts playing, we create a bookmark to enable users to easily navigate back to your game 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 counters on the bookmarks notify users of outstanding requests for your games and encourage them to respond.
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:
Newsfeed stories
The News Feed is shown immediately to users upon logging into Facebook, making it core to the Facebook experience.
Discovery stories
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.
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.
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.
Timeline
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.
Search
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.
Page
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.
You can also associate the app with an existing Page assuming that:
- You are an admin of both the app and page.
- The page is in the 'App Page' category.
- The page name is a substring of the app name (For example an app called 'Myapp' with a page called 'Myapp' is okay, but an app called 'Myapp' with a page called 'Myapp USA' is not).
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:
- Block App
- Remove App
- Contact Developer
- Report App
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.
Bookmarks for Games on Facebook.com
Bookmarks enable users to easily navigate back to your game from within Facebook. Bookmarks are automatically added for your game after the user starts playing. 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 as a '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 game. 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.
Requests for Games on Facebook.com
Requests on Facebook are meant to provide prominent but lightweight notifications about interesting changes to content relevant to users.
The Notifications API allows you to send free-form text messages to any user of your game. 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 game. 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 a game:
- 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).
Games & Apps Dashboard
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.
Analytics
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
App Dashboard and clicking the "insights" link.
Next Steps
