Facebook has published a JS SDK for some time, and "open graph" has been around for at least a year, permitting applications to post to users' newsfeeds (among other things) after the user grants permission. Timeline was announced at the Facebook developer conference in the summer of 2011, which is basically a new design for the profile that features information differently. Facebook is also rolling out new features to application developers to take advantage of new ways to group information on a Timeline profile, but they require users' granting new permissions to applications, when applications request it via a new dialog.

Specifically, a "publish_actions" permission can be requested through a new authentication dialog, that demonstrates various actions an application makes available, and it shows how the content will be aggregated. This is an improvement on posting every item to the news feed. The grouping itself is configurable and data can be more useful depending on how it is grouped. The Timeline stuff specifies three concepts:

• object
• action
• aggregation

These are all pretty straightforward concepts for most programmers, though it does require using Facebook's admin tools to create these things, which is not necessarily straightforward. I experienced a slew of problems in getting this set up. Some problems: I wasn't using a "verified" developer account (verify by SMS or by adding a credit card), developer account SMS verification never worked, misleading error messages masking real errors (oauth permission error was reported when in one case, the real issue was no "content aggregation" had been set up on my test app), a debugger tool that said the page incorrectly specified facebook meta tags (e.g. "og:type") despite the facebook social plugins (e.g. the "send" plugin, emails content to someone) working fine. Not a polished development experience.

After working through the issues, an application can present a "add to timeline" button for the user with XFBML, which can either prompt the user to both request authentication and grant permission, or just ask for the new "publish_actions" permission itself. When this is working on your application, there is a pretty good flow, and it is possible to authenticate and grant permissions without popping a second dialog, making for a better user experience. Make sure you are using the latest Facebook JS SDK code, there may be a beta/nightly type of alternative URL to point at (since the code is loaded from facebook).

Code suggestions:

• Could package the XFBML code in a jquery plugin.
• load the plugin async (dynamic script tag), needs to happen before parsing the XFBML on the page
• Make a general function to take an action, object, and url to handle your facebook timeline interaction

Some of the setup I needed:

• a facebook account with Timeline enabled. Timeline was not enabled as of this writing, but is possible to "turn on" for developer accounts.
• verified my account as a developer account by adding a credit card to my account. SMS verification never worked, the SMS message never arrived.
• create a test application with my test facebook app credentials
• establish (and keep open) an SSH tunnel so that facebook can call back into the local test facebook application

More information:

• I kept the Facebook app permissions screen open in one browser window, so that I could remove my test app to test the authentication and authorization flow. If I tried to pop the dialog and the app already had permission, it wouldn't open.