Facebook How-To: Creating Your First Application

What is a Facebook application? What can a Facebook application do? How do you create one, and what resources do you need to do it? How do Facebook applications communicate with users? And how can Facebook applications make money?

The answers to these questions are out there, but they are scattered among many different Wiki pages. In this tutorial, I'll lead you through the process of creating a complete Facebook application... and I'll continue to add features to that application on an ongoing basis.

Before We Start: Get a Facebook Account!

You are on Facebook, right?

If not, get over there right now and create an account. Then let Facebook help you to find friends who are already on board. The "friend factor" is what makes a social networking site like Facebook interesting... so a Facebook account with no friends can't do anything worthwhile or fun with most Facebook applications.

So get yourself on Facebook, and make sure you have at least five Facebook friends before you continue. Feel free to add me, Thomas Boutell, as a friend.

What Is A Facebook Application?

Great, now you're on Facebook and ready to go. But what exactly is a Facebook application, anyway?

Virtually all social networking sites allow you to add friends, and to interact with your friends in some way. On nearly every social networking site, you can:

  • Send your friends "email" within the site (as opposed to regular email)
  • Post bulletins (on MySpace) or write on your Wall (on Facebook)
  • Write blog entries (on MySpace) or notes (on Facebook)
  • "Poke" your friends to get their attention (on Facebook)
  • Share and tag photos
  • Plan events
Traditionally, social networking sites simply roll out features like these and say, "hey, that ought to be enough for anybody!"

But Facebook chose to think about things a little differently. Facebook looks at each of these features as an application, in exactly the same way that Microsoft Word and Firefox are applications of your computer's desktop operating system. And this analogy isn't something I invented on my own. Facebook is often referred to as a "social operating system."

But what does an operating system do for us? Does it process words or crunch budget numbers? No— it provides the services that word processing and spreadsheet applications need... and then it gets out of the way!

By allowing third-party programmers (that's you!) to create their own Facebook applications, Facebook has chosen to do the very same thing for social networks. Instead of saying "here is our feature set, take it or leave it," Facebook allows anyone to create a new application... and allows users to add and remove applications from their accounts, in much the same way that users can add and remove optional programs like games and music players from their computers.

Facebook Applications: Some Good Examples

Here are several good examples of Facebook applications that add new abilities to Facebook:
  • Superpoke takes the idea of Facebook's "poke" feature and runs with it. Superpoke offers hundreds of whimsical ways to "poke" your friends. Silly? Sure. But Superpoke enjoys an enormous audience, because when people interact with their friends, they very often want to be silly. And there's quite a bit of advertising revenue to be earned by such a popular application. While the application seems trivial, "under the hood" there are some very sophisticated things going on to allow users to "poke" large numbers of friends while living within certain limitations imposed by Facebook. I'll discuss how to deal with these issues later in this tutorial.
  • My Heritage allows Facebook users to choose to display "heritage flags" relating to their ethnicity and background. This application is a bit more detailed and a lot less frivolous.
  • Where I've Been provides interactive maps that allow users to share information about the places they have traveled to in their lives.
  • Finally, Supergroup is my own fantasy rock band simulator. Users invite their friends to join fantasy bands, and then interact with them in a variety of ways. This is the application we'll spend the most time looking at (and rewriting and improving!) in this tutorial.

What A Facebook Application Isn't

I've talked about similarities between desktop applications like Microsoft Word and Facebook applications like Where I've Been. I should take a moment to point out a big, big difference: a Facebook application does not "live" on your own computer, and you do not install anything on your own computer when you choose to add a Facebook application to your account. This is a very good thing, because no user in their right mind would risk installing an untrusted Windows application for no better reason than to throw sheep at their friends. Facebook applications, because they run entirely on the Web, represent a vastly lower risk for the user and are much easier to install. That's a big part of their appeal.

Where Does A Facebook Application Run, Exactly?

If Facebook applications don't "live" on the user's computer, where do they live? Do they run on a server provided by Facebook?

Nope! If Facebook applications ran on Facebook's web servers, then Facebook would have to bear the cost of running them. And that wouldn't be a good deal for Facebook. Also, Facebook would have to deal with the security implications of many untrusted programs running on their computers.

Instead, your Facebook application must run on your own web site... And that brings us to the requirements for following along with this tutorial.

Requirements: What You'll Need

To participate in this tutorial, you'll need the following resources:
  • 1. A Facebook account. We already took care of this.
  • 2. A web site of your own. This should be a "real" web site, not a MySpace or Facebook page.
  • 3. Support for PHP on that web site. Worthwhile Facebook applications need to store information and make decisions in a safe and reliable way. You can't do that with just HTML. HTML is a markup language for presenting text, not a programming language. But don't worry— I'll introduce the basic concepts of PHP in this tutorial! Just make sure your web hosting account includes PHP.

    PHP is not the only web development language that can be used to write Facebook applications. Facebook also officially supports Java, Microsoft has made tools available for their .NET languages, and third parties have created tools for Ruby and other languages that take advantage of Facebook's open API (Application Programming Interface). But PHP is free, friendly, popular, and the choice of many corporate sites... including Facebook itself. So it is also my choice for this tutorial.

  • 4. A MySQL database on your web site. Your Facebook application will need a place to reliably store information. MySQL is free and included in all serious web hosting packages, such as those offered by pair.com for example.
  • 5. The Facebook developer application. This is a Facebook application, not an application for your computer. All you have to do is visit the Facebook Developer application page while logged into Facebook, and agree to add the application. You will use this application to manage your own Facebook applications. Without it, you can't sign up to create applications of your own. So be sure to add this application to your Facebook account before you continue.
  • 6. The Facebook "client library" for PHP. You can download the Facebook platform library directly here, or locate it via the official Facebook Developers resources page.
The Facebook client library is packaged in the .tar.gz format. If you're used to working in a Windows environment, it might not be clear to you what you should do with this file.

You may find it easiest to unpack the client library with WinZip and then drag the facebook-platform folder to your web site with your favorite FTP program. Another option, if you have access to a Linux or other Unix shell account on your web host, is to upload the file "as-is" and then unpack it in a directory on your site, like this:

tar -zxf facebook-platform.tar.gz

MacOS X users can easily extract .tar.gz files directly on the desktop.

Can I host my Facebook application on my own computer?

The short answer: no. Facebook applications need to be available 24-7, and they need to run on web sites that are a reliable part of the Internet. Good web hosting can cost ten bucks a month or less, so there is no good reason to host your Facebook application at home.

But hey, it's your application. If you desperately want to host at home, you should read my article on how to host your web site at home. Just remember: from a practical and professional perspective, it's a terrible idea. Don't say I didn't warn you.

What You Need To Know

I've laid out the tools you need at your disposal. But what skills should you already have before following this tutorial?

You really should know HTML, and have some experience making simple web pages in "real" HTML, not just with "what you see is what you get" tools that write all of the HTML code for you. If you need a basic HTML tutorial, check out the w3schools tutorial.

If you know PHP, this will be easier, but it is not absolutely necessary. I'll introduce enough PHP concepts to help you get by. Still, I do recommend checking out the tutorial on the official PHP site.

You don't have to know JavaScript or CSS already, but both will help you to speed through the more advanced material in this tutorial.

But relax— this isn't hard! With just a little effort you'll be writing Facebook applications in no time.

How Facebook Applications Work

I've said that a Facebook application must live on your own web site. But if that's the case, how does the user see your application as a part of Facebook's site? And how do you access Facebook's resources in order to send Facebook notifications, update Facebook profiles and so on?

Take a look at the following diagram:

This diagram depicts the relationship between:

  • 1. The user's web browser, running on their personal computer.
  • 2. Facebook's web site, more specifically apps.facebook.com, which acts as a "front door" to Facebook applications.
  • 3. Your web server, where your web site is hosted.
This diagram shows two different types of Facebook applications: "iframe" applications and "FBML" applications. But what is the difference between the two types?

Understanding the difference between iframe and canvas applications

An "iframe application" is a Facebook application that relies upon HTML's "iframe" element to display itself. This HTML element allows one page to be easily embedded in another. The web browser fetches both the original page and the embedded page directly, and treats them more or less as completely separate things. This is reflected by the arrows in the diagram, which show the web browser communicating directly with both Facebook and our own site.

In an iframe application, Facebook's web site outputs an iframe element that refers to your site. After that, the user's browser communicates directly with your web site.

Your web site, in turn, will often communicate directly with Facebook's web site in order to carry out various actions, notably sending Facebook invitations and notifications. This is reflected by the arrows connecting your site with Facebook.

The iframe approach is very well-suited to quickly embedding one site in another... which is exactly what we are trying to do when we create a Facebook application. But it also has drawbacks, as we'll see.

A "canvas application" approaches the problem in a completely different way. Here the web browser never actually communicates directly with your own web site (well, almost never). Instead, all requests for "canvas pages" that are part of the application are first fielded by Facebook, which communicates directly with your web site and returns the result to the browser. Your web site's response is presented directly as part of a Facebook page.

There's one big catch with canvas applications: Facebook can't simply trust whatever HTML, JavaScript and CSS you choose to put into a page. For example, with unrestricted JavaScript and CSS, you could easily fake Facebook email messages or even prompt the user for their password again in a very believable way. And that's a big security risk.

Facebook solves this problem by replacing the usual unrestricted HTML, JavaScript and CSS with its own versions. Instead of regular HTML, canvas pages are written in FBML (FaceBook Markup Language). The bad news is that FBML is a subset of regular HTML, with some elements not included. But the good news is that FBML also adds many new tags which make it easy to deliver features that take a great deal of time to duplicate "by hand." And that makes canvas application programming much faster.

Almost never: times when the browser does connect to your server

There are two times when a browser does connect directly to your server, even though the application is a canvas application:

1. To fetch images and other embedded content. Your img elements will still reference your web site directly. The same rule applies to Flash applets, videos and MP3 audio files.

2. When you use the fb:iframe element. Facebook provides the fb:iframe element to help you get the best of both worlds by embedding an iframe when FBML is not the easiest way to get something accomplished.

iframes versus FBML: which is better?

After reading the above, you're probably wondering why anyone would use FBML. If FBML is a limited subset of HTML— and yes, Facebook also restricts what we can do with JavaScript and CSS to a certain degree— then why not just use an iframe, which allows us to use HTML, JavaScript and CSS to our hearts' content?

Actually, FBML has one giant advantage over iframes: special Facebook-specific tags that make it much easier to present your application as part of the Facebook experience. Want to display a user's name as a link to their profile, just like Facebook does? FBML has you covered. Want to limit the visibility of things based on who is looking at them? FBML helps you do that too. Want to display a video or music player that is similar to those normally used on Facebook? FBML has that built right in... and so on. And if you really want to do something that's too hard to do with Facebook's limited versions of HTML, CSS and JavaScript, there's an FBML tag to include an iframe in your page, giving you the best of both worlds.

On the other hand, iframe applications do have a few advantages. The most important is that testing your application is less time-consuming at first, because You don't necessarily need Facebook in the picture while you test it. But as your application becomes more complex, it will do more and more things that involve services provided by Facebook. So testing it by itself will make less and less sense.

A secondary advantage is that an iframe application can be easier to port to another social network, such as MySpace (but not Bebo, which actually supports a subset of FBML).

This tutorial will focus primarily on FBML applications, because they take on a truly native appearance in Facebook and offer all of the possible features. Just keep in mind that the iframe option is also available.

Registering Our Facebook Application

Enough theory, already! It's time to code our first Facebook application. But before we can begin, we'll need to register our application with Facebook. We'll do that using the Facebook developer application.

Click here to access the developer application, or select it from Facebook. You'll see a welcome page that features a developers' discussion board, important news and updates from the Facebook team, and a "My Applications" area... which, so far, will be empty. It's time to change that.

Click on the "Set Up New Application" button to get the process started. The "New Application" page will appear, beginning with the "Required Fields" section.

What Should I Call My Application?

Hey, that's up to you. But remember that your application's name should be short and unique so that people can recognize it.

(In other words, don't name it Superpoke... or Supergroup, for that matter.)

Also, the name of your application must not contain the word "face." this is an official Facebook policy, and your application will be deleted if you do not obey their policies.

(So far, the word "book" is allowed.)

Enter a name for your application. Then check the box to indicate that you have read the terms and conditions... which, by the way, you should actually read. Violating these rules is a serious matter and, again, your application will be deleted if you ignore them.

"Optional Fields:" Not So Optional

You can be forgiven for thinking that you are done at this point, but you're really not. We still haven't answered some of the most important prompts in the form, and our application can't work without them. So click "Optional Fields" to display the rest of the registration form.

The following fields are required or at least important to even the simplest applications, so don't try to skip them. There are other fields on the registration pages which I do not mention here because they are not essential. We'll revisit some of them later.

These fields are essential and must be set correctly for good results:

The Callback URL

As I mentioned earlier, in a canvas application, the browser talks to Facebook and Facebook's server talks to your web site. This is the URL on your site where your Facebook application's code will be located. Users will not access this URL directly— this will be a PHP page that outputs FBML rather than HTML. We haven't written this page yet, of course, but it's time to choose a location for it.

Good Choices for Callback URLs

If your site is called www.example.com, where should your Facebook applications live on the site?

The good news is that users won't see your callback URL directly. So there is no need to pick a particularly handsome URL. But you should organize your Facebook applications beneath a single parent directory, simply to make it easier for them to share resources.

On my own site, my Facebook applications live in sub-folders of a folder called facebook, which is inside my document root folder (the main folder of my site). So the callback URL for my Supergroup application looks like this:


So the right callback URL for your application will probably look like this:


Notice that I didn't end this URL with a filename ending in .php. Instead, I just refer to the name of the folder. On my web server, a page called index.php is automatically delivered when a folder is accessed without a filename, and the same is probably true for yours. This is convenient, not just because it saves typing but also because you can more easily switch from PHP to another language in the future if you so choose without changing your URLs.

The Canvas Page URL

The canvas page URL is the location on Facebook's apps.facebook.com site where your application will live— or rather, appear to live from the user's perspective. Most of the URL is already filled in. You just choose the last part of the name, which is made up of letters and digits only.

This URL is seen by the actual user, so it is worthwhile to pick a good name. I chose supergroupapp because supergroup was already taken, but you should pick the most recognizable name that is still available. And get this right the first time— you will be breaking many a link if you change it later.

FBML versus iframe

The next decision to be made: "use FBML" versus "use iframe." In this tutorial, I'll be focusing on "canvas applications," those which use FBML. So I recommend that you make that choice. If you choose the iframe option, you'll have to write your code with that in mind and you will not have easy access to handy FBML elements like fb:name that do much of the work of creating a familiar Facebook interface for you.

Can your application be added on Facebook?

I sure hope so!

By default, your application can't be added to a Facebook account. That's not very useful— not even for testing. So click the "Yes" radio button.

When you click "Yes," an additional "Installation Options" section will be added to the page. This is important, because there are additional essential options in that section.


When you first create an application, it is not open to the public. Only developers of the application are allowed to add it.

You, of course, are automatically a developer. But since Facebook is a social operating system, a Facebook application with only one user isn't very interesting. So you should do one of two things:

A. Add the names of some friends to the "developers" list, or

B. Decide to allow everyone to add your application from the beginning. This is not as bad an idea as it sounds, because hardly anyone will know your application exists until you go out of your way to tell them. Still, people might spot your activities with your application in their news feeds, and that might lead them to test things you haven't finished debugging yet. If that concerns you, go with option A.

Also, note that it is possible that an unscrupulous Facebook "friend" could notice newsfeed stories from your application, visit the application and start looking for security bugs you haven't had time to fix yet... and perhaps take over your web site. Ouch!

It's not very likely if you have good friends. But if you are friends with hundreds of quasi-strangers, you should take this risk seriously and choose option A so that you don't have to be fanatically careful at every stage of development... just with your final product!

Installation Options

By now you should see an "Installation Options" section in the page. If not, go back and make sure you clicked the "Yes" option next to "can your application be added on Facebook?"

Who can add my application?

"Gee, isn't this a dumb question?" Well, not quite. Yes, most Facebook applications, including the application we'll create in this tutorial, are oriented toward users. But a smaller number are intended to be embedded in Facebook pages instead, such as fan pages for bands. And some applications are in both categories.

To make it possible for users (including yourself) to add your application to their Facebook accounts, you must check the "Users" box here, next to "Who can add your application to their Facebook account?"

Post-Add URL

This is the page where the user will "land" after they add your application. You would be forgiven for thinking that this would automatically be your canvas page if it is not filled out. Alas, it isn't. So you'll need to reenter your canvas page URL here:


If you wanted, you could also add additional parameters to indicate that this is a first-time access after adding the application. The following URL uses parameters packed in the correct way to be read from the $_REQUEST PHP variable:


But since Facebook automatically passes add=1 to your application in this situation, this isn't really necessary.

Application Description

This is simply a description of what your application does, intended to be read by users. It's not absolutely required that you fill this out now, but you'll want to do it soon.

Post-Remove URL

This is a URL where your web site will be notified when an application is removed. Your application will get the bad news directly from Facebook's server, not the browser.

Since the user has just removed your application, this can't be your canvas page! It can, however, be your callback URL. And again, Facebook automatically passes a parameter to your application to help you recognize what has happened. So I suggest entering your callback URL here.

Developer Mode

Right now, your application is open to the world: anyone can add it to their account.

Is that bad? Well, not too bad, because no one knows about your application yet. But as soon as news feed stories start being generated by your test activities, people will. If you're not ready for that, check this box.

You can also prevent people from finding out about the application by checking the "Private Installation" box. But this has the drawback that you won't be able to gauge whether your application's newsfeed stories are working properly.

Submitting the Application

Great, we're ready to go! Our settings are fully tricked out. Now all we have to do is write the actual application. Darn, you knew there was a catch somewhere.

Click on the "Submit" button at the bottom of the form to add your application to Facebook.

After you add your application, you will see another "Submit Application" link in your list of applications. This link is completely different: it is used to add your application to Facebook's public application directory. You're not ready to do that yet, so don't. Although, if you're a risk-taker, you might choose to do it a few days early knowing that Facebook takes a while to check out new applications that are added to the directory.

When you are ready to make your second application, you'll probably wonder where the "Add Another Application" button is. The answer is that you must click on "Apply for another key."

Confusing? You bet it is. But that's the price we pay for getting in on the ground floor.