I'm doing some Facebook development, using the PHP client library. I've been absolutely boggled by the lack of documentation. I mean, maybe I'm just missing it, but... nothing for the PHP client library at all. And the way they treat some development issues as trivial reminds me of professors leaving the really difficult problems as "an exercise for the student".

So I'm going to document my problems and solutions here on my website. I assume you're already familiar with web development in general, so you should have a good grasp of HTML and whatever client you're using. I'm a PHP programmer, so that's what I'll deal with first.

IFrames, AJAX, and Sessions

As an experienced web developer, you might already have an application on your website that you'd like to make available for Facebook users. Facebook's documentation implies that it's easy to make your existing application work in an iframe.

You, oh experienced one, have just swallowed the hook. Don't be ashamed: I did it, too, and I've got 20 years of development experience under my belt. (As well as an extra 100 pounds of "management potential".)

I spent a month creating a web-based puzzle game. I used HTML, JavaScript, and JQuery to rapidly develop effects and make AJAX easy. I figured Facebook would give me the leaderboards and social interaction I needed to make it truly outstanding.

But when I tried to integrate with Facebook, I ran face-first into a wall. The method I copied from the example code requiring the user to add my app caused continuous reloading. When I got rid of that, my "hint" and "done" buttons stopped working.

The problem was that my AJAX calls for those weren't passing along any session data. The Facebook documentation said I should use the Facebook session id, modified to comply with PHP naming requirements. That didn't help, so I started debug-printing the variables. That caused massive parser errors, but with the help of Firebug I discovered the true problem: cookies weren't being passed along.

More delving in the Facebook Developer's Wiki indicated this was a common problem. The Facebook stuff worked on the page load because Facebook passes its required data as GET parameters to the iframe. It also claims to modify your links to add them (as GET parameters). But third-party cookies don't get passed, so my app had no way to keep track of the session.

MORE delving in the wiki and the forum indicated that AJAX calls in an iframe "may present the developer with validation and authorization issues". (Exercise for the student.) One Facebook developer stated on the forums, "I find that most applications don't really need sessions." Well, puzzle applications do, just to keep track of board state. (Okay, they don't really require sessions; but nobody wants to pass all the entire board history around with every click.)

There's a simple solution, of course: just add the original Facebook parameters to every AJAX call. No biggie.

Unless you're worried about security. Finding those GET parameters is simple as pie. Copying them to another page is no big deal (especially with GreaseMonkey floating about). Add these together, and you've got instant identity theft: anyone can play the game as anyone else.

The best solutions involve fingerprinting (which often rules out AOL users and others behind a proxy) and one-time tokens (which has its own problems).

The Moral: IFrames are only really useful for sessionless apps, apps that don't use AJAX, or apps that don't care about security. If you've got something actually useful, Facebook integration will be a challenge.

PHP development

Undaunted (like an idiot), I came up with an idea that required no session. It leveraged the social power of Facebook: wouldn't work without it, in fact. Better yet, there was a clear path to making money!

Unfortunately, I ran into immediate problems with the PHP client library. Namely, there was no documentation.

The sample apps showed how to use require_login(). But I didn't want to force users to add my app; I wanted to leverage all the Facebook users, as much as possible. Finding the get_loggedin_user() and get_canvas_user() functions was more difficult, requiring a peek through the library source code. Figuring out how to use them required combing through the forums for a little while.

Then there came the big problem: how do you access the Facebook API from PHP?

Some trial-and-error didn't help much. I searched the forums and found some sample code, but I wanted a reference. I was almost resigned to diving into the library code again when I suddenly realized the pattern: use the api_client field of your Facebook instance and call the function with an underscore instead of a dot. So, if your instance of Facebook is $fb, friends.get becomes $fb->api_client->friends_get(), users.getInfo becomes $fb->api_client->users_getInfo(), and so on.

I really wish someone had written that down somewhere obvious and visible.

The Moral: There is no documentation for the Facebook PHP client library, but you can derive the functions you need.

Maybe one day I'll write up a quick tutorial. Or a good example program. Maybe Mastermind or something.