Inside Facebook

The new stream APIs that Facebook announced today appear to offer a rich level of data interaction between Facebook, applications, and external sites. So how does it actually work, and how do you go about implementing it?

The first step is to persuade your users to grant extended permissions to your application. Previously the extended permissions covered more abstract topics such as allowing an application to access a user’s data online (which may mean little to most users) or to allow e-mails to be sent (which users may be reluctant to grant). The stream, however, offers a lot more benefit to the end user and so could bring this feature of the Facebook Platform into more regular use.

Getting the special permission to be able to read a user’s stream data is as simple as persuading them to click on a link. The FBML tag is as follows:

<fb:prompt-permission perms=”read_stream”>Grant permission to read from my stream</fb:prompt-permission>

and can be styled as the developer wishes i.e. as a button, or possibly even a graphic. This pops up the dialogue box below, which not only describes what this means to the user but has a helpful illustration of the direction data moves in, and some example posts from the user’s own feed:

Although ideally (from a developer’s point of view) this would be the default setting and all applications could read from the stream once authorized – it is a possibility that this will be the case in the future – if given sufficient incentive to click on the link, users who start this process shouldn’t be too confused as to what they’re agreeing to.

Now you have all the permissions you need to read the stream, what can you pull back? So far, it looks like very little is off-limits. Not only links, posts and status messages are available but also feed stories from other applications – the first time this kind of cross-application data-sharing has been possible. I generated a story using the Living Social “Top 5″ application and immediately this item appeared in my stream.get API request, complete with links to all of the media in the story, it’s text, the name of the application and comments and “likes” from friends. In theory, I could take this feed story and re-present it in my own application, styled in a way of my own choosing.

As well as just pulling back all the most recent data, the stream can be queried on a number of data levels:

• The user the feed item belongs to.
• The user, or even Facebook Page, that generated the content. (The stream contains user and Page information and treats them equally.)
• The type of content, which may be an application story or link. Stories from only particular sources can be retrieved, allowing the generation of filters by application or content type
• Date and time information. Stream items can be queried between particular dates, or just retrieve the top 20, 50 or more

Once the call is made a large set of data is returned, including:

• The user the story appeared to
• The story content including links to files, attachments and images
• The publisher of the content (whether user or Page)
• Comments attached to the story (although only a selection are shown)
• The number of “likes”

There are a host of other data points transferred and this is certainly more complex than many of Facebook’s other feeds, although the documentation is relatively complete already. The data above, and more, could be put to a number of users including creating more subtle or sophisticated filters than Facebook offers, showing general feed content in applications, filtering the stream by application type, and of course to display the Facebook stream on external sites or in external desktop applications. The potential is here not just for existing Connect sites and Facebook applications but for a whole new set of applications to be developed.