Académique Documents
Professionnel Documents
Culture Documents
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.
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.).
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.
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.
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.
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.
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.
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.
IFrames
High latency
The API may experience intermittent high latency, which will cause the IFrame to load very slowly,
or it might time out.
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.
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.
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.
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
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.
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.
JavaScript Library
Failure to load JavaScript file
The JavaScript file may fail to load, which can cause the plugin to not render.
JavaScript error
The JavaScript file may fail to load properly.
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).
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.
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+.
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.
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.
14