Anatomy of a Facebook Connect Site

From Facebook Developer Wiki
Jump to: navigation, search Facebook Connect is about integrating social context into other Web sites. There are many creative ways to do that, but we've noticed some common themes found among most sites and listed them here. Many of these examples use our sample application, The Run Around. For in-depth explanation of the source, see The Run Around. Facebook Connect can be as simple or complex as you need. The simplest Facebook Connect sites simply integrate XFBML into your existing Web pages, to give the user access to the Facebook experience from your site. Here are a few scenarios:
• • •

Use XFBML to add Facebook images and capabilities such as profile pictures and the ability to make comments or share your content. Use the JavaScript Client Library (or start using the open source JavaScript SDK) to request information about the user or publish directly to the user's stream Integrate with your own authentication code to build a full-fledged Facebook Connect app (such as The Run Around) and manage the user's login to your site and Facebook simultaneously.

No matter how you use Facebook Connect, the user is in control. This gives the user confidence in your site. Facebook Connect provides a mechanism called extended permissions for requesting additional privileges from the user.

How Facebook Connect Works
Facebook Connect greatly simplifies application building for Facebook developers. At its simplest, developing a Facebook Connect application involves adding a few XFBML tags to an HTML page. Facebook Connect uses a cross-domain communication channel to open an iframe on the HTML page for each XFBML tag. When the user clicks a tag, Facebook Connect handles the interaction and lets the user log in, publish updates, and so on. A Facebook Connect application can use any or all of the following:
• • • •

XFBML tags JavaScript, with calls to the JavaScript client library PHP pages, with calls to the Facebook PHP API Code in any language, with calls to the Facebook RESTful API

1

The most common cases are simple Web pages with XFBML tags and calls to the JavaScript client library.

Using XFBML Tags
XFBML is a very easy way to get started building a Facebook Connect application, because Facebook handles the login, the session, and other housekeeping for you. To use XFBML tags in your Web page, you'll need:
• • • •

A special XHTML namespace so that the browser will ignore XFBML tags A JavaScript call that activates the Facebook FeatureLoader XFBML tags, which provide the Facebook experience A file called xd_receiver.htm, to support older browsers

Using the JavaScript Client Library
The JavaScript client library provides a more powerful interface for Facebook Connect applications. To use the Javascript client library, you'll need:
• •

A JavaScript call that activates the Facebook FeatureLoader A file called xd_receiver.htm, to support older browsers

One of the most powerful features of Facebook Connect is the ability to tie a Facebook Connect application to your own website's login mechanism. You can use the JavaScript client library to retrieve the user's ID and login state, detect whether the user has connected with your site, and then change their login state in your site's login mechanism accordingly.

Examples of the Facebook Connect Experience
Presence Indicator
When a user connects with a site, they want to know what actually happened. The recommended way to indicate that they are acting in the context of Facebook is to show their real name and profile picture, with a Facebook favicon embedded in the corner of the picture.

Sample XFBML <fb:name uid="1256100362" useyou="false"> </fb:name>

2

<fb:profile-pic uid="1256100362" facebook-logo="true" size="thumb"> </fb:profile-pic>

Friends Page
Once a user has several friends who have connected with the site, the activity of those friends becomes an important part of their experience. Typically there is a page for Friends' Activity - for instance, on Yelp you could see Friends' Reviews, or on Digg you could see Stories Friends Have Dugg. Tying it together into a page is helpful.

User Actions and Content
Many sites display user actions throughout the site. On Digg, you can see people who've dugg stories; Yelp will show you people who have written reviews. For sites like that, you can use XFBML to display the names and profile pics of Facebook users who have contributed content. Sample FBML Depending on how frequently they show up and what the context of the site is, you may choose to display a Facebook favicon in the corner of the photos to mark the users as Facebook users. <fb:name uid="127942391993" ></fb:name> <fb:profile-pic uid="127942391993" facebook-logo="true" size="thumb" ></fb:profile-pic>

3

Example Connect Site

Connect/Authentication and Authorization
From Facebook Developer Wiki
Jump to: navigation, search You can use Facebook Connect functionality as a login mechanism for the users of your website, iPhone application, or desktop application. Your users can connect their accounts on your site or application (if one exists) with their Facebook accounts. Using Facebook Connect, your users can link accounts, then you can start making a richer, more social experience on your site with your connected users' Facebook data. What's more, you can have users share their activities on your site back on Facebook.
o

Benefits
Using Facebook Connect to authenticate your users has many significant benefits.
• •

• •

Our research has shown that sites that implement Facebook Connect see user registration rates increase by 30 - 200%. With just two clicks you can offer a user-customized experience on your site – the user connects to your site, then you can immediately display that user's data on your site, personalizing his or her experience quickly and easily. When a user has authorized your application, you can make API calls to Facebook to get more user data so you can provide a more personalized experience. You can prompt a user for extended permissions for an even deeper integration with Facebook.

How It Works
When a user visits your site or installs your application, you can display a Facebook Connect button, like the following: 4

If you have an iPhone app. The user is not registered with Facebook. you can display a button like this: When the user clicks the Connect with Facebook button. The user clicks the button to log in to your site. Scenario 1: User Is Logged in to Facebook The user visits your site and sees the Connect with Facebook button. Facebook detects the user's login state and displays a Facebook Connect dialog that easily allows the user to connect to your site: 5 . What the dialog displays depends upon the user's Facebook state: • • • The user is logged into Facebook. The user is not logged in to Facebook. If the user is logged in to Facebook. a Facebook Connect dialog appears.

The user clicks the button to log in to your site.The user clicks the Connect button and is immediately logged in to your site. Scenario 2: User Is Not Logged in to Facebook The user visits your site and sees the Connect with Facebook button. 6 . Notice that your site is aware of the user's Facebook presence. and displays the user's Facebook profile pic and name as well as some of the user's friends who have already connected to your site.

This dialog prompts the user to enter his or her Facebook login credentials: The user enters the login credentials.If the user is not logged in to Facebook. and is immediately logged in to your site. 7 . Notice that your site is aware of the user's Facebook presence. and displays the user's Facebook profile pic and name as well as some of the user's friends who have already connected to your site. Facebook displays a Facebook Connect dialog. clicks the Connect button.

Facebook displays a Sign Up for Facebook dialog. This dialog prompts the user to register for the Facebook: 8 . The user clicks the button to log in to your site.Scenario 3: The User Is not Registered with Facebook The user visits your site and sees the Connect with Facebook button. If the user is not registered with Facebook.

as it's a necessary part of their Connect integration. Scenario 4: Prompting the User for Extended Permissions Some sites ask the user to grant them special extended permissions when the user first connects. Notice that your site is aware of the user's Facebook presence. and displays the user's Facebook name.The user signs up for Facebook but may log in via Connect only after their email address has been validated. a site might 9 . For example.

immediately need to read user data after the user connects because the user's stream is part of the site or application's experience. unless you must use what the permission grants immediately. or none of them. After the user clicks Connect. In this case. the permissions dialogs appear. the user clicks the Connect with Facebook button on the site. just one of them. In this case. and the Connect with Facebook dialog appears. The user can choose to grant both permissions. Facebook recommends against prompting for permissions right after the user connects. 10 . the site is asking for constant authorization/offline access and the ability to read from the user's stream (Feed and Wall).

and iPhone apps. Implementation Implementing authorization follows pretty similar paths for websites. • • • • Authorization and Authentication for Facebook Connect Websites Authorization and Authentication for Facebook Connect for iPhone Authentication and Authorization for Facebook for Mobile Applications Authorization and Authentication for Desktop Applications 11 . desktop applications.After the user finishes granting permissions. with the user's Facebook information prominently displayed. the user returns to the site.

Authorizing Applications From Facebook Developer Wiki Jump to: navigation. the following occurs: • Whenever the user interacts with your application. read Connect/Authentication and Authorization. You don't need to have a user authorize your application as soon as the user visits your canvas page. Facebook sends you some user data (known as automatic authentication) and lets your application take a number of actions. and decide how to integrate it into the profile as the user continues to engage with it. For Facebook Connect authentication. What You Get After a User Authorizes Your Application Once a user authorizes your application. When a user who hasn't authorized your application visits your application's canvas page. When a user visits your application canvas page. that user is counted as an active user. This way a user can engage with your application quickly and easily. And if the user interacts with your application tab or Publisher on a friend's profile. search One goal of Facebook Platform is to make user interaction with your applications as frictionless an experience as possible. A user doesn't have to authorize your application before being considered an active user. 12 . Note: Much of this information is discussed at New Design User Login. giving your application access to more user data which you can query on behalf of this user. A user authorizes an application when the application presents a login screen where the user accepts the application's terms of service and lets the application access his or her profile data. that user can begin interacting with your application immediately. Facebook passes a temporary session key. • What You Get Before a User Authorizes Your Application Facebook publishes metrics based on monthly active users.

Which parameters are sent depends upon what the user is doing with your application. if your application still calls the method. For FBML canvas page applications. in which case the parameters are sent as POST parameters. the parameters are sent as POST parameter. You can also call users. Post-Authorize Redirect URL: You can redirect a user to this URL after the user authorizes your application for the first time. Note: Facebook deprecated require_add. For iframe applications. which you specify in your application's settings in the Developer application: • • • Post-Authorize Callback URL: Facebook pings this URL when a user authorizes your application for the first time. Users can interact with your application's Publisher integration. You can prompt the user to grant your application extended permissions.php will get redirected to login. URLs Relevant to Authorization Once a user has authorized your application. as all requests to add. the behavior will be similar to the require_login PHP function. unless you are preloading FQL using the fb_iframe_post option. even without an active session. you can utilize the following URLs.isAppUser to determine if the user has authorized your application.php and not the login dialog. 13 .getStandardInfo to get data for analytics. which are described under Understanding Authorization and Authentication. the parameters are sent as GET parameters. How Users Can Authorize an Application A user can authorize your application in a number of ways. update the user's status.• • • • You can call users. so your application can send the user email. However. and so forth. You can prompt the user to add integration points (such as an application tab) to his or her profile. The user needs to authorize your application only once. Post-Remove Callback URL: Facebook pings the URL when a user removes your application.php. You can use this URL only if the user authorizes your application through login. Parameters Passed to Your Application Facebook sends parameters to your application in the form of a signature (read more about signatures below).

e. When a user first visits an application tab. fb_sig_profile_session_key is passed instead. Note: As mentioned in Bug 4117. then the user has authorized your application. fb_sig_canvas_user is passed if user has not authorized your application. fb_sig_friends: The UIDs of the visiting user's friends. 14 . which is a UNIX timestamp. This is a UNIX timestamp. the fb_sig_canvas_user and fb_sig_friends parameters are only passed when a user arrives at your application from a link within facebook. while fb_sig_user is passed if the user has authorized your application. fb_sig_ext_perms: Any extended permissions that the user has granted to your application. fb_sig_api_key: Your application's API key. This parameter is sent only if the user has granted any.com and provided the user's privacy settings allow the user to be seen.that is. fb_sig_time: The current time. Facebook passes the following parameters only if fb_sig_added is true (that is. with both set to the profile owner's user ID.registerUsers Note: As described in Automatic Authentication. fb_sig_in_profile_tab: This parameter is sent if this request is for a user's tab for your application. fb_sig_expires: The time when this session key will expire. fb_sig_user/fb_sig_canvas_user: The visiting user's ID. These parameters are relevant to requests sent to your application: • • fb_sig_in_canvas: This parameter is true if the request is for your application's canvas page. fb_sig_linked_account_ids[n]: These are the account_id values that match the user's email hash that were previously sent to facebook using connect. there are some situations in which both fb_sig_user and fb_sig_canvas_user are passed when the user has not authorized the application (i. This parameter isn't passed when an application tab is being requested. fb_sig_profile_update_time: The time when this user's profile was last updated. if the user has authorized your application): • • • • fb_sig_session_key: The valid session key for this user. fb_sig_locale: The user's locale. fb_sig_user and fb_sig_profile_user are passed.Facebook passes the following parameters to your application when a user interacts with your application: • • • • • • • fb_sig_added: If set to true. This parameter is set to 0 if the session is infinite -. fb_sig_added is 0). the user granted your application offline access. This is a UNIX timestamp.

The user authorizing your application will not be redirected to this URL (specify the postauthorize redirect URL in your application's settings to configure the redirect). Facebook sends a number of POST parameters to your Post-Authorize Callback URL in the form of a POST request. This URL is pinged when a person authorizes your application. fb_sig_profile_session_key: The session key for the profile owner. search The Post-Authorize Callback URL is briefly described in Creating Your First Application. which you use to render this user's profile tab content. fb_sig_page_added: If this request is on behalf of a Page. This applies both to the signatures Facebook generates and the ones that your application needs to generate. How Signatures Are Generated You can read about how these signatures are generated. The session secret also gets passed to a SWF object inside your Publisher.• • • • • • fb_sig_profile_user: The user ID of the profile owner for the tab being requested. fb_sig_logged_out_facebook: This parameter is sent if the user is not currently logged into Facebook. Facebook's servers send this request in the background. Facebook's servers will POST several fields back to this URL along with a signature. POST Parameters After a user authorizes your application. POST Parameters of Ping The following fields are sent to your Post-Authorize URL in the form of a POST request. Post-Authorize Callback URL From Facebook Developer Wiki Jump to: navigation. Facebook's servers send this request in the background. This is sent only to a SWF rendered by fb:swf that resides within the domain or subdomain of your application's callback URL. fb_sig_page_id: The ID of the Page if this request is on behalf of a Page. only the parameters that get passed may be different. Type Name Description 15 . fb_sig_ss: The session secret. and can be passed to IFrames rendered with fb:iframe. used in place of your application's secret key for secure API calls. this parameter indicates whether the Page has added this application.

registerUsers. Benefits 16 .g. This is the signature of the POST. The api_key of your application that is being fb_sig_api_key installed. 1187756160. also see Authorizing Applications. fb_sig_authorize For more explanation. 609143784) A UNIX timestamp for when the user last updated fb_sig_profile_update_time their profile. JSON-encoded array of linked account ids that were set with Connect. Detecting Connect Status From Facebook Developer Wiki Jump to: navigation. then your ping will include the corresponding set of linked ids for that user. If you have previously registered a user's email address.7131) The uid of the person who is authorizing your fb_sig_user application (e.int string int int string int string string string Set to 1 to indicate the user is authorizing your application [Note: this variable was fb_sig_install] A UNIX timestamp indicating when the user fb_sig_time authorized (e. With the exception that it fb_sig truncates fb_sig_ from variable names when creating the signature. search • Detecting whether users are logged in to Facebook and/or your site This article covers how to detect whether a user is logged in to Facebook when they visit your site. The expiration time originally given to your fb_sig_expires application for the original session_key. Facebook uses the same signing process that your application uses to make requests to Facebook. The active session_key for the user who is fb_sig_session_key authorizing the application. and that fb_sig_linked_account_ids user then accepts a Connect request for your application. and whether they are already a connected user of your site.g.

Detecting a user’s Connect status has many significant benefits. When the user logs in to Facebook and returns to your site using another computer. o The number of users who have Connected with your site. if the user has already connected with your site. This will allow you to potentially increase engagement through a low friction login and detection process. and when they log out of Facebook. you can perform a number of actions that enhance the user’s experience. The ability to store metrics of Facebook users. o The number of users who Connect to your site when already logged in to Facebook versus those who have not logged in*. More importantly. The ability to automatically prompt a user to Connect. where a user is automatically logged in to sites they have connected with. your users will maintain a persistent Facebook session across multiple domains. • • • The ability to automatically login a Connected user when they return to your website. How It Works When a user visits your site and has already logged in to Facebook or a Facebook Connect enabled site. When you enable single sign-on. We call this "single sign on". the user will be automatically logged in to your site. 17 . o The number of logged in Facebook users who visit your site. they are logged out of all of them. you can immediately detect when a logged in Facebook user is visiting your site. you can log them in automatically whenever they are logged in to Facebook. Scenario 1: Detect a User From Computer to Computer The user visits your site and connects with Facebook from his or her computer.With some simple Javascript. Over 40% of Facebook users are logged in using third party sites.

Scenario 2: Detect Users Coming Directly From Facebook A user publishes a story from your site to his or her stream. A friend of that user sees the story and clicks on the link. you detect that he or she is logged into Facebook. This must be done via Javascript after your page loads because this must ping Facebook's servers via Javascript using the Facebook cookies. taking them to your site. After the friend arrives at your site. 18 . and you immediately present a dialog to Connect. Implementation The implementation of this feature requires using Javascript to first detect the logged in state of the Facebook user.

Connect. Not logged in – this state means that the user is not logged in to Facebook. you must first have the user log in (and potentially connect) with your site. Basic FB.Connect. 1. you must first have the user connect with your site. 4. then you may still want to prompt them more actively to log in.init() usage and calling (default) Reloading Page on Connect State Changes Requiring a Specific Connect state Handling Connect State Changes Dynamically 1. In order to make API calls on the user's behalf. This is not possible unless the user has granted an infinite session. it did work this way.Connect. they are both a "not connected" state).init. For most applications. This implementation relies on the understanding of three states of Facebook Connect. 3. 2. you can reload a page or use Ajax to update your page automatically. and if they are in state 2 (not logged in). Because the user is not logged in to Facebook. If you were familiar with building a Facebook Application on Facebook. You must be in this state to make API calls on the user's behalf.Once the Javascript detection first happens.get_status. Though if you are storing information in your own cookies.Connect.Connect. Many developers have asked how to detect this automatically on the server when a user first appears on their site. This state is returned as FB.get_status.Connect. This state is returned as ConnectState. 2. Once initialized. we don't know whether the user has connected with your website.get_status to determine the user’s state. You can determine the current state for a user visiting your site via the JavaScript method FB. you first need to initialize Facebook Connect by calling FB.get_status.ConnectState. the distinction between (2) and (3) is not important (that is. Connected – the user is logged in to Facebook and has already connected with your website.get_status.userNotLoggedIn if you call FB. but that was because the app was running within Facebook. 19 . 3. you may want to remember which users have connected their accounts.connected if you call FB. you can call FB.init() usage and calling (default) To get the user’s current connect state. Basic FB. 1. There a number of scenarios that may arise when you try to determine a user’s Connect state. This state is returned as ConnectState. In order to make API calls on the user's behalf. Not authorized – this state means that the user is logged in to Facebook but has not yet connected with your website.appNotAuthorized if you call FB.

ensureInit(function() { FB. {"reloadIfSessionStateChanged":true}). "<YOUR-CROSS-DOMAIN-CHANNELURL>". On index. and use member.requireSession(). To enable this scenario. }).appNotAuthorized: case FB. loggedIn = false. 2.php"}). it's often simplest to reload the page when the user either connects or logs out.waitUntilReady( function( status ) { switch ( status ) { case FB. case FB. break.init("<YOUR-API-KEY>".connected: loggedIn = true.ConnectState.php to serve users who are logged in/connected. you can pass a configuration setting "reloadIfSessionStateChanged":true to the FB.Connect.userNotLoggedIn: FB.ConnectState. For example. } }). Reloading Page on Connect State Changes For sites whose content is partially or fully generated on the server-side. 3.Connect.Connect.ConnectState.init(API_KEY).php. "<YOUR-CROSS-DOMAIN-CHANNELURL>".Connect. For example: FB.init function. {"ifUserConnected":"member. FB. a website may choose to use index. Requiring a Specific Connect state Some sites use separate pages for connected and non-connected users. you can use the ifUserConnected and ifUserNotConnected settings.init("<YOUR-API-KEY>".php to serve a user who has not yet logged in/connected. you can call: FB. To enable this scenario. 20 .get_status().FB.

By setting "ifUserNotConnected":"index. the onConnected function will be invoked whenever the user is connected and the onNotConnected function will be invoked whenever the user is logged out. On member. this Web page will automatically redirect to index. "ifUserNotConnected":onNotConnected}). {"ifUserNotConnected":"index. Even if you aren't supporting a deep integration with Facebook Connect..init("<YOUR-API-KEY>".php". and make them much more prominent when a logged-in Facebook user is visiting your site. 21 .php..By setting "ifUserConnected":"member. you can also specify a callback function for ifUserConnected and ifUserNotConnected: FB.php when it detects that the current user is not connected..php when it detects that the current user is already connected. "<YOUR-CROSS-DOMAIN-CHANNEL-URL>". To handle this situation. function onConnected(user_id) { . } function onNotConnected() { . } With this setting.) to respond to state changes without a page reload.php"}).init("<YOUR-API-KEY>". this Web page will automatically redirect to member. 4. you can call: FB. AJAX requests.php". etc. {"ifUserConnected":onConnected.. "<YOUR-CROSS-DOMAIN-CHANNELURL>". you can use this javascript to tweak the presentation of your site for Facebook-related features. Best Practices Being able to detect the current Connect state of a user is a powerful tool. Handling Connect State Changes Dynamically Some sites rely on client-side techniques (JavaScript.

they will be logged into Facebook.init (object appSettings) Advanced Use If the simple configuration settings are not are sufficient for your scenario. If you are using Facebook Connect as a way to log in to your site. object notConnectedArg) public static Waitable FB. string xdChannelUrl. you can still use the user's Connect status to automatically log users into your site using your own account system. • • • public static void FB. you can use the detection methods listed here to immediately log the user in whenever they are logged into Facebook and visit your site. over 40% of users visiting other websites are actively logged in to Facebook. 2. object appSettings) public static void FB.get_sessionWaitable() Note: While these approaches are asynchronous.init (object appSettings) public static void FB.init (string apiKey. When users click on links from Facebook to your site (such as an advertisement on Facebook. Based on some of our analysis.Connect. Using these detection methods for links that come from Facebook is a great way to increase your conversion rate and the success of the social loop. or a link or story shared by a friend of theirs). string xdChannelUrl. This would work even if they visit a new computer and log into Facebook first. the actual execution will often be synchronous due to client-side caching of server state. If you are not using Facebook as your primary login mechanism.Facebook. 2.init (string apiKey. For example. you can also use other API calls to track user state. simply store a mapping from Facebook user IDs to your own account identifiers and then use the Facebook session to look up and use a local account on your site.get_status() public static Waitable FB. you can make the Facebook Share button most prominent. 22 . when you detect a Facebook user. Reference • • • • public static void FB. A few more notes: 1. object appSettings) public static void FB.1.Facebook.Connect.Facebook. To do this.ifUserConnected (object connectedArg. if you support a Share button as part of a list of several sharing options.

the Facebook markup language). we support three general approaches towards integrating data -– XFBML. In particular. Facebook Connect provides additional JavaScript methods (like stream. with some exceptions. These approaches can freely be intermixed within a single site. You can't use the requirelogin attribute.getAppProperties. You can't make any API calls that require your application secret. search One of the primary goals of Facebook Connect is to provide developers choice with respect to how they integrate Facebook data into their site. you'll need to use the JavaScript library to perform the following actions that require AJAX dialogs when called by the REST API: • • • To log in a user.streamPublish.setRefHandle. Most of the Facebook Connect examples on this wiki show how to use either XFBML and the Facebook JavaScript library or the Facebook PHP Library. 23 . If you're using the Facebook JavaScript Library and the Facebook PHP Library. this process will be automatic (as the JavaScript library will save the session in a set of cookies local to your site.php. This article describes how to transfer sessions generated in one environment to the other. Moreover. you need to call showPermissionDialog. the Facebook JavaScript Client Library. such as admin. By and large. and the Permissions API. Transferring Sessions From JavaScript to the Server If a session is generated using the Facebook Connect login flow. admin.facebook. which the PHP library will parse). you should use requireSession. You can't use the promptpermission attribute. To use Feed forms. the API is fully supported. and the Facebook Server-Side Libraries. fbml. With Facebook Connect. that session may also be used with the Facebook PHP Library.setAppProperties. To prompt for extended permissions. you should use FB.Connect. Note that the session will not be available on the server side until the next HTTP request.Using Facebook Connect with Server-Side Libraries From Facebook Developer Wiki Jump to: navigation.* methods) as well as XFBML (which is an extension to FBML.com/restserver. you can make calls to the Facebook Platform REST server -http://api.

by calling require_login) are not session secret-based.getSession – when first requesting a session.If you're not using the Facebook PHP Library.NET There is an ASP. so almost all interoperability scenarios will involve moving sessions from JavaScript to the server. Promote a non-session-secret-based session – the auth.NET: Facebook Connect Authentication for ASP. 2. If you’re not using the Facebook PHP library.NET. Authorization and Authentication for Desktop Applications From Facebook Developer Wiki Jump to: navigation.NET library that can help you verify your Facebook Connect users and transfer their session from JavaScript to ASP. You can also read this article for more info: How to Retrieve User Data from Facebook Connect in ASP. By default. sessions generated on the server-side (for example. If your site is using the traditional redirect/popup experience or the user has previously granted your site offline access. Transferring Sessions From JavaScript to ASP. please see Verifying The Signature for details on the cookie format and how to ensure that the cookies you're transferring are secure. The Facebook Connect login flow is JavaScript-based. search 24 . Explicitly ask for a session secret-based session in auth.NET Transferring Sessions From the Server to JavaScript A session secret-based session is required for the Facebook JavaScript Client Library. The PHP 5 client automatically saves the session in a set of cookies local to your site. you can ask for a session secret-based session via this API.promoteSession API call can be used to promote an already existing session to a session secret-based session. so a valid session secret-based session should be available immediately after either of these methods succeeds. If you’re using our PHP 5 client library. you can also indicate this in the Facebook object constructor. which the Facebook JavaScript library will parse. please see the article Verifying The Signature for details on the cookie format and how to ensure that the cookies you’re transferring are secure. In order to get a session secret-based session. you have two options: 1. it may be necessary to promote a session from the server to JavaScript.

Facebook returns the user's user ID (UID). format. To use Facebook API calls from your desktop application. Authorizing and authenticating your users involves a series of tasks: • • • • • You need to determine the user's Facebook login state. or C++.. Once you have a user session. If it doesn't match. sig) Make this call to the api. you can take steps to end a user's session.facebook. or if the user has deauthorized it. you have to prompt the user to authorize your application again by redirecting the user to login.php. Examples include Facebook for Adobe AIR or the Facebook Exporter for iPhoto.A desktop application runs on a user's computer as an application. as described in Prompting for Permissions below. you can prompt the user for extended permissions. VB.php.NET. it doesn't run in a browser.NET. session_key. and you want to get more information from a user than what the API can offer. Please note that this method only works if you can control a browser window (such as Webkit) directly. Detecting the User's Login State When a user launches your application. detecting whether the user has authorized your application previously. direct the user to log in when logging in to your application. If need be.getLoggedInUser(v. you need to authenticate that user. You should crosscheck the UID to make sure it matches the UID that was part of the session object returned from a previous call to login. To check for the session.getLoggedInUser: users. If the user isn't logged in to Facebook. You can also check the time for the expires parameter that was returned earlier to see if you need to re-authorize the user. You do this by validating the session when user launches your application again. call_id..com/restserver. in case the user didn't grant you a non-expiring session. call users. you need to trigger certain actions in a browser window such as login and permission dialogs. ASP.php.0 Library for Facebook Platform. but not PHP (unless using Phalanger PHP) or JavaScript. You can use various Facebook client libraries like ActionScript 3. 25 .

facebook.getSession (though this method still works.NET applications Objective C/Cocoa applications Note: You no longer need to create an auth token. don't create a separate popup window.com/login. This way you don't need to redirect the user to a browser to log in to Facebook. it's not as seamless as using Facebook Connect).Logging In and Getting a Session Facebook has made the desktop authorization process simpler.php using WebKit (or your controlled browser environment of choice). you need to use WebKit or an equivalent programmatically controlled browser environment. For information on how to frame an HTML page from within a desktop application. you need to launch display an HTML page in a frame within your application. read one of the following articles for the environment in which you're developing: • • • Adobe AIR applications . nor do you need to call auth. To log a user into a desktop application. Desktop applications now use Facebook Connect for authentication. the user logs in from your application directly. direct the browser to www. To do this. when the user launches your application. Include the following URL parameters: • • api_key=YOURAPIKEY fbconnect=true 26 . In order for you to authenticate your users.

• • • • • • • v=1.facebook. next=URL: The next URL to request after the user logs in to your application. This URL either can be a subdomain of your Connect URL (which you specify in your application settings) or it can be anywhere on the facebook. return_session=true. This URL either can be a subdomain of your Connect URL or it can be anywhere on Facebook.0&next=http:// www.php? api_key=YOURAPIKEY&connect_display=popup&v=1.facebook. See Extended permissions#Requiring Extended Permissions for more information.0 connect_display: Set to popup to display the login dialog as a popup window.com/login.com/connect/login_success. prompt the user for them after the user authorizes your application. then Facebook grants your application a session.86400. session_key_only: Set to true if you want to get a session for the user without logging the user out of any other Facebook sessions in any browser.com/connect/login_failure.html&cancel_url=http ://www.com/connect/login_success. This session is appended to the URL as a JSONdecodable object of the form: &session={“session_key”:”SESSIONKEY”.html.facebook.facebook. The session gets stored in a cookie in your WebKit instance. like www.com/connect/login_success.permission: A comma-separated list of extended permissions you require from the user.124344360027 .html&fbconnect=tr ue&return_session=true&session_key_only=true&req_perms=read _stream.offline_access If the user is redirected to the URL specified by the next parameter.facebook. “expires”:0 || UNIXTIME.publish_stream. The user cannot authorize your application without granting it these permissions.com domain. For example. req_perms=permission. See Prompting for Permissions below. This requests a session from Facebook.html. “uid”:USERID. If you there are optional permissions you would like from the user.com/connect/login_failure. “secret”:”SESSIONSECRET”} In continuing with the above example. cancel_url=URL: The next URL to request if the user cancels or otherwise cannot log in successfully.html?session= %7B%22session_key%22%3A %223.kxhAu6W0qo_bLGjmdWrgfw__. Set to page to do a full-page redirect to the login page. the full URL for logging in a user could be: http://www.permission. the redirect for a successful login would be: http://www. like www.facebook.

you should store the session key so the user doesn't have to log in the next time he or she launches your application. Since this is within your desktop application. format. You can disregard the application secret and you should never include it in your desktop application's code. typically on the user's desktop where the user installed your application. You should crosscheck the UID to make sure it matches the UID that was part of the session object returned from a previous call to login.php. you should append ss=true to every call. you are given an API key and an application secret. In this case. or create a window or browser within your own application to do this. Instead. you have to prompt the user to authorize your application again by redirecting the user to login.facebook.php.getLoggedInUser(v. as above. session_key. or until the user closes your application. To check for the session. Important: Use the Session Secret. not the Application Secret When you configure an application with the Facebook Developer application. The session secret expires when the session key does.688626964%22%2C%22uid%22%3A%22688626964%22%2C%22expires %22%3A1243443600%2C%22secret%22%3A %220NVNMxpO6jVyDcVCvVv_PA__%22%2C%22sig%22%3A %22ac1c0c77c137567389defea70481b7aa%22%7D If the user grants your application the offline_access extended permission. Once the browser has been redirected successfully and you have your session information.php. You can see which API methods you can call with a session secret. If it doesn’t match. When you sign your API calls using the session secret. 28 . as described above. as it can be decompiled and used maliciously. You should store it along with the session key. sig). you may either direct the user's main browser to this URL. call_id. you should automatically close the browser window. you get a session secret when the user authorizes your application. Desktop sessions last 24 hours. call users. Make this call to the api.com/restserver.getLoggedInUser: users. 0 gets returned for expires and the session never expires unless the user removes the application. Facebook returns the user's user ID (UID).

append the following URL parameters: • • • • • • • • api_key=YOURAPIKEY fbconnect=true v=1. You need to include the xxRESULTTOKENxx parameter in the URL. where needed. like read_stream. and the current user is a Page admin. When you direct the user to www. The xxRESULTTOKENxx parameter gets replaced with a comma-separated string listing any permissions that the user granted to your application.com domain.com/connect/prompt_permissions.php. Direct the user to www. setting this URL parameter 29 .com/connect/prompt_permissions.php. At any time in your application flow.facebook.facebook.PERMISSION: A comma-separated string of the permissions you want the user to grant. ext_perm=PERMISSION. This URL either can be a subdomain of your Connect URL (which you specify in your application settings) or it can be anywhere on the facebook. Pass the req_perms parameter to login. is necessary immediately after authorization. You should use this method if having a certain permission.html. as described above.facebook.Prompting for Permissions There are two ways your desktop application can prompt a user for extended permissions: • • When a user authorizes your application.0 display=popup extern=1 next=URL: The next URL to request after the user logs in to your application. like www.php. enable_profile_selector: If one of the permissions you are requesting is publish_stream.com/connect/login_success.

After the user grants the permission. profile_selector_ids: A URL-encoded.publish_ stream&enable_profile_selector=1&profile_selector_ids=1234% 2C5454 The user then is prompted with a series of dialogs. The user can choose to grant some. So. if the user granted your application both permissions.html? xxRESULTTOKENxx&display=popup&ext_perm=read_stream. one for each permission. This allowing the user to select for which Page(s) the permission should be granted. comma-separated list of profile IDs used to filter the profiles in the profile selector. or all of the permissions for which you are prompting. the redirect would be: http://www. in the above example. none.php the next time that user launches your application: SELECT [comma-separated list of perms previously granted] FROM permissions WHERE uid=[UID you stored from previous session] For example: SELECT read_stream.query) to restserver. The dropdown contains only Pages for which the publish_stream permission hasn't been granted.facebook.publish_stream FROM permissions WHERE uid=563683308 30 .0&next=http://www.com/connect/login_success.facebook.• to '1' causes a dropdown list to appear in the permission dialog.com/connect/prompt_permissions.php? api_key=YOURAPIKEY&v=1. For example.com/conne ct/login_success. you can use the page admin (FQL) and the permissions (FQL) tables to query which Pages the user admininsters have the publish_stream permission. If the user isn't the admin of any Pages. the full URL for prompting a user for the read_stream and publish_stream permissions could be: http://www. make the following FQL query (by calling fql.facebook.html? read_stream%2Cpublish_stream To confirm the permissions a user granted your application. the dropdown list doesn't appear.

or has not granted the publish_stream permission. The post also appears in the streams (News Feeds) of any user connected to both the user and the target of the post. followed by a dialog with the stream story. Users can add their own message to the post.streamPublish Description This method publishes a post to the user's stream using stream. This method works in one of two ways: • • To display a Feed form to the user.Connect. If you need to.This query returns the list of permissions that user or Page admin granted your application. you can redirect the user to prompt_permissions. If you specify a target_id then the post appears on the Wall of the target and not the user posting the item. Ending a User's Session Users don't log out of desktop applications. The user does not need to have any permissions with your site to publish in this manner. FB.php and ask for them again. To publish directly to the user's stream.publish. you can revoke a user's authorization of your application by calling auth. Before your application can publish directly. The user will have to authorize/connect to your application the next time the user launches it. You use the JavaScript call when the user may have not authorized your site. If you want.expireSession.publish API call. the user must grant the publish_stream extended permission. This is the JavaScript client version of the stream. you can terminate a user's session by calling auth. A user's session expires after 24 hours. 31 . you may either direct the user's main browser to this URL. or create a window or browser within your own application to do this. Since this is within your desktop application.revokeAuthorization. If the user isn't logged into Facebook then a login popup will appear. or when the user closes your application. without any additional prompting. If the user or Page admin removed any permissions since the last time the user launched your application. Set the auto_publish parameter to true.

ly/AJTnf'. This field should typically be blank. String actor_id) Parameters user_message String The main user-entered message for the post. Facebook displays a preview of the attachment to the user as it will look when it appears on the user's Wall. 'What do you think?'. containing the link text and a hyperlink. String user_message_prompt. The ID of the user or the Page where you are publishing the content. Examples • • • • • • • • • • • • • • • • • • Prompt a user to update his or her status: FB. } } FB. You can also include other key/value pairs which will be stored as metadata.Connect. relevant links. exception) { if (post_id) { post_to_my_server(post_id). If you specify a target_id. then check the results: function stream_callback (post_id. null.only fill this field with content the user has actually entered themselves. Signature streamPublish(String user_message.You can supply a predefined object called attachment.streamPublish(). A dictionary of Action links objects.ly/hifZk'}]}. the post appears on the wall of the target user. Object action_links. attachment.streamPublish(''. Function callback.streamPublish(''. FB.Connect. 32 attachment action_links target_id Object Object String . 'src':'http://bit. null. Prompt a user to post a image. Boolean auto_publish.Connect. 'href':'http://bit. attachment. attachment). 4). Object attachment. stream_callback).Connect.streamPublish(''. A dictionary object containing the text of the post. String target_id. and optionally a media type. Prompt a user to post to a friend's Wall: FB. See Stream Attachments for details. null. This mimics the action of posting on a friend's Wall. Prompt a user to update his or her stream with an image attachment: var attachment = {'media': [{'type':'image'. not the user that published the post.

This field can contain plain text only.user_message_prompt String callback auto_publish actor_id The sentence that appears before the user message field (e. If the user has not set the extended permission. as well as the {*actor*} token. post_id returns the id of the published post Function (which can be null if the user cancels). 33 . exception returns error description if an error occurred. The attachment gives you the opportunity to expand on the post by describing what the user did in your application. (Default value is null) Returns Boolean Attachment (Streams) From Facebook Developer Wiki Jump to: navigation. search • Introduction You can add a lot of rich information to a post by including an attachment. caption: A subtitle for the post that should describe why the user posted the item or the action the user took. however. (Default value is false) Allows the logged in user to publish on a Facebook Page's behalf if the user is an admin of the Page. which gets replaced by a link to the profile of the session user. The URL should not be longer than 1024 characters. The attachment is an array of structured data that defines the post. make sure you account for the width of any thumbnail. The post will appear on the Page's Wall as if the Page had posted it. then the post will Boolean be published without user approval. "What's on your mind?") A function that takes two parameters: post_id and exception. Attachments are optional. It contains these optional fields: • • • name: The title of the post. then the method will fail.g. If the user has granted the publish_stream extended permission AND this parameter is true. If String specified. actor_id indicates the ID of the Page that will publish the post. The post should fit on one line in a user's stream. href: The URL to the source of the post referenced in the name.

it will be rendered as the value (e. Examples To attach a link with a description use the following example: {'name':'Google'.'descripti on':'Google Home Page'} Here's an attachment.• • • • • The caption should fit on one line in a user's stream. The value can either be a string or an array. flash. Then. The xid allows you to get comments made to this post using the Comments API. You could pass through key/value pairs that record the user's latitude and longitude when the user publishes the post.g. make sure you account for the width of any thumbnail. you might have an application that uses geo-tagging. The key should be the label of the property (e. you can use that data to plot out a geographic distribution of your users and their actions. If it's a string. when you retrieve the streams for many of your users. "0:17"). comments_xid: An application-specific xid associated with the stream post.."text" and "href".g. Your own key/value pairs: You can include your own key/value pairs for your own use later on. but Facebook displays the first 300 or so characters of text by default. These key/value pairs won't appear in any user's stream when published. media is an array that contains one of the following types: image. The key can have a maximum length of 50 characters. the array can contain two properties -. The text key will point to the value (again. The description can contain up to 1.000 characters. these key/value pairs get returned with the rest of the user's stream.get. The value can have a maximum length of 70 characters. complete with properties and an action link: var 34 . The href key will point to a link which will hyperlink the value. or mp3. but Facebook stores them.google.. This field can contain plain text only and should be no longer than is necessary for a reader to understand the story. "Length"). then the full property will be rendered as "Length: 0:17"). For example. properties: A dictionary of key/value pairs that provide more information about the post. which are described below.'href':'http://www. description: Descriptive text about the story. If it's an array. or attachments with more than one image. if the value is "0:17". It also allows you to associate comments made to this post with a Comments Box for FBML fb:comments. users can see the remaining text by clicking a "See More" link that we append automatically to long stories. media: Rich media that provides visual content for the post. Make sure you specify only one of these types in your post. When you retrieve the user's stream later with stream.com/'.

Connect.ly/KYbaN'}. only one photo gets displayed in the Feed story. Photos can be up to 90 pixels in both height and width. FB.jpg'. Facebook will choose only one of these types. flash 3. 'media': [{ 'type': 'image'. in this order: 1. Including Media in the Attachment You can include rich media in the attachment for a post into a user's stream. 'properties': { 'category': { 'text': 'humor'. action_links). respectively. 'href':'http://bit. However. flash. which can be one of the following: image. Flash objects.wordpress.com/2009/03/funn y-pictures-your-cat-is-bursting-with-joy1. or mp3. 'caption': '{*actor*} rated the lolcat 5 stars'. You can include up to 5 photos in the media array. Note: If you include more than one media type in the array. mp3 Using the image Media Type The image media type is part an array which itself contains an array of up to five JSONencoded photo records. 'src': 'http://icanhascheezburger. Each record must contain a src key. 'ratings': '5 stars' }. 'href': 'http://bit. which maps to the URL where a user should be taken if he or she clicks the photo.streamPublish(message.files. The media parameter contains a type. and music. and an href key. these media types render photos. 'href': 'http://bit.message = 'Check out this cute pic.ly/187gO1'}] }.ly/19DTbF'}]. 'description': 'a funny looking cat'. 'href': ' http://bit.'. var attachment = { 'name': 'i\'m bursting with joy'. attachment. var action_links = [{'text':'Recaption this'. 35 . which maps to the photo URL. image 2. the user can see the remaining photos by clicking a "See More" link that gets appended to the story.ly/187gO1'.

files.com/2009/03/funn y-pictures-kitten-finished-his-milk-and-wants-a-cookie.com/completestore/2009/1/ 18/128768048603560273.get or querying on the stream (FQL) table.icanhascheezburger. 'href': 'http://ihasahotdog.Here's an example of a JSON-encoded array of an image media type in an overall attachment array. Both the height and width must be an integer between 30 and 90. which is the URL of an photo that should be displayed in place of the Flash object until the user clicks to prompt the Flash object to play. If you specify both expanded_width and expanded_height in the array. the dimensions of the Flash object will be the same as its thumbnail. and the minimum dimensions are 30px wide and 30px high. {'media': [{'type': 'image'. when you get the attachment by calling stream. 'src': 'http://photos. The array can also include two optional fields to specify the width and height of the Flash object once the user clicks on it. Using the flash Media Type The flash media type is part of an array containing two other required fields: • • swfsrc. The array can include two optional fields. the photo and the Flash object are rendered in a space up to 90 pixels in both height or width. 'src': 'http://icanhascheezburger. which can be used to override the default choices.jpg'. the image gets returned as type photo. {'type': 'image'.com/upcoming/?pid=20869'}]} Note: Although you pass photos and other images as type image. imgsrc. The maximum dimensions are 460px in both height or width. 36 . inclusive.wordpress. width and height. it will resize to the specified size. when the user clicks on the Flash object. with an emphasis on scaling the image to be 90 pixels wide.com/2009/03/30/funny-picturesawlll-gone-cookie-now/'}. By default. 'href': 'http://icanhascheezburger. which is the URL of the Flash object to be rendered.jpg'. If expanded dimensions are not specified.

com/photos/EMPIRE17. 'album': 'In Rainbows'}]} See Also Connect/Integrating an Invite Form into Your Website From Facebook Developer Wiki 37 .looptvandfilm. artist.com/2009/04/funn y-pictures-hairless-cat-phones-home.mapsofwar.MP3'. 'expanded_height': '120'}]} Using the mp3 Media Type The mp3 media type is part of an array containing one other required field: src.wordpress. 'artist': 'Radiohead'. 'title': '20 Step'. 'imgsrc': 'http://icanhascheezburger. 'expanded_width': '160'. 'swfsrc': 'http://www. 'src': 'http://www.files.swf'. all of which map to strings. Here's an example of a JSON-encoded array of a mp3 media type in an overall attachment array: {'media': [{'type': 'mp3'. 'width': '80'.com/blog/Radiohead %20-%20In%20Rainbows/01%20-%20Radiohead%20%2015%20Step. 'height': '60'.jpg'.Here's an example of a JSON-encoded array of a flash media type in an overall attachment array: {'media': [{'type': 'flash'. and album fields. which is the URL of the MP3 file to be rendered within Facebook's MP3 player widget. The array can optionally include title.

com/ignore/fb_friends_msg" method="POST" invite="true" type="SocialToo" content="<fb:name uid='(facebook id of user goes here)' useyou='false' /> is a member of SocialToo. along with an fb:serverfbml XFBML tag."> <script type="text/fbml"> <fb:fbml> <fb:request-form action="http://socialtoo. You can do so utilizing the fb:request-form and fb:multi-friend-selector FBML tags. Please read our getting started guide to learn more. search Facebook is changing how you invite users in early 2010. o Creating a Full Multi-friend Selector Request or Invite Displaying the full fb:multi-friend-selector form is easy. please read the Developer Roadmap. simply click on the "Register" button below.com and would like to share that experience with you.<fb:req-choice url="http://socialtoo.com?facebook_login=1" label="Register" />[% END %]"> <fb:multi-friend-selector showborder="false" actiontext="Invite your Facebook Friends to use SocialToo" /> 38 . After the user is logged in through Facebook Connect.com example above: • • You'll first need to provide the user a way to log in via Facebook Connect. To register. provide the following code on a page somewhere that you want your users to invite their friends: <fb:serverfbml style="width: 776px. Note: XFBML tags are meant to run on your website using Facebook Connect. For more information. FBML tags can only run on your website in the context of an fb:serverfbml XFBML tag) Here is how it would have been done in the SocialToo.Jump to: navigation.

Creating a Condensed Multi-friend Selector Request or Invite If you need something more simple. To register."> <script type="text/fbml"> <fb:fbml> <fb:request-form action="http://socialtoo. In this case.com and would like to share that experience with you.com/ignore/fb_friends_msg" method="POST" invite="true" type="SocialToo" content="<fb:name uid='(facebook id of user goes here)' useyou='false' /> is a member of SocialToo. or perhaps just record that they were already invited so you don't have to display their picture in the future. Here is what you need to do: 1. It's not much different than what you did to render the full multi-friend selector containing a user's friends. Then. Make sure the user is logged in via Facebook Connect. This is just FBML. 2.it's really that simple . let's try this with just a condensed multi friend selector. The "content" attribute is what a user's friends will see when they receive the request. Note that the fb:request-form and fb:multifriend-selector tags must be wrapped in fb:serverfbml tags to work on your website. it gets marked as an invite. encouraging the user to invite their friends. you can create a condensed multi-friend selector. The "invite" attribute is what defines this as an "invite" or a "request". the "action" attribute is the URL Facebook posts to if the user clicks "Ignore". Use this to redirect the user to another page or provide them with a custom message of some sort. Then. specifying text to display. as above. we specify a fb:multi-friend-selector tag.just copy and paste the code and you're done! Now.</fb:request-form> </fb:fbml> </script> </fb:serverfbml> In the example above.<fb:req-choice 39 . copy code similar to this onto the page: <fb:serverfbml style="width: 776px. simply click on the "Register" button below. If true. Yes . within the fb:request-form you'll always want to include a friend selector of some sort.

Facebook adds the parameters. you'll want to add something in your back end code that can track the friends that were just invited by that user. Doing so makes a little box that looks something like this: Handling the Response from a Request or Invite Once you have posted XFBML on a site to display the friend invite or request form to a user. and Detecting Your Remaining Requests Like applications on Facebook. You may be able to find some useful things to do with that information as well. In addition. every website utilizing Facebook Connect is subject to limits on how often they can send requests and invites to users. You'll want to take the list of IDs (a 0-based array). Be sure to check out all of this information in detail in the fb:request-form documentation. Those limits are based on 40 . you can add these to the exclude list in the form the next time you display it for the user in order to keep them from inviting their friends more than once. Then. Allocations. Limits. "ids[]".com?facebook_login=1" label="Register" />[% END %]"> <fb:multi-friend-selector showborder="false" actiontext="Invite your Facebook Friends to use SocialToo" condensed="true" /> </fb:request-form> </fb:fbml> </script> </fb:serverfbml> Note: The only difference between this and the above example is that we added a condensed="true" attribute in the fb:multi-friend-selector.url="http://socialtoo. and track which friends a user has invited. and "typeahead" to the URL it posts to when a user submits the form. the "typeahead" parameter sent on POST is the text entered into the type-ahead box of your friend selector.

user feedback about your site's use of Facebook's communication channels (email. and requests). the sections on requests and invites. allowing them to select only that many friends per day. Next Step: Finding Friends through Facebook Another useful application of invites and requests is the ability to utilize fb:connect-form to automatically associate your users' friends with their Facebook accounts if they have one. There are actually two versions of this button . please read the Developer Roadmap. Just include "requests_per_day" as your integration_point_name variable. For more information. For information about the condensed version.the full version and the condensed version. This page describes the full version. Facebook provides the admin.getAllocation API call for you to retrieve such. Each day. This can serve as a useful way for your users to find new friends they didn't know already existed on your site. subject to how well the website adheres to the Platform Principles and Policies and the way it encourages users to share information with each other. Details will follow soon. see fb:multi-friend-selector (condensed). search • Description Facebook is modifying the way you can use the multi-friend selectors. You can also look it up under the User Response tab under your application's Insights. notifications. This number will show automatically in the multi-friend selector form the user sees. and Facebook will return to you the number of requests remaining. This interface includes a series of <input type="hidden" name="ids[]" value="[friend id]"> which are included for selected users in the form that gets submitted to your <fb:request-form> 41 . This is a nearly full-page interface intended to be used on canvas pages to allow the user to send a "large" number of requests or invitations (where "large" is generally some number more than 4). Fb:multi-friend-selector From Facebook Developer Wiki Jump to: navigation. This tag must be used inside an fb:request-form tag. Facebook allocates a certain number of requests allowed in that day per user. If you need to detect that limit programatically. specifically.

and is capped at the 42 required actiontext optional showborder bool rows int max int . the default "Skip" is more appropriate. (Default value is 5 and the value must be between 3 and 10. a full page version of this is available. please choose the appropriate bypass string for the context in which the multi-friend selector appears. After the friend authorizes your application. Please see Multi_friend_selector for information about using it. "Cancel" may be the appropriate string. as "Cancel" may imply the cancellation of the application flow instead. For developers using iframes.action URL. if the user clicks a link to explicitly arrive at the multi-friend selector. However. This value ranges from 1 to 35. For example. If a user attempts to go over this limit. Your users can invite their friends who aren't yet on Facebook by entering their email addresses in the text box at the bottom of the multi-friend selector. A user may invite a number of people each day equal to the maximum number of requests allocated to your application. Both the Skip this Step button and the Submit button take the user to the parent fb:request-form action URL. if the user arrives at the multi-friend selector within the context of an application flow. You need to use Express Registration in order to have those friends join Facebook and authorize your application at the same time. it gets bookmarked automatically.) The maximum number of users that can be selected. The number of rows of friends to show in the multifriend-selector. Indicates whether you want a border around the outside of the multi-friend-selector. As a best practice suggestion. the following message appears: Attributes Require d Name Type string Description An instructional message to display to users at the top of the multi-friend-selector.

The value must be one of: 2 (which sets the box to 368px wide). (All of them. This attribute is ignored if it is greater than the number of requests your application is able to send.) Indicates whether you want to display an email invite section in the multi-friend-selector. (Default value is 5. The number of columns of friends to show in the multi-friend selector. 3 (which sets it to 466px wide). Set this attribute to "step". The version of the Bypass button you want to use. which results in Skip This Step. Examples <fb:multi-friend-selector actiontext="Select the friends you want to invite. "cancel".)" rows="3"/> 43 . exclude_ids array bypass string A comma-separated list of user IDs to exclude from the multi-friend-selector. or "skip". Cancel. or Skip. (Default value is skip. respectively. which also determines the width of the invite box. or 5 (which sets it to 740px wide).) email_invite bool cols int POST Variables Required Name ids Type array Description An array of the user IDs chosen by the user.number of friend requests the user has remaining under their limit.

search 44 .Extended permissions From Facebook Developer Wiki Jump to: navigation.

You need an active session read_stream with the user to get this data.Facebook offers some API functionality that requires the user to specifically opt in before your application or site can use that functionality. Without this permission. comments. The available extended permissions are: Permission Description Lets your application or site post content. and share_item extended permissions. the user can choose to whom the permission applies: to the user him or herself and to any or all of the Pages. Users express this trust by granting your application or site specific extended permissions. photo_upload. If the user is a Page admin and encounters the permission dialog. This includes all of the posts in a user's stream. you need only prompt them for publish_stream. viewable to anyone on Facebook. When the user accepts. you can send the user email directly to the user's primary Facebook email address or the proxied email address (whichever address 45 . you can get still query for public data. and likes to a user's profile and in the streams of the user's friends without prompting the user. These permissions allow your application to perform certain actions. These methods are specific to certain use cases that require a greater level of trust from the user. email This permission allows an application to send email to its user. create_note. You can also prompt a user who administers a Facebook Page to grant permissions for the Page as well. so if you haven't prompted users for those permissions yet. Lets your application or site access a user's stream and display it. publish_stream This permission is a superset of the status_update. video_upload.

• 46 . Read more about session keys. edit.create. share_item Note: You should prompt users for the publish_stream permission instead. This permission allows a mobile application to send messages to the user sms and respond to messages from the user via text message. This permission allows an application to provide the mechanism for a user to post links to their profile. If the user grants this permission. since it includes the ability to let a user write notes. thread. This permission allows an application to provide the mechanism for a user to write.addTag methods. You can read from a user's Inbox via read_mailbox message.hasAppPermission method or the permissions FQL table.upload and photos.the user chose to share with you). since it includes the ability to update a user's status. This permission allows an application to provide the mechanism for a user to upload videos to their profile.cancel methods. This permission relaxes requirements on the photos.set or users. This permission grants an application the ability to read from a user's Facebook Inbox. photos uploaded by the application will bypass the pending state and the user will photo_upload not have to manually approve the photos each time.rsvp method. status_update Note: You should prompt users for the publish_stream permission instead. and message FQL tables. video_upload Note: You should prompt users for the publish_stream permission instead. Note: You should prompt users for the publish_stream permission instead. events. create_note Note: You should prompt users for the publish_stream permission instead.getThreadsInFolder as well as the mailbox_folder.setStatus method. since it includes the ability to upload a video. This permission grants an application access to user data when the user is offline_access offline or doesn't have an active session. This permission allows an app to RSVP to an event on behalf of a user via rsvp_event the events. since it includes the ability to let a user share links. and delete notes on their profile. This permission allows an app to create and modify events for a user via create_event the events. since it includes the ability to upload a photo. You can query whether a user has granted your application or site any of the above permissions using the users. This permission grants your application the ability to update a user's or Facebook Page's status with the status.edit and events.

publish_stream"> Grant permission for status updates </fb:prompt-permission> • • By directing them to the URL: http://www. The user is prompted for each permission in a separate dialog.php? api_key=YOUR_API_KEY&v=1. You can request one or more extended permissions from a user using one of these methods: • • • • By calling Facebook. read Authorization and Authentication for Desktop Applications. for use with IFrame applications and Facebook Connect sites. For example: <fb:prompt-permission perms="read_stream.showPermissionDialog. for use with FBJS and FBML applications. by directing the user to the URL: http://m. you can prompt only for the publish_stream permission using this method. Desktop applications can use this method only to prompt for permissions.com/connect/prompt_permissions. For Facebook Pages.showPermissionDialog. For Facebook Pages. but not a Facebook Page. By including the promptpermission attribute in a form. Use this method to prompt for any permission from a user. By calling FB.Connect. You can't use the promptpermission attribute for Connect sites and IFrame applications. For mobile applications.com/authorize. By including the fb:prompt-permission tag in your FBML application.Prompting Users to Grant Extended Permissions You must prompt your users to grant extended permissions. though you can use this to prompt for any permission from a user. For information on formatting this URL. 47 . though you can use this to prompt for any permission from a user. a permissions dialog like the following appears.facebook.facebook.php. you can prompt only for the publish_stream permission using this method.0&ext_perm=PERMISSION_NAME When the user submits the form or follows the URL.

php/en_US" type="text/javascript"></script> 48 . $fb = new Facebook('[API KEY]'.init call. this dialog appears after the authorization or Connect dialog. you need to pass the required_permissions parameter to require_login.Requiring Extended Permissions If your application or site requires any extended permissions from a user (for example. you need to include the permsToRequestOnConnect parameter in your FB. $fb->require_login($required_permissions = 'email. pass the permissions as a commaseparated string. <script src="http://static.4/FeatureL oader. prompting the user for the permission.facebook.read_stream'). You prompt the user to grant your application or site the extended permission by passing a special parameter to any of the following methods: • • • require_login (for applications and sites calling the server side API) FB. you might require a user's email address so you can send receipts for virtual goods bought within your application. If the user has never authorized your application or connected to your site before. or your application might read from a user's stream).init (for applications and sites using the original JavaScript Client Library) FB. '[APP SECRET]'). Facebook will display an extended permission dialog when the user visits your application or site. you need to pass a specific parameter when the user authorizes or logs in to your application or Facebook Connect site.com/js/api_lib/v0.ak.init with the Original JavaScript Client Library If you're using the [JavaScript Client Library]] with a Facebook Connect site or IFrame application. You can require more than one permission. If you do.login (for applications and sites using the open source JavaScript SDK) Using require_login with the Server Side API If you are using the PHP client with a canvas application or Facebook Connect site. If an existing user has never granted your application or site the extended permission.js. Using FB.

the user can revoke the extended permission there. }). {perms: 'email. On the Additional Permissions tab.login call.login(callback. direct the user to the URL: http://www. There is no direct URL for editing the permissions for a single application. call FB.Connect. you need to include the permissions in the options parameter of the FB.read_stream'}).showPermissionDialog. Should a user want to revoke an extended permission. 49 .com/editapps. { permsToRequestOnConnect : "email.login with the Open Source JavaScript SDK If you're using the open source JavaScript SDK. Users have to click the appropriate application's Edit Settings link on the Edit Applications page. FB.php. Revoking Extended Permissions If you need to revoke an extended permission from a user.revokeExtendedPermission.init("YOUR_API_KEY".read_stream".facebook. this applies to new users and users who have already connected. </script> If you're prompting an existing user for an extended permission. then click Edit Settings next to the application in question.<script>FB. Users can reach this page by clicking Edit Applications in the applications menu (or choosing Settings > Application Settings on the top menubar. null. Using FB. call auth.