Connect/Setting Up Your Site

From Facebook Developer Wiki

Jump to: navigation, search

To quickly integrate your site with Facebook Connect, you need to set up a basic Facebook application, get an API key, then add some snippets of JavaScript code to your site. By doing just this, you can easily have users log in with Facebook, or connect their accounts on Facebook with existing accounts on your site. All Connect sites should follow these steps.

Contents

Setting Up Your Application and Getting an API Key

If you don't already have a Facebook Platform API key for your site, create an application with the Facebook Developer application.

Note: Even if you have created an application and received an API key, you should review steps 1.4 through 1.7 and make sure your application settings are appropriate.

  1. Go to http://www.facebook.com/developers/createapp.php to create a new application.
  2. Enter a name for your application in the Application Name field.
  3. Accept the Developer Terms of Service, then click Save Changes.
  4. On the Basic tab, keep all of the defaults.
  5. Take note of the API Key, you'll need this shortly.
  6. Click the Connect tab. Set Connect URL to the top-level directory of the site where you plan to implement Facebook Connect (this is usually your domain, like http://www.example.com, but could also be a subdirectory).
  7. You should include a logo that appears on the Facebook Connect dialog. Next to Facebook Connect Logo, click Change your Facebook Connect logo and browse to an image file. The logo can be up to 99 pixels wide by 22 pixels tall, and must be in JPG, GIF, or PNG format. (Filename cannot be 'icon')
  8. If you plan to implement Facebook Connect across a number of subdomains of your site (for example, foo.example.com and bar.example.com), you need to enter a Base Domain (which would be example.com in this case). Specifying a base domain allows you to make calls using the PHP and JavaScript client libraries as well as get and store session information for any subdomain of the base domain. For more information about subdomains, see Supporting Subdomains In Facebook Connect.
  9. Click Save Changes.

Referencing Facebook Connect on Your Site

In order to reference Facebook Connect on your site, you need to upload a small file onto your server to enable communication between your site and Facebook. Then, for every file on your site where you want to integrate Facebook Connect, you need to add some JavaScript to those files to make sure you load the Facebook Connect features.

You can do this one of two ways: using the Facebook Connect Wizard, or creating the file yourself.

Using the Wizard

Using the Facebook Connect Wizard, you can quickly download and add a cross-domain communication channel file called xd_receiver.htm and place it in a directory relative to the Connect URL that you entered above.

Creating the File Yourself

  1. Create a cross-domain communication channel file called xd_receiver.htm and place it in a directory relative to the Connect URL that you entered above. For instance, let's say you're using http://www.example.com as your Connect URL, but you want to store your Facebook Connect files in their own subdirectory, say http://www.example.com/connect. You should create the xd_receiver.htm file in the directory from where you'll be serving your Connect Web pages (http://www.example.com/connect in our example). Copy the following content into the file:
    <!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>

    Or, you can download the file directly. This file will allow your application and Facebook to send data back and forth.

  2. Create another HTML file in the same directory as the one you created in the previous step, say, http://www.example.com/connect/test.html. Within the <html> tag for test.html, add this attribute: xmlns:fb="http://www.facebook.com/2008/fbml", as in:
    <html xmlns="http://www.w3.org/1999/xhtml" xmlns:fb="http://www.facebook.com/2008/fbml">

  3. Next, in your newly created test.html file, you need to refer to the Facebook JavaScript Feature Loader file, FeatureLoader.js.php. This will allow your site access to all of the features of Facebook Connect in JavaScript, like XFBML, JavaScript API calls, and so forth. This script should be referenced in the BODY of your file, not in the HEAD.
    <script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php/en_US" type="text/javascript"></script>

    Important: You need to reference the FeatureLoader script only once on a page. If you already have a Facebook Connect social widget on this page, you don't need to reference the FeatureLoader script again.

    Note: If your site is written in a language other than US English, you can specify a different locale when you reference this script. See Rendering Facebook Connect in Other Languages below.

  4. You can render a Facebook Connect login button using XFBML on your page, right alongside of your normal HTML. For instance, after the two lines that you just added, you could use a line of markup like this:
    <fb:login-button></fb:login-button>

    This will render the Facebook Connect login button, so that you'll be able to connect your Facebook account to your site. Optionally, you can add a JavaScript handler to the callback function to call when the user logs in:
    <fb:login-button onlogin="facebook_onlogin();"></fb:login-button>

  5. Finally, you need to include the following script after the login button:

    <script type="text/javascript"> FB.init("YOUR_API_KEY_HERE", "<path from web root>/xd_receiver.htm"); </script>

    For more details, see XFBML#Rendering_XFBML.

    All this script is doing is telling Facebook that you might want to render XFBML on your site, so it should load all necessary resources in order to do that.

  6. That's it! Try loading the test.html page you just created, then try connecting to Facebook. You've just created a basic Facebook Connect implementation!

    Here's the entire content of test.html:
    <html xmlns="http://www.w3.org/1999/xhtml" xmlns:fb="http://www.facebook.com/2008/fbml"> <head></head> <body> <script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script> <fb:login-button></fb:login-button> <script type="text/javascript"> FB.init("YOUR_API_KEY_HERE", "xd_receiver.htm"); </script> </body> </html>

Rendering Facebook Connect in Other Languages

If you have a Facebook Connect site and your content is in another language, you can have the Facebook Connect features (like the Connect dialog box, permission dialogs, and Feed forms) appear in the same language to provide your users with a seamless experience.

All you need to do is append the locale of your choice to the FeatureLoader.js.php script. For example, if your site is written in Spanish for a Latin American audience, you could choose to have Facebook Connect features appear in Spanish like this:

<script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php/es_LA" type="text/javascript"> </script>

Do this wherever you reference the FeatureLoader script. Otherwise, Facebook Connect defaults to the en_US (English/United States) locale.

Other Tutorials

This site shows a tutorial for integrating Facebook Connect with your existing site.

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