Beating Back Facebook Sharer.php Bugs

Epics3.com is a fairly simple site for sharing your photos on the web. It ties in nicely with Facebook and Twitter by either using simple share buttons at the bottom of each large image or through an API when the photos are uploaded via a browser or through e-mail.

On Twitter, the photo's caption is tweeted out with a link to the full size image. In the case of Facebook, though, just the caption is sent over using Facebook's API and it's posted on your wall as a link. Facebook had documented some hints which you can put into the web page's HTML so it can pick up a specific thumbnail of the image to post on your Facebook wall.

Bugs
Unfortunately, there is a Facebook bug, that pops up randomly, where the hints for finding the thumbnail image are ignored. This results in the first image on the webpage being posted to your wall. In the case of Epics3, as in most, this will result in the website's logo posted on your wall instead of the photo. Bad, bad, user experience. How could it work for months without a problem until recently?


click to enlarge

Documentation
Facebook's API documentation is notoriously horrible (on the other hand, Amazon Web Services documentation is the textbook case on how APIs should be documented).

After spending several hours tracking down this bug on the Internet, I concluded that no one had solved it. (I also doubt that it was well documented in a way that Facebook, Inc. can reproduce the problem). When searching for the bug I found many cases of users who had encountered the same problem with shrugged shoulders. After all, this is just HTML - there's no logic to debug.

Details
When you use Facebook's sharer.php button to post a link to your wall, Facebook's servers will take a quick look at the link and spider the webpage to find a suitable photo. You can tell Facebook exactly which photo to post next to the link by adding this HTML code to the HEAD of your webpage:

<link rel="image_src" href="http://example.com/thumbnail.jpg"/>


For some reason, this hint has worked intermittently, lately - most notably it has been failing on the weekends.

User Agent Solution
After several hours of no joy I finally gave up trying to get it to work according to Facebook's API. To solve my problem, I placed a conditional surrounding the entire web page's body. When an incoming request's user agent contains the word facebook, I return a webpage with nothing other than the image. [The full Facebook user agent is "facebook share (http://facebook.com/sharer.php)", but just looking for the word facebook should be enough.] When the user agent in the request is anything other than facebook, I simply return the normal Epics3 webpage.

Problem solved (I hope).