Adding a profile box and posting to the feed on facebook

Posted on by Pygmalion

Building an app is easy. At least that’s what facebook states. Yet it can be quite a challenge to get started if you’re not famliar with facebook’s API as the documentation can be quite confusing. Besides, the API seems to be still under development and therefore subject to changes. Chances are that you’ll code against deprecated API (e.g. after googling for a solution).

We’ll demonstrate how to 1) add a profile box to a user profile and 2) post a message to the news feed.

After we’ve set up the application in the Developer App, we’ll start with some code to instantiate a facebook object with our unique API key and application secret. This object contains the api_client object with all the API methods we need. It also contains methods to retrieve some values we’ll need during the application session, like the user’s unique ID.

// the facebook client library
include_once 'facebook-platform/php/facebook.php';
 
// Get these from http://developers.facebook.com
$api_key = '<your key goes here>';
$secret  = '<your app secret goes here>';
 
// We may want to use this URL later
$app_url = "http://apps.facebook.com/helfrichabsinthe/";
 
$facebook = new Facebook($api_key, $secret);
$facebook->require_frame();
$user = $facebook->require_login();

We’ll define a variable that contains the FBML code for our profile box. Actually, we’ll need two boxes. The “narrow box” is the one the users will be prompted to add to their profile. A user will be able to move it to the Boxes tab. This will be our “wide box.” There used to be a third box for mobile devices but it’s deprecated by now. For the sake of simplicity we’ll fill these boxes with our initial box code. We can modify this later.

The FBML code is passed by reference so we’ll be able to update it later without having to republish.

$Box = "<a href=\"{$app_url}\">I love Helfrich Absinthe.</a><br/>
<img src=\"http://www.helfrichdranken.nl/eshop/images/helfrich_verte.jpg\"
border=\"0\" height=\"120\" width=\"120\"><br/>
<a href=\"http://www.helfrichabsinthe.com/\" target=\"_blank\">
www.helfrichabsinthe.com</a>";
 
$facebook->api_client->call_method('facebook.Fbml.setRefHandle', 
array( 'handle' => 'BoxHandle', 'fbml' => "$Box" ,) );
$NarrowBox = "<fb:ref handle=\"BoxHandle\" />";
$WideBox = $NarrowBox;

Now we have all we need to instantiate the profile box. Note that it will only be visible after the user has added it. NULL values are used for deprecated parameters.

$ret = $facebook-&gt;api_client-&gt;profile_setFBML(NULL, $user, $WideBox, NULL, 
NULL, $NarrowBox);

Next we create a simple FBML canvas for our application to present itself. It contains the button that allows users to actually add the box to their profile.

<div style="padding: 10px;">
  <h2>Thanks for loving Helfrich Absinthe. We love you too, <fb:name 
firstnameonly="true" uid="<?=$user?>" useyou="false"/>!</h2><br/>
Please add us to your profile.<br/> <br/>
<fb:add-section-button section="profile" />
<br/>
</div>
<div style="padding: 10px;">
<img src="http://absintblog.be/wp-content/uploads/helfrich-verte-1.jpg">
</div>

Finally we want to prompt users to publish their action to the feed. There are several ways to do this, but most of them seem to be partially or fully deprecated. Facebook encourages the use of the FBJS function Facebook.streamPublish.

We won’t need templates to format the message. Instead we’ll pass a JSON object as a so-called attachment. We can also specify some “action links“. These are added as options to the line below our posting (after Comment, Like, etc.) and need to be passed as an array of JSON objects. It’s not as complicated as it probably sounds:

<script>
var attachment = {'caption':'{*actor*} loves Helfrich Absinthe.','description':
'Click the link below if you do too.','media':[{'type':'image','src':
'http://www.helfrichdranken.nl/eshop/images/helfrich_verte.jpg','href':
'http://www.helfrichabsinthe.com/'}]};
var actionlink = [{'text':'Click here if you do too.','href':
'http://apps.facebook.com/helfrichabsinthe/'}];
Facebook.streamPublish('loves Helfrich Absinthe.', attachment, actionlink);
</script>