Exploring the Facebook Platform, Part 2

by Fred Stutzman
October 24, 2007

Introduction

The Facebook Platform is changing the way we think about developing consumer software applications. By leveraging the power of the social graph, application designers are able to move their applications to the network, taking advantage of viral information flow. In part one of this article series exploring the Facebook Platform, we looked at the motivation behind the platform, some examples of the platform in action, and some strategies for making the platform work for you. Here, we're going to step through the actual process of building a simple Facebook Platform application. At the end of this article you'll have all the building blocks necessary to develop your own Facebook application--pretty much a Web 2.0 requirement these days. Let's get started!

First Things First

To get started developing a Facebook Platform tool, you'll first need a development environment--a place to build and test software. To this extent, you'll need a computer or shell account that has your programming language of choice installed. You'll also need access to a web server, which you'll use to host your content. You can get access to a web server a number of ways: you can turn on the web server on your home computer, or use a web hosting account. If you're familiar with web development, you should be able to get up and running pretty quickly--if not, grab a web developer friend and ask her to help you out!

Developer Accounts and Keys

Once you've got a basic development environment set up, you're going to need to get your hands on the tools required to develop Facebook applications.

Figure 1. Facebook developer application page

First, you'll need to add the Facebook developer application to your Facebook account (and if you aren't a Facebook member, well, you'll need to join the service). (Note: to view the Facebook Platform application pages linked to in this article, you must have a Facebook account and be logged into Facebook.) To add the developer account to your profile, simply go to the Facebook developer application and click through the simple signup steps. Once you've got the developer application added to your profile, you'll next register your application and apply for developer keys.

Figure 2. Facebook developer page: Set Up New Application

To accomplish these next steps, simply click on the Set Up New Application button located in the Facebook developer application. You'll be asked to fill in a few fields--I'll explain some of the less-than-obvious ones.

• Application Name: Yes, obvious, but choose wisely as this name will represent your application to all users.
• Callback URL: This URL should correspond to the location of where you are hosting your Facebook application. If you've uploaded your application to http://testserver.com/Facebook, this should be your Callback URL.
• Canvas Page URL: This is your application's "front page" in Facebook.
• Application Type: You'll want "Website" for this example.
• "Can your application be added on Facebook?": You might want to hold off on this until you are ready to turn your application on to the world, but there's no harm in saying yes to this. It will drop down a box asking you some more questions, but let's skip over that for now.

Figure 3. Facebook New Application page (click the image for a larger version)

Once you've stepped through these questions, Facebook will grant you a developer key. The developer key is a hash that you'll use for identifying your application to Facebook as you make API requests. Hint: You may want to actually apply for two keys, and use them for separate production/development environments. For the sake of this article, we're just going to use one key, but you'll certainly want to explore using a two-key approach if you're going to eventually move your application to a production environment.

Explaining a Few More Things

Now that you've got your hands on a developer key, let's step back a minute and explore some of the things you need to know about the mechanics of the Facebook Platform. As I stated before, you're going to need access to a web server to host your application. The Facebook Platform is set up in an interesting fashion. When someone uses a third-party Facebook application, a two-step process takes place. First, the user browses the application in Facebook--they click on links, browse the application, what have you. When the user makes these requests, they occur in Facebook, and then Facebook retransmits them to you, the third party. In a sense, Facebook serves as an intermediary for your application; if you look at your server logs for your application, you'll notice that all requests to the application will come from the Facebook IP range.

Facebook has set this architecture up to control the experience provided by third parties. Facebook has implemented its own markup language (FMBL) and has even implemented its own variant of JavaScript. When a user interacts with a third-party application, the application talks to Facebook in these special languages.

Outside of this high-level theory of operations, what else do you need to know about Facebook apps? Well, you should know a little terminology.

• FBML: Facebook Markup Language. This is a proprietary language that developers use to build interaction points with Facebook. While most of your application's business logic will be in a canonical language, the view-level output will be structured in FBML. FBML's entities are HTML-like.
• Canvas page: The canvas page is the application's home page. This is the starting place for users to experience your application--and a good amount of ongoing interaction takes place in the canvas page.

Let's Get Started

Now you've got your hands on a developer key and familiarized yourself with the basic logic of the interaction, so you're almost ready to go! Before we start coding, however, let's talk about how people will experience your Facebook application.

Facebook applications have many purposes, but for the purpose of this example, lets say we want to create an application that displays a famous quote on an individual's profile. How do we accomplish this? The first thing you want people to do is add the application (i.e., stepping through Facebook's "Add Application"). Once they've added the application, you're going to want the quote to begin appearing on people's profiles. The function call that governs this is setFBML. setFBML essentially lets you place FBML (content) on a user's profile, which is going to be key to getting that quote on the user's profile.

To sum up, you want the user to add the app, and you want the app to fire and update the person's profile with your quote (via setFBML). Sounds pretty easy (and it is pretty easy), but we're going to want to pay attention to a few things along the way.

Coding

Now that we're ready to get our hands on the code, let's download a library from the Facebook developer site. Facebook has libraries in all sorts of languages, but for this example I'll be using FBML 1.0 with Facebook's PHP 5 libraries.

Once you've downloaded the library, unpack them into a directory. We're going to need to include these libraries in our application, so you might want to move them into a sub-directory of your overall application. Once we've got our libraries set up, we're actually going to build a canvas page. For the purpose of this example, we're going to place all of the logic on this page. Let's call the file index.php, and we'll begin by putting in some configuration options. Basically, we're going to want to include the client libraries, define the API and secret keys, and then start your Facebook session.

<?php
/* Begin application configuration and variable definition
*/

// the facebook client library
include_once '../client/facebook.php';

// Get these from http://developers.facebook.com
$api_key = 'Use your API key';
$secret  = 'Use your secret key';

// FB Specific Calls
$facebook = new Facebook($api_key, $secret);
$facebook->require_frame();
$user = $facebook->require_login();

?>

Now that we've done a very basic configuration of our application, we're going to want to do two things. First, we're going to want to include some display elements to show up on our canvas page, and we're going to want some logic to set the quotes on the individual's profile.

Still editing index.php, let's include some display elements:

<h1>Welcome to the Great Quotes Application</h1>
<h2>This application will display a great quote on your Facebook profile!</h2>

This very simple snippet will display in the canvas page. You'll notice that FBML natively supports h1s and h2s--we're writing in FBML to be viewed in Facebook.

Finally, we're going to want to include the logic that sets the quote in the profile. To do so, let's add some final edits to index.php.

<?php 
$fbml = <<<EndHereDoc
<fb:wide>
<h1>A great quote!</h1>
<h2>It is a miracle that curiosity survives formal education. – Albert Einstein</h2>
</fb:wide>
<fb:narrow>
<h1>A great quote!</h1>
<h2>It is a miracle that curiosity survives formal education. – Albert Einstein</h2>
</fb:narrow>
EndHereDoc;

$facebook->api_client->profile_setFBML($fbml, $user);

?>

As you can see, we've dropped back into PHP mode, defining a variable arbitrarily named $fbml. In this variable, you can see we've included our quote (wrapped in basic markup) inside of two odd blocks. They are <fb:wide> and <fb:narrow>. These two code blocks correspond to the snippet's position on someone's profile. This lets the designer define two separate looks: for the wide view (when viewing the app on the right side of an individual's Facebook profile), and the narrow view (when viewing the app in the left-hand column of a Facebook profile). After this variable is defined, we set it with the setFBML call $facebook->api_client->profile_setFBML($fbml, $user);.

Now, this great quote should render in the profile of a user who has added our application. However, as setFBML is required for FBML to be set on the profile, what do we do if a user adds our application and doesn't view the canvas page? Thankfully, Facebook allows us to set a default FBML. To do so, edit your application's settings (from your Facebook developer account, linked from your profile), and cut and paste your FBML snippet in as your default FBML. You'd be interested in this part.

<fb:wide>
<h1>A great quote!</h1>
<h2>It is a miracle that curiosity survives formal education. – Albert Einstein</h2>
</fb:wide>
<fb:narrow>
<h1>A great quote!</h1>
<h2>It is a miracle that curiosity survives formal education. – Albert Einstein</h2>
</fb:narrow>

This way, after a user adds the application, they'll get the snippet added to their profile regardless of whether they view the canvas page.

Finally, one might ask how one might update the quote on the profile of people who've already added your application. To do so, they're going to have to come back to the canvas page, which will let you call setFBML for the user, redefining the FBML on their profile. However, this option is somewhat limiting, especially for developers of more dynamic applications. To solve this problem, you'll actually want to set the FBML as a pointer to another page that contains FBML logic. Using the refreshRefURL call, you can dynamically set the content on an individual's profile without forcing them to step through a setFBML again. See these threads on the Facebook developer message board for more information.

AIM Facebook Platform Plugin from AOL Labs

Developers at AOL Labs recognized the potential for integration of AOL's APIs with the Facebook platform early on, and worked to create the AIM Facebook platform plugin. The plugin notifies you whenever someone writes on your own or a friend's Facebook wall, when someone sends you a message on Facebook, or when a Facebook friend updates their profile.

Figure 4. The AIM Facebook platform plugin

It's easy to think of other potential integrations of the AOL APIs and the Facebook platform. Perhaps after reading this article, you'll decide to create the next one!

Conclusion

In this article, we've stepped through the process of setting yourself up with a Facebook developer account, getting keys for a Facebook developer application, and we've deployed a very simple Facebook developer application. We've created the framework for a simple application; my goal was to show you how easy it is to get your feet wet with the Facebook API. Once you get a little experience with the interaction, you'll be developing more powerful applications in no time.

Resources

• "Exploring the Facebook Platform, Part 1": The first article in this series, by Fred Stutzman, August 23, 2007
• The AIM Facebook plugin page
• Facebook Platform home page
• Facebook Platform documentation
• Developer resources: Sample code and libraries
• Inside Facebook: An excellent blog chronicling the Facebook Platform