On April 21st 2010 at the F8 conference, King Zuck announced the Graph API and Facebook’s move towards wider integration with the rest of the web.  As a Facebook app development team our ears pricked up and we listened carefully. Apparently “the new Graph API attempts to drastically simplify the way developers read and write data to Facebook.”

The good news was that the Graph API and the Open Graph protocol were going to open up lots of interesting integration points on external websites.

The bad news was the inclusion of the word “attempts”. The old methods of authentication API calls were destined to be deprecated and thus lots of our work was about to become obsolete. Last night, three months after F8, we released a major overhaul of the wishli.st app, and thought we’d better share a few of the things we learnt along the way.

What we’re running…

First, a quick run through of what we were running until yesterday.

On Facebook we had an FBML application – all very simple.  Backing it we were running a Debian/Apache/MYSQL/PHP5 single server.

The code stack is CodeIgniter 1.7.2 with a few hacks to allow us to run the same code base on development, staging and live environments (I’ll write this up another day because it’s pretty handy).

To authenticate users and interact with the Facebook API we were using Elliot Haughin’s Facebook library for CodeIgniter, which is basically a wrapper for the Facebook PHP SDK.

We thought it would be so easy…

“How hard can it be”, we thought?  Lets just take the new Facebook PHP SDK, drop it into place, mangle Elliot’s library so it wraps up the new SDK and all will be well.  How wrong we were.  We tried for two days to make this method work and then gave up.  At least Facebook have now versioned their libraries on github however.

Lesson one: The old PHP wrapper was never going to work with the new API.

Luckily we heard Elliot was releasing a new version of his library that used the new API which would save us the nightmare of developing one ourselves. As soon as it was linked to on twitter we grabbed a copy.

Unfortunately for Elliot though, it’s not possible to simply drop the Facebook SDK into a CodeIgniter library.  Elliot has had to modify the Facebook SDK which could prove to be a maintenance nightmare in the future, but never mind.  We downloaded Elliot’s library and went to drop it into our code and then hit our next big problem. We’re using CodeIgniter 1.7.2 and the new library is for CodeIgniter 2.0 (which is yet to be properly released).

Lesson two: The easy solution is rarely as easy as you think.

So, our next challenge was to get this CodeIgniter 2.0 library converted to a CodeIgniter 1.7.2 library.  This turned out to be reasonably easy and, rather than include it here, I wrote it up on the Github project wiki where other people can benefit from it.

Lesson three: A little sharing goes a long way.

So far, so good.  We could call the authentication mechanism and nearly got as far as getting a session token. And then our framework bit us. Getting a Facebook session token requires passing variables back and forth in query strings. CodeIgniter does not “do” query strings.

For lots of good reasons CodeIgniter defaults to using URL segments to pass information and whilst we could enable query strings we would lose out beautiful URLs (such as http://facebook.wishli.st/wishlist/userid) and get ugly ones (such as http://facebook.wishli.st/?c=wishlist&m=default&q=userid).

Much frustration and ideological “discussion” ensued about the evils of query strings (and why they are so handy, and how come everybody else uses them) and not a lot of fun was had by anyone involved.

Lessons four: Silly technical things can easily become a massive problem if you don’t talk about them.

We were banging our heads against a brick wall.  The code should work.  The config looked right. Debugging it was horrific.  Facebook didn’t seem to react consistently – things that worked one day didn’t work the next.  My face hurt from frowning. And so I tackled it in the way I always do (a way I really must unlearn). I woke up in the middle of the night thinking about it, I put a pot of coffee on and registered a new Facebook app to use as a testbed called LATENIGHTEXPERIMENT.

I realised that there must be something in our CodeIgniter config/install/multi-layered hacks that was causing Facebook authentication to fail and the only way to work out what it was… not to! Eg. Fresh install of CI, fresh install of Elliot’s libraries and a completely bare metal controller and view to test with.  Some time around 4am I got a working authenticated session and was able to email my co-founder Dave with the immortal words that universally signify triumph “Bring the motherf***ing noise!“.  It didn’t do anything except get a list of my friends but it was basically sorted and all we had to do now was drop in the old controllers, right?

Lesson five: Celebrate the achievements, however small, when things are rough.  With swearing. And another coffee.

Dropping in all the controllers, views and other custom written code was the next step then converting all the old API calls into new ones. It should have been so easy. In the end, it took the best part of a month.  I picked the homepage of the app, commented out things that didn’t work and added false returns from deeper functions until it did. Then unpicked each hack and replaced it with the “real call”.

Lesson six: When faced with a massive code headache: pick one tiny area, break it down and “fake it til you make it”.  You’re going to have to go all the way down the stack before you can come back up again.

One thing thats worth mentioning specifically, you’ll need a “logged out” view.  Old Facebook apps could have these, but most choose to just throw up an “Authenticate this app” box on the first page. The logged out view is now used to render a “Connect with Facebook” button, but is also a handy place to explain WTF your app does, before you ask users to give over their details.  You could also give access to a subset of your functionality too.  Handy, huh?

Code changes

Verbose bitching aside, I should give some examples of the code we swapped out.

Calls to the user

$this->facebook_connect->user['uid']

Becomes…

$this->facebook_connect->get_user_id()

Calls to FQL

No massive changes, just pass a more complex array with your FQL in rather than a simple statement:

$fql_query = 'SELECT uid, birthday_date FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1 = '.$this->facebook_connect->user['uid'].')';

Becomes…

$fql_result = $this->facebook_connect->client->fql_query($fql_query);

$fql = 'SELECT uid, birthday_date FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1 = '.$this->current_user['facebook_id'].')';
$param = array(
'method' => 'fql.query',
'query' => $fql,
'callback' => ''
);
$fql_result = $this->facebook_connect->api($param);

The switch to iFrames

While reading many examples of code and the few tutorials, we kept seeing references to iFrames and a shift towards using the Javascript SDK. Eventually, after much heart-ache and bitching because we both firmly believe that iFrames suck, we came to terms with the fact that Facebook are pushing developers towards iFrames:

We don’t recommend FBML for new developers. If you aren’t already using FBML, you should instead implement your application within an iframe, using the JavaScript SDK and social plugins for client-side integration with Facebook services.
http://developers.facebook.com/docs/reference/fbml/

When you build an application on Facebook, your application’s primary page views come via the canvas page, an iframe hosted by Facebook at http://apps.facebook.com/your_app/ that points to your application.
http://developers.facebook.com/docs/guides/canvas/

The fine details of converting from an FBML app to an iFrame app I will save for another long post (we’re still working out some of the niggles) suffice to say: it’s far from easy and it’s a bitch to debug.

One major bonus of doing this, apart from buying us time without needing to upgrade our code again, is that we could launch the app as a standalone site more easily in the future.

A final note

This was going to be a reasonably technical post but instead it’s turned into a bit of a rambling diatribe. If it wasn’t for the community of developers in the Facebook ecosystem (and a few CodeIgniter stars), we’d have been properly screwed.  If you’re struggling with converting your old app get in touch and we’ll see if we can help.  There are tutorials and examples out there but we really didn’t find it an easy ride and Facebook were shag all help.

Frankly we were left feeling lonely, isolated and unloved.  The state of the documentation, the forums and the examples for the new stuff is crap, mismatched, inconsistent and with very little support.

The old API is nearly all still running but you need to use the new permissions mechanisms and the roadmap for when it is shutdown is unclear.  We bit the bullet and did it now but I can’t help thinking that lots of apps – and therefore companies – are going to be screwed when it does. Three months from announcement to a working example and two weeks from that first “bring the noise” email to re-releasing the app is not a smooth path.

My advice: start looking at your stuff now!