How to Post to Facebook's "Stream" using Facebook Connect and XFBML

For my day job, I’ve been developing a facebook application to coincide with its annual SpayDay event. Developing the application has caused several headaches, but once I realized that the majority of the facebook integration wouldn’t happen from the Facebook Developer Toolkit (an ASP.NET Facebook Development Framework), and instead from JavaScript-based XFBML, life got a lot easier. Specifically, the application that I’m developing is an ASP.NET-based iframe application, which probably isn’t the best choice for a facebook application, but it’s what I’m familiar with, so it works.

Facebook recently announced that they are streamlining their primary integration points to the stream (users’ facebook wall posts) and to the inbox. As of writing this article, the inbox API isn’t out yet, but the StreamPublish function (the function that everyone is supposed to use to write to people’s streams and facebook walls), has been out for a while. For the purpose of this demonstration, we’ll be writing an XFBML function using FacebookConnect. Typically this would apply to IFrame Applications on Facebook.

Here’s how to implement posting to a Facebook user’s wall/stream using Facebook Connect.

First, there some prerequisites to place on your page before you can use XFMBL. Basically, it’s a couple of scripts that you need to reference which process the FBML and pass data back and forth to Facebook using a cross-domain receiver. You can learn how to add those scripts to your page here.

The next thing to do is to write a function that will call the XFBML, which will look something like this. Note that the specific text I used is for the SpayDay application, but it’s pretty easy to start making modifications to specific parts of the post.

    <script type="text/javascript">

        //post story function
        function PostStory() {

            //init facebook
            FB_RequireFeatures(["Connect"], function() {

                FB.Facebook.init('PLACE_YOUR_API_KEY_HERE', 'xd_receiver.htm');

                FB.ensureInit(function() {

                    var message = 'I support Bill The Aircraft Carrier in the SpayDay Online Photo Contest! Will you vote for Bill The Aircraft Carrier?';
                    var attachment = {
                        'name': 'Vote for Bill The Aircraft Carrier!',
                        'href': 'http://spayday.factor360.com/contest.html?page=viewInd&id=48082&contestId=2', 'caption': '{*actor*} supports Bill The Aircraft Carrier in the SpayDay Online Photo Contest!',
                        'description': 'Bill The Aircraft Carrier`s favorite thing to do is fight the Klingons, but sometimes gets in trouble because he/she likes to fight the Klingons. Bill The Aircraft Carrier makes me smile because... he has spock-like ears.',
                        "media": [{ "type": "image", "src": "http://spayday.factor360.com/calendar_contest/images/69839_1.jpg", "href": "http://spayday.factor360.com/contest.html?page=viewInd&id=48082&contestId=2"}]
                    };
                    var action_links = [{ 'text': 'Vote for Bill The Aircraft Carrier!', 'href': 'http://spayday.factor360.com/contest.html?page=viewInd&id=48082&contestId=2'}];
                    FB.Connect.streamPublish(message, attachment, action_links, null, "Share your support for Bill The Aircraft Carrier!", callback, false, null);
                });
            });
            function callback(post_id, exception) {
                alert('Wall Post Complete');
            }
}
</script>

A Few Notes: 

The message variable is the text box that the user can modify. More often than not this will be left blank, but you can give the user a ‘suggestion’ as to what to right.
The ‘name’ field in the attachment is the title of the hyperlink, the ‘href’ field is destination URL.
the ‘caption’ field is basically a description for the link and the ‘description’ field is an extended description of the link.
The media field is used to add images and other media types. The example I have just loads one image, but you can also attach things such as video (look on Facebook’s Wiki for details)
The ‘Action Links’ are calls for users to perform a specific action, in our case, voting for the entry. These typically show up on the bottom of stories in the feed.
the “False” setting in the streamPublish function (second to last field), indicates that the pop-up should occur before the story is posted. If you want to automatically post the story and have extended permissions to posts to the users wall, you can set this to true and it will post the story without popup.
The “callback” function occurs after the wall post is complete. Typically you would use this to provide the user a notice, something along the lines of “Thanks for posting a story”

Now that we have our function written, we simply need to call it. You can use hat with a plain old hyperlink:
<a href=’#‘ onclick=‘PostStory(); return false;’>Post a story!</a>
That’s pretty much it. Once you get the hang of a few different XFBML functions, the rest come pretty easily. You should see something like this if all is well with your code:

One debugging hint. If nothing pops up at wall and you can’t get ANY XFBML to work, make sure to set your Facebook Connect URL to the same URL as your Facebook Application in your Application’s settings in the Developer Application.