Fork Me On Github

Facebook API Wrapper

Download on GitHub

This simple jQuery wrapper framework for Facebook's Open Graph API has been gradually created and improved upon over the past few years. It started off as just the basics, and has grown as our requirements have grown.

The general idea is that it takes all the pain out of using Facebook's javascript SDK - you just drop this file into your project, and all the most common requirements are there, ready and waiting to be used with just a few lines of code.

Getting Started

Of course, you'll need to setup your Facebook app at https://developers.facebook.com/apps before you can start using the SDK. There are plenty of guides out there to get you started. Make sure you configure your app/site URL correctly, and make a note of the App ID. Then, just embed the frmwrk.facebook.x.js file into your web page, and add a little javascript configuration to your site:

$facebook_config = {
     app_id: '', // Facebook App ID, required
     scope: '', // Permissions, comma separated
     user_fields: '' // The default user fields you want to return, comma separated
};

Pretty straight forward - the only required field is app_id, which you'll get after setting up your Facebook app as above.

For more info on permissions, see https://developers.facebook.com/docs/facebook-login/permissions
The full list of user fields available can be found at https://developers.facebook.com/docs/graph-api/reference/user

Authorisation

$facebook.login(callback)

The primary reason this wrapper exists - authenticating users with Facebook. Just call this function to allow your users to log in to your app. The callback parameter is optional, and allows you to specify a callback function once the user has authenticated, and their data has been fetched from Facebook. If no callback is passed, the default $facebook.fnc_login_auth() function will be called (see the callbacks section below).

$facebook.revoke(callback)

De-authenticates the user from your app. You'll no longer have access to their data - all permissions will be removed, they'll have to authenticate again to log back in. Optional callback parameter. If no callback is passed, the default $facebook.fnc_revoked() function will be called (see the callbacks section below).

$facebook.logout(callback)

Logs the user out of Facebook completely. They'll still be authorised to use your app/website though. Optional callback parameter. If no callback is passed, the default $facebook.fnc_revoked() function will be called (see the callbacks section below).

Callbacks

There are a series of default callbacks that can be used, by first defining them like the example below:

var $facebook_functions = {
fnc_ready: function(){
	// your code here
}

The following callbacks are available:

$facebook.fnc_ready()

Fired once the Facebook SDK has loaded and initialised. You're now ready to start making calls to the API.

$facebook.fnc_auto_not_logged_in()

Fired after the Facebook SDK has loaded and the user's auth status has been determined as "not currently logged into Facebook." Fired again if the user's auth status changes to this at any time.

$facebook.fnc_auto_not_auth()

Fired after the Facebook SDK has loaded and the user's auth status has been determined as "logged into Facebook, but not authorised with your app." Fired again if the user's auth status changes to this at any time.

$facebook.fnc_auto_auth()

Fired after the Facebook SDK has loaded and the user's auth status has been determined as "logged into Facebook and authorised with your app." Waits for the user's data to be fetched before firing. Fired again if the user's auth status changes to this at any time.

$facebook.fnc_login_pre()

Fired immediately when $facebook.login() is called, without waiting for a response.

$facebook.fnc_login_auth()

Fired after using $facebook.login() and the user's auth status has been determined as "logged into Facebook and authorised with your app." Waits for the user's data to be fetched before firing.

$facebook.fnc_cancelled()

Fired if the user denies permissions from the Facebook authentication dialog.

$facebook.fnc_revoked()

Fired if the user revokes their permissions from your app, unless an alternative callback is specified when using $facebook.revoke().

$facebook.fnc_loggedout()

Fired if the user uses the $facebook.logout() function, unless an alternative callback is specified.

Data Variables

$facebook.init

Equal to false, until the Facebook SDK has initialised and is ready to use. Will then be set to true.

$facebook.got_status

Equal to false, until the user's authentication status has been fetched. Will then be set to true.

$facebook.auth_response

Once a user has authenticated, contains the authorisation response from Facebook, including the user's access token and the signed request.

$facebook.logged_in

Will be true if the user is currently logged in, otherwise false.

$facebook.got_user

Will be true once the user's data, as defined in the $facebook.user_fields config option, has been fetched.

$facebook.user

Stores the current user's Facebook data, as defined in the $facebook.user_fields config option, once they are logged in.

$facebook.status

Stores the current user's auth status. Will be 'connected', 'not_authorized', or 'not_logged_in'.

$facebook.permissions

Stores the permissions that the current user has granted the app.

$facebook.friends

Stores the user's friends, if $facebook.get_app_friends() is called.

$facebook.default_stream_privacy

Stores the user's default stream privacy setting for posts, i.e. public, friends only, private etc.

$facebook.canvas_info

Stores information about the Facebook canvas, if $facebook.canvas_get_info() is called.

Canvas Functions

These functions are for canvas and tab apps only. They will have no effect outside of this.

$facebook.canvas_get_info(callback)

Get information about the Facebook canvas, such as size and position. Stores data in $facebook.canvas_info. Can be passed a callback.

$facebook.canvas_scroll_top()

Scroll the canvas to the top of the page.

$facebook.canvas_scroll_to(y)

Scroll the canvas to a particular height. Y-coordinate must be passed.

$facebook.canvas_set_size(height,width)

Set the size of the canvas, in pixels. Width is optional, and will default to 810.

$facebook.canvas_set_size_repeat()

Automatically sets the canvas size, and updates every half a second for apps that vary in dimension. Defaults to 810 wide, and the height of the document.

$facebook.canvas_set_autosize()

Calls Facebook's default autosize canvas function. This will grow the canvas to whatever height is required, but it will not shrink again with your content, only grow. As such, $facebook.canvas_set_size_repeat() is recommended instead.

Other Functions

$facebook.add_perms(permissions,callback)

Request additional permissions for the current user. Pass permissions as a comma separated string. Can also be passed a callback function.

$facebook.get_app_friends(callback)

Fetch friends of the current user who also use the current app. Stores data in $facebook.friends. Can be passed a callback function.

$facebook.upload_photo(url,description,callback)

Upload a photo to the user's Facebook profile. Will be saved to an album dedicated to the current app. Pass the image URL, and optionally a description and callback function.

$facebook.friend_request(fbid,callback)

Open a friend request dialog. Pass the facebook id of the friend to request, and optionally a callback function.

Compatability

This API wrapper has been tested to a reasonable extent in all modern browsers, as well as many older ones. Compatible browsers include, but are not limited to, the following:

Chrome (all versions?)
Firefox 8+
IE 8+
Opera 12+

Safari 6+
Safari for iOS 6+

More Info

Facebook's official API endpoint documentation is available online at https://developers.facebook.com/docs/graph-api/reference

Wrap Up

This API wrapper has been written for our own apps, and used extensively. That doesn't mean to say it's the best, most foolproof way of doing things, it's just how we do it. We've open sourced it on the off chance that someone else might benefit from it, as well as for feedback, advice, suggestions and recommendations on how to improve it.

We hope it comes in useful!