You are on page 1of 14

Contents

Introduction ............................................................................................................................................................................... 4
General Best Practices ........................................................................................................................................................... 4
Caching and Real-Time API ............................................................................................................................................ 4
Canvas Apps: Use IFrame ................................................................................................................................................ 4
Logging .................................................................................................................................................................................... 5
Pre-loading information .................................................................................................................................................. 5
API Read Tier ........................................................................................................................................................................ 5
Staging Environment......................................................................................................................................................... 5
Gatekeeper............................................................................................................................................................................. 6
Handling Errors with Exceptions ................................................................................................................................. 6
Potential Issues: API ............................................................................................................................................................... 6
Server unreachable ....................................................................................................................................................... 6
Standard error code returns ..................................................................................................................................... 6
Unexpected error code returns ................................................................................................................................ 7
Empty or bad data returned ...................................................................................................................................... 7
High latency...................................................................................................................................................................... 8
Rate limited (API_EC_TOO_MANY_CALLS) .......................................................................................................... 8
Potential Issues: Social Plugins .......................................................................................................................................... 8
IFrames ................................................................................................................................................................................... 8
High latency...................................................................................................................................................................... 8
Firewall blocking content ........................................................................................................................................... 9
Load successful, display broken .............................................................................................................................. 9
Server error 500, failure to load .............................................................................................................................. 9
General error ................................................................................................................................................................... 9
FBML/XFBML ....................................................................................................................................................................... 9
Firewall blocking content ........................................................................................................................................... 9
High latency.................................................................................................................................................................... 10
Load successful, display broken ............................................................................................................................ 10
Server error 500, failure to load ............................................................................................................................ 10
Failure to load Javascript file .................................................................................................................................. 10
Javascript error, failure to load plugin ................................................................................................................ 10
General error ................................................................................................................................................................. 11

2
Javascript Library .................................................................................................................................................................. 11
Failure to load Javascript file .................................................................................................................................. 11
Javascript error ............................................................................................................................................................. 11
Miscellaneous .......................................................................................................................................................................... 12
Like button is replacing ad units or Flash.......................................................................................................... 12
Large friends lists ........................................................................................................................................................ 12
Cross-domain cookies do not work in Safari .................................................................................................... 12
Tools to Debug ........................................................................................................................................................................ 12
Test accounts ................................................................................................................................................................. 12
Firebug ............................................................................................................................................................................. 12
Charles and Fiddler ..................................................................................................................................................... 12
Tools to Track Platform Changes .................................................................................................................................... 13
“Push Changes” on the Developer’s Wiki ........................................................................................................... 13
Testing changes on beta.facebook.com............................................................................................................... 13
Migrations settings ...................................................................................................................................................... 13
Platform live status ..................................................................................................................................................... 13
Additional helpful links ............................................................................................................................................. 13
Reporting Issues .................................................................................................................................................................... 14

3
Introduction
This guide describes issues that can arise with your Facebook Platform integration. It details how
you can prepare your code to react appropriately to these issues, so you can preserve the optimal
user experience.

This is not meant to be a performance guide. For performance, see


http://developers.facebook.com/docs/guides/performance.

Problems are sorted by the frequency with which they can occur. Solutions are generally presented
as a series of suggestions, with the ones that maintain the most optimal user experience appearing
earlier. When “application” is referenced, it means anything that makes requests to the Facebook
API server (for example, a JavaScript application, iPhone application, canvas-based Flash game,
LAMP server, etc.).

General Best Practices

Caching and Real-Time API


Caching is very important for performance. You can also use it to gracefully handle Platform issues
that are detailed in this doc. Caching enables you to pull a user’s Facebook information from your
own servers rather than requesting it from Facebook’s API servers.

At minimum, we recommend caching on two levels, but this may vary based on the functionality of
your application.

1. Caching users’ friends lists. The cache key is the user’s ID and the value is a serialized list
(or linear array) of their friends’ Facebook user IDs.
2. Caching individual user data. The cache key is the user’s ID and the value is a serialized
associative array of the user’s profile fields and values.

You can cache user data indefinitely, but we strongly recommend you use the Realtime API to keep
user data current. You must subscribe to all pertinent fields of each of your users’ profiles. If the
user updates his or her data on Facebook, your server will receive a ping that lets your application
know this happened. Then, you can request the new user information in order to keep it fresh.
This is important to do so users aren’t confused by seeing old data within your application, which
will remove unnecessary customer support complaints. See
http://developers.facebook.com/docs/api/realtime for more info.

Canvas Apps: Use IFrame


IFrame applications are contained within their own sandbox, so they function like any website off
of facebook.com. This alleviates the need to understand how Facebook proxies, filters, and
sanitizes your code in order to render it as FBML.

4
Logging
Logging as much information as you can is extremely helpful when your users report problems,
especially when determining API issues. When you make API calls, you should track these fields at
minimum.

 Facebook user ID
 API endpoint or plugin type
o E.g., users.getinfo or “like” (for the Like button Social Plugin)
 Time taken (if pertinent)
o From the point the call was transmitted over the wire to the time you received the
response from the API server.
 Timestamp
o Current server time
 Parameters and values
o E.g., a serialized list of parameters and values sent to the API server, or parameters
used to render the Social Plugin.
 User IP address
 Error code received
 Error message received

You may want to track other information like browser, operating system, etc. The more
information you can log, the better. Additionally, you may want to track average Time Taken and
aggregate number of errors logged for each “API endpoint or plugin type” in order to get a high
level idea of what might be going wrong.

Pre-loading Information
If there are points in the user experience where you can pre-load information, you should do it.
This will allow a buffer that will enable you to spare the user from a bad experience if you run into
errors. E.g., if you have an application that displays a user’s photos in a gallery, you should pre-load
photos for the next couple of pages. If you are creating a canvas app, you should preload your FQL
queries whenever possible. For more information, see “Preload FQL Query and Multiquery” at
http://developers.facebook.com/docs/guides/performance.

This will also increase the perceived performance of your application.

API Read Tier


There is a read-only API tier at https://api-read.facebook.com/ that will lead to shorter round trips
and a faster application, if utilized. For a comprehensive list of endpoints that are supported, see
the latest PHP SDK.

Staging Environment
For proper quality assurance, you should have a staging environment in order to test your changes
before they’re pushed live. For more about developer environments, see
http://en.wikipedia.org/wiki/Development_environment.

5
Gatekeeper
In order to push new features live and test them with a small group of users (like your QA team or
developers), you should have “gatekeeper” functionality. This means that you can specify a certain
feature and easily toggle it on or off for a certain subset of users through a GUI. This has the added
benefit that you can easily toggle functionality on or off if it’s not functioning properly.

Handling Errors with Exceptions


You should be cognizant of all of the errors our API can return and handle them gracefully in an
Exception. You should try the API call and if it fails, catch it, log it, and handle it. See
http://developers.facebook.com/docs/reference/api for a list of API endpoints; click on one for the
list of errors.

Potential Issues: API


Server unreachable
Generally this stems from a general server error 500
(http://en.wikipedia.org/wiki/List_of_HTTP_status_codes). The API server suffers from an internal
server error and your application doesn’t receive any information back.

Solution: Pulling from cache


If you store Facebook data in a cache, you should resort to that even if it’s stale. This will only work
for read requests that fail.

Solution: Store, delay, and retry the request asynchronously


If possible, store the request and let the user experience progress so the user can continue
interacting with your application. Then, retry the request in a separate thread multiple times over a
delayed interval. You should cap the retries at a hard number so your application isn’t rate limited
by the API server.

Solution: Cancel the request


Display an error to the user if the user experience is broken due to the server being unreachable.
Otherwise fail silently so that the user can continue using your application. Make sure you log the
issue.

Solution: Retry the request synchronously


If it’s not possible to store the request to retry later and the request must succeed before the user
can proceed, delay the user experience (e.g., a modal “loading” dialog) and retry the request. You
should cap the retries at a hard number so your application isn’t rate limited.

Standard error codes


The API will return errors depending on a variety of conditions. Typically these stem from partial,
inaccurate, malformed, or incomplete data from your application, or because you don’t have proper
extended permissions (http://developers.facebook.com/docs/authentication/permissions) to
make an API call on behalf of a user.

6
Solution: Pull from cache
If a read request fails, you should handle the error gracefully, log it, and revert to your server cache.
This will maintain the user experience while you can investigate your code. In order to set proper
Exceptions, see http://developers.facebook.com/docs/reference/api for a list of API endpoints;
click on each for the list of errors.

Solution: Investigate your code


The majority of the time, errors like these will introduce themselves because there’s a bug in your
code. E.g., you’re making assumptions of the extended permissions you have for users, or there was
an application change pushed that is passing incorrect parameters to the API.

Unexpected error code returns


Your application may receive an error you didn’t expect because it wasn’t documented on the
Developers site.

Another potential issue is that you will receive a known error like “Invalid signature”, but it might
be a red herring. This can stem from server issues within the API and should be handled gracefully.

Solution: Implement exceptions


You should have an exception to catch arbitrary errors like these, log them, and let the user
continue their experience, if possible.

Empty or bad data returned


There may be times when empty data is returned by the API server.

Solution: Assume the call was successful


If the call is non-critical—e.g., publishing to the user’s stream—you should just assume the call was
successful and allow for the user experience to continue. In the case that it’s a write call, like
publishing to a user’s stream, do not call the endpoint again. This prevents spam in case the call
actually did succeed.

Solution: Pull from cache


This will only work for read requests that fail. If you store Facebook data in a cache, you should
resort to that even if it’s stale.

Solution: Store, delay, and retry the request asynchronously


If possible, store the request and let the user experience progress so they’re not inhibited. Then,
retry the request in a separate thread multiple times over a delayed interval. You should cap the
retries at a hard number so your application isn’t rate limited by the API server.

Solution: Cancel the request


Display an error to the user if the user experience is broken due to the bad data, otherwise fail
silently so that the user can progress and log the issue.

7
Solution: Retry the request synchronously
If it’s not possible to store the request to retry later and it’s imperative that the request is
successful, delay the user experience (e.g., a modal “loading” dialog) and retry the request. You
should cap the retries at a hard number so your application isn’t rate limited.

High latency
Your application might experience high latency between it and the API server. This can be the result
of numerous issues including technical difficulties on your server, on the API server, latency
between your server and the API server, DNS issues, or other problems.

Solution: Call the API asynchronously


If you don’t need to rely on the return of the call for the user experience, you should call it
asynchronously so that it doesn’t impede the user. E.g., publishing to the user’s wall.

Solution: Pull from cache


For read queries that are slow, you should just revert to your local cache. Once the call returns
successfully, refresh the cache.

Solution: Preloading information


If possible, you should preload information specific to Facebook. E.g., if the user is viewing a
carousel of Facebook photos, you should preload 5-10 photos, anticipating that the user will
eventually view them.

Rate limited (API_EC_TOO_MANY_CALLS)


If your application is making too many calls, the API server might rate limit you automatically,
returning an “API_EC_TOO_MANY_CALLS” error
(http://wiki.developers.facebook.com/index.php/Error_codes).

Solution: Optimize your calls


Generally, this should not happen. If it does, it is because your application has been determined to
be making too many API calls. Iterate on your code so you’re making as few calls as possible in
order to maintain the user experience needed. You should also avoid complicated FQL queries. To
understand if your application is being throttled, go to Insights and click “Throttling”.

Potential Issues: Social Plugins

IFrames

High latency
The API may experience intermittent high latency, which will cause the IFrame to load very slowly,
or it might time out.

Solution: Add “onLoad” to IFrame


Add the “onLoad” parameter to your IFrame and specify a JavaScript callback that will be pinged
once the IFrame is completely loaded. Create a parallel function that monitors the total time that

8
has amassed since the user loaded the page. If you think the call is taking too long (determined by
you) and the “onLoad” callback hasn’t been pinged, swap the IFrame out with other content or hide
it.

Firewall blocking content


If a user is behind a firewall (e.g., at work), the Facebook content may fail to load properly.

Solution: N/A
There isn’t a way to proactively handle this problem gracefully if you use an IFrame. Instead use,
XFBML with the JavaScript SDK and see the suggestion in the XFBML section below.

Load successful, display broken


There may be scenarios where the plugin appears to load successfully, but the display is actually
broken (e.g., if you’re specifying a JavaScript callback).

Solution: N/A
There isn’t a way to proactively handle this problem gracefully if you use an IFrame. Instead use,
XFBML with the JavaScript SDK and see the suggestion in the XFBML section below.

Server error 500, failure to load


There may be scenarios where the fails to load properly because of a server error.

Solution: N/A
There isn’t a way to proactively handle this problem gracefully if you use an IFrame. Instead use,
XFBML with the JavaScript SDK and see the suggestion in the XFBML section below.

General error

There isn’t a way to proactively handle this problem gracefully if you use an IFrame. Instead use,
XFBML with the JavaScript SDK and see the suggestion in the XFBML section below.

FBML/XFBML

Firewall blocking content


If a user is behind a firewall (e.g., at work), the Facebook content may fail to load properly.

Solution: Subscribe to “xfbml.render”


In JavaScript, you can subscribe to Like button events. You can subscribe to “xfbml.render”, which
enables you to know when the Like button has properly loaded. When the page first loads, you can
start a timer also waits for the “xfbml.render” event to be fired. If it doesn’t fire after a certain
amount of time (determined by you), you can swap the plugin out and log the error. For more
information, see http://developers.facebook.com/docs/reference/javascript/FB.Event.subscribe.

9
High latency
If the API server may have high latency, which will cause the IFrame to load very slowly, or it might
time out.

Solution: Subscribe to “xfbml.render”


In JavaScript, you can subscribe to Like button events. You can subscribe to “xfbml.render” which
enables you to know when the Like button has properly loaded. When the page first loads, you can
start a timer that waits for the “xfbml.render” event to be fired. If it doesn’t fire after a certain
amount of time (as determined by you), you can swap the plugin out and log the error. For more
information, see http://developers.facebook.com/docs/reference/javascript/FB.Event.subscribe.

Load successful, display broken


There may be scenarios where the plugin appears to load successfully, but the display is actually
broken (e.g., if you’re specifying a JavaScript callback).

Solution: Subscribe to “xfbml.render”


In JavaScript, you can subscribe to Like button events. You can subscribe to “xfbml.render” which
enables you to know when the Like button has properly loaded. When the page first loads, you can
start a timer also waits for the “xfbml.render” event to be fired. If isn’t fired after a certain of time,
you can swap the plugin out and log the error. For more information, see
http://developers.facebook.com/docs/reference/javascript/FB.Event.subscribe.

Server error 500, failure to load


There may be scenarios where the fails to load properly because of a server error.

Solution: Subscribe to “xfbml.render”


In JavaScript, you can subscribe to Like button events. You can subscribe to “xfbml.render” which
enables you to know when the Like button has properly loaded. When the page first loads, you can
start a timer that waits for the “xfbml.render” event to be fired. If it doesn’t fire after a certain
amount of time, you can swap the plugin out and log the error. For more information, see
http://developers.facebook.com/docs/reference/javascript/FB.Event.subscribe.

Failure to load JavaScript file


The JavaScript file may fail to load, which can cause the plugin to not render.

Solution: Load a local copy


The JavaScript library is open source and can be hosted on your server
(http://github.com/facebook/connect-js). Use “readyState” to detect when the JavaScript include
has been loaded. For more information, see http://unixpapa.com/js/dyna.html. If the file hasn’t
loaded, then revert to your local copy.

JavaScript error, failure to load plugin


The JavaScript file may fail to load properly, which can cause the plugin to not render.

10
Solution: Load a local copy of the JS file
The JavaScript SDK is open source and can be hosted on your server
(http://github.com/facebook/connect-js). If you detect there’s an error or the plugin hasn’t loaded,
temporarily load your local copy.

General error
A user can encounter an error like the one below. This can happen for a variety of reasons, but it
usually occurs when your server cannot be reached by our bot that scrapes your site in order to
create the object in the Open Graph.

Solution: Lint your URLs


Facebook offers a URL linting tool at http://developers.facebook.com/tools/lint/. You can input a
single URL and it will return important debug information about the page, including if errors were
discovered or if you’re missing Open Graph Protocol tags. This tool also outputs a JSON array of
information so you can build automated tools to lint your website.

Solution: Ensure our bot can reach your server


Our bot functions with the User Agent “facebookexternalhit/*”. Make sure you’re not blocking that
user agent. Also, make sure the IP ranges at
http://wiki.developers.facebook.com/index.php/Facebook_IP_Addresses can reach your server.

JavaScript Library
Failure to load JavaScript file
The JavaScript file may fail to load, which can cause the plugin to not render.

Solution: Load a local copy


The JavaScript library is open source and can be hosted on your server
(http://github.com/facebook/connect-js). Use “readyState” to detect when the JavaScript include
has been loaded. For more information, see http://unixpapa.com/js/dyna.html. If the file hasn’t
loaded, then revert to your local copy.

JavaScript error
The JavaScript file may fail to load properly.

Solution: Load a local copy of the JS file


The JavaScript SDK is open source and can be hosted on your server
(http://github.com/facebook/connect-js). If you detect there’s an error, temporarily load your
local copy.

11
Miscellaneous
Like button is replacing ad units or Flash
You may notice that the Like button is replacing an ad unit or a Flash movie on your website, or vice
versa. This is because of a conflict between cross domain files. To fix it, specify a custom cross
domain file (see http://wiki.github.com/facebook/connect-js/custom-channel-url).

Large friends lists


Users with large friend lists (e.g., > 500) may create unforeseen issues within your application,
especially if you don’t have any accounts available to test with a large number of friends.

Solution: Test with a user account that has a lot of friends


You should proactively test with a user account that has a lot of friends, which will help you detect
this type of issue.

Solution: Spoof a user account to test


Create a test that emulates a Facebook user with a large number of friends (> 1000). This will help
diagnose bugs before you go live with your product.

Cross-domain cookies do not work in Safari


The user authentication information is stored in cookies; however, Safari does not (by default)
allow cross-domain cookies to be set. Without the cookie, the app loses the user authentication
information across requests.

Solution: Set a P3P header


See http://anantgarg.com/2010/02/18/cross-domain-cookies-in-safari/.

Tools to Debug
Test accounts
You can create test Facebook user accounts by going to
http://wiki.developers.facebook.com/index.php/Test_Accounts. This ensures that Facebook’s
automated user integrity tools will not disable your accounts.

Firebug (Firefox only)


Firebug is a great Firefox add-on to quickly debug DOM and JavaScript related issues. You can
easily inspect and edit HTML/CSS elements while you view the webpage. Also, you can execute
JavaScript within your browsers. For more information and to download the tool, go to
http://www.getfirebug.com/.

HTTP Live Headers (Firefox only)


The Live Headers add on for Firefox is useful to see an assortment of issues, including redirect
problems. Get it at https://addons.mozilla.org/en-US/firefox/addon/3829/.

12
Charles and Fiddler
Charles and Fiddler are very useful tools to understand what API calls are being made and what is
being returned. To download them, visit http://www.charlesproxy.com/ or
http://www.fiddler2.com/fiddler2/.

Internet Explorer
You can debug visual issues for multiple versions of IE simultaneously using Expression Web
SuperPreview (http://expression.microsoft.com/en-us/dd565874.aspx) or by using Virtual
Machines (http://www.microsoft.com/downloads/details.aspx?FamilyID=21eabb90-958f-4b64-
b5f1-73d0a413c8ef&displaylang=en). To debug Javascript and DOM problems, use “Developer
Tools” in IE 7+.

Chrome and Safari


DOM and Javascript issues can be inspected in Chrome by viewing “Developer tools”. In Safari,
these can be debugged using the “Web Inspector”.

Tools to Track Platform Changes


“Push Changes” on the Developer’s Wiki
Generally, we push changes weekly. You can see the major changes we’ve pushed each week by
visiting http://wiki.developers.facebook.com/index.php/Push_Changes.

Testing changes on beta.facebook.com


Before we push changes, we update our beta tier so developers can test them. You should regularly
test your app on our beta tier to ensure everything is functioning properly. You can do this by
pointing your API calls to beta.facebook.com.

Migrations settings
To ensure applications are not broken by data structure changes, we have a UI where you can easily
turn new functionality on or off. You can view the “Migrations” tab by visiting
http://www.facebook.com/developers/apps.php, and editing the settings of your application.

Platform Live Status feed


If your application is having issues you believe are due to Platform, check
http://developers.facebook.com/live_status. This is an up-to-date view of known issues and allows
you to quickly check the general health of Platform.

Additional helpful links


 http://developers.facebook.com/blog/
 http://forum.developers.facebook.com/
 http://wiki.developers.facebook.com/index.php/IRC_channel

13
Reporting Issues
1. Search for a similar bug at http://bugs.developers.facebook.com/.
2. If a bug doesn’t exist, file one. For best practices, see
http://bugs.developers.facebook.com/page.cgi?id=bug-writing.html.
3. If it’s critical, send the report to your technical contact at Facebook.

Alternatively, you can utilize the Developer Forum at http://forum.developers.facebook.com/ or


our IRC channel at #facebook on irc.freenode.net.

14

You might also like