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 alpha 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
We will be actively iterating on this, and expect to have a beta release shortly. Once we've worked out all the kinks, we will announce the final release. Remember, this is an alpha release!
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://static.ak.fbcdn.net/connect/en_US/core.js"></script>
<script>
FB.init({
apiKey : 'YOUR API KEY',
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({
apiKey : 'YOUR API KEY',
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.type = 'text/javascript';
e.src = 'http://static.ak.fbcdn.net/connect/en_US/core.js';
e.async = true;
document.getElementById('fb-root').appendChild(e);
}());
</script>
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]:
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()][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 Alpha 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.