The more things change, the more they stay the same

The legacy gadgets API has had a storied life, as both the first version of the gadgets API that drove iGoogle, and the direct predecessor of the current gadgets.* API. As with many APIs there comes a time when we must say goodbye to the past, and embrace the present. The gadgets.* API has gained wide acceptance, both on Google and non-Google gadget containers, and is the standard API for gadget development. And so, as of today, the legacy gadgets API is officially deprecated.

I'll give you all a moment to wipe away the tears of sadness (or joy as the case may be). Now, here are the details:

• The legacy API is officially deprecated as of today, September 14th.
• For three months, the legacy API will continue in its current state.
• On or around December 14th, any new gadget submissions to the iGoogle directory must be using the gadgets.*, in order to be accepted, but existing gadgets may continue to use the legacy API.
• On the same date, the remaining inlined gadgets will be disabled.
• Finally, one year after deprecation, September 14th, 2010, gadgets using the legacy API will cease to function on iGoogle, and the majority of other Google-owned gadget containers (such as orkut, Gmail, and Calendar).
• Reminders will be posted when these important dates approach.

We're also working on some tools to aid you in the transition: a gadget migration tool that will parse your existing gadget and convert legacy calls to gadgets.*, and a migration guide for developers who wish to migrate their gadgets by hand. Watch for announcements on these tools in the next few weeks.

For most gadgets, the changes should be simple to implement. For each _IG_* method, there is usually a direct equivalent gadgets.* method. For instance, _IG_AdjustIFrameHeight maps directly to gadgets.window.adjustHeight, and performing a find and replace is sufficient. In a small subset of cases, multiple _IG_* methods map to a single gadgets.* method. For instance, _IG_FetchContent and _IG_FetchXmlContent both map to gadgets.io.makeRequest with different parameters. Developers should refer to the relevant section of the developer's guide to find gadgets.* equivalents.

If you have any questions, as always, feel free to inquire in the iGoogle Developer Forum.

Posted by Dan Holevoet, Developer Programs

iGoogle is a social being

If you've been a devoted reader of this blog you're probably no stranger to the idea that "social is better" when it comes to the web. Activities such as reading the news, doing a crossword puzzle, sharing a todo list, or watching a video are all better when done with a friend. Coincidentally, these are all things that iGoogle users love to do, so bringing social to iGoogle is a logical next step.

Developers have had a chance to sneak a peek at what iGoogle has been doing in the social space for many months, in the iGoogle developer sandbox. As of today, social gadgets taking advantage of the OpenSocial API will now work in both the US and Australia, with other countries soon to follow. That's tens of millions of iGoogle users with access to social gadgets, if you're keeping count.

Of course, iGoogle is a little bit different than most of the sites which support OpenSocial, so here's a quick rundown of the differences:

1. An iGoogle page is personal, and not shared with other users. In OpenSocial terms, this means that VIEWER and OWNER are always the same person.
2. Friendship between two users may be non-mutual. This allows developers to use a "following" model in their applications. For cases where it's important to verify mutual friendship (sharing private data, for instance), developers can use the isFriendsWith filter when requesting the user's mutual friends.
3. iGoogle has users without canvas view, with canvas view but without social, and with social, all at the same time. And, some users sign in to use iGoogle while others remain signed out. Developers should make sure their gadgets work gracefully across feature sets so that users always have the optimal experience. This blog post provides more details and an example gadget for checking different cases.
4. iGoogle supports organic growth of applications with two mechanisms.
   • Application sharing (via requestShareApp), allows developers to reach a wider audience by encouraging users to engage their friends inside of a given application. By default, requestShareApp will list all of the user's Friends and users can auto invite new friends by email. iGoogle will email recipients without iGoogle accounts, or present a notification within the UI to existing iGoogle users to add the gadget and become friends.
   • Updates (via requestCreateActivity), allow developers to call out specific user actions, to share them with a wider audience. There is a current limit of 3 updates per user, per app, per day, which may be increased in the future.

To see some great examples of new (or upgraded) gadgets using social features, check out this page. Then, when you're ready, take a look at the getting started guide for details on writing your own social gadgets for iGoogle. As always, if you have questions, please visit us in the iGoogle Developer Forum.

Posted by Dan Holevoet, Developer Programs

Every happy gadget is the same, every unhappy gadget is unhappy in its own way

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.

1. 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.
2. 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."
3. 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."
4. 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!
5. 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

Announcing UX improvements in the sandbox

Over the last few days, we've introduced several improvements to the sandbox to help flesh out what the full social experience will look like for your users.

First, sharing a gadget is a richer experience — requestShareApp invites now display notifications at the top of the invitee's iGoogle page and in the "gadget shares" link on the left nav bar. This system smoothly handles all the different use cases for you. If you invite a friend who does not yet use iGoogle, they will receive an email inviting them to join iGoogle and to share the gadget with you. Then, if your friend creates an account they will be prompted to add you as a friend. If your friend already has iGoogle but does not have you listed as a friend and/or does not have the gadget, they will see one of the new social notifications prompting them to add the gadget and/or to add you as a friend, respectively. Finally if the friend you invited already has you as a friend and the gadget, they'll get a dismissable message saying that you have invited them. As a developer you won't have to worry at all about whether or not someone uses iGoogle, has the gadget, or is friends with the user — requestShareApp will handle that all transparently for you!

Next, you can delete the "Sandbox Friends" gadget, because our real control for editing and expanding your friends list is here, living in the "Friends" link on the left hand nav bar. This, in addition to the prompts described above, is how users will add friends to their accounts.

And finally, the Updates gadget continues to improve — multimedia Updates should be displaying much more cleanly now, and you can also filter Updates for those posted by your own gadgets. Remember that the final version of Updates, like the friends control and social notifications will live on the left nav bar, and gadgets will be limited to three Updates per user per day.

Posted by Dan Holevoet, Developer Programs

Stem the 401 Tide

Some of you may have noticed that OpenSocial API calls in the sandbox have started returning 401s, regardless of whether or not you've enabled social ACLs in your gadget. We're in the process of changing a few things behind the scenes, one of which has the unfortunate side effect of breaking the ACL check. While this is straightened out, make sure to visit: http://www.google.com/ig?force_sandbox=1 for a squeaky-clean and error-free sandbox.

Posted by Dan Holevoet, Developer Programs