From Facebook Developer Wiki

Contents 1 Using the Open Stream API 2 Prompting for Permission to Access Streams 2.1 About the read_stream Permission 2.2 About the publish_stream Permission 2.3 Streamlining Prompting for Permissions 2.4 Additional Notes about Permissions 3 Reading Data from the Stream 3.1 Reading a Stream Using stream.get 3.2 Reading a Stream Using FQL 3.3 Reading a Stream Using Activity Streams 4 Writing into a User's Stream 5 See Also

Using the Open Stream API

The stream is the flow of information on Facebook, which manifests itself on a user's home page as the News Feed and on the user's profile as the Wall. It represents the content a user shares with friends in a real-time setting. Initially the stream content appeared only on Facebook, and now with the Open Stream API, developers can connect to their users' streams and let their users read their streams wherever they want. This means that for the first time, you can build new user interfaces for the stream everywhere including Web, mobile, and desktop applications.

The stream API allows for reading and creating content. Thus, your applications can get users' stories, comments, and likes, and incorporate this data into your user experience. In addition, your applications can create content directly in your users' streams, and allow for the posting of comments and likes. Think of the stream API as having your own Publisher embedded in your application.

You can get stream activity in a number of ways:

• Through the stream API calls: stream.get and stream.getComments (if you want to return just comments from a user's stream)
• Through the stream, stream_filter, and comment FQL tables. (The comment table has a new indexed column, post_id.)
• Through an Atom feed using the open Activity Streams standard.

You can create content directly into a user's stream through the stream.publish call. This call is very flexible in terms of the content you can render, and also allows your application to update the user's status. You can also add or remove likes and comments to or from posts in a user's stream.

You don't have to create templates to publish content with stream.publish.

You can continue to use Feed forms to publish application stories to users' profiles. stream.publish is the streamlined, more robust alternative to API calls like status.set and links.post, while stream.get is the streamlined, more robust alternative to many Feed-related *.get calls like notes.get and links.get.

Prompting for Permission to Access Streams

Before you can interact with a user's stream, the user needs to grant your application either or both of these extended permissions: publish_stream and read_stream, depending upon what you plan to do.

About the read_stream Permission

The read_stream permission lets your application or site access a user's stream and display it. This includes all of the posts in a user's stream. You need an active session with the user to get this data.

About the publish_stream Permission

The publish_stream permission lets your application or site post content, comments, and likes to a user's profile and in the streams of the user's friends without prompting the user. Once you get the permission, you can publish to a user's stream with stream.publish automatically.

The stream.publish method is intended to be used in cases where Feed forms are not available or do not make sense in the natural workflow, such as:

• Mobile and desktop applications as well as applications where users are directly publishing to their streams, similar to the Facebook for Adobe AIR application.
• Publishing to the stream when a user is not using the application.
• Your application performs an action repeatedly, making the user experience awkward if Feed forms disrupt the application flow. For example, syncing a user’s status from another site with Facebook.

Streamlining Prompting for Permissions

Since the stream APIs simplify the ways in which you have your users publish content to their profiles, it makes sense to have a more streamlined permissions model to match.

Instead of prompting your users for the status_update, photo_upload, video_upload, create_note, and share_item extended permissions, you can simply prompt them for the publish_stream extended permission, and that single permission lets your users update their statuses, upload photos and videos, write notes, and share links all from your application or site. You'd still use existing API calls for photos, videos, notes, and links, but you can use stream.publish to let users publish posts and statuses to their profiles.

To make it easier for you to ask the user for extended permissions, you can now send a comma-separated string of permissions when you prompt for permissions. A series of Connect-style dialogs appears, allowing the user to accept or reject each permission. You can pass the comma-separated string of permissions using:

• The fb:prompt-permission tag
• FB.Connect.showPermissionDialog
• The promptpermission attribute in a form

Also, the FB.Connect.showPermissionDialog callback function no longer takes a boolean parameter. The callback now is of type CallbackWithObject, and takes one string parameter. On success, the callback returns a string with a comma separated list of the permissions the user granted. On failure, or if the user canceled the permissions dialog, null gets returned.

Additional Notes about Permissions

The user has the option to revoke any extended permission at any time, at which point your application or site won't be able to get or publish to the stream.

If a user has already granted your application other related extended permissions, such as status_update, photo_upload, video_upload, create_note, and share_item, your application won't necessarily have to prompt the user for the publish_feed permission to perform that same function using the appropriate API calls, like status.set or video.upload.

For example, if your application lets your users write notes and a user has already granted your application the note_create permission, you don't need to prompt that user for the publish_stream permission in order for the user to write a note within your application. However, if you expanded the scope of your application such that you allow your users to post links, then you'd have to prompt your users for either the publish_stream permission or the share_item permission before your users can post links to their streams.

Reading Data from the Stream

Facebook gives you the power to read users' streams, including content from both the News Feed and the Wall. You can then display the stream's contents in your application or on your site. Reading the stream gives you all the content of a user's stream, including posts from the user and the user's friends, regardless of privacy settings of the posts.

To read a user's stream, you need the read_stream extended permission. You get the stream using the stream.get API call, FQL query, and Activity Streams.

The following API calls are useful for getting data from users' streams:

• stream.get (PHP) and stream_get (JavaScript Client Library)
• stream.getComments (PHP) and stream_getComments (JavaScript Client Library)
• stream.getFilters (PHP) and stream_getFilters (JavaScript Client Library)

The following FQL tables are useful for retrieving stream data:

• stream, which lets you query and retrieve the complete stream for a user.
• profile, which returns specific user or Page information, like name, link, profile picture, and type (user or Page).
• connection, which lets you determine the users and Pages to whom a given user is connected (as friend or fan/supporter).
• stream_filter, which returns a filtered view of the stream based on a user's filters.

The comment FQL table now has a post_id column. Use this for determining the post ID for a comment on that post. See also stream.getComments.

In addition, you can use the open Activity Streams standard to read streams.

Content you display from reading a user's stream is subject to Facebook caching policies.

Reading a Stream Using stream.get

You can get all the contents of a user's stream by calling stream.get with an active session.

Reading a Stream Using FQL

You can make an FQL query on the stream FQL table to get a user's stream.

You can make an FQL query on the stream_filter FQL table, passing your application ID and a type set to application to get posts from only your application in a user's stream.

If you make the query without an active session, you must pass a viewer_id so you know whose stream you are retrieving.

If you make the query with a session, you'll get all posts from that user's stream regardless of privacy settings on those posts.

Reading a Stream Using Activity Streams

You can use the Activity Streams feed with an active session to get all posts in a user's stream regardless of the privacy settings on those posts. For information, read Using Activity Streams.

Writing into a User's Stream

Once the user grants your application or site the publish_stream permission, you can let your user post content back into his or her stream from your application or site.

Users can post content in a number of ways:

• stream.publish -- which lets users publish to their streams from your application or site.
• FB.Connect.streamPublish -- which lets users publish to their streams from your Facebook Connect sites and applications using the JavaScript Client Library.
• Facebook.streamPublish, an FBJS call which lets users publish to their streams from FBML applications.
• stream.addComment -- which lets users add comments to posts in their streams from your application or site.
• stream.addLike-- which lets users like posts in their streams from your application or site.
• stream.remove-- which lets users remove posts from their streams from your application or site.
• stream.removeLike -- which lets users remove their likes on posts in their streams from your application or site.
• stream.removeComment-- which lets users remove their comments on posts in their streams from your application or site.

See Also

You can read the Stream Release Notes for more background information about streams.