Not so long ago we wrote about the need to keep your social gadgets
robust to adversity. We received a lot of questions about how to detect when social conditions have broken down, and what to tell users when they have. So here's a quick cheatsheet for how to determine what might be interfering with the normal operation of your gadget, and what to do about each of them.
- The user is in a domain without canvas view.
All gadgets that take advantage of canvas view should also be prepared to support those domains for which canvas view is not available. To confirm that a canvas view is available, you can insert a Content section without a view specified, as outlined in this blog post. If your gadget does not support a home view only environment, we suggest telling the user "This gadget requires a feature that is not available in your locale at this time. Please check back at a later date." For more on views, check out the iGoogle Developer Guide.
- The user is in a domain where OpenSocial is not available.
If a user is in a domain where canvas view is available a good next step is to test whether that domain has access to OpenSocial functionality. A gadget can determine if the user is on an OpenSocial supported domain or not by calling gadgets.util.hasFeature('opensocial-0.8'), which will return true if the domain supports OpenSocial. If your gadget requires OpenSocial to operate correctly, we recommend you tell the user "This gadget requires a feature that is not available in your locale at this time. Please check back at a later date."
- The user is not signed in.
Remember that a significant portion of iGoogle's users are not signed in and won't have any available social information to draw from. A gadget can determine if the user has signed in or not by making a request for the owner or viewer and checking the ID of the user. A logged out user is considered anonymous, and will have a viewer ID of -1. If your gadget requires access to OpenSocial information in order to operate we suggest you give users the message "This gadget cannot access the information it needs so that you can share or collaborate with friends. Please sign in to enable access." In many cases, of course, gadgets can still function even without social features. In that case - we suggest the message "This gadget lets you share and collaborate with friends on iGoogle. Sign in to use these features."
- The user has not enabled the gadget's social access.
After installing a gadget a user will be prompted to enable that gadget to access their friend list and activity stream. If the gadget makes an OpenSocial request for information that the user has not enabled access to, it will fail with error code 403 (FORBIDDEN). If your gadget needs access to one or both of these datasets, we recommend the message "This gadget cannot access the information it needs so that you can share or collaborate with friends. Please adjust the gadget's settings to enable access." Similarly if your gadget can still function without access to these social features we recommend the message "This gadget lets you share and collaborate with friends on iGoogle. Please adjust the gadgets settings to use these features." Remember that all users will see your gadget displayed without social access at least once, so make sure your gadget handles this case gracefully!
- The user hasn't added any friends.
Finally remember that most users will begin with no friends on their friends list. If your gadget needs friends in order operate normally, we recommend that you use tell your users "You can use this gadget to share and collaborate with friends on iGoogle. Share with friends." where you can link "share with friends" to the requestShareApp call, which allows users to simultaneously add friends and invite them to add your gadget.
By keeping these cases in mind you should be able to help ensure your users get the most out of the social functionality of your gadget. To see an example of how to detect these and other conditions in a live gadget, check out the newly updated
Testing iGoogle State gadget.
Tyler Odean, Associate Product Manager, iGoogle Team
