You are on page 1of 26

http://174.37.50.

154/app/677644/home
?url

caused too many redirections.


http://apps.facebook.com/facial-video-ghhgee/

The URL http://174.37.50.154/app/677644/publisher caused too many redirections.

1. Application Directory
2. Application Profile
3. Canvas Page
4. Profile
a. Profile Box
b. Applications Menu
5. User Dashboard
6. Interacting with Users
a. Bookmarks
b. Application Tabs
c. Boxes Tab
d. Application Info Sessions
e. Publisher
f. Feed Forms
7. Privacy Settings
8. News Feed
9. Alerts
10. Requests
11. User Dashboard
12. Interacting with Users

http://apps.facebook.com/
facial-video-ghhgee/
Facial Videos
Facial Videos

Annamarie O'Brien

Facial Videos

Barbara Swanson

Facial Videos

Facial Videos
Facial Videos

Jeanne Martin

Facial Videos

John D Shine

Facial Videos

Lenny Smith

Facial Videos

Alumina Sector

Anatomy of an App
Guiding Principles

A Facebook application can take on many forms. However, to fully utilize the
suite of integration points and deliver a full user experience, we recommend
integrating your application into the following areas of the Facebook profile:

Application Directory
Application Profile
Canvas Page
Profile

1. Profile Boxes
2. Applications Menu
3. Bookmarks
4. Application Tabs
5. Boxes Tab
6. Application Info Sessions
7. Publisher
8. Feed Forms

Privacy Settings
News Feed
Alerts
Requests
User Dashboard
Interacting with Users

On this page, you'll see how our sample application Smiley integrates many of these various
components. Note that none of these integration points are mandatory, but the more you include
in your application the richer the user experience becomes

Application Directory

Many users may find your application by browsing the Casebook Application Directory. This is
where beautiful imagery and concise, descriptive text pay off. You need to submit your application
to Passbook so it can be included in the directory.

Application Profile

The Application Profile tells users about your application and is accessed from the Forsook
Application Directory. It should inspire users to interact with your application. The profile is a
Face-book Page

Canvas Page

This is the main page of your application on Facebook. Application canvas pages appear within the
Facebook frame and can either be FBML (Facebook's version of HTML) or an external Web site
presented within an iframe.

Profile

The Facebook profile is the online representation of a user's real world identity. We have included
many integration points on the profile. This enables you to empower users to express themselves
through your application.

Profile Box

The profile box is usually the place to show the most recently updated information or the most
recent actions of the user. This information should reflect how the user would want to represent
their identity through your application on their profile.
The user can choose to put your box on the main section of her profile (the Wall and Info tabs -
see Smiley in the lower left corner of the image), or can put it on the Boxes tab (see below).

Applications Menu

The Applications menu is where users go to access your applications. They can bookmark
applications, edit application settings, and go to their recently viewed and bookmarked

applications.

User Dashboard

The user dashboard is usually accessed at the top of the application's canvas page. This is where
users manage their own content within an application or see information about another user's
content within that application.
To create a dashboard, use the fb:dashboard FBML tag.

Interacting with Users

While the current version of the API does not support performing Facebook-specific actions
directly, you can direct your users to various Facebook pages to perform an action. To do this, link
the user to one of the following pages:

To... Use this URL...


View the
specified
http://www.facebook.com/profile.php?id=XXXXX
user's
profile.
Poke the
specified http://www.facebook.com/poke.php?id=XXXXX
user.
Send a
messag http://www.facebook.com/message.php?id=XXXXX&subject=XXXIX&msg=XXXIX
e to the Note: {{c|subject}} and {{c|msg}} parameters are optional ways to pre-fill the
specified contents of the message (the user will still be able to edit the message before sending).
user.
Add the
specified
http://www.facebook.com/addfriend.php?id=XXXXX
user as
a friend.
See
photos
taken by
http://www.facebook.com/photos.php?id=XXXXX
the
specified
user.
Read or
post on
the
http://www.facebook.com/wall.php?id=XXXXX
specified
user's
Wall.
Read
the
specified http://www.facebook.com/notes.php?id=XXXXX
user's
notes.
Note: Casebook dozen't look fondly upon Pammy behavior, so please don't encourage your users
to abuse this functionality.
Bookmarks

Bookmarks appear on every user's home page as well as on the Applications menu.

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

More information about tabs and how they behave can be found on the Developers Wiki
Boxes Tab

The Boxes tab contains application profile boxes. Users can move profile boxes from the main
profile to the Boxes tab and vice Visa.

Application Info Sessions

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.

When a user chooses to add an application info section, you set the format with the profile.seating
API call.

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' Mini-
Feeds.

Privacy Settings

Users can set their privacy options from your application's privacy/settings page. These options
include approval for publishing stories...
... and whether the user wants to add or remove your application's profile box, tab, and info
section, and who can see these elements.

A user can also decide whether to add a bookmark for your application. Bookmarks appear on the
Applications menu — see above.

News Feed

Applications can access News Feed and post stories to it. Each user has a maximum number of
News Feed stories that they can see from all applications. Once that maximum is reached they
cannot see any more application stories during that sweep. For example, the Photos application
publishes News Feed stories about photos your friends have uploaded recently.

You send News Feed stories as notifications; use Notifications.send.


In addition, your application can post stories directly onto users' profiles by using Feed forms (see
above).

Alerts

Applications can send notifications to a user through email. Users must grant your application
permission before they can receive email. The user of the application who triggers this action
must approve of the email. You send email with notifications.sendEmail.

Requests
Applications can create requests that show up at the top right of a user's homepage. These
requests are usually initiated by a user's friend and often require the user to take some form of
action. An example of this in the Photos application is a photo tag request confirmation.

Like News Feed stories, requests are also sent in the form of notifications, so use
notifications.send.

User Dashboard

The user dashboard is usually accessed at the top of the application's canvas page. This is where
users manage their own content within an application or see information about another user's
content within that application.

To create a dashboard, use the fb:dashboard FBML tag.

Interacting with Users

While the current version of the API does not support performing Facebook-specific actions
directly, you can direct your users to various Facebook pages to perform an action. To do this, link
the user to one of the following pages:

To... Use this URL...


View the
specified
http://www.facebook.com/profile.php?id=XXXXX
user's
profile.
Poke the
specified http://www.facebook.com/poke.php?id=XXXXX
user.
Send a
messag http://www.facebook.com/message.php?id=XXXXX&subject=XXXIX&msg=XXXIX
e to the Note: {{c|subject}} and {{c|msg}} parameters are optional ways to pre-fill the
specified contents of the message (the user will still be able to edit the message before sending).
user.
Add the
specified
http://www.facebook.com/addfriend.php?id=XXXXX
user as
a friend.
See
photos
taken by
http://www.facebook.com/photos.php?id=XXXXX
the
specified
user.
Read or http://www.facebook.com/wall.php?id=XXXXX
post on
the
specified
user's
Wall.
Read
the
specified http://www.facebook.com/notes.php?id=XXXXX
user's
notes.
Note: Casebook dozen't look fondly upon Pammy behavior, so please don't encourage your users
to abuse this functionality.

Building an application on Facebook gives you the opportunity to deeply integrate into the core
Facebook experience. By leveraging Facebook's integration points you can make your application
feel native to the site, and create a seamless experience as users browse Facebook. Your
application can integrate with all aspects of the Facebook user experience, from the profile page
to bookmarks and the stream.

Applications that run within Facebook use all the same fundamental technologies as websites
which integrate Facebook. Other than some differences in user authentication, all of the
technologies discussed in the Facebook for Websites guide are available to applications on
Facebook. You should start with that guide if you are new to developing with Facebook's APIs.

This guide walks you through the basics of getting your application set up and provides an
overview of the key Facebook integration points.

Canvas Bookmarks

Getting Started
When you build an application on Facebook, your application's primary page views come via the
canvas page, an iframe hosted by Facebook at http://apps.facebook.com/your_app/ that
points to your application. When you register your application, you choose a Canvas Page URL
(your_app in the example above) and a Canvas Callback URL (e.g.,
http://www.example.com/canvas/). When a user visits http://apps.facebook.com/your_app/,
Facebook loads your specified Canvas Callback URL within an iframe on that page. Likewise,
when a user visits http://apps.facebook.com/your_app/foo/bar, Facebook loads the URL
http://www.example.com/canvas/foo/bar in the canvas page iframe.

To get started, register your Facebook application. Once you have entered your basic application
information, click the "Canvas" tab on the left hand side of the configuration screen, and specify a
Canvas Page URL and Canvas Callback URL for your application:
To test that things are working properly, put up a simple page at your Canvas Callback URL and
visit http://apps.facebook.com/your_app/. You should see your page load in the Canvas Page
iframe:

In general, you should use only one Application ID for your base domain; a single Application ID
allows you to create a full-featured application.

Authentication
Canvas applications use cookies to get user authentication information. The cookie includes a
signature for all the values as the argument sig. The signature scheme is described in detail in
the Canvas authentication guide. This PHP snippet returns all the official Facebook arguments and
verifies the signature with your app's Application Secret:

<?php

define('FACEBOOK_APP_ID', 'your application id');


define('FACEBOOK_SECRET', 'your application secret');

function get_facebook_cookie($app_id, $application_secret) {


$args = array();
parse_str(trim($_COOKIE['fbs_' . $app_id], '\\"'), $args);
ksort($args);
$payload = '';
foreach ($args as $key => $value) {
if ($key != 'sig') {
$payload .= $key . '=' . $value;
}
}
if (md5($payload . $application_secret) != $args['sig']) {
return null;
}
return $args;
}

$cookie = get_facebook_cookie(FACEBOOK_APP_ID, FACEBOOK_SECRET);


echo 'The ID of the current user is ' . $cookie['uid'];

?>

When a user first visits your application, he or she will not be logged in to it. In this state, the
cookie won't include uid. The recommended way to handle this case is to render a logged out
version of your application with a Facebook login button, just like you would on a Facebook
Connect site:

<html>
<body>
<?php if ($cookie) { ?>
Your user ID is <?= $cookie['uid'] ?>
<?php } else { ?>
<fb:login-button>Install Example App</fb:login-button>
<?php } ?>

<div id="fb-root"></div>
<script src="http://connect.facebook.net/en_US/all.js"></script>
<script>
FB.init({appId: 'your app id', xfbml: true});
FB.Event.subscribe('auth.login', function(response) {
// Reload the application in the logged-in state
window.top.location = 'http://apps.facebook.com/your_app/';
});
</script>
</body>
</html>

Check out the full PHP example application on GitHub for working "Getting Started" examples to
copy to get started more quickly.

Making API Calls


We are currently in the process upgrading our core server API from the old REST API to the more
modern Graph API. However, most of the methods required for canvas applications to integrate
with Facebook have not yet been upgraded to the new API. For the time being, we recommend
you continue using the old REST API in canvas apps instead of the new APIs for the sake of
completeness.

Included in the arguments passed to your canvas callback URL is oauth_access_token. That
argument can be used to make OAuth 2.0-authenticated calls to the REST API on behalf of the
active user. For example, you can call the friends.get method by fetching the URL:

https://api.facebook.com/method/friends.get?
format=json&
access_token=...

In PHP, using the $args data structure above, you could fetch the current user's list of friends
with:
$friends = json_decode(file_get_contents(
'https://api.facebook.com/method/friends.get?' .
'format=json&access_token=' .
$cookie['oauth_access_token']));

Integration Points
Once you have developed your application using the REST API, you can integrate your applications
with the communication channels and integration points Facebook provides to help grow your user
base and re-engage existing users. The most important integration points are:

• Stream publishing
• Requests
• Bookmarks and Counters
• Application and Games dashboards
• Profile tabs

Stream Publishing
The stream is shown immediately to users upon logging into Facebook, making it core to the
Facebook experience. You can prompt a user to publish stories about what she is doing in your
application to her wall. If she publishes the story, it will appear on her wall and in all her friends'
streams. Stories published from your application will include a link to your canvas page, and can
optionally include an rich attachment. Effective use of stream publishing enables new users to
discover your application, and existing users to re-engage with it.

A basic example of how to prompt a user to publish a story using the Facebook JavaScript SDK:

<script>
FB.ui(
{
method: 'stream.publish',
message: 'Check out this great app! http://apps.facebook.com/{your_app}'
}
);
</script>

The code above prompts the user with this dialog:

Read the complete documentation on stream publishing and attachments.


Requests
Requests are a great way to enable users to invite their friends to your application, and for users
to confirm connections from your application. As an example if user A wants to invite user B to
join a group inside your application, user A could send user B a request, asking if user B would
like to join. User B will receive the request and have the opportunity to respond. Users can easily
send requests by simply clicking on friend's faces and hitting send.

Using FBML tags you can render request forms and friend selectors. There are many ways to
customize your requests including the display of the friend selector, and what options are
available to the recipient of the request. Complete documentation is available here. Iframe
applications simply need to wrap the FBML tags in a <fb:serverFbml> tag for them to render.

An example request form:

<fb:serverFbml>
<script type="text/fbml">
<fb:fbml>
<fb:request-form
method='POST'
type='join my Smiley group'
content='Would you like to join my Smiley group?
<fb:req-choice url="http://apps.facebook.com/smiley/yes.php"
label="Yes" />'
<fb:req-choice url="http://apps.facebook.com/smiley/no.php"
label="No" />'
<fb:multi-friend-selector
actiontext="Invite your friends to join your Smiley group.">
</fb:request-form>
</fb:fbml>
</script>
</fb:serverFbml>

The above code renders this on your canvas page:


After the user chooses a friend and clicks Send, the request will look like this to the recipient:
Bookmarks and Counters
Bookmarks enable users to easily navigate back to your application. Placing a bookmark button on
your canvas page enables users to add your application to their list of bookmarks on the left
column of the homepage. Once a user has installed your bookmark, you can set a counter which
will appear next to it. You should set the counter to remind users of actions they need to take
within your application.

Including the bookmark XFBML will render the bookmark button on your canvas page:

<fb:bookmark></fb:bookmark>

Which will generate this button:

Complete documentation about the bookmark button can be found here.

When a user needs to return to your application, you should increment the counter:

$result = json_decode(file_get_contents(
'https://api.facebook.com/method/dashboard.incrementCount?' .
'format=json&access_token=' .
$cookie['oauth_access_token']));

This will increment the counter for this user:

Complete documentation on the counter can be found here.

Application and Game Dashboards


The Application and Game Dashboards help users discover and engage with applications on
Facebook. A user's recently used applications appear at the top of the dashboard and a user's
friends' recently used applications are shown in the bottom sections. When users engage with
your application, it will automatically show up in the dashboard. To make your appearance in the
dashboard more engaging you can publish news and activity. These are bullet point messages
telling your users and their friends what is new in your application.

For example, you can add news to a user's dashboard by calling:

$news = array(array('message' => 'Come back and see our new Smileys'));

$result = json_decode(file_get_contents(
'https://api.facebook.com/method/dashboard.addNews?' .
'news=' . urlencode(json_encode($news)) .
'&format=json&access_token=' .
$cookie['oauth_access_token']));
This will appear in the user's dashboard:

There is a lot you can do to take advantage of the dashboards. Complete documentation can be
found here.

Profile Tabs

All profiles on Facebook have tabs. For example, users have a 'Photos' tab and a 'Links' tab by
default. A user can add a tab for your application to her profile. When one of the user's friends
visits her profile, the friend can check out the profile tab to get a sense of what your application is
about, what the user has been doing in your application, and the friend can click back to your
canvas page.

To enable users to add a profile tab, set a tab name and a tab URL in the Facebook Developer
app:

When a user navigates to the profile tab, Facebook makes a request to the tab URL you specified.
A number of POST parameters are included with the request. You can verify the parameters using
the same technique described here, but using $_POST parameters instead of the parameters from
the cookie.

Facebook does not pass back who the viewing user is when she first visits your tab. Facebook
does send the profile owner's ID in the fb_sig_profile_user parameter, so you know whose profile
to display content for. See Authentication for more information.