From Facebook Developer Wiki

The Live Stream Box is a social widget that lets users visiting your site or application share activity and comments in real time. The Live Stream Box works best when you are running a real-time event, like live streaming video for concerts, speeches, or webcasts, live Web chats, webinars, mass-multiplayer games, and more.

The Live Stream Box lets users:

• Log in to your site using their Facebook accounts with Facebook Connect.
• Communicate and share with each other and their friends in real time at large scale (supporting millions of simultaneous users).
• View what their friends are saying as well as the general audience viewing the live stream.
• Comment on and "like" their friends' posts.
• Share their updates directly on their Facebook profile and in their friends home page Streams. Each story on Facebook includes a link back to your site (through a URL you specify).

If you want to let your users comment on an article or blog post, consider using the Comments Box instead.

[edit] Technical Notes

There are three ways to render a Live Stream Box:

• Using FBML inline on an application canvas page or application profile tab (using the fb:live-stream FBML tag)
• Using Facebook Connect and XFBML on your site (using the fb:live-stream XFBML tag)
• Using an IFrame on your site

The Live Stream Box can handle a very substantial load, supporting millions of simultaneous users. The information may move fast, so users will not necessarily see everything that gets posted and cannot page through all the history.

Content posted to the Live Stream Box is not archived and not accessible via any APIs. If you want to be able to retrieve content, or let your users comment on an article or blog post, consider using the Comments Box instead.

[edit] Adding a Live Stream Box to Your Site or IFrame Application

To add a Live Stream Box to your site, all you need to do is get a Facebook Platform API key, add a small file to your site, and add a few lines of code. No matter which method you choose to render the Live Stream Box (FBML, XFBML, IFrame), you need to do the following steps:

1. Go to http://www.facebook.com/developers/createapp.php to create a new application.
2. Enter the name of your site in the Application Name field, read and accept the Developer Terms of Service, then click Save Changes. The application name appears in your users' streams next to posts created through your Live Stream as "via <application name>".
3. On the Basic tab, keep all of the defaults and you should upload an Icon. This icon appears in Feed stories published on Facebook. Take note of the API Key, you'll need this shortly.
   Note: If you already have an API key for your Facebook Connect site or another Facebook social widget like the Fan Box, then you should use that API key instead.
4. On the Connect tab, set the Connect URL to your server so Facebook can verify the call is coming from you. This is also the page where users are directed if they click the "via <application name>" link from their streams.
   Note: If you're adding the Live Stream Box to a canvas page application, make sure the Connect URL points to your canvas page URL.
   
5. You should include a logo that appears in the Facebook Connect dialog when the user logs in to your Live Stream Box. Next to Facebook Connect Logo, click Change your Facebook Connect logo and browse to an image file. The logo can be up to 99 pixels wide by 22 pixels tall, and must be in JPG, GIF, or PNG format.
6. Click Save Changes.

Then read the section relevant to how you plan to render the Live Stream Box.

[edit] On FBML Canvas Pages

If you already have an FBML application on Facebook, you can easily integrate a Live Stream Box on your canvas pages if you want to host a Live Stream event within your application.

When you're configuring the Live Stream Box settings, make sure the Connect URL points to your canvas page URL (see above).

After you get a new application ID (you need a separate one for the Live Stream Box), add the fb:live-stream FBML tag to your canvas page. This tag takes the following parameters:

• event_app_id: This is the application ID from the application you just created above. You must specify either the application ID or the API key.
• apikey: The API key from the application you just created above (or are already using on your Facebook Connect site or with a Facebook social widget like the Fan Box). You must specify either the application ID or the API key.
• width: The width of the box in pixels. The width defaults to 450 pixels.
• height: The height of the box in pixels. The height defaults to 400 pixels.
• xid (optional): If you want to have multiple Live Stream Boxes on your canvas pages, specify a unique XID for each box. Specify xid=EVENT_NAME, where EVENT_NAME represents the event. EVENT_NAME can include only numbers, letters, and underscores. The default XID is xid=default.

For example:

[edit] On Facebook Connect Sites

If you have your own site where you want to implement a Live Stream Box, you need to add some JavaScript code to the page where you want the box to appear.

1. Download a cross-domain communication channel file, then upload it to the directory with the file that will reference the Live Stream Box. This file will allow your site and Facebook to send data back and forth.
2. Edit the HTML file where you plan to reference the Live Stream Box.
   1. Within the <html> tag, add this attribute: xmlns:fb="http://www.facebook.com/2008/fbml", as in:
      
      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:fb="http://www.facebook.com/2008/fbml">
      
      
   2. Next, add the following code to each file where you want a Live Stream Box to appear. Replace YOUR_API_KEY_HERE with the API key you received earlier (or are already using on your Facebook Connect site or with a Facebook social widget like the Fan Box), set the height and width for the box, and include the path to xd_receiver.htm.
      
      <script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script>
      <fb:live-stream width="<widthInPixels>" height="<heightInPixels>"></fb:live-stream>
      <script type="text/javascript"> FB.init("YOUR_API_KEY_HERE", "<path from web root>/xd_receiver.htm"); </script>
      
      Note: You can create multiple Live Stream Boxes to cover multiple events. Add xid="EVENT_NAME", specifying a name to uniquely identify the event (EVENT_NAME can include only numbers, letters, and underscores). The default XID is xid="default".
3. That's it! You've just installed your own Live Stream Box, now try it out!

Important: If you want to place a Live Stream Box on a page on your site that already references Facebook Connect (that is, the page contains one script that calls FeatureLoader.js.php and another that calls FB.init), then you must not reference these scripts again. You simply can just put in the fb:live-stream tag where you want the Live Stream Box to appear. As in:

Sample Live Stream Box File

Here's the entire content of a sample file containing a Live Stream Box:

[edit] In an IFrame

You can render the Live Stream Box in an IFrame on your site. Use an <iframe> tag, and include the following URL parameters with the IFrame source:

• app_id: This is the application ID from the application you just created above. Alternately, you can specify the API key (use the api_key parameter) that you received earlier or are already using on your Facebook Connect site or with a Facebook social widget like the Fan Box.
• width: The width of the box in pixels. The width defaults to 450 pixels.
• height: The height of the box in pixels. The height defaults to 400 pixels.
• xid (optional): If you want to have multiple Live Stream Boxes on your site, specify a unique XID for each box. Specify xid=EVENT_NAME, where EVENT_NAME represents the event. EVENT_NAME can include only numbers, letters, and underscores. The default XID is xid=default.
  Note: If you're using a new XID you must be logged in as the developer of your application to initialize the new XID. Otherwise, the Live Stream Box appears as a blank widget if it's not initialized.

It's also a good idea to specify a height and width of the IFrame that matches the dimensions of the Live Stream Box.

For example:

[edit] Publishing to Facebook

The Live Stream Box integrates with Facebook. When a user posts to your live stream, the content appears on the user's Facebook profile and in the streams of the user and the user's friends.

Users can comment on or "like" any posts made by their friends in the Live Stream Box. The comments and likes appear on the Friends tab in the Live Stream Box and in the users' streams on Facebook as well.

[edit] Administering the Live Stream Box

Once you deploy a Live Stream Box, it doesn't require any administration, other than banning disruptive or abusive users. Anyone listed as a developer of your Live Stream Box (on the Basic tab of the application settings editor in the Developer application) or listed as a widget moderator/administrator (on the Widgets tab in the application settings editor) can ban users from the Live Stream Box itself -- look for the Ban User link under a user's comment, where users would normally see the Comment and Like links.

Each Live Stream Box and xid stream must be loaded once by an application developer before it can be used by users.

[edit] Using the Live Stream Box across Different Locales

By default, the Live Stream Box only displays statuses from the same locale as the viewer and anyone using Facebook from an English (US) locale. You can specify one additional locale for viewers, regardless of their locale, by choosing the appropriate language from the Language menu in the Facebook Developer application.

For example, if you select German for your application's language, then anyone viewing the Live Stream Box can see posts from users in the German or English (US) locale. A user in the Spanish locale would see Spanish locale statuses in addition to English and German statuses, but they would not see a status from a user in a Japanese locale.

[edit] See Also

• fb:comments (XFBML)
• fb:comments (FBML)