With the exponential growth of Facebook over the past few years, it’s safe to say that quite a large number of active web users today own and use a Facebook account regularly. Facebook connect, which Facebook launched late 2008, is a set of APIs which allow you to integrate your users’ Facebook profile into your web application. Apart from allowing your visitors to login to your site using their Facebook identity (hence negating the registration process), it also allows you to leverage on the various social features of Facebook. Let’s take a overview of Facebook Connect, and how we can integrate it into our web application.

Facebook APIs

Facebook provides both RESTFUL and Javascript APIs. A great number of client libraries are available for creating your web application, though Facebook provides official support for only a handful of them. We will be using Facebook’s official PHP 5 client and Javascript libraries.

FQL and XFBML

Before we look delve deeper into Facebook connect integration, let’s look at FQL and XFBML – the two essential components of the Facebook connect platform.

FQL (yes, Facebook Query Language!) allows you to query data from Facebook easily using a SQL like syntax. This can be a substitute to invoking specific API methods using the client library. As a quick example, if we want to retrieve the name of a particular user, we could do:

SELECT name FROM user WHERE uid=12345

Simple isn’t it? It’s important to note here that though FQL is very similar to SQL, it doesn’t fully conform to all aspects of SQL that you might come to expect. Take a look at the FQL documentation to find out about syntax support, and the various tables provided by FQL.

XFBML is a markup language provided by Facebook which allows you to embed Facebook based widgets and information into your page. By using XFBML tags, it’s much easier to embed information into the page, than having to query for it first (using FQL or an API call) and then displaying it in the application. For example, to display the user’s name, we do that simply by using the tag:

<fb:name uid="12345" />

With the basics out of the way, let’s get started on building a simple Facebook connect application using PHP.

Getting the API key

The very first thing you need to do when you are looking to make use of Facebook Connect is to apply for an API key. To get that, you need to sign in to the Facebook Developer app and create a profile for your web application.

Once you have chosen a name for your Facebook Connect application, and create the application, a profile will be created for your connect application within the Facebook Developer app. You can edit this profile to add in additional information about your application. Also, note that Facebook provides you with an API Key and a Secret, both of which you need to use while calling any FB Connect API method (for authenticating your request).

Although there are many fields, options and settions, you just need to provide Facebook with the URL of your Facebook Connect application, and you can get your application up and running! This can be done by clicking on the “Connect” link and filling in the “Connect URL” field:

When you are testing your application, it’s a good idea to place it under a sandbox such that only the developers have access to it. You can do that by going to “Advanced” tab and enabling the sandbox mode:

That’s it, we are ready to use Facebook Connect!

Creating the web app

Our sample Facebook Connect application will be really simple. Here’s the link to the demo (login using you FB account).

When the user visits the web app, we detect whether the user is already signed into Facebook. Facebook uses a single-on system – which means that if the user is alreadt signed into his Facebook account, we can detect that in our web application, and we can directly send the user along to the internal pages. In case the user is not logged in onto Facebook, we will give an overview of what our web application is about, and ask the user to login using Facebook Connect. Once the user is logged in, we will just display a list of his friends.

There are various ways of achieving this, but we will be using a mixture of XFBML, FQL and API calls to illustrate those concepts.

In our index.php, what we first need to do is to include the the official PHP client library for the REST API provided by Facebook. If you have not already download the PHP library, download it right here.

require_once 'facebook-platform/php/facebook.php';

The file facebook.php contains a class that we will be using to make all our Facebook API calls. As I have already mentioned, the API Key, and the Secret (which we obtained during the application registration above) are compulsory parameters for all API requests. So, for convenience, we can store this information on a config.php file, which we can include from all our application pages.

// config.php
// enter your application's API key and secret here:

$ApiKey = '12345667890';
$AppSecret = 'ABCDEFGHIJKLMNOPQRST';

Ok, with that out of the way, our next step is to initialise the Facebook class:

$facebook = new Facebook($ApiKey, $AppSecret);

If your $ApiKey and $AppSecret credentials match, we will subsequently be able to make calls to the Facebook API invoking the methods of the $facebook object. As we have discussed, we need to first check if the user is already logged into Facebook. We do that by checking the ‘user’ property of the $facebook object is set. If the user is logged in, $facebook->user will contain the logged in user’s Facebook ID.

if( !$facebook->user )
{
   // the user does NOT have a valid Facebook session
   // (i.e. not logged onto Facebook)
   // we will show some information about our app and ask the user
   // to login using FB connect:

   echo '<h2>Hey, this application will list all your friends on Facebook!
                But, you need to login using your Facebook account
                to continue!';
   echo '<fb:login-button onlogin="javascript:location.reload(true)">
           </fb:login-button>';
}
else {
   // show the user's list of friends (let's use FQL for this):

   $fqlQuery = "SELECT name FROM user WHERE uid IN (SELECT uid2 FROM
                       friend WHERE uid1 = $facebook->user)";
   $fbFriends = $facebook->api_client->fql_query($fqlQuery);

   if( $fbFriends == NULL )
   {
     echo "<p>Oh no, you don't have any friends on Facebook! </p>";
   }
   else {
     echo "<h3>Your friends are: </h3>";
     foreach ($fbFriends as $fbFriend)
     {
       echo $fbFriend['name'] . "<br />";
     }
   }
}

The above code block encompasses most of our simple application logic! It also goes to show how straightforward Facebook Connect really is, once you get the hang of it. We have used both FQL and XFBML in the code snippet. Let’s break it down and see what each code segment does.

echo '<fb:login-button onlogin="javascript:location.reload(true)">
               </fb:login-button>';

We are using XFBML above to render a Facebook connect login button for users who are not presently logged in. This button, when clicked, will open a pop-up window, which will allow the users to enter their Facebook credentials and log in.

Once they login, the current page will automatically refresh, and since the user has a valid Facebook session this time, $facebook->user will return the user’s Facebook ID. To enable XFBML, we need to include two Javascript snippets to be embedded onto the page:

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

FeatureLoader.js.php is a lightweight file that helps bootstrap the rest of the Connect library. It’s required for any XFBML functionality, and must be placed before any other Facebook Connect scripts or API calls. We can either place it in the HEAD tag, or right after the BODY tag.

The other Javascript snippet that’s needed is:

<script type="text/javascript">
 FB_RequireFeatures(["XFBML"], function(){
 FB.Facebook.init("YOUR_API_KEY", "xd_receiver.htm");
 });
 </script>

This code snippet can be placed anywhere after the FeatureLoader.js.php. The snippet enables the use of XFBML. The file xd_receiver.htm creates a Cross Domain Communication Channel between third-party Web pages and Facebook pages. We need to create a xd_receiver.htm page with the following contents, and place it in the same directory as the main index.php 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" >
<head>
    <title>Cross-Domain Receiver Page</title>
</head>
<body>
<script src="http://static.ak.connect.facebook.com
                   /js/api_lib/v0.4/XdCommReceiver.js?2"
              type="text/javascript">
</script>
</body>
</html>

For logged-in users, we use FQL to retrieve the user’s friends.

$fqlQuery = "SELECT name FROM user WHERE uid IN (SELECT uid2 FROM
                         friend WHERE uid1 = $user)";
$fbFriends = $facebook->api_client->fql_query($fqlQuery);

$fbFriends will return a NULL, if no result is found. If the query produces results, an array of resulting users is returned. We can traverse this associative array and retrieve the various properies which we have queried for. In our case we have only queried for ‘name’, so we can print the names as:

foreach ($fbFriends as $fbFriend)
{
    echo $fbFriend['name'] . "<br />";
}

Of course, we can retrieve lots of other details about the users (including a URL to a profile picture).

With that, we come to the end of our quick Facebook connect tutorial. Although our sample application is ridiculously simple in functionality, and we only scratched the basics of the Facebook Connect platform, Facebook Connect does allow developers to harness the full power of Facebook’s social features right from our application. You should check out the Facebook API documentation, and follow their development blog if you are serious about going for deeper levels of integration with Facebook.

You can download our demo files here.

Tagged with: facebook, facebook-connect, PHP