Pretty much everybody in the developed world (and most of the developing world) interacts with Facebook as an application. Not many people have to actually deal with Facebook from an API level. I’ve spent a few months writing some code that tries to perform a few simple tasks on Facebook, and it’s been rough. Here’s a random collection of things I’ve learned, gotchas, and other points worth noting in the process. As a brief point of reference, most of my interaction with Facebook comes from the server-side code, written in Java, although I’ve played around with Facebook’s JavaScript SDK as well.
A little bit of background first – the code I worked on involved Facebook’s custom audiences and managing custom tabs on a Facebook page. This means using both the Facebook ads API and their Open Graph API. There’s 2 different sets of concerns around those, 1 of which is rate limiting. How does rate limiting with Facebook work? Well, good luck. Oh, and with the ads API, there are account levels that affect the rate limiting. Complicated enough? Wonderful, moving on!
The first thing you’re going to want to do is bookmark Facebook’s Graph API explorer (https://developers.facebook.com/tools/explorer by the way). This is an interactive endpoint for Facebook API calls, similar to I/O Docs if you’re familiar with that. Use this to test every API call you intend to make. Just be forewarned, the Graph API Explorer doesn’t include the access token in the URL field, you’re going to need to remember to add that yourself if you’re making your Facebook API calls from the server (as opposed to their JavaScript library).
Most people think that if you have an account, you have an (note the the singular) account ID. If you want to use Facebook’s ads API, you have at least 2 IDs -your account ID and your ad account ID. If all you’re using is the ads API, no problem. If your application goes beyond ads, you’re going to need to track both the user’s regular account ID and their ad account ID. FYI, the ad account ID doesn’t come with the regular user information when a user logs in, so you’re going to have to call Facebook’s /me/adaccounts endpoint to get that ID. Look, Facebook already has account IDs, the simple thing would be to just use the account IDs they already have. However, Facebook chose not to keep things simple for developers, so if you’re application is going to interact with the regular Open Graph API and the Ads API, make sure you’re paying attention to which account ID you need, and make sure you have it handy.
While we’re on the topics of multiples, let’s talk about access tokens. There are 3 – user, app, and page. The user-level access token is pretty straightforward and standard. Log in, get a token indicating you’ve authenticated with the service and have permission to interact with the API. These are generally specific to the user/application combo, so you can revoke the application’s permission to interact with the site without impacting any other service you use. Next up is the application access token. OK…a lot of social network APIs let applications make requests that don’t require a specific user’s authorization, and from what I’ve seen you rarely if ever have to use it, so it’s not really a concern, although having a second access token does seem clunky – especially if you never really end up using it. Last up is the page access token. This token is required to edit Facebook pages via the API, and I’m still not sure why it’s required. You list which pages a user has permission to edit using their access token, so there’s no reason not to use that same access token to actually manipulate the contents of the page.
Any permissions your app needs beyond profile information has to be approved by Facebook before people can use your app. This isn’t blanket approval for the app period, but rather approval for each specific permission that you’re asking for. No problem right? Well, until you realize that at no point during this approval process are you going to be dealing directly with anybody from Facebook. Instead, you fill out an application for app approval, complete with step-by-step instructions on how to use the application, complete with screen shots showing your application in use, and then you send this thing off and wait until they get back to you, hoping for the best in the meantime. And if that doesn’t pan out, there’s no way of replying to the reviewer and working directly with them to get this issue(s) resolved and your app approved. Instead, you have to divine the issue as best you can from the reviewer’s comments (sometimes this is far easier to do than others), and re-submit your application for another review. The best advice on this I can offer is to make whatever part of your app appears on Facebook as awesome as possible, because I’m not totally sure the reviewer will even look at your app itself if you’re making a web-based application.
Oh, and if you want to work with Facebook for things like standard-level ads API access (the highest of the 3 levels they offer, and the 1 you’re actually going to need if you actually anticipate your app being any kind of success)? Still no direct interaction with Facebook from what I can tell, just another form to fill out, submit, and hope for the best, or really just any contact back, as I’ve been waiting over 2 weeks as of when I’m writing this.
The only thing I’ve seen that gets feedback from Facebook is posting in their developers group. If you can see the posts in that group, you’ve probably noticed something about all the authors – namely everything is posted from personal accounts – there’s nothing there that’s clearly from a company making apps that deal with Facebook. Either almost no business writes applications for Facebook (which seems unlikely), or Facebook only wants questions from personal accounts. Seriously? Why not allow corporate developer accounts? That way multiple developers working on an application can have a single account to use for logging into, administering, and following up on company applications. Even better would be to have a developer account that essentially serves as an umbrella account for various personal accounts, that way if someone leaves a company you can remove them as the administrator of the application without forcing the rest of your team to memorize a new password. But seriously, company accounts should be a thing. I made the mistake of posting a question on the developers group from an internal company account and found it had disappeared shortly thereafter. Seriously Facebook, company accounts.
That said, the developers group does have a couple of Facebook engineers who sit in the group and do a pretty good job of answering questions (thanks David Doyle and Emil Hesslow!). It’s a pretty busy group, and occasionally a question slips through the cracks, although that’s pretty rare. Generally, I’ve found the developers group to be the best way of getting real answers out of the app review process.
Really the most aggravating thing of all about Facebook development is trying to understand their documentation. That’s when the documentation’s there in the first place. If you’re hoping to figure out what a given call returns, you’ll either need to use the Graph Explorer linked above to make the call yourself or you can search the Internet in the hopes that someone else has posted an answer to your question. Generally speaking, the most useful documentation on Facebook development features are found on sites that don’t have facebook.com in the URL. The best part is when the Facebook documentation is just plain wrong, although don’t expect StackOverflow to help much either.
Here’s an example that I had to deal with: Facebook custom audiences. According to their developers reference on creating custom audiences, you can specify an opt_out_link parameter. What’s not in the documentation is any indicate of just how that link is used in your custom audience. Is it just a link to a static page on your site? Is it an endpoint called when a user says they don’t want to see that ad? How does Facebook use it to communicate to you that a user doesn’t want to be targeted by ads? That’s important, because Facebook’s custom audience documentation also says that you have to remove people who have opted out of being tracked from all custom audiences they’re in, so knowing how the opt_out_link works is important. By the way, none of the Facebook examples for creating a custom audience, either on Facebook or on other sites show this field being set, which begs the question of just how important they consider it in the first place. By the way, after finally stumbling on the answer the third or fourth time I tried to Google around for it, the opt_out_link should be a link to an unsubscribe page on your site. It appears (when set) in the “Why am I seeing this ad?” dialog, right underneath the box explaining that the Facebook user was targeting their existing mailing lists.
By the way, want to preview something, say…to test the above random piece of information you found on some blog you never heard of about how opt_out_link works? Here’s a fun piece of trivia – Facebook has no developer sandbox. Everything you do, you do with real accounts and real data. The closest you can come to test versions of this stuff is using unpublished pages, or setting up and previewing ad campaigns, previewing the ads, and then immediately disabling them before people see your ads. That’s because with Facebook, you get nothing but the absolute best practices. PS – if you’re previewing an ad, you need to publish the unpublished page you’re using as your test page, just FYI. Remember, it’s not real development if it’s not live to Facebook’s billions of users while you’re working on it.
If you’re building a web application, your best bet is to use Facebook’s JavaScript SDK whenever feasible. It’s pretty clean and straightforward, and has Facebook pop up dialogs for any instance when a user needs to interact with Facebook. The JavaScript SDK actually does a really good job of simplifying interacting with Facebook. If you need to interact with Facebook from your Java code, then I’ve found RestFB to be a pretty good library. Even if they don’t have a built-in object for what you’re looking for, their DefaultWebRequestor object (which you can pull from their DefaultFacebookClient) lets you make arbitrary Open Graph API calls.
Facebook development is a frustrating experience, not helped in the slightest by Facebook’s resources and app approval process. That said, there’s some really good libraries out there to make the actual coding itself a lot easier. The good news is, there’s plenty of opportunity for Facebook to fix a lot of their problems and actually make Facebook development something desirable instead of something you hate but still have to do. If you do find yourself forced to develop a Facebook application, then really all I can say is, good luck…