Step-by-step Guide to Creating an Application

Introduction

Integrating Hello World

Pushing FBML to the profile box

Using mock-AJAX in the profile box

Using MySQL to create a counter

Putting the examples together

Downloads

Introduction

This tutorial describes how we created a platform application called 'tutorialapp' that you can use as a template when creating your own platform app. The tutorial assumes that you have access to a web server running php5.

The final version of 'tutorialapp' is hosted at http://tperry256.dreamhost.com/f8/tutorialapp/. If you follow this link it will ask you to login to Facebook and add the 'tutorialapp' application. You can get access to a server like this from a variety of hosting companies for just a few dollars a month.

When you create your own app, you will using a different application name and a different server. We have highlighted these things that will be different for your application.

Integrating Hello World

Go to http://developers.facebook.com/

Click on 'Get Started'

Click on 'Add Facebook Developer Application'

A link to 'Developer' should appear in the left nav on Facebook now. Go to the Developer App.

Click on the button that says 'Setup New Application'

Here are the steps for filling out the form:

Application Name: for our app, we put 'Tutorial Application' - you should put in a different name.

Check the Terms of service box.

Click on the Optional Fields link - this will bring up more options.

Support E-mail: your Facebook contact email may be filled in automatically, but you might not want to give out your personal email to everyone who adds your app! You do have to put a valid email address that you can check, however.

Callback Url: for our app, we put 'http://tperry256.dreamhost.com/f8/tutorialapp/' - you should put something DIFFERENT - in particular, you should put the url of the directory on your server where you will create your application.

Canvas Page URL: http://apps.facebook.com/: for our app, we put 'tutorialapp' - you must put in a different name.

Use FBML: keep this setting.

Application Type: leave this set to 'Website'.

Can your application be added to Facebook: set to 'yes' - this will bring up more options.

TOS URL: you can leave this blank.

Post-Add Url: for our app, we put 'http://apps.facebook.com/tutorialapp/' -- you should put something DIFFERENT - in particular, you should put your full canvas page url.

Default FBML: type in the text 'hello'.

Leave everything else under Installation Options blank.

Side Nav Url: for our app, we put 'http://apps.facebook.com/tutorialapp/' -- you should put something DIFFERENT - in particular, you should put your canvas page url here as well.

Leave everything else under Integration Points blank.

Click on the 'Submit' button.

Go the the 'My Applications' page and check that your application was created. There are a couple ways to get here depending on where you are in the Developer application.

Copy the latest version of the php5 client library into your application's directory on the server.

There are some links to the client library in the downloads section. If you are using a unix shell and are currently in that directory, these commands will work:

wget http://developers.facebook.com/clientlibs/facebook-platform.tar.gz

tar zxvf facebook-platform.tar.gz

cp facebook-platform/client/facebook.php .

cp facebook-platform/client/facebookapi_php5_restlib.php .

rm -rf facebook-platform.tar.gz facebook-platform

Create an 'appinclude.php' file that you will include at the top of all the php pages in your app. Paste this code into the file:

require_once 'facebook.php';



$appapikey = '[your api_key]';

$appsecret = '[your secret]';

$facebook = new Facebook($appapikey, $appsecret);

$user = $facebook->require_login();



//[todo: change the following url to your callback url]

$appcallbackurl = 'http://tperry256.dreamhost.com/f8/tutorialapp/';



//catch the exception that gets thrown if the cookie has an invalid session_key in it

try {

  if (!$facebook->api_client->users_isAppAdded()) {

    $facebook->redirect($facebook->get_add_url());

  }

} catch (Exception $ex) {

  //this will clear cookies for your application and redirect them to a login prompt

  $facebook->set_user(null, null);

  $facebook->redirect($appcallbackurl);

}

Replace '[your app_key]' and '[your secret]' with the 'app_key' and 'secret' for your application that are shown on the 'My Applications' page of the Developer app. You should also replace our callback url with your callback url.

Create a 'index.php' file which will be your application's home page. Paste this code into the file:

require_once 'appinclude.php';



echo "hello $user";

Type YOUR APP's callback url into your browser's address bar. You could also type in your canvas page url because going here will also cause your 'index.php' to run. Either way, the only way to get your application added at this time is to type a url into your browser's address bar.

here is OUR APP's callback url: http://tperry256.dreamhost.com/f8/tutorialapp/

here is OUR APP's canvas page url:http://apps.facebook.com/tutorialapp/

Click 'I agree' to accept the terms of service for your application and then click the button to 'Add [your application name]' to add it.

You should then be redirected to a canvas page which contains the output of your 'index.php' file.

Go to your profile and look for a profile box for your application which contains the 'hello' -- this is the default FBML that you set before.

Finally look for a left-nav link that will take you back to your canvas page.

Pushing FBML to the profile box

Here is an extended version of 'index.php'. When the user submits the form, this code puts the text they submitted in the profile box.

Note that submitting the empty string causes the profile box to disappear!

require_once 'appinclude.php';



echo "hello $user";



if (isset($_REQUEST['profiletext'])) {

  $facebook->api_client->profile_setFBML($_REQUEST['profiletext'], $user);

  $facebook->redirect($facebook->get_facebook_url() . '/profile.php');

}



echo '';

echo '
';

echo '';

echo '';

Using mock-AJAX in the profile box

This code pushes a form into the profile box that uses the mock-AJAX feature of FBML to give the illusion that you can dynamically update the content of the profile box.

Notice how the if statement at the very top of this 'index.php' file handles the mock-AJAX call.

if (isset($_REQUEST['mockfbmltext'])) {

  echo $_REQUEST['mockfbmltext'];

  exit;

}



require_once 'appinclude.php';



echo "hello $user";



$fbml = <<This is the subtitle










  clickrewriteurl="$appcallbackurl"

  clickrewriteid="preview" value="Draw text below"

/>










EndHereDoc;



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



echo "the following form was added to the profile box:";



echo $fbml;

Using MySQL to create a counter

This example assumes that you have a way to create a mysql database which the php scripts on your server can connect to.

If you don't already have a database, create one.

Create a table in the database called 'counter' which has a single integer column called 'count'.

Create a new file called 'dbappinclude.php' and paste the following code into the file. Don't forget to replace the items in brackets with your actual db host, user, pass, and name.

require_once 'appinclude.php';



$dbhost = '[your db host]';

$dbuser = '[your db user]';

$dbpass = '[your db pass]';

$dbname = '[your db name]';



$conn = mysql_connect($dbhost, $dbuser, $dbpass);

mysql_select_db($dbname, $conn);



function query($q) {

  global $conn;

  $result = mysql_query($q, $conn);

  if (!$result) {

    die("Invalid query -- $q -- " . mysql_error());

  }

  return $result;

}

Now try out this version of 'index.php'. It displays a counter that gets updated every time 'index.php' is loaded.

require_once 'dbappinclude.php';



echo "hello $user";



$rs = query("select count from counter");

if ($row = mysql_fetch_assoc($rs)) {

  $count = $row['count'];

  query("update counter set count=count+1");

} else {

  query("insert into counter values (1)");

  $count = 1;

}



echo "the count is $count";

Putting the examples together

Here's a final version of 'index.php' which puts all these examples together. It assumes that you have created 'dbappinclude.php' from the previous example.

if (isset($_REQUEST['mockfbmltext'])) {

  echo $_REQUEST['mockfbmltext'];

  exit;

}



require_once 'dbappinclude.php';



echo "hello $user";



$rs = query("select count from counter");

if ($row = mysql_fetch_assoc($rs)) {

  $count = $row['count'];

  query("update counter set count=count+1");

} else {

  query("insert into counter values (1)");

  $count = 1;

}



echo "the count is $count";



if (isset($_REQUEST['profiletext'])) {

  $facebook->api_client->profile_setFBML($_REQUEST['profiletext'], $user);

  $facebook->redirect($facebook->get_facebook_url() . '/profile.php');

}



echo '';

echo '
';

echo '';

echo '';



$fbml = <<






  clickrewriteurl="$appcallbackurl"

  clickrewriteid="preview" value="Draw text below"

/>










EndHereDoc;



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



echo "the following form was added to the profile box:";



echo $fbml;

Downloads

facebook_client.tar.gz -- the latest php5 platform client library

tutorialapp.tar.gz -- source fo the final combined example; you need to fill in your own app_key, application secret, and db info to make it work on your server

tutorialapp.zip -- same as tutorialapp.tar.gz but in a zip file

Tech Bits

Tuesday, June 3, 2008

Facebook App Creation