Getting to Grips with the Facebook Platform

The Purpose of the Facebook Platform

As you develop your Facebook applications, you'll find that the Facebook Platform is essential—in fact you won't really be able to do anything without it. So what does it do? Well, before answering that, let's look at a typical web-based application.

The Standard Web Application Model

If you've ever designed and built a web application before, then you'd have done it in a fairly standard way. Your application and any associated data would have been placed on a web server, and then your application users will access it from their web browsers via the Internet:

Getting to Grips with the Facebook Platform

The Facebook model is slightly different.

The Facebook Web Application Model

As far as your application users are concerned, they will just access and your application, by using a web browser and the Internet. But, that's not where the application lives—it's actually on your own server:

Getting to Grips with the Facebook Platform

Once you've looked at the Facebook web application model and realized that your application actually resides on your own server, it becomes obvious what the purpose of the Facebook Platform is—to provide an interface between your application and itself.

There is an important matter to be considered here. If the application actually resides on your server, and your application becomes very successful (according to Facebook there are currently 25 million active users), then will your server be able to able to cope with that number of hits?

Don't be too alarmed. This doesn't mean that your server will be accessed every time someone looks at his or her profile. Facebook employs a cache to stop that happening:

Getting to Grips with the Facebook Platform

Of course, at this stage, you're probably more concerned with just getting the application working—so let's continue looking at the Platform, but just bear that point in mind.


The Facebook Platform Elements

There are three elements to the Facebook Platform:

  • The Facebook API (Application Programming Interface)
  • FBML—Facebook Markup Language
  • FQL—Facebook Query Language

We'll now spend some time with each of these elements, and you'll see how you can use them individually, and in conjunction to make powerful yet simple applications. The great thing is that if you haven't got your web server set up yet, don't worry, because Facebook supplies you with all of the tools that you would need in order to do a test run with each of the elements.

The Facebook API

If you've already done some programming, then you'll probably know what an API (or Application Programming Interface) is. It's a set of software libraries that enable you to work with an application (in this case, Facebook) without knowing anything about its internal workings. All you have to do is obtain the libraries, and start making use of them in your own application.

Now, before you start downloading files, you can actually learn more about their functionality by making use of the Facebook API Test Console.

The Facebook API Test Console

If you want to make use of the Facebook Test Console, you'll first need to access the Facebook developers' section—you'll find a link to this at the bottom of every Facebook page:

Getting to Grips with the Facebook Platform

Alternatively, you can use the URL to go there directly in your browser. When you get to this page, you'll find a link to the Tools page:

Or, again, you can go directly to, where you'll find the API Test Console:

Getting to Grips with the Facebook Platform

You'll find that the API Test Console has a number of fields:

  • User ID—A read-only field which (when you're logged on to Facebook) unsurprisingly displays your user ID number.
  • Response Format—With this, you can select the type of response that you want, and this can be:
    • XML
    • JSON Facebook
    • PHP Client
  • Callback—If you are using XML or JSON, then you can encapsulate the response in a function.
  • Method—The actual Facebook method that you want to test.

Once you've logged in, you'll see that your User ID is displayed, and that all the drop-downs are enabled:

Getting to Grips with the Facebook Platform

You will also notice that a new link, documentation, appears on the screen, which is very useful. All you have to do is to select a method from the drop-down list, and then click on documentation. Once you've done that you'll see:

  • A description of the method
  • The parameters used by the method
  • An example return XML
  • A description of the expected response.
  • The FQL equivalent (we will discuss this later in the chapter.)
  • Error codes

For now, let's just change the Response Format to Facebook PHP Client, and then click on Call Method to see what happens:

Getting to Grips with the Facebook Platform

In this case, you can see that the method returns an array of user ids—each one being the ID of one of the friends of the currently logged in user (that is your list of friends because you're the person logged in). You could, of course, go on to use this array in PHP as part of your application, but don't worry about that at the moment. For the time being, we'll just concentrate on working with our prototyping in the test console.

However, before we move on, it's worth noting that you can obtain an array of friends only for the currently logged in user. You can't obtain the list of friends for any other user. So, for example, you would not be able to use friends.get on id 286601116 or 705175505. In fact, you wouldn't be able to use friends.get for 614902533 (as shown in the example) because that's my ID and not yours.

On the other hand, having obtained a list of valid IDs we can now do something more interesting with them. For example, we can use the users.getinfo method to obtain the first name and birthday for particular users:

Getting to Grips with the Facebook Platform

As you can see, a multidimensional array is returned to your PHP code (if you were actually using this in an application).Therefore, for example, if you were to load the array into a variable $birthdays, then $birthdays[0][birthday] would contain January 27, 1960.

Of course, in the above example, the most important piece of information is the first birthday in the array—record that in your diary for future reference. And, if you're thinking that I'm old enough to be your father, well, in some cases this is actually true:

Getting to Grips with the Facebook Platform

Now that you've come to grips with the API Test console, we can turn our attention to FBML and the FBML Test Console.


FBML, as mentioned previously, is the Facebook Markup Language. If you've used HTML in web pages, then you'll have no problem with FBML. Even if you've not used HTML ever, you'll still have no problems with FBML. It can be used to format your information just like HTML, but it also does a lot more than just formatting as we'll soon see, by looking at the FBML Test Console.

The FBML Test Console

We've already seen that we can learn how to use the Facebook API methods in the API Test Console, and we can do the same with FBML in the FBML Test Console. Just go to the Tools page as you did for the API Test Console, but this time click on the FBML Test Console tab:

Getting to Grips with the Facebook Platform

In this console, we're mainly interested in two areas:

  • The code entry box—this is the large box on the left-hand-side of the console
  • The preview area on the top-right of the console

Next, we need some code to test:

<table cellpadding=0 cellspacing=0><tr><td>
<table cellpadding=0 cellspacing=0>
<fb:profile-pic uid=614902533></fb:profile-pic>
<fb:name useyou=false uid=614902533 firstnameonly=true></fb:name>
<table cellpadding=0 cellspacing=0><tr><td>
<fb:profile-pic uid=286603790></fb:profile-pic>
<fb:name useyou=false uid=286603790 firstnameonly=true></fb:name>
<table cellpadding=0 cellspacing=0><tr><td>
<fb:profile-pic uid=505543152></fb:profile-pic>
<fb:name useyou=false uid=505543152 firstnameonly=true></fb:name>

You'll notice from the code that we can mix HTML (we've used <table> </table>, <tr> </tr> and <td> </td> to tabulate the information) with FBML (<fb:name> </fb:name> and <fb:profile-pic> </fb:profile-pic> to extract and display the Facebook data). If you put this into the code entry box and click Preview, then you'll see how your application would look:

Getting to Grips with the Facebook Platform

Having seen how we can achieve an output using a mixture of HTML and FBML, it would be interesting to see how you can get much the same results even more easily, by using only FBML:

<fb:user-table cols="3">
<fb:user-item uid="614902533"/>
<fb:user-item uid="286603790"/>
<fb:user-item uid="505543152"/>
<fb:user-item uid="515482742"/>
<fb:user-item uid="517311956"/>
<fb:user-item uid="521240370"/>

You can see from the code that we're able to use the FBML <fb:user-table> tag to create a table, and we've used the <fb:user-item> tag to obtain the information that we want from Facebook. The resulting application would look like this:

Getting to Grips with the Facebook Platform

We've looked at the Facebook API and FBML, and learned how useful they can be. Now, we'll move on to the potentially most powerful element of the Facebook platform—FQL.


It may interest you to know that the information that you can obtain from Facebook is actually stored in a database, and that's where FQL comes in. So, instead of using the API methods, we can query the tables in the database to obtain the information that we require. For example, if you want the first name, surname, and birthday of each of your friends, then you can use the following query in the API Test Console:

SELECT first_name, last_name,birthday
FROM user
WHERE uid IN ( SELECT uid1
FROM friend
WHERE uid2=614902533)

And don't forget to replace my id (614902533) with your own because you can only use the details of friends of the logged in user, that is you.

Now, we still need to use the API, but for this, we only need one method—fql.query:

Getting to Grips with the Facebook Platform

You'll realize of course, that this means that you're not limited to the information supplied by the API methods and the FBML tags. You're actually able to extract the exact data that you want.

Now that you're conversant with the Facebook Platform, you will want to create your first Facebook application. However, before you do that, you'll need to obtain the Facebook Client Libraries.

Obtaining the Facebook Client Libraries

If you're going to build a Facebook application, then you're going to need access to the Facebook API, and to do that, you'll have to download the client libraries onto your server. In order to do this, you'll need to go to the developers' page—remember that you can use the URL, or use the link given at the bottom of each Facebook page:

Getting to Grips with the Facebook Platform

Once you're there, find the link to the Resources page:

Getting to Grips with the Facebook Platform

Or, go directly to

When you're in the Resources page, you can click on the library that you want to use. In this instance, we're going to be using the PHP (4 and 5) Client Library:

Getting to Grips with the Facebook Platform

Of course, if you want to know more about a library, then just click on Description of contents:

Getting to Grips with the Facebook Platform

So far, everything we've looked at will be the same whether you are using Windows or Linux on your server, and that's true for most of what we'll be doing. However, this is one instance when what you do will depend on your server's operating system.

The file that you're going to download is compressed, but not in a form normally used in Windows (you'll notice that they have a tar.gz suffix). So, you'll need to obtain software that can uncompress the files for you. A quick Google search will find a lot of them, but a suitable one is available from, although you'll find that it does display some annoying pop-ups, so you may want to delete it once you're finished. However, once you've installed WinAce, you'll be able to uncompress the libraries:

Getting to Grips with the Facebook Platform

If, on the other hand, you're using Linux, then you'll be able to uncompress the files quite readily. If you prefer to use a GUI type interface, then there is a software, which you can use, called Ark:

Getting to Grips with the Facebook Platform

However, if you prefer to use the command line (as I do), then you can both download and uncompress the files very easily:

cd /srv/www
tar -xvzf facebook-platform.tar.gz

Of course, you'll need to change /srv/www to a suitable directory on your own server, one that you can write to. And in case you're not used to the commands, cd moves you to the directory, wget downloads the library, and tar uncompresses it. If you type the commands on the command line, then you'll see something like this:

Getting to Grips with the Facebook Platform

At the moment, it doesn't actually matter where you place the libraries, but regardless of whether you're using Windows or Linux, you should end up with a set of PHP files somewhere on your server:

Getting to Grips with the Facebook Platform

And now, you are ready to move on to telling Facebook about the application that you're going to be creating.

So far, we've spent a bit of time looking at the Facebook Platform—you have learned where it fits in with any application that you build, and you have learned how to experiment with the Platform's functionality, without even having an application.


Adding the Developer Application

You may be wondering why you need to add another application in order to create your own. Quite simply—you don't use developer to create your application—you use the developer application to add yours into Facebook.

So, start by going to the developer's page (remember that you'll find a link at the bottom of every Facebook page, or you can go directly to Next, you'll have to click on Get Started, and then Add Facebook Developer


Getting to Grips with the Facebook Platform

You can change the settings if you want, but you might as well keep the default settings, and press Add Developer.

Once you've added the Developer application, you'll be able to access it from your left-hand side navigation:

Getting to Grips with the Facebook Platform

At this point, you don't actually need an application. What we're going to do is set up our new application in Facebook, and then create it.

Setting Up Your Application

If you click on Developer in your left-hand side navigation pane, you'll see a button to Set Up New Application:

Getting to Grips with the Facebook Platform

You'll now find that you need to type in details about your application (obviously!). Some fields are required, while others are optional. We'll deal with the required fields first.

Required Fields

Don't worry, you won't have masses of fields to fill in before you can get started with your application—in fact there is only one required field, plus a tick box:

Getting to Grips with the Facebook Platform

So, all you have to do, at this stage, is choose a suitable name for your application. As this will be displayed on Facebook, decide on a name that describes your application best (avoiding anything rude or insulting). In this example, I'm developing an application for an imaginary private detective, Pygoscelis P. Ellsworthy, so I'm going to name the application Pygoscelis P. Ellsworthy's Suspect Tracker:

Getting to Grips with the Facebook Platform

You'll need to tick the box to say that you've read the Facebook Platform terms and conditions (and we always read those, don't we?). However, don't click on Submit yet, as the remainder of the fields are defined as optional, although some are still essential (as we're about to see).

Optional Fields

By default, the optional fields are hidden, so to see them, click on Optional Fields (no surprise there then).

Base Options

As soon as you click on Optional Fields, the Base options will become visible—these are the options required by any application that you build, although others will be made available to you depending on what you enter into the Base options.

Getting to Grips with the Facebook Platform

You'll see that Support E-Mail has already been filled in for you, using your Facebook email address. Obviously, you'll need to change that, if that's not the address that you want to use. Apart from Support E-Mail, there are only two fields that we're interested in at the moment:

  • Callback URL—The URL of your application (that is on your server).
  • Canvas Page URL—The URL for your application within Facebook (obviously this needs to be unique).

So, in the case of Pygoscelis P. Ellsworthy's Suspect Tracker, the optional fields would look like this:

Getting to Grips with the Facebook Platform

And a big tip here—make sure that you end the Callback URL with a / (in your code, NOT in the Installation options box), and you'll save yourself many hours of heartache wondering why your application isn't working correctly.

You can ignore all the other fields in this section at the moment, apart from one question that you must answer, Can your application be added on Facebook? Obviously, the answer will be Yes. But don't worry about your application being accessed by thousands of people before you're ready—in a moment we'll see how to stop that.

When you set Can your application be added on Facebook? to Yes, you'll find that the Installation Options are displayed.

Installation Options

Since we want our application to be added on to Facebook, we'll need to fill in some Installation Options. As with the Base options, we can leave most of them blank, just filling in a few essential ones:

Getting to Grips with the Facebook Platform

As you can see, the Post-Add URL needs to be added (this should be the same as your Canvas Page URL), and you can enter some arbitrary text into the Default FBML box.

Now, I did mention a little while ago that you can prevent your application being used before you're ready, and this is the section where you do that. Just tick the Developer Mode box.

Integration Points

The only field that you need to fill in at this point is the Side Nav URL (and this should be set to the same as your application's Canvas Page URL, in the base options):

Getting to Grips with the Facebook Platform

All you have to do now is click Submit, and Facebook will create an API key for you (you'll need that and the secret key when you write the code for your application):

Getting to Grips with the Facebook Platform

And with that done, we can move on to actually building the application itself.



In this article, we've looked at the Facebook Platform and learned that it consists of three elements that must be used by your application to interface with Facebook:

  • The Facebook API—A library of PHP methods that will enable your application to extract data from Facebook.
  • FBML—The Facebook Markup Language—used to obtain and format Facebook data.
  • FQL—The Facebook Query Language—used to extract information directly from the Facebook database.

Each of the platform elements can be used in the development of your application, but you don't need to develop an application in order to test them out. For that you can make use of:

  • The API Test Console
  • The FBML Test Console

Before you can start developing your own application, you will need to download the Facebook Client Library, and if you're using Windows, then you'll need to obtain suitable software for uncompressing it.

You have to add the Facebook Developer application. Once you've done that, you can start adding your own applications.

When setting up your application, you must give it a sensible name, and a suitable location (the Callback URL). The Callback URL must be to your own server, and don't forget to add a / at the end of the URL.

When you submit your application, you'll be given an API key, and a secret key. You'll need to use these in your application. Now, you are ready to create your application.

You've been reading an excerpt of:

Learning Facebook Application Development

Explore Title