Facebook Tabbed App Undocumented JS API

A couple weeks ago I’ve posted about some issues that I had while developing applications that runs inside a Facebook tab ( http://blog.millermedeiros.com/2010/05/facebook-you-are-doing-it-wrong/ ) and now I’m going to talk about “hidden features” that I’ve found..

Facebook documentation doesn’t explain what is available inside a tab and how to access the API from a tab, the only page that talks about this subject is really vague and doesn’t really help unless you already knows how the system works… (they may delete this page anytime soon since they are deprecating the old documentation)

Facebook deleted the old documentation about the Javascript API but it wasn’t really helpful since it was only about Facebook Connect apps and not for tabs.. Everything was accessed by the FB object and you don’t have access to this object inside a tab since they replace all function and variables names for “security reasons”… The new Graph API also doesn’t work inside a tab (as of May 2010) so the new documentation won’t help either.

Important note: you are entering in dangerous waters, content described here is not documented by Facebook and may change/stop working without any previous notice. (not that it makes a huge difference since Facebook always break things anyway, doesn’t matter if it’s documented or not)

How I’ve found what I needed

After spending a couple hours trying to access the methods described on the documentation, searching on the forum and getting really frustrated I decided to forget about the documentation and figure out everything by myself using the DOM panel on Firebug.

screenshot of Firebug  showing the 'Facebook object' on a facebook tabbed application

Important: The objects that you can access (eg: Facebook object) will only appear after interacting with the page (clicking on a link, focusing a textfield, etc..), the same happen to your JavaScript functions and vars. — JavaScript inside a tab only runs after user interaction.

All methods, functions, vars that you can access from inside your app will be named following this pattern: “a”+”appId”+”_”+”member name” (e.g. a12345_myCustomObject, a12345_myFunction(), etc..) – just use the search field on Firebug and find out what you have access.

Notes about the Facebook namespace

I didn’t spent too much time trying to find out what each method does and which kind of parameters you should pass. So I just have some notes about a few methods:

only get user ID if he gave basic permissions and has interacted with the page
it isn’t really to detect if the user is logged, it detects if the user gave permission to the app.
doesn’t work.
show prompt to ask for “basic permissions” – [params: callback success, callback fail].
doesn’t really work and there is no option to close the popup, causes an endless loop of popups, everytime you close another one appears.
shows “extended permissions” prompt. [params: permission_type, callback_function(result)]
show prompt to add app to your profile (as a tab).
add a post to a wall. [params: message, attachment, action_links, target_id, user_message_prompt, callback function(postID, exception, data), auto_publish, actor_id]
doesn’t work inside a tab because there is no way to set the Google Analytics account ID, FBML tag used for that doesn’t work inside a tab.

Other Available Functions/Objects

Keep in mind that those objects/functions can be different from the native JS objects; some features may be missing and some things may work differently.

Global Objects

  • Ajax
  • Animation
  • Date
  • Dialog
  • document
    • createElement
    • getElementById
    • getRootElement
    • setLocation
  • console //used for debug (firebug, webkit js console, etc..)
  • LiveMessage
  • Math
  • RegExp
  • String

Global Functions

  • clearInterval
  • clearTimeout
  • escape
  • isFinite
  • isNaN
  • parseFloat
  • parseInt
  • setInterval
  • setTimeout
  • unescape

My best advice is to avoid doing any JS/HTML/CSS inside a Facebook tab, if you have the option to do everything using Flash do it, it will be way faster and you will have less problems. – I’m really disappointed with Facebook…

If you really need some JavaScript the best thing is to use Firebug to find out what is available, it’s way more useful than the poor documentation.

Good luck!

Edit (2010/08/12) – surprisingly enough, there is an undocumented way of using iFrames inside tabs, make sure you also check the other examples, it may save you a lot of headache.



Thanks man, this came in handy... I couldn't get the Facebook.requireLogin() method to fire though, so i used the requirerlogin="1" attribute added to an anchor tag. Do you know if its possible to add extended permissions to the basic permissions request, instead of having to ask seperately?


weird... seems extended permissions are automatically being granted, but only after refreshing the tab once user has granted basic permissions.

ok, got it working now, didn't add a callback function to requireLogin(), duh... Still find it strange that my app is being granted extended permissions which i haven't asked for though...

[...] though, Facebook decided to use different variable names for the graph API and the normal API. And, as usual with Facebook, this “feature” is extremely poorly documented. For your own reference, it’s [...]