An Intro to Facebook Connect Development
Posted by Jesse Stay on September 26th, 2008 9:28 AMJust recently at F8, Facebook announced the launch of the ability to integrate your website’s users with users inside Facebook through a technology they call Facebook Connect. Such technology enables your website’s users to login using their Facebook username and password, right on your site, and link their profile and friend information directly to your own site for display and access outside of Facebook. Once authenticated, your site can also make calls for those users (with their permission) back to Facebook, enabling an interesting viral opportunity for your website or brand. Facebook Connect is not live yet, predicted to launch in September of 2008, it is in Sandbox mode currently. (It’s very important to note that only developers of your Facebook Connect apps can currently login through Facebook Connect! When Facebook Connect goes live to the public anyone will be able to start using it.)
This post is intended to be a guide for developers looking to get started with Facebook Connect, or CIOs and CTOs with an interest to learn what Facebook Connect can bring to your company, and what resources will be needed to do so. This will be a basic howto on getting started in Facebook Connect.
Facebook Connect – How it Works
Facebook Connect is basically a series of libraries on top of the existing Facebook Javascript Client Library which enable any site on the web to allow a user to log into Facebook, right on the site itself (via a simple dialogue box that Facebook pops up), authenticate that user, and retrieve a session for that user right on the 3rd party website. The session is set by enabling a series of cookies for the facebook.com domain that can be accessed via the Facebook API. Then, either using server-side APIs or the Javascript Client API, the developer can retrieve info about the user and their friends, just like they would through a Facebook App itself.
Each 3rd Party website set up on the service requires an App to be set up on Facebook for the site, just as you would set up any other App on Facebook. The Callback URL is the base URL of the site you are trying to integrate Facebook Connect for, and your site must call Facebook Connect from that URL in order for it to work.
With simple Facebook Javascript Client code (which is just a snippet of Javascript you can place on any page), Facebook has also introduced “xFBML”, a standard of FBML designed to be placed on websites outside of Facebook. So, for instance, assuming you have his Facebook ID and you have the permissions to see it, you could just put <fb:name uid=”4”/> on your website and your website would automatically display Mark Zuckerberg’s name – the same works with <fb:profile-pic/> and almost any other FBML tag you can think of.
This code enables you to place a <fb:login-button/> tag on your website, which renders a simple Facebook Connect login button for your users to authenticate to Facebook with.
Facebook then sends successful requests to a FB.Facebook.get_sessionState().waitUntilReady() Javascript method call, in which you can place other Javascript code to handle the request after that. Such code could be an AJAX request to update your database with the authenticated user’s Facebook ID, or anything else you might need to do with that user after they log in. (Keep in mind that Facebook limits you to what you can and can’t store in the database)
Figure 1 - Graphic courtesy Facebook
Facebook’s Sample Apps
There are 2 snippets of sample code that Facebook provides for you to download and look over. One is a full-featured app, called “The Runaround”, written in PHP that shows most of the features Facebook Connect provides. You can see it in action at http://www.somethingtoputhere.com/therunaround/. Then, download the code and see how it works at http://www.somethingtoputhere.com/therunaround/demo.tgz.
The other sample Facebook provides is a much more simple series of static HTML files that each perform a different function. The first is a very basic implementation of Facebook Connect, showing what the login flow would look like with a simple <fb:login-button/> login button implementation and simple API call back to the server via the Facebook Javascript Client Library to get a list of the user’s friends and popup with that list of friends in a javascript alert() box.
The second shows the power of the Facebook Javascript Client Library running on your own website by allowing you to use xFBML right in the source of your page to render different things. Such tags featured are <fb:name/>, <fb:profile-pic/>, <fb:eventlink/>, <fb:grouplink/> and <fb:pronoun/>. It’s a great example showing that just about any FBML tag can be used on an external website that incorporates Facebook Connect.
The third example delves a little further by showing how you can display simple friend selectors and invite forms by utilizing <fb:serverfbml/> to render them. (The <fb:request-form/> tag must be rendered from Facebook’s servers and this takes care of that)
Set up of the static HTML demos is as simple as going to Facebook, setting up an App under the callback URL of the domain you will be hosting them under, and entering your API key in the place specified in the source HTML. Beyond that you just need to place the provided xd_receiver.htm file in the place specified in the HTML and you’re all set to try it out! You can download the static HTML demos at this link.
Simple “Hello Friends” for Facebook Connect
Let’s give this a try on your own site. To start, you need to create an App within Facebook. You’ll need to add the Developer app to your account at first (I suggest you purchase my book, FBML Essentials, if you would like to learn how to do this). Then, (we’re going to go by the new Facebook design for all of this since it will launch to all in just a matter of days), click on the “Applications” link at the top of your profile, and click “Set up New Application” in the top right.
After this, just name your App (I’m calling mine the “Stay N’ Alive” App), check the box saying you agree to the Facebook Platform Terms of Service, and then click the “Optional Fields” link. After this all you need to specify is a callback URL for your site. I’m specifying http://staynalive.com, which is where my files will be hosted. This should be the base URL of your site you will be calling Facebook from. After that, add any developers you would like to also be able to log in through Facebook Connect (this won’t be necessary when Facebook Connect goes live), and click “Submit”.
On the following page you’ll now have an API Key and Secret Key. For the purposes of our Hello Friends app we only need the API key – copy and paste this somewhere so you can access it later. Or you can always come back to this page through the Developer app on Facebook.
Now, let’s get to our sample website. To make your website work, you’ll need to start with some basic HTML – put this in a file like index.html. I used the following:
<html>
<head>
<title>Facebook Connect “Hello Friends” Example</title>
</head>
<body>
<p id=”hello”>Hello
World!</p>
<div>
<fb:login-button></fb:login-button>
</div>
</body>
</html>
In the example above we create a simple HTML page that when printed, says, “Hello World”. You might notice we added an FBML tag in there called <fb:login-button/> which right now doesn’t display anything in the browser. There’s nothing telling your web page what to do with that FBML, so it treats it like a normal XML tag. So, let’s add in some Javascript from the Facebook Javascript Client Library to tell it what to do with that:
<html>
<head>
<title>Facebook Connect “Hello Friends” Example</title>
</head>
<body>
<p id=”hello”>Hello World!</p>
<div><fb:login-button></fb:login-button></div>
<script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script>
<script type="text/javascript">
FB_RequireFeatures(["XFBML"],function()
{
FB.Facebook.init("YOUR_API_KEY_GOES_HERE","xd_receiver.htm");
});
</script>
</body>
</html>
Please note that you must insert the API Key you saved above from your application set up where I put YOUR_API_KEY_GOES_HERE.
To make it render the xFBML appropriately we added 2 new snippets of code. The first, we loaded the Facebook Javascript Client library, via http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php. You may want to set this as a configuration variable somewhere if you use it in PHP, as it could always change in the future.
Secondly, we added a bit of Javascript code. We call the FB_RequireFeatures() method from the Facebook Javascript Client Library we just loaded, and pass to it an array with one element, “XFBML”, and an anonymous function that calls FB.Facebook.init() with your API key and xd_receiver.htm. FB_RequireFeatures is a function that just loads the features from the Facebook Javascript Client Library that you will need, and then runs the callback, which in this case is the anonymous function you set. You have to call FB.Facebook.init() to specify what your API Key is (so Facebook knows which App it is referencing), along with the location of the cross domain scripting file, called xd_receiver.htm. You should also create the xd_receiver.htm file – it should simply contain the following code (which you can get from the demo files above):
<!DOCTYPE
html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<title>cross domain receiver page</title>
</head>
<body>
<script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/XdCommReceiver.debug.js" type="text/javascript"></script>
</body>
</html>
Place the xd_recevier.htm file in the same location as the index.html file you created above (note that index.html can be called anything – you just need to know how to call it from your browser), and then load the page. Now you will see something that looks like this:
You’ll notice there’s now a pretty button rendered by Facebook for logging into Facebook Connect. If you click on it, a dialogue box will pop up, asking you to log in. If you log in, it will simply close the dialogue box and go back to the same page. (Please note that if it redirects to Facebook.com you are probably not listed as a developer of the App. As long as Facebook Connect is in Sandbox mode, you must be a developer of the App to log in via Facebook Connect!)
So, how do we get it to know that the user has logged in, and do something with that user? We just need to add one snippet of javascript in the FB_RequireFeatures callback function above. Make your FB_RequireFeatures Javascript look like this:
<script type="text/javascript">
FB_RequireFeatures(["XFBML"],function()
{
FB.Facebook.init("YOUR_API_KEY_GOES_HERE", "xd_receiver.htm");
FB.Facebook.get_sessionState().waitUntilReady(function(){
document.getElementById(“hello”).innerHTML =“Hello Friends”
FB.Facebook.apiClient.friends_get(null,function(result, ex) {
window.alert("Friends list: "+ result);
});
});
});
</script>
In our revised example, we add a new function call, called FB.Facebook.get_sessionState().waitUntilReady(), which gets passed a callback function. In our case we just pass it an anonymous function. In this function, you can make it do whatever you want it to do after it recognizes the user is logged in. In our example we start by resetting the innerHTML of our “hello” element (which used to say “hello world”), and replace it with “Hello Friends”.
Following that we make a call to the Facebook client via Javascript to retrieve the logged in user’s friends list. We then do a javascript alert to list out the user’s friends list. Other things you could do in this callback could be a call via ajax to load some PHP code that does server side calls to the Facebook API. If you look at the RunAround App code it does this, as will our next example in this series which we will debut later. You could also send a mini feed story out to Facebook just as you would in the regular Facebook API – you can see once the user is logged in you can treat them just as you would any other Facebook user in a regular Facebook Application. If you want to get rid of the Facebook Connect button (pictured above) after the user has logged in, you can do that either via javascript and removing the button from your page’s DOM, or you could always include CSS that renders the .fb_login_ready class hidden. After the user is logged in, the class of the login button changes from fb_login_not_logged_in to fb_login_ready.
Now that you have all the above code in place, you should be able to have a user log in to Facebook right on your site, you should be able to render FBML right on your site, and you should be able to take a user’s credentials and retrieve information from Facebook about that user. You can now begin to understand the power of Facebook Connect – keep in mind that all this was performed in a static HTML file!
You can now access almost any API call that does not require a user’s secret key. Per the Facebook documentation, the only inaccessible API calls via the Facebook Javascript Client library are calls that set admin data or profile data. If you want to do this you will need to set your secret API key through your server.
You can start studying more on Facebook Connect at the Facebook Developers Wiki at http://wiki.developers.facebook.com/index.php/Facebook_Connect.
(4.64 out of 5)
(4.22 out of 5)
September 26th, 2008 at 10:08 am
Outdated images in this post.
Facebook asks email and password in a popup window now, to avoid phishing. Also connect button is different now. See FB connect live in http://www.theinsider.com/
September 26th, 2008 at 10:47 am
Good point, Vivek. I had forgotten about that when we posted. I'll get some updated images up there ASAP.
September 26th, 2008 at 10:59 am
Perfect timing Jesse! We have the Bay Area fb meetup totally focused on Fb connect next Monday on 29th.
We have developers share their real experience w FB connect and a Q&A w Luke Shepard of facebook.
Too bad you are not in town to join us.
September 26th, 2008 at 1:42 pm
Nice, more people have information about me. Hope Facebook makes a million off my info
September 26th, 2008 at 3:58 pm
Great post Jesse!
September 26th, 2008 at 4:07 pm
One question though and that's with logging into Facebook connect as surely sites could replicate the login process and then obtain users email addresses and passwords. I expect that Facebook redirects to the social networking site but not everyone is savy and I see an opportunity for this to be misused. How safe is this Jesse and is what I mention possible?
September 27th, 2008 at 1:03 am
Joe, I imagine that would be very possible, and very good point. Currently Facebook does do a popup for the login process to prevent phishing, but I think the potential for phishing could be very possible, and definitely something to worry about.
October 8th, 2008 at 12:40 pm
On a related note about phishing, this problem is there with sharing icons we see in all blogs & product sites, where they show icons for facebook, myspace, stubleupon, digg etc., When we click on those icons it opens a page or popup of the specific social site & asks for login/password. Bad guys can easily imitate & grab user id / password. Non-technical people will not notice the difference while sharing the links in zombie mode.
October 13th, 2008 at 8:34 am
That is what I was really looking for, much better than on the Facebook wiki
Thanx!
October 28th, 2008 at 6:37 pm
[...] to Mike Arrington Facebook Connect will be launching on November 30th. Facebook started rallying developers and [...]