The Facebook API battle/disaster night

I thought it would be fairly simple...

I had worked on a Facebook iframe application once before, and I remembered that the addition of requiring Facebook login and then being able to render XFBML components was not very complicated at all.  It was a matter of pasting in some code in a few different places, and magically, the page would request you to log in and add the application, and then it could show you your Facebook picture and name.  (By the way: FBML = Facebook Markup Language, and XFBML is the version you can use on off-site pages, i.e. your pages in an iframe, or on Connect app pages.)

Well, there I was, just over a year later.  I began delving into the wiki/documentation on authentication etc., and what I began to realize is that everything seemed to be in transition.  There was this new "graph API", and OAuth authentication, and a new Javascript API -- or at least, these all appear to be new, based on the look of the pages and what I could gather from the descriptions.

I really only wanted to be able do 3 things: require login and authentication of the app, pull/display users' names, and pull/display users' profile picture thumbnail.

Many long hours of confusion later, I had gone through stages something like this:

1. using the wrong new stuff (a PHP API which I now think is supposed to be for Connect apps?);
2. trying to use the old PHP library, cross-domain receiver file, XFBML, and iframe resizing... I don't even remember what didn't work in this combination, but some piece didn't;
3. trying to combine the old PHP library and XFBML paste-in code with some of the newer stuff, I think? I don't even remember;
4. attempting to manually implement the OAuth redirection cycle (things like obtaining a key and this and that), which actually almost worked...;
5. deciding to give up on making this an iframe application that's actually within the Facebook chrome, and instead, switching it over to a Connect app, using the easy authentication/login via the new Javascript API and all of which is luckily still compatible with XFBML.

...wow.  It was a long, tiring, frustrating struggle.  Much of it was due to over-documentation, if you will, and a lack of clarity in terms of marking pages regarding at which level of API/platform transition the information and code on that page would still be relevant and functional.


And now for the bombardment of a list of links.  Here are some of the many Wiki pages/sections I tried to use to figure this out...

(Note: seems like they are really in transition currently - some of the links may not work or will give a message saying the content is moved/updated)


New (pages are in the theme of the new documentation)

Overview guide to apps (new)

Authentication (new)

Graph API (new)

JavaScript SDK (new)

Old REST API - apparently the precursor to the new Graph API


Old, but seems to still apply / be compatible with new stuff

XFBML (including tag list)


Old, and seems to not apply / not be compatible with new stuff

API (old?)

PHP (old?)

FB_RequireFeatures (old?) - for dynamically loading components of the JS API (via FeatureLoader.js.php)

Authorization and Authentication for Canvas Page Applications on Facebook - matches with the old(?) PHP library

Extended Permissions

Connect/Setting up your site - including XFBML rendering (but uses the FeatureLoader.js.php)

Resizable iframe

As I mentioned in my post about setting up the Facebook app, I selected the option to allow the iframe (which holds all of my content -- it pulls my app pages from toryg.net) to be resizable.  I didn't really know what that meant when I was setting it up, but now I've realized: if my content is longer vertically on the page than what's seen in the browser window, the content just gets cut off.  (Thanks to Firebug, I found the css command that was setting the iframe to have overflow: scroll; -- so when I was testing two instances of the swf on one page, I would simply go into Firebug and cancel that line so I was able to scroll the iframe and see everything.)

Today I decided to figure out how to actually fix this.  Thanks to the resizable iframe page (on the Developers' Wiki), I found out I had to set up two things first:

• allow for cross-domain JavaScript communication (between my server and Facebook's server)
• load in the JavaScript client library, which is simply a call to pull a script stored on Facebook's servers

Then in JavaScript I had merely to call up the CanvasUtil features, set the location of the xd_receiver.htm file, and call a library function (startTimerToSizeToContent()) which watches changes in the canvas content and automatically resizes the iframe appropriately.  (In other words, I copied the several lines of code from the resizable iframe page.)

The only hitch I had was that at first I was placing those few lines of Javascript up in the head of the page, and then that hidden div in the body hadn't been created yet when the script was trying to initialize.  Thus, unfortunately, I have to stick the script in the body, right after that div.  But it works now, so that no matter how vertically-long my content is, the iframe changes to accommodate it and I can scroll freely and see everything.

Setting up the Facebook application

Luckily this task does not seem nearly as daunting to me as it might, since I have worked through the process before when I took the User Interfaces and the Web course (which was CIS 399.006 prior to the renaming of all the 399s) and my partner and I were creating a Facebook app for our project.  However, since things may have changed since then, I've decided to figure out the process again with the help of instructions and documentation, and consult my code from the prior app only if I get stuck.

Some of the basic information was easy: what to name the app (Trace Race), an email address for Facebook to use to contact me, and an email address for app users to contact the developer (which I set to the email I created while setting up my web hosting service).  There are also spaces to fill in a few callback URLs, but as I haven't created any of the pages yet, I'm leaving those blank for a moment.

The first major choice to be made was whether to build the app as an iframe or with FBML.  I found an article on the developers' wiki explaining the differences and pros/cons of both structures.  After reading this over, I decided to go with the iframe-based structure for a few reasons: it reduces the overhead for AJAX calls (which I do expect to use), it avoids the slowdown caused by reloading Facebook Chat (this happens in FBML apps because page reloads must reload the whole page, whereas iframe reloads only reload the frame), and XFBML provides a faster way to use Facebook elements or access Facebook data than making individual API calls (and I don't expect to be making many of those anyhow).

The next question was whether to use the resizable iframe option.  This allows some control over the size of the iframe as opposed to having to fit the app into a fixed-size frame.  Although I am not sure yet how large the Flash gameboard area will be, I imagine that the pages without the gameboard and the pages with the board will probably have a different-sized content area, so I will try out turning on the resizing option.  Maybe I will turn it off later once I see how the pages are coming together.

Finally (though the app isn't totally set up--have to connect the database and hook in Facebook API code), I ran the simplest of tests.  On my web hosting space I created a directory for the pages for this app and entered it as the canvas callback URL in the app settings.  I chose a canvas URL, which is the direct link to the app in the form of "http://apps.facebook.com/[name]": http://apps.facebook.com/tracerace/.  So now if you access the canvas URL, you'll see the directory index (being pulled via an iframe from my server space) and can click to the test.html page.  Sweet!

p.s. I have added a screenshot showing the test page on my server space being pulled into the app's iframe, BUT, since the app is indeed live and publicly accessible--albeit in a primitive bare-bones fashion--you can actually go to the URL and see it yourself.  (At least, I believe so--a Facebook account may be required.  I haven't tested that.)