Photo by Coccinelle69

In the last post I talked about the mechanics of how an app communicates with Facebook. With the alpha release of Ringside, there’s now an example of how to implement the server side of Facebook. It’s open-source and the two most interesting parts are their underlying mysql database and the PHP interface code that implements the API on top of that. Using mysql makes it hard to scale to massive numbers of users, so it’s not ready to power Facebook yet. On the other hand, having enough users to strain a single database server is a good problem to have. At that point you should have the resources to reimplement something more advanced under the hood.

Having a reference host for any plugin architecture is immensely helpful, especially one that’s open source. For example, if I was having trouble with the details of fetching events, I could open up ringside/api/includes/ringside/api/facebook/EventsGet.php and inspect exactly what their implementation is. There’s no guarantee that it’s the same as Facebook’s code, but it’s at least an unambiguous and exact specification of what somebody else thinks it should be doing. To get your own copy of the source using SVN, run
svn co https://ringside.svn.sourceforge.net/svnroot/ringside ringside

The other exciting part of Ringside’s release is their mysql schema. It could become a defacto standard for expressing the data that underlies all social networks. Anybody who’s able to take their own data source and translate it into the same tables can plug that into Ringside’s system. Turn the key, and you’ve got your own private Facebook. The schema is at ringside/api/config/ringside-schema.sql

If you want to customize it, the API source is full of great examples of how to work with the database to extend its capabilities, though the LGPL licence might require your changes to also be published.

Photo by fallsroad

Facebook’s API comes wrapped in libraries for all the popular server languages, but there will come a day when you need to debug the raw HTTP transactions that they all boil down to. As a scripting language, the PHP implementation is easy to understand, and I ended up tweaking mine to output the exact text that’s flowing between me and Facebook. This was partly to help debugging, but also for my own curiosity. I’d like to model some of my interfaces on Facebook’s since it’s simple, robust and flexible.

You call a method by sending an HTTP request to "http://api.facebook.com/restserver.php". Arguments to the method are passed in the POST string sent as part of the request. Here’s an example for an event API call, split up on ampersands so that it won’t go off the edge of the blog, and with any secret values replaced with X:

uid=XXXXXXXXX&
eids=&
start_time=0&
end_time=1000000000000&
rsvp_status=&
method=facebook.events.get&
session_key=XXXXXXXXXXXXXXXXXXXXXXXX_XXXXXXXXX&
api_key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&
call_id=1206547876.5053
&v=1.0&
sig=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

This is generated by taking the normal PHP arguments to each method, along with stored login and API keys, and serializing them into this string. If CURL is present on the server, this is then used to send the request, otherwise PHP’s native HTTP access functions are used.

Assuming that the call name (specified in "method") and the other arguments check out, then the Facebook server will return a string as its response. This string is in XML, and looks something like this:

<?xml version="1.0" encoding="UTF_8"?>
<events_get_response xmlns="http://api.facebook.com/1.0/&quot;
xmlns:xsi="http://www.w3.org/2001/XMLSchema_instance&quot;
xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd&quot;
list="true">
  <event>
    <eid>5172087276</eid>
    <name>Blog World Expo example</name>
    <tagline>http://www.blogworldexpo.com/</tagline&gt;
    <nid>0</nid>
    <pic>http://profile.ak.facebook.com/object2/5/55/s5172087276_7478.jpg</pic&gt;
    <pic_big>http://profile.ak.facebook.com/object2/5/55/n5172087276_7478.jpg</pic_big&gt;
    <pic_small>http://profile.ak.facebook.com/object2/5/55/t5172087276_7478.jpg</pic_small&gt;
    <host>BlogWorld</host>
… <snip …
</event>
</events_get_response>

The library then takes this simple XML string, and parses it into a PHP hierarchical array of values that looks like this:

Array
(
    [0] => Array
        (
            [eid] => 5172087276
            [name] => Blog World Expo example
            [tagline] => http://www.blogworldexpo.com/
            [nid] => 0
            [pic] => http://profile.ak.facebook.com/object2/5/55/s5172087276_7478.jpg
            [pic_big] => http://profile.ak.facebook.com/object2/5/55/n5172087276_7478.jpg
            [pic_small] => http://profile.ak.facebook.com/object2/5/55/t5172087276_7478.jpg
            [host] => BlogWorld
… <snip> …
        )
)

This always matches the structure of the XML. Facebook use a restricted subset that avoids tag attributes and anything else that might make it hard to map to this JSON style format.

Another possibility is that an error will be returned. In that case, the XML will normally just be a couple of tags, the error message string and the numeric error code. This gets converted to a PHP exception.

To dig into this code yourself, I recommend looking through facebookapi_php5_restlib.php in the client folder of the Facebook SDK. That’s a good place to add your own debugging code too, though there’s already some that can be enabled by setting the $GLOBALS[‘facebook_config’][‘debug’] variable to true.

Photo of the original Ajax by Oboulko

One of the toughest parts of the Facebook API is their Ajax support. There’s a good page on their wiki with a small piece of sample code, but since Event Connector uses Ajax heavily, I thought it would be a good real-world example. Here’s the PHP source code.

I’ve removed the application settings from config.php, so you’ll need to create your own application in Facebook and follow the same steps you do for the Footprints sample before you can use it. There’s some inline comments explain the control flow, and covering some of the Ajax quirks. One thing to be aware of is the 10 second time-out in all Facebook page requests. If you’re doing any heavy work on the server, or it could get overloaded, you’ll need a strategy to prevent your users seeing an error screen, which is exactly why I went with Ajax for this situation.

More Facebook API posts

I’m a statistics junkie. Picking some significant metrics, and sticking with them to measure performance is the only way to figure out what’s working and what isn’t. I usually try to design in some measurement tools, but that’s hard with Facebook apps, since their setup hides the referring address/previous page and other useful information.

Luckily, they recently introduced a new statistics page for every app, which you can access from the More Stats link below the application name, from the main developer page.

The first big innovation is the ability to see how many people added and removed you during the previous 24 hours. Before, you could only guess at this by comparing the user totals from day to day, but this wouldn’t tell you how much turnover you had from people removing your app. The most useful part of this, and one that’s a bit hidden, is that the total number of adds is actually a link. If you click on it, you’ll see a bar graph like the one above, showing you exactly where your new users came from.

The top picture is for Funhouse Photo, and it tells me a lot. I was suspicious that my app was very non-viral because the growth in users was very linear, but this confirms that I’m getting the majority from the directory and direct searches, rather than feed stories or other friend-to-friend communications. To improve growth that needs to change, and I’ll be able to tell very quickly if alterations to the app help by looking at those stats.

Less exciting, but still very useful, are the response metrics. I’ve had a recurrent problem with time-outs on my facebook apps because they’re doing heavy processing on the server. It seems like any page request that takes more than 8 seconds to complete results in a Facebook error screen for the user, so to work around that I had to implement asynchronous Ajax loading of page elements that might take a while. Looking at the response statistics shows that both my apps that use this aren’t returning error pages for any users, something I couldn’t verify before.

The final interesting feature is a selection of the URLs that were requested from the app recently. This sampling is a great way to figure out how people are using your app, which features they’re accessing and how often. My apps generally encode a lot of information in the URL using GET rather than POST, so I’m able to get quite a fine-grained look at my users’ interactions with them.

Funhouse Photo User Count: 1,723 total, 95 active. As I mention above, I’ve got new insight into the growth pattern from the add statistics. It explains why growth is so linear, there’s little friend-to-friend spreading of the app.

Event Connector User Count: 71 total, 11 active. The add source statistics show that most of the trickle of new users came from the product directory, which is what I’d expect since I don’t have a conference signed up yet.

There isn’t an official guide on how to submit your app to Facebook’s directory, so here’s what I’ve found after going through the process several times.

You don’t have to submit your app to the directory. I never did for Defrag Connector, since it was distributed directly by the conference promoter, and wouldn’t have been helpful to the general public anyway. The strength of the directory is that it gives you access to the early-adopters, people who are actively looking for a new app to try. What you want long-term is an app that’s viral, so friends spread it to their friends to reach a much wider audience, but the directory is a good way to start the ball rolling.

In preparation for submission, you need to go to your Developer application and click on My Applications. Below each of your apps is an ‘Edit about page’ link. This is where you can provide a short description, a screenshot, and importantly, set the two directory categories you want your app to appear in. I’ve got no statistics to back this up, but it seems like "Just for Fun" is one of the most popular categories, so I’d recommend that if possible.

Next, make sure your app has an icon, by going to ‘Edit Settings’ for your application. Even though the icon is part of the optional fields section, Event Connector was initially rejected for not having one.

Once you’ve filled out all the information on those pages, you can click on "Submit Application" to the right of your app. There, you’ll need to fill out another description, and supply a larger icon for the directory listing. Once you’ve done that, your app is almost ready to be submitted.

The final hurdle is making sure you have enough users. You need a minimum of five to demonstrate you’ve been testing your app, and that you can personally persuade five people to use it. Hit up your friends and get them to give it a test run, and let you know what they think.

Once you’ve met all those conditions, you can submit the app for review. I’ve found it’s taken me two to three days, and as far as I can tell the inspection is fairly perfunctory. I can’t imagine it’s a sought-after job reviewing the apps, and I’ve had a spotty experience with the quality of the examination.

I submitted Event Connector four times in total before it was accepted. The first rejection was for the lack of an icon, which I fixed, but then the next two were random and confusing, claiming that my app had no content, and then that it violated the ToS because it gave access to secret events. Since there was little information in the rejections, and after research I couldn’t reproduce the problems, I resubmitted the app unchanged both times, and it was eventually accepted. Unlike the Firefox directory, there’s no two-way communication between the reviewers and the app developers, so I wasn’t able to get any additional guidance.

Once you’re in, you should get an immediate spike in the number of users, as the app shows up in the ‘Just added’ section of the directory. Then, I’d expect a steady flow of users, the size depending on the categories and appeal of your app. Hopefully you can gather a good base to build on with some viral distribution.

Funhouse Photo User Count: 1,697 total, 76 active. Still ticking upward, with fairly slow growth.

Event Connector User Count: 67 total, 6 active. I’m getting the Facebook equivalent of cosmic background radiation, in terms of new users through the directory. Still an uphill battle winning a new conference.

Facebook is walking a tightrope with its API; they need to expose enough functionality so we can develop compelling services, but guard against malicious applications that could degrade the Facebook user experience, for example by flooding people with spam.

The API is a compromise between these two conflicting goals, and I’m going to cover what you can and can’t do. Overall, I’ve been able to see some patterns in the decisions they’ve made about what to expose, and how to expose it:

• Apps can only see what the logged-in user can see.
• Getting access to any information held by Facebook requires the user to go through a screen where they temporarily authorize, or permanently add, the application.
• The Facebook team are very conservative about letting applications change data held by Facebook. Most of the API is focused on reading data, there’s only a few specific places where you can alter data:

1. Adding an application box to the user’s profile. This gives the app a small sandbox to draw something interesting, but the content has to be statically set by the application, and then is stored by Facebook. The only time you can update it is if the user takes an action that involves your application, there’s no way to fetch it dynamically. If there’s some scripts within the markup you place in the box, they aren’t run unless the user clicks on it in the profile.
2. Publish an item on the feed. You can only publish to the current user’s feed, and the app is has time limits on how often it may call it, once every 12 hours for stories, 10 times a 48 hour period for actions.
3. Send notifications or emails to friends. Again, there’s limits on how many you can send in a day, up to 10 emails and 40 emails and notifications. The user also has to go through an additional screen to authorize emails.
4. Photo upload. An app must get additional permission from the user before it’s allowed to upload photos. Each application only has to do this once per user, the permission is granted permanently.
5. Setting the user’s status text. This is another operation that requires an additional step of seeking permission from the user.

• There’s no way to use the API to affect anything not covered here, such as adding information to group or event pages.

There is an alternative way to perform some actions that aren’t covered by the API, by hand-crafting Facebook internal URLs, and redirecting to them. There’s actually a bit of official documentation on this here.

Funhouse Photo User Count: 1493 total, 123 active. Back to the more typical growth rate, which is strong evidence the strong growth of the last few days was caused by Columbus Day boredom.

Event Connector User Count: 40 total, 10 active. Not much happening here so far, I’m reaching out to some more event promoters to get them to give it a go.

After growing so linearly it was almost creepy, Funhouse Photo gained over 200 users since yesterday. And I have no clue why! I’ve been searching to see if it got mentioned or reviewed somewhere, but I’m drawing a blank. I don’t get much information from Facebook about how people found the app, I’d need to manually build in some tracking myself, and I’d probably not be able to get much information about the referring page anyway since Facebook does so much redirection.

Oh, I did just have a thought. It was Columbus Day yesterday, I bet there was a lot of bored people looking for something fun to do on Facebook. Interesting, probably won’t translate into a long-term trend if that’s the case.

I wish I could have made it to Graphing Social Patterns, the Facebook developer conference. From the notes, it looks like Danny Sullivan is thinking along the same lines as me with social search; wanting to use your friends’ browsing habits to give you more focused results.

Funhouse Photo User Count: 1466 total, 344 active. Probably a Columbus Day blip, but nice to see a growth spike.

Event Connector User Count: 39 total, 5 active. Still working with Emile and Tim from New Media Expo to arrange some distribution of their connector, but not much activity otherwise.