Facebook Connect is a set of APIs that make your application more social. With it you gain access to:
- Identity: name, photos, events and more -- User.
- Social Graph: friends and connections -- Connection.
- Stream: activity, distribution, and integration points within Facebook, like stream stories and Publishers UI Dialogs.
This repository contains the open source JavaScript SDK that allows you to utilize the above on your website. Except as otherwise noted, the Facebook Connect JavaScript SDK is licensed under the Apache Licence, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0.html)
This is an beta release. In order to guide the development of the library and allow you to freely inspect and use the source, we have open sourced the client JavaScript SDK. At a high level, the SDK provides:
- Authentication & Authorization
- Ability to make API calls
- Ability to show UI dialogs
- XFBML Tags & Widgets
- Data Access Abstractions
The examples are a good place to start. Here's an example of initializing (FB.init()) the library with all the options turned on:
<div id="fb-root"></div>
<script src="http://connect.facebook.net/en_US/all.js"></script>
<script>
FB.init({
appId : 'YOUR APP ID',
status : true, // check login status
cookie : true, // enable cookies to allow the server to access the session
xfbml : true // parse XFBML
});
</script>
For better performance, you should load the initial script itself in a
non-blocking manner. This will mean you have to be more conscious about how you
invoke anything in the FB namespace, as asynchronously loading the script can
cause it to arrive after your application scripts have been loaded. To make
this more convenient, the library looks for a global named fbAsyncInit.
If it exists, this function will be executed once the library has been loaded.
You should trigger all FB related logic from here. When using this approach,
you should put the code right after the opening <body> tag. This will allow
Facebook to initialize in parallel with the rest of your page.
<div id="fb-root"></div>
<script>
window.fbAsyncInit = function() {
FB.init({
appId : 'YOUR APP ID',
status : true, // check login status
cookie : true, // enable cookies to allow the server to access the session
xfbml : true // parse XFBML
});
};
(function() {
var e = document.createElement('script');
e.src = document.location.protocol + '//connect.facebook.net/en_US/all.js';
e.async = true;
document.getElementById('fb-root').appendChild(e);
}());
</script>
Facebook Connect features are available many locales. You can replace the
en_US locale specifed above with one of the supported Facebook
Locales. For example, to load up the library and trigger dialogs,
popups and widgets to be in Hindi (hi_IN), you can load the library from this
URL:
http://connect.facebook.net/hi_IN/all.js
Facebook Connect is also available over SSL. You should only use this when your
own page is served over https://. The library will rely on the current page
protocol at runtime. The SSL URL is the same, only the protocol is changed:
https://connect.facebook.net/en_US/all.js
Facebook Connect provides the great benefit of removing the registration process by allowing the user to login to your site with their Facebook account. This is achieved by sharing the logged in user state between http://www.facebook.com/ and your site http://www.example.com/. A Connected user remains logged in to your site as long as they are logged in to Facebook.
This means you get to skip a lot of the boring stuff when you're building your hot new application. You don't need to create your own registration flow, and your users don't have to create new profiles, upload profile pictures or remember a username. But not only that, you also get the user's social graph, and many other useful pieces of information. Facebook Connect can also be used with your existing user management system as many sites already do.
The first step is figuring out how you identify who the current user is, and how to make API calls on their behalf. In fact, almost half of the public API deals directly with auth:
- FB.login() -- login and/or request extended permissions
- FB.logout() -- logout (only if the user is connected with your application)
- FB.getLoginStatus() -- get current login status from facebook.com
- FB.getSession() -- synchronous accessor for the current session
In addition, there many events that you can subscribe to using FB.Event.subscribe():
- auth.statusChange
- auth.sessionChange
- auth.login
- auth.logout
Facebook provides many server-side APIs to enable you to integrate data from Facebook into your site, as well as allowing you to submit data into Facebook. The JavaScript SDK makes all this available to you via FB.api():
FB.api(
{
method: 'fql.query',
query: 'SELECT name FROM user WHERE uid=5526183'
},
function(response) {
alert('Name is ' + response[0].name);
}
);
One of the most powerful features of the SDK is to integrate Facebook UI flows into your application. The most common example of this is the stream.publish dialog. FB.ui() is the method that allows you to trigger this and other dialogs. For example:
FB.ui(
{
method: 'stream.publish',
attachment: {
name: 'Connect',
caption: 'The Facebook Connect JavaScript SDK',
description: (
'A small JavaScript library that allows you to harness ' +
'the power of Facebook, bringing the user\'s identity, ' +
'social graph and distribution power to your site.'
),
href: 'http://fbrell.com/'
},
action_links: [
{ text: 'fbrell', href: 'http://fbrell.com/' }
]
},
function(response) {
if (response && response.post_id) {
alert('Post was published.');
} else {
alert('Post was not published.');
}
}
);
UI dialogs are documented at TODO.
XFBML and Widgets provide a simple, low effort means of integrating social features into your site. The current set of supported tags are:
- fb:comments
- fb:fan
- fb:live-stream
- fb:login-button
- fb:name
- fb:profile-pic
- fb:serverfbml
- fb:share-button
We have made API documentation available for the public APIs here. In addition, the code itself contains full documentation for the private APIs if you want to study the internals.
We have a list of FAQs that detail some of the changes and provide information about the new SDK.
We are maintaining a changelog as we update the SDK. Since this is an Beta SDK, we might need to break compatibility between releases if the need arises.
The repository also contains simple examples showing the use of the SDK with popular JavaScript libraries such as Dojo, jQuery, MooTools, Prototype and YUI.
We are relying on the GitHub issues tracker linked from above for feedback. File bugs or other issues here.
We are working hard to ensure your experience using Connect is stable. In order to keep us nimble and allow us to bring you new functionality, without compromising on stability, we have ensured full test coverage of the new SDK. We are including this in the open source repository to assure you of our commitment to quality, but also with the hopes that you will contribute back to help keep it stable. The easiest way to do so is to file bugs and include a test case.