How to use FB.Connect.streamPublish()

Do you like this story?

Please note: This guide is dated and I would recommend using the new Facebook Javascript API for this functionality. Check out this guide on the Facebook Developer site.

I have spent countless hours searching the Developer forums and reading over the wiki and haven't found a single, all-encompassing source that describes how to properly use FB.Connect.streamPublish(). This article is geared towards iFrame applications, but the same methods are used for external web sites using Facebook Connect. Also, if you own a web design company, please take a minute and add it to The Web Company Directory for free!

First, it is extremely important to have the proper connect settings.

1. Connect URL

Click the Connect tab in your application's settings, and set the Connect URL to your site's address with no ending / (i.e. http://www.ugadevelopers.com/frmatch).

(iFrame apps: Also ensure that you have set your Bookmark URL equal to your Canvas URL: http://apps.facebook.com/<yourapp>)

2. Cross-Domain Communication Channel

Next, you need to set up a cross-domain communcation channel so your Connect calls can send/receive info to FB. Enter this into a file and save it as xd_receiver.htm:


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
 <title>Cross-Domain Receiver Page</title>
</head>
<body>
 <script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/XdCommReceiver.js?2" type="text/javascript"></script>
</body>
</html>

Save this file into the same directory as your application. I saved it in the /frmatch/ directory.

3. Set up your page to make Connect calls.

In the file you are trying to make Connect calls in, you need the following code segments in the correct place:

3a. <html> tag

First, you have to include some special parameters in your <html> tag to let the browser know how to render the XML:


<html xmlns="http://www.w3.org/1999/xhtml" xmlns:fb="http://www.facebook.com/2008/fbml">

3b. FeatureLoader Javascript

Next, you need to include the FeatureLoader Javascript, which is responsible for loading the features necessary to make certain calls. (Note: You must place this line directly below the <body> tag!)




<body><script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script>

3c. streamPublish() call

Finally, we are ready to make the streamPublish() call. Here is a barebones script to test and make sure that everything is working correctly (don't forget to change to your api key):


<script type="text/javascript">
function publish() {
 FB_RequireFeatures(["Connect"], function() {
   FB.init('xxxxxxxxxx', 'xd_receiver.htm');
   FB.ensureInit(function() {
     FB.Connect.streamPublish();
   });
 });
}
</script>
<p>Stream Publish Test</p>
<a href="#" onclick="publish(); return false;">Post a story</a>

3d. Pop up dialog on window load

To pop up the feed dialog when the page loads (i.e. user lands on a high scores page and you present them a dialog to publish their high score), simply add the following script after the one above:


<script type="text/javascript">
window.onload = publish;
</script>

3e. streamPublish() with additional content

I assume most people want to display some content that is relevant to their app. Here is an example of attaching an image and a message to the post:



<script type="text/javascript">
 function publish() {
   var attachment = {     'name':'FriendMatch',     'href':'http://apps.facebook.com/frmatch',     'caption':'{*actor*} is playing FriendMatch!',     'media':[{       'type':'image',       'src':'http://www.ugadevelopers.com/frmatch/tile.png',       'href':'http://apps.facebook.com/frmatch/'     }]};       var action_links = [{'text':'Match Friends','href':'http://apps.facebook.com/frmatch'}];
   FB_RequireFeatures(["Connect"], function() {       FB.init('xxxxxxxxxx', 'xd_receiver.htm');         FB.ensureInit(function() {             FB.Connect.streamPublish('', attachment, action_links);           });       });   }
</script>