On November 6th, 2007, Facebook launched a series of new tools to help advertisers target the 54 million people now regularly using their site. They're still throwing around a 3% weekly growth rate and have a target of 60 million active users by the end of the year, so it's not hard to picture the day in the not-so-distant future when hospitals Facebook babies before handing them over and the little bundle of joy comes with a neural implant that pokes their parental units when the diaper is full.

The new tools round out the Facebook Business offerings to an even six:

             
• Social Ads
             
• Pages
             
• Beacon
             
• Insights
             
• Platform
             
• Polls

Platform and Polls are old news to anyone following the company, so the really interesting news is in the other four. All of them are very much interlinked, so that you create a Page for your brand or product, advertise it through Social Ads to a very targeted market, learn about your success through Insights, and connect to your off-Facebook (off-Book?) service via Beacon, build custom apps for your Page on Platform, and learn about your users through Polls. It's a marketer's dream, but what does it mean for you as a user? The web is somewhat up in arms about Beacon particularly because it just stinks of privacy violations, at least if you care about things like companies tracking your every move online. This post is going to dig deep in Beacon and see what makes it tick from a purely technical perspective, but we'd be happy to do a follow-up post about the ethical question if there's enough interest. Leave a comment and let us know!

Pinging Beacon

This post is an in-depth look at Beacon, and is broken down into a few sections to make it easier for you to navigate:

• Beacon in a Nutshell: an overview of Beacon and a visual tour of the user interface elements
• Beacon from 10,000 Feet: a look at the technology behind Beacon from way up high. Read this if you don't want the finer details but do want an idea of how it works.
• Blocking Beacon: if you're concerned about privacy and want to stop Beacon, check this part out.
• Walking through the Code: this is the section for you if you're the type of person who loves reading code listings and wants to know exactly what makes it tick.

Beacon in a Nutshell

Here's what Facebook has to say:

Allow your customers to share with their friends the actions they take on your website. For user actions you define, Facebook Beacon will publish a story in the user's profile and to friends' News Feeds with a link back to your site.

What that means in real terms, is that you can add a recipe to your recipe box on Epicurious, and you'll get a very familiar looking Facebook pop-up in the bottom right corner of your window letting you know that your new recipe is being sent to your news feed:

If you do nothing, you have effectively opted-in and you have consented for the item to be published (i.e.: Facebook will assume your consent to publish the content). The window will disappear eventually, and the next time you log into Facebook, you'll see a notice like this one at the top of your homepage:

If you go to your Profile page, the items will appear mixed in with everything else in you mini-feed:

You'll notice that those two screen captures show different recipes being added, which is because Beacon isn't entirely without issues. Although I've been playing with it for a few hours now, items about Epicurious recipes stopped being added to my feed just after 7:30pm. There may be some internal limitations applied by the algorithm to stop feeds from being overloaded with actions from any one site, or it might just be broken :). The help page on Epicurious explains that they are sending four types of actions to Facebook:

             
1. Rate a recipe
            
2. Review a recipe
            
3. Add a recipe to your Recipe Box
            
4. Register on Epicurious

Encounters with Beacon are slowly starting to be reported on other sites as well. A post from yesterday on Groundswell documents a Close encounter with Facebook Beacon in which Charlene Li (Vice President, Principal Analyst for Forrester Research) had her first run-in on Overstock.com. In her post, she explains how she bought a coffee table from that site and was surprised to discover, when she logged into Facebook later that week, that there was a notice at the top of her page about the purchase:

Charlene should have been shown the pop-up window as well but she might have missed it or something might have failed to show it while she was on Overstock (there's a slight delay before it pops up, so it's possible that she navigated away from the page or closed the window before she saw it). It's unfortunate that it didn't work as advertised because, as she says:

The biggest problem is the lack of transparency. Facebook is right in that I would really like to have some things that I do on third party sites to conveniently appear in newsfeed, e.g. events I'm attending from Evite or eBay/craigslist listings so that my friends know about them. That's the promise of Beacon. But I need to be in control and not get blindsided as I did in the example above. I was seriously wigged out, but wouldn't have been if Overstock had simply told me that they were inserting a Facebook Beacon and given me the opportunity at that time to opt-in to Beacon.

As I mentioned above, this isn't a post about the privacy or security concerns of Beacon (though it will address some of them below). There's some pretty neat web technology at play which we thought would interest our more technical readers, and so, just like we used to do with Dad's calculator we're going to take Beacon apart and put it back together again (hopefully in one piece – sorry Dad!).

Beacon from 10,000 Feet

That basically wraps up our tour of how Beacon does what it does. It's a fairly long explanation, so here's a quick summary:

            
1. The partner site page includes the beacon.js file, sets a

   <meta>

   tag with a name, and then calls Facebook.publish_action.
            
2. Facebook.publish_action builds a query_params object and then passes it to Facebook._send_request.
            
3. Facebook._send_request dynamically generates an

   <iframe>

   which loads the URL http://www.facebook.com/beacon/auth_iframe.php and passes the query_params. At this point, Facebook now knows about the news feed item whether you choose to publish it or not.
            
4. The

   <iframe>

   loads a facebook_helper.html file, which lives on the partner site, and which contains a call to Facebook.process_message_from_helper.
            
5. Facebook.process_message_from_helper parses a call to Facebook._perform_action from its own query_string and calls it.
            
6. Facebook._perform_action dynamically creates the toast pop-up and displays it in the bottom right corner of the window.
            
7. The user is given the choice of cancelling the publication (i.e.: opting-out), which will cause the item not to appear in their news feed.

And there you go! A very clever series of steps to allow for a very simple integration by partners and a neat side-step of the Cross-site Scripting security features in modern browsers.

Blocking Beacon

Those of you wearing tin foil hats (or hats at all, really), are probably wondering how you can block this nefarious beast from spreading all of your secrets. You've got a few options:

• If you're not worried about Facebook knowing what you do but are worried about your friends finding out, you can go into the External Websites area of your Privacy settings and set specific sites to never publish. They'll only show up after you've triggered them the first time, so the list will only contain sites you've already visited which are Beacon-enabled.
            
• If you're worried about Facebook and you're friends knowing what you do on other sites, make sure you don't browse other sites while you're logged into Facebook. When you add a recipe to your recipe box and aren't logged in, a request is still made for the beacon.js file and gets as far as creating the

  <iframe>

  and loading auth_iframe in it, but that page now returns "no user" and the process stops.
            
• If you're paranoid about the entire process (or don't trust yourself to always log out of Facebook before browsing other sites), and you just want to make sure that nothing gets through, and you're using Firefox, follow Nate Weiner's excellent instructions in his Block Facebook Beacon post (basically, install the BlockSite add-on and add www.facebook.com/beacon/* and facebook.com/beacon/* to the list). If you're running InternetExplorer, you can try following these instructions to add the same two URLs to your restricted zone, but your life would really be much improved by downloading Firefox so I'd recommend you do that instead. UPDATE: we've confirmed that the exceptionally useful AdBlockPlus for Firefox will also block Beacon if you add a pattern for http://*facebook.com/beacon* to the list of filters. The script tag embed for the beacon.js file gets blocked which prevents the rest of the app from working. Note that you can set ABP to be disabled for certain sites (a virtual necessity if you use them often and they have heavy Flash requirements), which will in turn allow Beacon to work.
  

Walking Through the Code

IMPORTANT NOTE: All of the code shown here is copyright and all rights reserved and please-don't-sue-us owned by the respective parties who wrote and publish it. It was not disassembled for profit and we used only publicly available free tools (Firefox with the FireBug and TamperData Add-Ons installed) and source which was available through standard web protocols.

It has traditionally been very difficult to connect two websites together and exchange information between them without building complex backend integrations. Sure, they could have built Beacon by implementing a web service in which the third party servers (like Epicurious) would contact the Facebook services through an entirely backend channel whenever I did a certain something (like add a recipe to my recipe box), but that would have meant asking partners to invest some fairly serious engineering effort in order to support it, and the opportunity to display a fun pop-up window to allow me to opt-out would have been gone. Instead, Facebook followed the route of having partners embed a JavaScript file on their site, and make a simple JavaScript call to populate the item. Let's take a look at an example:

I'm a big fan of risotto – so big, in fact, that one of the reasons I married my wife was to get better access to her Risotto Milanese. I can't think of anything I'd really rather have for breakfast, so we're going to use a recipe for Breakfast Risotto as our example (you should load that page in another tab so that you can flip back and forth).

If you take a look at the source and search for Facebook, you'll find two entries. The first is on line 133 and sets up the name of this item for the news feed entry:

<meta name="facebook_label" content="Breakfast Risotto Recipe">

The second is on line 167 and actually pulls in the Facebook JavaScript file:

<script type="text/javascript" src="http://facebook.com/beacon/beacon.js.php?source=5194643289"></script>

The source ID (5194643289) identifies Epicurious and corresponds to a list maintained internally by Facebook, which allows them to validate sources. You can actually load that file directly and you'll find a suprisingly well formatted JavaScript class called window.Facebook. We'll dig into it a little bit later on, but the first method deserves mention all by itself, entirely based on its name:

write_awesome : function(url) {
             return '';
},

The two lines we're particularly interested in on the Epicurious page have to do with adding this recipe to our recipe box, and you'll find them on lines 1195 and 1197:

<a href="javascript:void(0);" id="addRecipeButton">Save To Recipe Box</a>
<script type="text/javascript">new LoginRequiredLink('240748',
                'addRecipeButton',
                '/user/recipebox/save?id=240748&returnto=/recipes/food/views/240748',
                'recipeBox',
                'recipeBox');</script>

For all intents and purposes, this has nothing to do with Beacon and basically just rewrites the addRecipeButton link to point to the right URL for saving it if you're logged in (note: a more modern approach would be to use Ajax to send a message to the server to save this recipe and prevent having to actually go to a different page, which would improve the experience here since the back button from the save page takes you back to effectively the same page in the pre-saved state). If you want to follow the rest of the way through this you're going to need to register an account on Epicurious, so go ahead and do that and I'll wait right here. Done? Great. Reload that page and you should now have an enabled Save to Recipe Box" button. Now, before you go and click on it to watch Beacon in action, you'll need to make sure that you've logged into Facebook in another tab or window. This is critical and is in fact overlooked by a lot of the people who are upset about the potential privacy violations: don't leave yourself logged into Facebook and you won't have a problem with other people using your machine and logging Beacon events. Go ahead and login and then hit that button.

You should now be on a page which shows the recipe as added. There's a lot of Epicurious-centered JavaScript at play on this page which we're not overly concerned about, so I'm not going to mention it except where it affects the Beacon integration. As on the previous page, we have a

<meta>

tag with the recipe name in it, and the inclusion of the JavaScript file (line 133 and 167 again), but now we have some more code which actually makes the magic happen. The next mention of Facebook is way down on line 1184, in a function called runOnLoad:

<script language="javascript">
    runOnLoad(function() {
        if (Facebook) {
                Facebook.publish_action('queue',
                    'http://www.epicurious.com/recipes/food/views/240748?mbid=fbfeed');
        }
    });</script>

Basically, if the Facebook object was instantiated when the beacon.js file was included, go ahead and publish an action of type 'queue' with the URL of this page as the link (with a tracker on the end so Epicurious knows you came to the recipe from a Facebook feed). The runOnLoad function gets called down on line 1330 from inside a

<script>

tag. Now we're making progress! Let's take a look at what the publish_action function does – you'll find it on line 20 of beacon.js in unadulterated form, or right here all marked up:

publish_action : function(action, urls) {
    urls = urls || window.location.href;

Set the urls variable to the value passed in or the location of the current page.

    setTimeout(function() {

Set a timeout of 50 milleseconds and then call the following function.

        if (Facebook._BROADCAST_ACTIONS[action]) {
            var query_params = [['action_name', action]];

Check to see if we were passed a valid type of action and set the action_name to the value passed in. The list of available actions is quite extensive: buy, wish_list, queue, sign_up, bid, review, add, book, comment, create, design, download, find, fly, get, join, play, post, rate, rent, shop, stay, subscribe, support, update, view, vote, watch, enjoy, order.

            if (typeof urls == 'object') {
                for (var i = 0; i < urls.length; ++i) {
                query_params = query_params.concat([['urls[' + i + ']', urls[i]]]);
            } 
       } else {
            query_params = query_params.concat([['urls[0]', urls]]);
        }
        Facebook._send_request('http://www.facebook.com/beacon/auth_iframe.php', query_params);
        }
    }, 50);},

Manipulate the URL if required to build the request and then send it to facebook using the _send_request function.

The next piece of code is key to how this whole thing works. Those of you familiar with JavaScript will know that browsers spend a lot of effort preventing something called Cross-Site Scripting (often shortened to XSS). We covered this back in July 2006 with a post on 5 Tips for Protecting Your Site Against XSS, and Wikipedia has an excellent a very in-depth look at the issue in their Cross-site Scripting entry. The gist of it is that you can't have a script from one site run on another site and you can't drop a cookie from one site and read it from another, so how does your news event from Epicurious get posted into Facebook without using a backend server connection? All thanks to the humble _send_request function (line 75 in beacon.js):

_send_request : function(url, query_params) {
    query_params = query_params.concat([['source_id', Facebook._source_id],
        ['random', Math.random()],
        ['ref_url', window.location.href]]);
    var src = url + '?' + Facebook._form_query_string(query_params);

This is pretty simple – parse the info handed to this function and get ready for below.

        setTimeout(function() {
        var ifr = document.createElement('iframe');
        ifr.style.display     = 'block';
        ifr.style.width       = '0px';
        ifr.style.height      = '0px';
        ifr.style.border      = '0px';
        ifr.style.margin      = '0px';
        ifr.style.padding     = '0px';
        ifr.style.overflow    = 'hidden';
        ifr.style.visibility  = 'hidden';
        ifr.src = src;
        document.body.appendChild(ifr);
    }, 0);
},

This is where it all goes down. This code creates an

<iframe>

on the fly and inserts into the document, using the URL that got passed in from publish_action above.

So, an

<iframe>

on the page loads content from the Facebook server, getting passed in the action you performed and the URL to link back to. If you look above, you'll see that the

<iframe>

is loading content from http://www.facebook.com/beacon/auth_iframe.php, which you can try to load directly but will likely get an "invalid ref url" error. We can fake it out by passing in the same values which would be built into query_params and passed in: http://www.epicurious.com/facebook_helper.html?function_name=_perform_action&arg1=null&arg2=<auth_token_redacted>&random=1609429394. Two notes: 1) There's a piece in the URL which looks like it's encoded in JavaScript Object Notation (JSON), which I've removed for publishing this post. It's impossible to tell by looking at it, but it might contain a key which relates back to my Facebook account. It's not needed for the purposes of understanding the functionality, and if you'd really like to see what it looks like, you can recreate the steps up to this point and check it out for yourself. 2) You'll need to use a URL Encoder to pass in the ref_url parameter – I usually use Eric Meyer's Decoder/Encoder. If you follow that URL, you'll get a page with a simple block of HTML on it, which is what loads in the

<iframe>

(it will make a blank page in your browser – view source to see what's in it):

<html><body><script type="text/javascript">window.onload = function() {
    window.top.Facebook.process_message_from_helper(
        window.location.search.substring(1),
        window.location.hash.substring(1));}</script>
</body></html>

Nice and short: when the page loads into the

<iframe>

, call the process_message_from_helper function in the Facebook object at the top level of this window (being the page on Epicurious which instantiated the

<iframe>

). You may not have known that window.location had a bunch of really useful properties within it, including search (everything in the query string of a URL, or after the ?), and hash (the anchor tag on a page, or everything after the #). Back to the beacon.js file, line 290:

process_message_from_helper : function(query_string, hash_string) {
            var params = Facebook._parse_query_string(query_string);

Facebook._parse_query_string is to an internal function (beacon.js, line 276) which pulls about the key/value pairs from the query string (e.g."action_name=queue") and returns an array containing the key and value (e.g.: ["action_name", "queue"]).

            var argument_list = [];
            var function_name = '';
            for (var i = 0; i < params.length; ++i) {
                var key = params[i][0];
                var val = params[i][1];
                if (key.substring(0, 3) == 'arg') {
                    argument_list[parseInt(key.substring(3))] = val;
                }

Some of the keys stored in the query_string start with 'argx' to denote that they arguments (where x is an integer indicating which argument this is – arg0, arg1, arg2, etc.). If that's the case, store the value in the argument_list array at that location (e.g.: arg0 goes into the argument_list[0]).

                          if (key == 'function_name') {
                                       function_name = val;
                          }
             }
             Facebook[function_name].apply(null, argument_list);
}

If the key is 'function_name', then we want to call that function in the Facebook object. That

if

really could have been an

else

(extending the previous

if

) since it's impossible for the key to start with arg and be equal to 'function_name', but maybe there's more code to come or something has been removed. Either way, the final step is to call any functions that got passed in and pass them the argument_list which we've built up.

It's interesting to note that none of the arguments which got stored when we built the query_string above started with arg or had a key of function_name. Since we had to fake our way into seeing the auth_iframe.php page, we didn't get a look at the full set of arguments passed into it from Epicurious. The trail would have gone cold here, were it not for the wonderful Firefox add-on called TamperData. With the add-on installed and the sidebar open, you can watch all of the GET and POST requests that a page makes as it loads. The recipe save page from Epicurious makes 116 requests to build the page, pulling from three servers (www.epicurious.com, www.google-analytics.com, and www.facebook.com). We only really care about the ones made to Facebook, of which there are 6. The GET call to auth_iframe.php is the one we're after, and it looks like this:

http://www.facebook.com/beacon/auth_iframe.php?action_name=queue
&urls[0]=http%3A%2F%2Fwww.epicurious.com%2Frecipes%2Ffood%2Fviews%2F240748%3Fmbid%3Dfbfeed
&source_id=5194643289
&random=0.2268030104517741
&ref_url=http%3A%2F%2Fwww.epicurious.com%2Frecipes%2Ffood%2Fviews%2F240748%3Frecipename%3DBREAKFAST%2520RISOTTO%26saved_to_box%3Dy

Which is not dissimilar to the version we constructed. Thanks to TamperData, we can get the response to that request, which contains the following location:

Location=http://www.epicurious.com/facebook_helper.html?function_name=_perform_action
&arg0=queue
&arg1=%5B%22http%3A%5C%2F%5C%2Fwww.epicurious.com%5C%2Frecipes%5C%2Ffood%5C%2F
views%5C%2F240748%3Fmbid%3Dfbfeed%22%5D
&arg2=<auth_token_redacted>
&random=1305590124

When the call gets made from Epicurious rather than by us, the response fits right into the pattern that process_message_from_helper is looking for. In fact, if you go to that URL and view the source, you'll seem the same thing we saw when we loaded auth_iframe directly, except now being served from Epicurious instead of Facebook. Applying what we know from process_message_from_helper, we've now essentially called:

_perform_action(queue, ["http://www.epicurious.com/recipes/food/views/240748?mbid=fbfeed"], <auth_token_redacted>, 1305590124);

Note that we've made a trip through the Facebook server to get here, which means Facebook has already recorded this news feed item whether we choose to publish it or not. This is a much longer function so I've edited out some parts which are not key to the core functionality. If you'd like to see the whole thing, we're now on line 159 of beacon.js. One thing to note before we dive in: the term 'toast' will only make sense if you've actually seen the pop-up appear. Since it rises up from the bottom edge of the window frame, it looks a lot like toast popping up in a toaster :)

_perform_action : function(action_name, urls, auth_token) {
             Facebook._kill_toast();

Although it may sound like it, no one at Facebook has a vendetta against breakfast foods (that we know of). This just kills the window if it's already visible from a previous instantiation.

             var toast = Facebook._toast = document.createElement('div');
             var query_param = [['action_name', action_name],
                          ['urls', urls],
                          ['source_id', Facebook._source_id],
                          ['ref_url', window.location.href],
                          ['random', Math.random()]];
             if (auth_token) {
                          query_param.push(['auth_token', auth_token]);
             }
             var src = Facebook._action_toast_url + '?' + Facebook._form_query_string(query_param);

Create the HTML element that will hold our toast, then setup the query_params. The toast window contains another

<iframe>

into which we will once again pass our familiar query_params (see below). The next block is formatting for the

<iframe>

and has been removed.

              [...redacted...]
             var iframe_style = 'width: 345px; height: auto; left: 0px;'
                         + 'border: 0px; margin: 0px; padding: 0px; display: block; position: absolute; background: transparent;';
             toast_inner.innerHTML = '<iframe src="%27%20+%20src%20+%20%27" style="" 
                     allowtransparency="true" frameborder="0" scrolling="no"></iframe>';

Format the

<iframe>

and then set the innerHTML of the inside of our toast window to contain it, passing in the src variable defined above. _action_toast_url is defined in beacon.js as http://www.facebook.com/beacon/action_toast.php.

              var iframe = Facebook._toast_iframe =
              toast_inner.getElementsByTagName('iframe')[0];
             iframe.style.bottom = '-150px';
             toast.appendChild(toast_inner);
              document.body.appendChild(toast);
             [...redacted...]
         }}

Lastly, append the inner_toast div to the toast div which we created at the top. The next block calculates the position of the div and sets some style values.

We're almost done, honest. Referring back to our TamperData output, the URL for the

<iframe>

in the toast window that actually gets called by Epicurious is:

http://www.facebook.com/beacon/action_toast.php?action_name=queue&urls=["http%3A%2F%2Fwww.epicurious.com%2Frecipes%2Ffood%2F
views%2F240748%3Fmbid%3Dfbfeed"]&source_id=5194643289&ref_url=http%3A%2F%2Fwww.epicurious.com%2Frecipes%2Ffood>%2Fviews%2F240748%3F
recipename%3DBREAKFAST RISOTTO%26saved_to_box%3Dy&random=0.820036078758848&auth_token=<auth_token_redacted>

If you were logged into Facebook, and I hadn't removed the auth_token, and you load that URL in a window, you would probably see the contents of the toast window rendered in all of its glory. Since you can't do that, I'll just repeat the screenshot of the toast window from above:

You have five options at this point:

            
1. Close: closes the toast window and sends the news item to your news feed.
            
2. Learn More: takes you to a page on the Epicurious site with more information about the Facebook integration (Facebook Action Sharing and Story Publishing).
            
3. This isn't me: pops up a new window with a Facebook login in it so that you can login and add the item to your own news feed. This closes the toast window, but closing the login window without logging in didn't seem to log me out of Facebook. The recipe hasn't shown up in my feed, so I'm assuming that still blocked it from being published.
            
4. No Thanks: closes the toast window and stops the story from being published.

One important privacy consideration, despite this not being a privacy post, is that Facebook still knows that you added a recipe to your recipe box (or bought a book on Amazon, or a coffee table on Overstock.com, even if block the item from being posted to your news feed. I haven't seen any evidence here that shows that Beacon is sending along anything other than basically an action type, a name (in the

<meta>

tag), and a URL to link the name to, but that doesn't mean that it isn't hiding it in some of the encoded values along the way. Also, adding recipes to your recipe box is a lot more innocent than, say, purchasing adult DVDs or registering for Monster.com when you already have a job, so carefully consider what information you're broadcasting.

Wrapping Up

That well and truly brings us to the end of our look at Facebook Beacon. It seems impossible that you might have read all this way down and not have been lulled into sleep, but if you're still awak (hi!) and have questions, leave them in the comments below and I'll do my best to answer them. If you're interested in reading more about this topic, and particularly about the privacy concerns or integration between Beacon and the other Business tools, let me know! Thanks for reading :)