AKA "A tale of two share widgets".

I recently built an internet toy. A big part of the toy is social sharing; I wanted players to tell their friends their scores. Most people use Twitter or Facebook, so sharing to those services should be as simple as possible.

A "Share your score on Twitter" button took me about 5 minutes. It's just a link. Customise a couple of parameters and you're good to go. Tumblr's just as easy. You have to click through a few options to see an example, but it's also just a link. But Facebook... oh, Facebook.

Facebook's sharing process is shamefully convoluted. If you just want to share a URL, you can use a straightforward hyperlink, though it will discourage you¹. But if you want to share a URL with a customised description – something Twitter and Tumblr managed with a simple link – here's what you have to do:

1. Create a developer account.
2. Create a new app.
3. Get that app approved & available to the public.
4. Include Facebook's JavaScript in your own page².
5. Include an empty div in your page for Facebook's JavaScript to use.
6. Make a call to FB.ui with the relevant details.

And to top it all off you're now maintaining that code forever, because Facebook's API thrashes around like a ferret on a leash. The Share button is deprecated! No, the Share button is supported! But you should use the JavaScript Feed Dialog! There's also a URL redirection method, hidden away with a minimum of documentation (and still requiring an App ID). And the format might change, so make sure you're reading Facebook bug reports! But good luck finding them, as they're excluded from the Google search index. The Facebook developer experience is a fractal of being told to go fuck yourself.

The story might end there. We have to create an app first, but the URL redirection method is just a link. So it should be equally simple, right? No. It doesn't work. I got an error 100: "Invalid parameter (requires valid redirect_uri)." What is a valid redirect_uri? What's an invalid redirect_uri? There is nothing in the documentation. Why was mine invalid? The error doesn't say. I'd fat-fingered it and missed off an ampersand so I wasn't supplying a redirect_uri at all, but there's a lot of voodoo out there about not escaping the URL or setting your app domain. Obviously I wasted an hour on that before realising my mistake. Couldn't we have had a "missing required parameter" error instead of "invalid parameter"? No, because then you wouldn't feel the full force of Facebook's contempt. And even then, when you've finally got it working, mobile users won't be able to share it.

Move fast and break things is a valid philosophy for a startup, but it doesn't work if you're a platform. Cool URLs don't change; cool APIs don't flipflop around based on whimsy.

Further reading: oAuth of Fealty by Ian Bogost.