I’m quickly prototyping something that needs to interact with Facebook’s API and got absolutely lost by all their documentation – which is plentiful, but poorly curated.

I lost a full day of time trying to figure out why my code wasn’t doing what I wanted it to do, trying to understand how it works so I could figure out what I was actually telling it to do. I eventually hit the “ah ha!” moment where I realized that by following the Facebook “getting started” guides, I was telling my code to do embarrassingly stupid things. This all tends to dance around the execution order , which isn’t really documented at all. Everything below should have been very obvious — and would have been obvious, had I not gone through the “getting started” guides, which really just throws you off track.

Here’s a collection of quick notes that I’ve made.

Documentation Organization

Facebook has made a lot of API changes over the past few years, and all the information is still up on their site… and out on the web. While they’re (thankfully) still supporting deprecated features, their documentation doesn’t always say what is the preferred method or not – and the countless 3rd party tutorials and StackOverflow activity don’t either. The “Getting Started” documentation and on-site + github code samples also doesn’t tie together with the API documentation well either. If you go through the tutorials and demos, you’ll see multiple ways to handle a login/registration button… yet none seem to resemble what is going on in the API. There’s simply no uniformity, consistency, or ‘official recommendations’.

I made the mistake of going through their demos and trying to “learn” their API. That did more damage than good. Just jump into the Javascript SDK API Reference Documentation itself. After 20 minutes reading the API docs themselves, I realized what was happening under the hood… and got everything I needed to do working perfectly within minutes.

Execution Order

The Javascript SDK operations in the following manner:

1. Define what happens on window.fbAsyncInit – the function the SDK will call once Facebook’s javascript code is fully loaded. This requires, at the very least, calling the FB.init() routine. FB.init() registers your app against the API and allows you to actually do things.
2. Load the SDK. this is the few lines of code that start “(function(d){ var js, id = ‘facebook-jssdk’;…” .
3. Once loaded, the SDK will call “window.fbAsyncInit”
4. window.fbAsyncInit will call FB.init() , enabling the API for you.

The important things to learn from this are :

1. If you write any code that touches the FB namespace before the SDK is fully loaded (Step 3), you’ll get an error.
2. If you write any code that touches the FB namespace before FB.init() is called (Step 4), you’ll get an error.
3. You should assume that the entire FB namespace is off-limits until window.fbAsyncInit is executed.
4. You should probably not touch anything in the FB namespace until you call FB.init().

This means that just about everything you want to do either needs to be:

1. defined or run after FB.init()
2. defined or run with some sort of callback mechanism, after FB.init()

That’s not hard to do, once you actually know that’s what you have to do.

Coding Style / Tips

The standard way the Facebook API is ‘instructed to integrated is to drop in a few lines of script. The problem is that the how&why this works isn’t documented well, and is not linked to properly on their site. Unless you’re trying to do exactly what the tutorials are for – or wanting to code specific Facebook API code on every page, you’ll probably get lost trying to get things to run in the order that you want.

Below I’ll mark up the Facebook SDK code and offer some of ideas on how to get coding faster than I did… I wasted a lot of time going through the Facebook docs, reading StackOverflow and reverse engineering a bunch of sites that had good UX integrations with Facebook to figure this out.

// before loading the Facebook SDK, load some utility functions that you will write
<script type="text/javascript" language="javascript" src="/js/fb_Utils.js"></script>
<div id="fb-root"></div>
<script>
    // when Facebook's SDK is loaded, it calls "window.fbAsyncInit"
    // the SDK load is the second block of code below
    window.fbAsyncInit = function() {
        FB.init({
            appId      : 'YOUR_APP_ID', // App ID
            channelUrl : '//WWW.YOUR_DOMAIN.COM/channel.html', // Channel File
            status     : true, 
            cookie     : true,
            xfbml      : true,
            oauth      : true 
        });
        // Additional initialization code here
        // ----------------------
        // ----------------------
        // the above is the fairly standard example from Facebook
        // now we'll do something custom 
        // we want to wrap all our facebook init stuff within a function that runs post async, but is cached across the site
        fb_Utils.initialize();
    };
    // this block actually loads the SDK
    (function(d){
       var js, id = 'facebook-jssdk'; if (d.getElementById(id)) {return;}
       js = d.createElement('script'); js.id = id; js.async = true;
       js.src = "//connect.facebook.net/en_US/all.js";
       d.getElementsByTagName('head')[0].appendChild(js);
     }(document));

</script>

One of the move annoying things I encountered, is that Facebook has that little, forgettable, line in their examples that read:

// Additional initialization code here

You might have missed that line, or not understood its meaning. It’s very easy to do, as its quite forgettable.

That line could really be written better as :

// Additional initialization code here
// NEARLY EVERYTHING YOU WRITE AGAINST THE FACEBOOK API NEEDS TO BE INITIALIZED / DEFINED / RUN HERE.
// YOU EITHER NEED TO INCLUDE YOUR CODE IN HERE, OR SET IT TO RUN AFTER THIS BLOCK HAS EXECUTED ( VIA CALLBACKS, STACKS, ETC ).
// (sorry for yelling, but you get the point)

So, let’s explore some ways to make this happen…

In the code above I called fb_Utils.initialize() , which would have been defined in /js/fb_Utils.js (or any other file) as something like this:

// grab a console for quick logging
var console = window['console'];


// i originally ran into a bunch of issues where a function would have been called before the Facebook API inits. 
// the two ideas i had were to either:
// 1) pass calls through a function that would ensure we already initialized, or use a callback to retry on intervals
// 1) pass calls through a function that would ensure we already initialized, or pop calls into an array to try after initialization
// seems like both those ideas are popular, with dozens of variations on each used across popular sites on the web
// i'll showcase some of them below

var fb_Utils= {
    _initialized : false
    ,
    isInitialized: function() {
        return this._initialized;
    }
    ,
    // wrap all our facebook init stuff within a function that runs post async, but is cached across the site
    initialize : function(){
        // if you wanted to , you could migrate into this section the following codeblock from your site template:
        // -- FB.init({
        // --    appId : 'app_id'
        // --    ...
        // -- });
        // i looked at a handful of sites, and people are split between calling the facebook init here, or on their templates
        // personally i'm calling it from my templates for now, but only because i have the entire section driven by variables

    // mark that we've run through the initialization routine
    this._initialized= true;

    // if we have anything to run after initialization, do it.
    while ( this._runOnInit.length ) { (this._runOnInit.pop())(); }
}
,
// i checked StackOverflow to see if anyone had tried a SetTimeout based callback before, and yes they did.
// link - http://facebook.stackoverflow.com/questions/3548493/how-to-detect-when-facebooks-fb-init-is-complete
// this works like a charm
// just wrap your facebook API commmands in a fb_Utils.ensureInit(function_here) , and they'll run once we've initialized
ensureInit :  function(callback) {
    if(!fb_Utils._initialized) {
        setTimeout(function() {fb_Utils.ensureInit(callback);}, 50);
    } else {
        if(callback) { callback(); }
    }
}
,
// our other option is to create an array of functions to run on init
_runOnInit: []
,
// we can then wrap items in fb_Utils.runOnInit(function_here) , and they
runOnInit: function(f) {
    if(this._initialized) {
        f();
    } else {
        this._runOnInit.push(f);
    }       
},
// a few of the Facebook demos use a function like this to illustrate the api
// here, we'll just wrap the FB.getLoginStatus call , along with our standard routines, into fb_Utils.handleLoginStatus()
// the benefit/point of this, is that you have this routine nicely compartmentalized, and can call it quickly across your site
handleLoginStatus : function(){
        FB.getLoginStatus(
            function(response){
                console.log('FB.getLoginStatus');
                console.log(response);
                if (response.authResponse) {
                    console.log('-authenticated');
                } else {
                    console.log('-not authenticated');
                }
            }
        );
    }
, 
// this is a silly debug tool , which we'll use below in an example
event_listener_tests : function(){  
    FB.Event.subscribe('auth.login', function(response){
      console.log('auth.login');
      console.log(response);
    });
    FB.Event.subscribe('auth.logout', function(response){
          console.log('auth.logout');
          console.log(response);
    });
    FB.Event.subscribe('auth.authResponseChange', function(response){
          console.log('auth.authResponseChange');
          console.log(response);
    });
    FB.Event.subscribe('auth.statusChange', function(response){
          console.log('auth.statusChange');
          console.log(response);
    });
}


}

So, with some fb_Utils code like the above, you might do the following to have all your code nicely asynchronous:

1. Within the body of your html templates, you can call functions using ensureInit()

fb_Utils.ensureInit(fb_Utils.handleLoginStatus)
fb_Utils.ensureInit(function(){alert("I'm ensured, but not insured, to run sometime after initialization occurred.);})

1. When you activate the SDK – probably in the document ‘head’ – you can decree which commands to run after initialization:

   window.fbAsyncInit = function() {
   // just for fun, imagine that FB.init() is located within the fb_Utils.initialize() function
   FB.init({});
   fb_Utils.runOnInit(fb_Utils.handleLoginStatus)
   fb_Utils.runOnInit(function(){alert("When the feeling is right, i'm gonna run all night. I'm going to run to you.");})
   fb_Utils.initialize();
   };
   

Concluding Thoughts

I’m not sure if I prefer the timeout based “ensureInit” or the stack based “runOnInit” concept more. Honestly, I don’t care. There’s probably a better method out there, but these both work well enough.

In terms of what kind of code should go into the fb_Utils and what should go in your site templates – that’s entirely a function of your site’s traffic patterns — and your decision of whether-or-not a routine is something that should be minimized for the initial page load or tossed onto every visitor.