Table of Contents

1. Basics.
   1. Why is this better than the current JS library?
   2. How do I use it?
2. Something’s not working.
   1. Has the Cookie format changed?
   2. Where did the named API methods go? Why is there just FB.api()?
   3. Where do I file a bug?
3. Planning Ahead.
   1. Where are the IFrame Dialogs?
   2. Where is the Canvas Support?
   3. Where is XFBML?
   4. What about Internationalization?

Basics.

Why is this better than the current JS library?

The new library is 10 times smaller in size and performs roughly 3 times faster (JavaScript performance) than the old library in most browsers. We’re also making the new library modular, so you only have to include what you need.

How do I use it?

The examples are a good place to start. The minimal you’ll need to have is:

<div id="fb-root"></div>
<script src="http://static.ak.fbcdn.net/connect/en_US/core.js"></script>
<script>
  FB.init({ apiKey: 'YOUR API KEY' });
</script>

Note: For easier development, we also have an unminifed (raw code with comments) version available using this URL:

http://static.ak.fbcdn.net/connect/en_US/core.debug.js

We also have documentation available here.

Something is not working.

Has the Cookie format changed?

As part of optimizing performance, we’ve changed the cookie format to be more compact. In the new model, there are only two top level cookies:

fbs_{api_key}: Signed Data
fb_{api_key}: Unsigned Data

The fbs cookie is essentially the signed session, the new format is:

{
  "uid": "5526183",
  "session_key": "XYZ",
  "secret": "ABC",
  "base_domain": "<optional, depending on your app settings>",
  "expires": 1234567890,
  "sig": "the signature"
}

Notice this follows a different approach than our existing signed sessions. We’ve made this change to shrink the serialized form by omitting the repeating prefix on the keys and chosen to include the signature as a part of the object itself under the key sig. Here’s an example of how the signature can be validated using the built in signature logic of the new SDK:

var apiSecret = 'YOUR APP SECRET';
var session = FB.copy({}, FB.getSession());
var expectedSig = session.sig;
delete session.sig;
var generatedSig = FB.md5sum(FB.QS.encode(session, '', false) + apiSecret);
console.log('Expected: ' + expectedSig);
console.log('Generated: ' + generatedSig);

NOTE: This is for reference only! Do NOT put your api secret in your JavaScript. You should be implementing this logic on your server.

NOTE: The fb_{api_key} cookie has not yet been implemented. We will update this entry when it’s ready.

Where did the named API methods go? Why is there just FB.api()?

In order to reduce the size of the library, and provide a consistent interface into the server side APIs, we’ve decided to forego the existing structure of having named methods for each API call. We have dozens of APIs and add new ones on a regular basis. This new approach gives us the flexibility to do so without requiring changes to the SDK itself.

For example, previously you would write something like:

var handleResponse = function(response) {
  console.log(response);
};
FB.Facebook.apiClient.users_getInfo(4, 'name', handleResponse);

Where as with the new approach you do:

var handleResponse = function(response) {
  console.log(response);
};
var request = {
  method: 'users.getInfo',
  uids: 4,
  fields: 'name'
};
FB.api(request, handleResponse);

There are a few advantages with this approach. First, this means new API calls are immediately usable by the new SDK without requiring any changes. Second, the size of the SDK does not grow as we add new Server side API calls. And finally, the API docs are immediately usable as the new format uses a named key/values instead of positional parameters. This is similar to how you make calls from the server with URL Query Parameters, so we think this it will be easier to understand.

Where do I file a bug?

Please provide full test case in order for your fellow developers to help you out when filing bugs.

Upcoming Features.

Where are the IFrame Dialogs?

These are not going away and will be available soon. Stay tuned.

Where is the Canvas Support?

The first iteration or the alpha release of the new SDK does not support Canvas pages. The current library is suitable for use with independent websites. You are free to experiment with the library on Canvas pages and let us know about your experience though :)

Where is XFBML?

XFBML is not going away and will be available soon. Stay tuned.

What about Internationalization?

Internationalization is a high priority goal for us. We’ve setup the infrastructure necessary to enable this for the new SDK. But the support is still rough, and we will be fixing that as we go along.

The current URL must specify en_US as the locale. Eventually we will support all the locales that are supported on the main site.

What are your long-term plans for this library?

Over the next few months, we plan to revamp and release the new JavaScript client library in phases with the following functionality:

1. Core: Authentication, authorization, Facebook Platform/Connect API calls, and publishing to the feed
2. XFBML/Widgets: UI markup, dynamic loading and events, widgets
3. Data: Data access abstractions

Today, we’re providing an alpha release of the Core module. As an early release, it doesn’t have all the features we intend to build, but we will be developing them incrementally over the next few months.