Platform Basics
From Facebook Developer Wiki
Contents |
About Facebook Platform
With Facebook Platform, Facebook and third-party developers like you are creating an ecosystem to help people share information and make the world a more open place. Facebook Platform offers a standards-based Web service with methods for accessing and contributing Facebook data as well as display and distribution layers for presenting your application on Facebook.
Through Facebook Platform, you have access to Facebook's representation of the social graph: the network of connections and relationships through which people communicate and share information in the real world. This means you can create uniquely social, uniquely relevant experiences for your users.
The combination of integration into the Facebook Web site, access to the social graph, and new business opportunities that Facebook Platform offers makes it a unique development platform, enabling you to be on the cutting edge of technology while having an impact on millions of users.
Some Basic Concepts
Facebook applications are applications that use Facebook Platform to access and incorporate Facebook social data. Facebook applications can be developed for use inside the Facebook Web site, on standalone Web sites, on desktops, or even on mobile devices.
With the introduction of Facebook Platform, all applications (including those developed by Facebook) can be added or removed by a user, which will add or remove an application from a user’s account. Users can add and remove applications at will.
Users can also authorize applications (by “logging in” to an application) to access their user data.
The social graph, in addition to providing social context to make a user’s experience more relevant, also enables a viral distribution model. Valuable content and applications themselves can spread through a user’s connections, meaning that a great application can rapidly be used by millions of people.
Applications developed for use inside Facebook can use integration points into the Facebook site, which you can use to give your users a seamless experience inside Facebook. Applications can also provide canvas pages specific to their applications, which users can access at http://apps.facebook.com/your_app/.
Integration Points into Facebook: The Photos Example
Facebook Platform includes integration points into the Facebook profile, which you can use to give your users a seamless experience inside Facebook. We've tried to expose a broad variety of integration points (including everything we use to build Facebook applications) for your use. One way to explore available integration points is by taking a look at how Facebook's popular Photos application integrates into the Facebook website.
Let's start with profile integration.
Feed: An application can publish content into a user's Feed, appearing on the user's Wall tab. These stories are most effective when they involve primary actions taken by or on the owner of the profile, are recent events (occurring in the past 24 hours), and involve the profile owner's friends. For instance, Photos might generate a Feed story like "Kate tagged Caitlin in a photo," alongside a preview of that photo.
Profile box: The profile box provides a space for the application to represent itself on a user's profile. Users think about profiles as representations of themselves, so profile boxes are best used as a way for users to express themselves, not a place to consume content. Profile boxes are most engaging when they showcase recent interactions of a user with her friends or with your applications, or show recent relevant content.
Publisher: Applications can integrate into the Publisher so users can create or find rich content and post it directly into their own or their friends' Walls. And these stories can leverage any of the new Feed story sizes — see below for more details.
Feed Forms: Feed forms are special FBML components that allow applications to publish Feed stories on the behalf of users. Your application can publish directly into the user's and the user's friends' Feeds.
Bookmarks: If a user has bookmarked your application, it will appear in the Applications menu on the bottom left side of the viewer's Facebook profile, which gives the viewer an easy way to always access your application.
Application Info Sections: The Info tab on the profile allows users to express their interests in a more structured way than before. Users can add structured information from your applications by way of application info sections. An application info section is a list of text and/or images provided by your application.
Application Tabs: Application tabs let users feature full canvas-like pages for applications they enjoy the most. Tabs behave like a hybrid of a canvas page and a profile box.
Boxes Tab: The Boxes tab contains application profile boxes. Users can move profile boxes from the main profile to the Boxes tab and vice versa.
There are also several integration points available outside of a user's profile.
Message Composer and Wall: Users of your application can include relevant attachments from your application in Facebook messages or as part of Wall posts.
Canvas pages: You can build a full presence for your application on canvas pages – you control the look and feel as well as the functionality of the pages. This is a great place to provide an in-depth experience for your users, build a community, encourage interaction, and surface content to users. Canvas pages which don’t require user context can also be indexed by external search engines.
News Feed: This is the easiest way for users to become engaged with your application. News Feed operates probabilistically, choosing the most relevant stories for each user, so it’s important to provide stories that your users will find valuable. The most effective News Feed stories contain information a user will find interesting, involve a user’s friends, and give the user a preview of what the user will see should she engage more deeply with an application.
Notifications: Your application can send notifications to a user. Be forewarned that your application's ability to send notifications will be impacted if users mark notifications as spam. It's important to only send notifications with real updates about a user's relevant interactions on your application.
Of course, many of these integration points are controlled by the user. The user can choose at any time not to show profile boxes, application info sections, or Feed stories from an application.
Understanding Platform Operations
Your application's interactions with the integration points above can occur in two ways: through the Web service API, and callbacks to your site from the canvas pages.
Note that you can use FBML to display your application. FBML is essentially HTML, restricted to not allow some tags, but augmented by Facebook-specific tags that let you seamlessly use display elements, social elements like the wall, privacy, and more. Whenever your application creates some piece of unique content for display, the language used will be FBML, in the same way that you’d use HTML to display your own pages. FBML is extensively documented on the Facebook Developers Wiki.
Facebook API Web Service
Once a user has authorized your application, you receive a temporary session key which grants you the right to make calls to the API Web service (api.facebook.com/restserver.php) on that user's behalf. All API calls made with that user's session key return information as the user would see it; so, the list of friends returned from friends.get using a user's session key would be the friends of the calling user. The photos returned from an album in a call to a photos.* method would be the set of photos that user can see in that album (depending on the privacy settings, a viewer might see no photos). You can prompt the user for the offline access extended permission so you can access that user's data without an active session.
If a user logs out of Facebook or removes your application, the session key is invalidated, and you can no longer act on that user's behalf nor access any data on behalf of the user.
Most data returned from our Web service is simple XML, defined by an XML schema document at http://api.facebook.com/1.0/facebook.xsd. You can use this to create bindings, run XSLT on the results, or simply use as a reference to understand the data being returned.
In addition to receiving data through the API, you can make changes to the parts of the site you control through the API. In this way, you are pushing data to Facebook, including FBML for display. Methods exist in the API to:
- Push application-defined FBML to the calling user's profile, which controls the profile box for your application, and any other profile integration points relating to your application she sees.
- Push application-defined content to a user's Feed.
- Send application-defined notifications to a user.
Canvas Pages
Every time a user accesses your canvas page (apps.facebook.com/your_app/somepage?some_arguments=...), we send your Web server the user ID (uid) of the viewing user and the page arguments. In return, you publish FBML that gets displayed immediately to that user on that page. Views of your canvas pages on Facebook and requests to your servers are one-to-one. When rendering this content, you may of course make calls to the API, and use whatever data you have available to construct this page. This request is analogous to a Web request to your regular Web site, with FBML and a user’s social context available to you.
There is no limit to the depth and breadth of your tree of canvas pages. Structure them however you like.
User Data Vs. Application Data
When designing your application, keep in mind the distinction between user data and application data. Any data provided directly to you by users is your data, which you can use as you like. Data provided by the Facebook API belongs to users and is only temporarily authorized by a user specifically for your responsible use.
Aside from temporarily caching some data to assist with storing, you can never store or redistribute any data provided by Facebook Platform. The only exceptions are data that are storable indefinitely, largely identifiers that are usually used as keys pointing to a user's data gathered by your application. Please refer to the Facebook Developer Terms of Service for more information.
