Facebook Connect Tutorial1

From Facebook Developer Wiki

Jump to: navigation, search

Contents

[edit] What You'll Learn

This tutorial covers how to add a Facebook Connect button to your site (in this case, a blog that allows user comments) and adds the user's Facebook name and profile picture when a user clicks the Connect button. Note that this tutorial covers only the first steps towards a full Facebook Connect implementation. A complete solution will almost always involve a server-side component. We'll cover additional integrations in later videos.

You can follow along the video tutorial as you read this article:
Image:Tutorial_Video.png


[edit] What You'll Need

  • A website for which you control the code and have server access. If you use software like MovableType, WordPress, or Drupal, check out our Facebook Connect Plugin Directory.
  • Basic knowledge of JavaScript and HTML.

[edit] Tutorial Step by Step

[edit] Adding a Connect Login Button to a Comment Form

Let's begin with a basic HTML file that contains this initial code for your blog's comment submission form:

<html> <body> <div id="comments_post"> <h3>Leave a comment:</h3> <form method="POST"> <div id="user"> Name: <input name="name" size="27"><br /> </div> <textarea name="comment" rows="5" cols="30"></textarea> <br /> <input type="submit" value="Submit Comment"> </form> </div> </body> </html>


First, we'll add a Facebook Connect login button.

  1. Add an <fb:login-button></fb:login-button> tag under the Name field.
  2. Because fb:login-button is an XFBML tag, we need some Facebook-specific JavaScript to actually render it. Put this line at the bottom of your HTML file, right before the closing </body> tag.
    <script type="text/javascript" src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php"></script>

  3. Create a cross domain receiver file, which is necessary for secure cross-domain communication with Facebook. Just copy and paste the following text into a file called xd_receiver.htm on your site:
    <!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" > <body> <script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/XdCommReceiver.js" type="text/javascript"></script> </body> </html>

  4. Each Connect website is treated as a Facebook application, and so it needs an API key. Go to the Facebook Developer application and click Create An Application. Fill in these fields:
    • Application Name: this will be what your users will see when they connect to your site.
    • Terms of Service: Select Agree. The Developer Terms of Service govern among other things how you can use the information on your site. Pay particular attention to section G, Facebook Connect.
    • Connect URL: This is the root URL of your site. Your cross-domain receiver file must be underneath the directory specified.
    • Icon (Optional): You can add an image to represent your site in the News Feed stories you publish.
    • Facebook Connect Logo (Optional): You can add an image to represent your site in the Connect dialog.
    • Base Domain (Optional): If your site runs on multiple subdomains, you may need to set the Base Domain. Note that this applies even if you run on something.com and www.something.com, as those are different subdomains.
  5. Submit your application, and make note of your API key.
  6. Go back to your original file. Underneath the <script> include, and right before the closing </body> tag, you need to add the following line of JavaScript, which tells Facebook your API key and the location of the cross-domain receiver file.
    <script type="text/javascript"> FB.init("3f0ba1d70537bbf9381bca2bbb9f9a93","xd_receiver.htm");</script>

  7. Finally, because XFBML is an extension to HTML, we need to make sure that the browser knows to ignore these tags. Do that by defining an XML namespace in your <html> tag. The top of your file should look like this:
    <!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" xmlns:fb="http://www.facebook.com/2008/fbml">

    Your file should look like this now:
    <!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" xmlns:fb="http://www.facebook.com/2008/fbml"> <body> <div id="comments_post"> <h3>Leave a comment:</h3> <form method="POST"> <div id="user"> Name: <input name="name" size="27"><br /> <fb:login-button></fb:login-button> </div> <textarea name="comment" rows="5" cols="30"></textarea> <br /> <input type="submit" value="Submit Comment"> </form> </div> <script type="text/javascript" src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php"></script> <script type="text/javascript"> FB.init("3f0ba1d70537bbf9381bca2bbb9f9a93","xd_receiver.htm"); </script> </body> </html>

  8. Go back to your browser and refresh the page. Click the Connect button, connect your account, and then ... nothing happens. Why? We need to change the login button so it displays the full call to action – "Connect With Facebook". Add an onlogin attribute to your login button, which is described in detail in the next section.


You can choose from a number of login button styles; read Facebook Connect Login Buttons for the various options.

[edit] Adding an onlogin Handler

Next, we'll add some JavaScript to execute when the user connects accounts.

Start by verifying that the Connect button works by adding an alert handler to the fb:login-button tag.

<fb:login-button onlogin="alert('hello');"></fb:login-button>


Go back and refresh the page, then click the Connect button. You should see the alert.

Now let's have the button do something. It should add the user's name and profile picture and make the login button disappear after the user connects. Replace your existing fb:login-button code with this:

<fb:login-button onlogin="update_user_box();"></fb:login-button>


Then after the button reference, you can define the function.

<script type="text/javascript"> function update_user_box() { var user_box = document.getElementById("user"); // add in some XFBML. note that we set useyou=false so it doesn't display "you" user_box.innerHTML = "<span>" + "<fb:profile-pic uid='loggedinuser' facebook-logo='true'></fb:profile-pic>" + "Welcome, <fb:name uid='loggedinuser' useyou='false'></fb:name>. You are signed in with your Facebook account." + "</span>"; // because this is XFBML, we need to tell Facebook to re-process the document FB.XFBML.Host.parseDomTree(); } </script>


Refresh the page, click the Connect button, and you see that the name and picture appear.

Now, your file looks like this:

<!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" xmlns:fb="http://www.facebook.com/2008/fbml"> <body> <div id="comments_post"> <h3>Leave a comment:</h3> <form method="POST"> <div id="user"> Name: <input name="name" size="27"><br /> <fb:login-button onlogin="update_user_box();"></fb:login-button> </div> <textarea name="comment" rows="5" cols="30"></textarea> <br /> <input type="submit" value="Submit Comment"> </form> </div> <script type="text/javascript"> function update_user_box() { var user_box = document.getElementById("user"); // add in some XFBML. note that we set useyou=false so it doesn't display "you" user_box.innerHTML = "<span>" + "<fb:profile-pic uid=loggedinuser facebook-logo=true></fb:profile-pic>" + "Welcome, <fb:name uid=loggedinuser useyou=false></fb:name>. You are signed in with your Facebook account." + "</span>"; // because this is XFBML, we need to tell Facebook to re-process the document FB.XFBML.Host.parseDomTree(); } </script> <script type="text/javascript" src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php"></script> <script type="text/javascript"> FB.init("3f0ba1d70537bbf9381bca2bbb9f9a93","xd_receiver.htm"); </script> </body> </html>

[edit] Correcting Page Load Behavior

You may have noticed that on page refresh, you always need to click the Connect button, which is really annoying. We have several ways of handling this. If you have a server-side component, you can detect that the user is logged in based on the cookies and just serve logged-in content directly. However, if you're doing it entirely in JavaScript (as in this example) you can use the ifUserConnected modifier to easily execute something on load if the user is logged in.

Modify your FB.init call to always run update_user_box whenever the user is connected, even if it's on page load:

FB.init("3f0ba1d70537bbf9381bca2bbb9f9a93","xd_receiver.htm", {"ifUserConnected" : update_user_box});

Now, on page load, if it detects that the user is logged into Facebook and connected with your site, it will execute this code. There is a minor flicker, which can be avoided with clever CSS tricks. The server-side rendering is also preferable if you have a lot of Facebook user specific content.

[edit] About Server-Side Security

In a real application, you could also include additional HTML to tell your server that this is a Facebook request. For example:

<input type="hidden" name="facebook-request" value="true" />


However, you definitely shouldn't set the user ID. The Facebook JavaScript library sets cookies that your server can use not only to get the user ID, but also to verify securely that the call came from Facebook. See Verifying The Signature for more details. We will cover this in a later tutorial.

[edit] Debugging Connect

If any of these steps don't work, check out the Facebook Connect FAQ. Soon, we'll post an article on debugging Facebook Connect for some information on the right tools and techniques to use to figure out exactly what's happening behind the scenes.

[edit] Other Tutorials

You can go here to find out how to integrate Facebook Connect into site that has its own login mechanism and existing user base. It will review topics like single sign on, linking an existing user to their Facebook ID, and creating a new account based on information from Facebook.

Retrieved from "http://wiki.developers.facebook.com/index.php/Facebook_Connect_Tutorial1"
reference