FBJS LocalProxy

From Facebook Developers Wiki

[edit] Intro

In FBJS the AJAX object is used to make Async requests to your server. AJAX allows you to make three different types of requests. RAW, JSON, and FBML. For FBML, it is necessary that the request go through our FBML proxy server so that we can collect data and render the FBML. For RAW and JSON types, there is no reason to go through the Facebook central server. The Ajax object now has a new property useLocalProxy that lets you make direct calls to your app server. If you find yourself using Ajax often it is worth checking out this new functionality.

[edit] Quickstart

Here's how to get it to work.

1. Set ajax.useLocalProxy = true
2. Include the tag <fb:local-proxy/> at the bottom of your FBML
3. Include the following crossdomain.xml file at the root of your application server.

<?xml version="1.0"?> 
<!DOCTYPE cross-domain-policy SYSTEM "http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">
<cross-domain-policy>
   <allow-access-from domain="apps.facebook.com" />
   <allow-access-from domain="apps.*.facebook.com" />
</cross-domain-policy>

Ajax calls should now work just as they did before in FBJS, except without the added latency of our proxy server.

To actually use the data that you get through this method, check out setInnerXHTML, which lets you insert a string of XHTML into the DOM.

NOTE: For clarification, the crossdomain.xml file needs to be in the root of your server. not the root of your application. (i.e. http://my.host.com/crossdomain.xml, not http://apps.facebook.com/myapp/crossdomain.xml)

User must have Flash Player 9 or greater installed in order for this to work.

[edit] Code sample

<script>
function do_ajax() {
  var ajax = new Ajax();
  var queryParams = { "param1" : 1, "param2" : 2 };
  ajax.responseType = Ajax.JSON;
  ajax.useLocalProxy = true;
  ajax.ondone = function(xhtml) {
    var p = document.getElementById('rewrite');
    p.setInnerXHTML(xhtml.content);
  }
  ajax.onerror = function() {
    console.log("there was an error");
  }
  ajax.post('http://foo.com/bar.json', queryParams); // Server port must be port 80
 }
</script>

<fb:local-proxy/>

In this example, we assume that bar.json looks like "{\"content\":\"<p>Click</p>\"}" or something similar. The only difference between this and the Ajax Example is the inclusion of fb:local-proxy and the fact that we set useLocalProxy to true. Also note the new method setInnerXHTML which provides a way to use the non-FBML content returned from Ajax calls.

NOTE: Make sure you have a modern version of Flash. I had Internet Explorer 7 installed with Flash 6 (fresh install) and this did not work at all (even though it worked in Firefox on my macbook). Updating to the latest Flash fixed this problem. An update here about the minimum browser/flash requirements would be great!

[edit] Tech

This method uses a trick set up by Flash. We use expose an ActionScript callback that FBJS can call into. The crossdomain.xml file then lets us make the cross-domain call to your server. The result is then returned to Javascript. To ensure the security, we restrict requests to the same domain as the canvas page registered by the app.

User must have Flash Player 9 or greater installed in order for this to work.