Facebook Developers

As part of our ongoing effort to improve communication with our developer community, we offer you the latest monthly roundup of the announcements, new features, and updates to Facebook Platform that occurred during August, 2009.

New Features

• Access your users' Inbox messages and notifications with the Inbox and Notifications APIs.
• Use Facebook Connect for simpler desktop application authorization.

Updates

• We enhanced the Open Stream API. Now Facebook Connect sites and IFrame and FBJS applications can publish to users' streams with two new API calls, a JavaScript version of stream.publish and an FBJS version. When using any stream.publish method to post application content, your application gets attribution in the post. And, you can now retrieve a Facebook Page's stream using stream.get or the stream FQL table, and you can prompt a user to grant extended permissions to any Facebook Page for which the user is an admin.
• We updated the design of Facebook Share. If you own or run a website, you can use Facebook Share so your users can easily share content from your site on Facebook.
• Final reminder for stream.get and stream FQL table: As we announced on May 19th, 2009, we're deprecating the posts field of the comments array returned by stream.get and the stream FQL table in favor of its replacement, comment_list, for proper XML serialization. We stopped returning the 'posts' field on August 25, 2009.
• Facebook Platform code face-lift: We're refactoring the Platform API and updating the JavaScript Client Library. The Platform API refactoring requires no changes on your part, while the JavaScript library update involves a new, optional feature loader and better organizing of features into distinct components within the library.
• We corrected the count of total applications users. This number isn't public facing, as it appears only on your application's Insights page.

Announcements

• Learn about our plans for improving user privacy on Platform.
• In order to improve site performance through better load balancing, we've begun to gradually serve more canvas page traffic from our east coast data center.

Articles/Videos

• Watch Facebook CEO Mark Zuckerberg address the Facebook Developer Garage São Paulo: here are the first video and the second video.

Keep an eye on this blog (or subscribe to the RSS feed), the Platform Status Feed (or subscribe to its RSS feed), and the weekly Push Changes articles for announcements, changes, and other important bulletins.

As always, we appreciate your continued feedback in our Developer Forum -- let us know how we can reach and communicate with you even better.

Facebook Share is one of the most powerful and simple ways for users to share articles, pages, video, or Flash content from your site with their friends on Facebook. Over 1 billion pieces of content are shared each week on Facebook, and many of those are links shared using Facebook Share. Today we're rolling out a new design for the Facebook Share dialog to make it more consistent with other forms of sharing on Facebook.

The new dialog includes all of the key features of Facebook Share -- users can post a link to their profile or send it in a message to just a few friends, choose an image to include, and add a comment. We expect the new design will increase the amount of content shared as well as the traffic back to your sites.

Enabling Users to Share Content from Your Site

We offer two ways for you to implement sharing features on your site:

• Share links with the Share button - You can add the Share button to your website with just a couple lines of code from our Share Partners page.
• FB.Connect.streamPublish Feed form - A few weeks ago, we announced a new dialog that enables you to invite users to publish specific stories to their profiles. An example would be publishing a story like "[User] commented on this post." For more examples and documentation, please check out the Developer Wiki.

In addition, users can install the Share bookmarklet directly into their browsers.

Once you implement Facebook Share or FB.Connect.streamPublish, you might look into Facebook Connect to add even more social features to your site.

We announced this morning plans to further improve users' control over their information. These changes are a result of our work with the Office of the Privacy Commissioner of Canada, which has spent more than a year reviewing our privacy policies. We see this as an opportunity to do something we think is important, affirming users' trust in Platform by giving them more informed and detailed privacy control.

It is important for developers to have access to information, but we want to balance that with transparency and control for users. We are working on making enhancements to our API to accomplish this objective. We have committed to making these enhancements over the next twelve months, and anticipate a lengthy beta period including opportunities for you to provide input, multiple blog posts, and updated documentation delivered well ahead of time. Understanding that this will likely require modifications to your code base, we want to give you the earliest heads up that these enhancements are on our road map.

We are still very much in the conceptual stages of development and many of the details are yet to be determined. However, we've committed to requiring developers to specify in advance what categories of user data they will need. When users authorize an application, they will have the opportunity to opt out of giving certain pieces of information. There may be some fields that, at minimum, are necessary for the application to function. We will make it clear that the user must authorize the required fields in order to use the application. We also anticipate that users will need to opt in to giving applications access to their friends' data.

A significant part of our roll out plan will involve educating users about why they should allow applications access to their information and their friends'. We plan on providing users with examples of ways applications utilize their data to create great social experiences. This should result in better informed users who are more eager to engage with applications on Facebook. We believe these changes will contribute to the overall health of our ecosystem, and appreciate your support as we continue to make Facebook Platform even better.

We're continuously looking for ways to open core Facebook experiences to developers for innovation. Today we set our focus on two communication channels: notifications and the Facebook Inbox. We're excited to release two new APIs that will let your applications access your users' inboxes and notifications in a structured manner. In addition, you can make your stream applications available as attachments for Facebook messages so that users can more easily share application content with friends.

Inbox API

Last week we announced an update to the Open Stream API to allow integration of Page streams with applications. Today we are releasing the Inbox API so you can provide users with even more opportunities to interact with rich Facebook features within your applications. For example, a desktop application geared toward small business owners could enable users to check their company's Page stream, as well as read messages and receive notifications, all from their desktop.

The Inbox API allows you to access your users' messages, once they grant your application the new read_mailbox extended permission. This lets your applications provide an interface for users to view their messages. For example, your application could pop up an alert when the user receives a new message.

To access information about a user's Inbox, you'll query any of three new FQL tables:

• mailbox_folder: This table gives you information about a user's folders; currently all users have three folders: Messages (inbox), Sent (outbox), and Updates.
• thread: This table gives you information about specific threads. For example, you can get information about recipients of a thread, whether a group or event sent the thread, when it was last updated, the subject, whether it is currently unread, and more.
• message: This table allows you to get information about each message in a thread. You can get information about who wrote the message, the content of the message and also information about the attachment to the message, if it exists, in the same format as attachments are returned in the stream.

While we currently don't allow applications to send messages through this API, we're always thinking about new functionality to offer through Facebook Platform.

To get started, as a developer you can access the Inbox APIs via the read_mailbox permission in order to develop and test your application. To launch your application to all users, please apply to the Inbox API whitelist here.

Application Attachments for Facebook Messages

We've simplified the way you can create application attachments that users can share with their friends through Facebook messages. This feature works only with the new Inbox, which a number of users have been testing. The updated Inbox will launch to all users in the coming weeks.

The new Inbox incorporates the same Publisher used to publish to the streams on the home page and profiles. We've enhanced the Publisher so it no longer requires you to create template bundles -- you can now use the simplified attachment model that stream.publish uses. As we roll out the new Inbox over the next few weeks, we'll deprecate the old message attachment process.

To integrate your applications into the new Inbox:

1. Create a Publisher endpoint and enter its URL as the Attachment v2 Callback URL you specify on the Advanced tab in your application settings.
2. In your Publisher integration, specify "attachment" for the content parameter, instead of "feed".
3. Test your attachments today with your test accounts on www.beta.facebook.com.

We're still supporting existing Publisher integrations that use the "feed" content type, but you should find the flexibility of stream attachments easier to use, as they're more universal throughout Facebook.

Notifications API

The notifications API lets your applications retrieve your users’ notifications to use within your application. We've created a notification FQL table and two new API methods, notifications.getList and notifications.markRead, that let you retrieve structured information about notifications and mark them as read.

The new FQL table contains the same information used to generate the instant notifications you see on the Facebook website. We've opened up that data so now you can create better experiences for your users. For example, you can now create new desktop experiences integrating notifications, letting your users stay in touch with their friends and other connections. For example, Facebook for Adobe AIR now uses the notifications API and Inbox API to display notifications and new message alerts alongside the application window.

As always, we're looking forward to see what you do with these features, and we welcome your feedback in the Developer Forum.

In a recent data review, we discovered a bug that was either under-reporting or over-reporting the total number of users who had authorized some Platform applications. We're correcting this number today, so you might see a different number of total users reported on your application's Insights page. This won't change the number of monthly active users reported for any application, which is the primary user count we publicize.

We've long believed that the true reflection of your application's success is best gauged by user engagement, which is why the monthly active user count is the metric we publicly display in search results and in the Application Directory. There were no reporting errors for monthly and daily active user totals (MAUs and DAUs, respectively). Both active user totals are determined daily; MAUs include users active within the 30 days prior to today, and DAUs include users active within the past 24 hours. Thus you always have the most current and accurate totals for user engagement with your application.

The total user count was an informational number you could use to track how many users have authorized your application. This number only appears on your Insights page, and is not public facing.

The Insights page contains a wealth of information and statistics about your application. You should check your Insights page often. Go to http://www.facebook.com/business/insights/app.php?id=YOUR_APP_ID

We always welcome your feedback. Please share it on the Developer Forum.

We're excited to announce that we've simplified the application authorization flow for desktop applications. The new authorization flow uses Facebook Connect and we recommend you use this system moving forward.

What's Changed

We made a few notable changes to the desktop authorization process. They include:

• No redirecting the user to a browser. Other than the Facebook Connect login and permission dialogs, you don't need to redirect a user to a browser to log in to your desktop application and grant extended permissions.
• Easier prompting for permissions. All you have to do is direct the user to a URL and prompt the user for the permissions your application requires. You can prompt for permission wherever appropriate in your application flow, or at login. A series of dialogs appears, one for each permission, and the user is free to grant them one by one.
• Session data gets returned automatically. In order to keep your application secure, we recommend you use the session secret Facebook returns on authorization and use that to make API requests, and not the application secret. You no longer need to create an auth token and create a session using that token. Sessions still last 24 hours.

You can read about it on the Developer Wiki. To see it in action, download Facebook for Adobe AIR, an open source desktop application that uses Facebook Connect for authorization. Or check out the source code.

Please share your feedback in our Developer Forum.

We launched the Open Stream API in April to give developers access to a core Facebook experience, and the ability publish to users' streams. The Open Stream API supports several different publishing methods as well as the Atom-based Activity Streams framework for reading the stream.

Today, we are announcing updates to the Open API Stream, including:

• Simpler JavaScript methods for publishing: Use the new stream.publish method in JavaScript to publish stories from your website or application.
• Facebook Pages support: Access the stream for Facebook Pages without a session and publish to the stream on behalf of a Page.
• Attribution: The name of your application will appear in the stream for stories published with the Open Stream API, allowing for greater visibility for applications in stream stories.

New JavaScript Methods for Publishing

With the launch of the Open Stream API, we created stream.publish, a method to simplify publishing into a user’s stream, and replacing the previous versions that relied on Feed templates. To publish stories using this method server-side, a user must first grant the publish_stream permission to your application to publish on the user’s behalf. You don't need any other permissions or approvals to use this method.

Now, we’ve created a JavaScript version of stream.publish (also available via FBJS as Facebook.streamPublish) which you can use at any time from your websites or applications. This method will always display a Feed form for the user to confirm publishing the story, unless the user has granted the publish_stream permission.

You can use these JavaScript methods from any website as a simple widget to prompt a user to publish a story even if they are not currently logged in to Facebook. They will be prompted to sign in to Facebook and then publish the story. This method can be used on any website with or without other Facebook Connect features, and will not prompt a user to Connect their accounts to your website.

Facebook Pages Support

With today's announcement, you can now access the full stream from Facebook Pages that publish posts to their streams. Using stream.get or the stream FQL table, you can access any data from Facebook Pages using the Page ID as the source ID. You don't need an active session to access a Page's stream.

In addition, we created a way for applications to publish to the stream on behalf of a Page. Once a Page admin grants permission to the application for that Page, your application can request the publish_stream permission for the Page by passing a new special parameter when you prompt for the permission. This enables a profile selector in the permission dialog. Your application can now post stories on behalf of the Page using any of the stream.publish calls just like it would for a user. You can do this through any the methods described for extended permissions including JavaScript (showPermissionDialog) or directly targeting the prompt_permissions.php URL; we'll describe the new parameters in these documents.

Attribution

For every story that gets published using any stream.publish method (the API method or either new JavaScript method listed above), we'll display the name of the application with a link that will direct to the application profile page. This feature will help users better identify from where stories are published, and more easily discover the applications their friends use.

If you are using any stream.publish method already, you don't have to make any changes. If you are using other Feed methods such as FB.Connect.showFeedDialog, feed.publishUserAction, or status.set, we recommend considering stream.publish to take advantage of this new feature. You should also review your application’s profile page to make sure it effectively represents your application or website and links to the right destination.

As always, we welcome your feedback in the Developer Forum. We can't wait to see how you'll publish into users' and Pages' streams now.

We're at the Facebook Developer Garage São Paulo today and hope you'll join us to hear a few words from Facebook CEO, Mark Zuckerberg.

Live video by Ustream

Tune in at 1:30 PM PST to watch the event live.

Platform events were mostly focused on the Developer Garage program this month. The Facebook Developer Garage program serves as a forum to share new ideas with developers and find partners like you.

At the Facebook Developer Garage Ireland, 150 developers focused on Facebook Connect and app demonstrations. Facebook’s Colm Long gave more insight into Facebook ads and the impressive growth figures in Ireland.

In nearby London, over 100 developers examined case studies about Facebook Pages and shared insight into how major television shows are using Facebook Pages to share content. They also discussed how to best leverage Facebook applications on Pages.

To the east in Pune, India, 150 developers gathered to learn about Facebook Platform and Facebook Connect from Facebook Engineer Ruchi Sanghvi. These entrepreneurs and developers brainstormed how they could create apps and fill niches specifically for the Indian market.

If you'd like to host a Developer Garage in your region, please see our Developer Wiki to learn more about the program or check out the Platform Page to find more Garages near you.

We look forward to seeing you at a Facebook event soon!