JavaScript Client Library

From Facebook Developers Wiki

Jump to: navigation, search

Contents

[edit] JavaScript Client Library (BETA)

The Facebook JavaScript client library allows you to access various features of Facebook Platform through JavaScript. For example, you can make Facebook API calls through JavaScript code from any Web site and makes it easy to create AJAX Facebook applications. Since the library does not require any server side code on your server, you can now create a Facebook application that can be hosted on any Web site that serves static HTML.

Applications that use this client library should be configured to load either directly for iframe-based applications or through the Fb:iframe tag for FBML-based application. Users can access the iframe-based applications through the Facebook Web site or directly on the application's own Web site.

There are currently two features in this client library:

[edit] Setting Up JavaScript Client

  1. Create a channel page to enable communication between your Web page and Facebook. See Cross_Domain_Communication_Channel for instructions.
  2. Reference this Facebook JavaScript file in your HTML page: http://static.ak.facebook.com/js/api_lib/v0.3/FeatureLoader.js

Now you can start calling various JavaScript methods in the JavaScript client library.

[edit] Facebook API Client

The library supports most existing Facebook API methods.

Note: Support for the Data Store API is temporarily disabled until we support user-level permissions.

Here is sample code for getting the list of the current user's friends.

<!-- Text area to display tracing information to the Web page. If you use Firebug or Safari debug console, these tracings will go to the JavaScript console as well. --> <textarea style="width: 1000px; height: 300px;" id="_traceTextBox"></textarea> <script src="http://static.ak.facebook.com/js/api_lib/v0.3/FeatureLoader.js" type="text/javascript"></script> <script type="text/javascript"> FB_RequireFeatures(["Api"], function() { // Create an ApiClient object, passing app's API key and // a site relative URL to xd_receiver.htm var api = new FB.ApiClient('<insert_you_app_key>', '<site_relative_url_to_channel_page>', null); // require user to login api.requireLogin(function(exception) { Debug.dump("Current user id is " + api.get_session().uid); // Get friends list api.friends_get(null, function(result, exception) { Debug.dump(result, 'friendsResult from non-batch execution '); }); }); }); </script>


This first step of the code calls FB_RequireFeatures() to ensure that the API client feature is loaded. After the API client feature is loaded, it creates an FB.ApiClient object and invokes its requireLogin() method. This step is required before any Rest API calls can be made. Once requireLogin() completes, it invokes the callback function. At that time, you can start calling other API methods. There are two ways to call them: normal mode and batched mode.

In normal mode, you pass a function callback as the last parameter to an API call. When an API method is called, it sends an HTTP request to the Facebook API server. Once the API call is completed, the callback function then gets invoked with the parameters result and exception, where result contains the result of the API call and exception contains any exception information in case of failure.

In batched mode, you can queue up a sequence of individual API calls, then group them all into a single HTTP request to the Facebook server to be executed. Because only a single HTTP request is sent, this could have a substantial performance benefit both on the Facebook API server and in terms of client side latency. To use a batch operation, you need to first create an FB.BatchSequencer object. After creating an FB.BatchSequencer object, it can be passed as the last argument of each individual API call. When you need to execute only batched operations, you can call the execute() method on the FB.BatchSequencer object. Here is some sample code:

/// Example of calling APIs in batched mode //First create a sequencer for batch execution var sequencer = new FB.BatchSequencer(); // By default, individual APIs may be executed in parallel on the server side. // To force sequencial executions on the server, uncomment the following code // sequencer.isParallel = false; //Calling friends_get API, passing the sequencer as last argument var pendingFriendsResult = api.friends_get(null, sequencer); // //Call notifications_get API, passing the sequencer as last argument var pendingNotificationsResult = api.notifications_get(sequencer); //Actually execute the API that is queued inside the sequencer, passing a callback function that is called //when the batch operation is completed. When the callback function is called, the 'result' or 'exception' properties of //pendingFriendsResult and pendingNotificationsResult are updated. sequencer.execute(function() { Debug.dump(pendingFriendsResult.result, 'friendsResult from batch execution'); Debug.dump(pendingNotificationsResult.result, 'notificationsResult from batch execution'); });


[edit] Canvas Client

If your application is intended to be hosted in an iframe-based canvas page on apps.facebook.com, you can use the FB.CanvasClient.* methods to control the size of the hosting iframe elements. For more information, see Resizable_IFrame.

[edit] JavaScript Client Documentation

For complete documentation of the JavaScript API library, download the zipped archive.

Note 3/12/2008: This documentation is not yet updated to include the FB_RequireFeatures and FB.CanvasClient methods.

[edit] Supported Browsers

The following browsers are currently supported:

  • Internet Explorer 6, Internet Explorer 7
  • Firefox 2
  • Safari 3

The beta versions of Internet Explorer 8 and Firefox 3 are not supported, but we will support them when they ship.

[edit] Demo

[edit] Authentication Model for the JavaScript API

For this type of application, we settled on the following design objectives:

  1. All Facebook REST API calls require that both the user and application are authenticated and authorized.
  2. After authentication, the session information should be known only by the user, the application, and Facebook.
  3. API calls using this authentication can be used only for operations that read or update user data or perform actions on behalf of the user/app combination. For example, profile.setFBML cannot be used to modify other users' FBML.

For more information, please read the Authentication Model for the JavaScript API.

[edit] Change History

A change history of JavaScript API-related work is available.

Retrieved from "http://wiki.developers.facebook.com/index.php/JavaScript_Client_Library"