iGoogle Developer's Guide

This guide will help you build and manage gadgets within the iGoogle environment. It is meant for developers who have some general familiarity with iGoogle, the Gadgets API, and JavaScript. The guide also provides links to other resources relating to gadget development in iGoogle.

Contents

1. Getting familiar with gadgets in iGoogle
   1. iGoogle gadget terminology
   2. Anatomy of an iGoogle gadget
   3. Writing your first iGoogle gadget
   4. Using the Google Gadgets Editor to host your gadget
   5. Adding a gadget to iGoogle
   6. Viewing your gadget
   7. Setting up the development environment
2. Gadgets
   1. Views
   2. Concatenating views
   3. Determining the current gadget view
   4. Getting all available views
   5. Designing for the home view
   6. Designing for the canvas view
   7. Navigating to another view
   8. Obtaining the gadget's ID
   9. Passing data to your gadget through requestNavigateTo()
   10. Sharing gadgets
   11. Sharing user preferences
   12. Managing Access Control
3. Updates
4. Profile data
5. Appdata limitations
6. Publishing gadgets to the iGoogle content directory
   1. Using the Gadget Checker to test your gadget
   2. Using the Gadget Dashboard
7. Creating an "Add to Google" button
   1. Setting userprefs in the "Add to Google" URL
8. Supported languages and countries
9. To learn more

Getting familiar with gadgets in iGoogle

Each gadget container has a different development experience. This section describes the process of developing gadgets for use on iGoogle.

iGoogle gadget terminology

This guide uses the following terms to describe elements and topics related to the iGoogle development experience.

Gadget	Third party code that uses the gadgets and OpenSocial APIs to extend the iGoogle experience.
Gadget definition	XML file that defines the gadget. Syntax is based on gadget XML, also known as the "gadget spec".
Gadget directory	Listing of available gadgets, ranked based on popularity and user feedback.
Left navigation	The list of links on the left hand side of iGoogle pages. The left navigation lists links to the canvas view for each gadget on a user's page.
Left navigation link	A link on the left navigation that opens a gadget's canvas page.
View	The location where a gadget is displayed. In iGoogle, gadgets can be displayed on either the canvas or home views. Both views are private. iGoogle does not allow users to see each other's gadgets.
Home view	The small view for a gadget, displayed with other gadgets. Shows all of your gadgets in their small display format. The home view is private, meaning that it is only visible to the logged in user.
Canvas view	The large view for a gadget, displayed alone without any other gadgets. The canvas view is private, meaning that is it only visible to the logged in user.
Friends	The OpenSocial API provides access to a user's network of friends. In iGoogle, you add friends using the Friends link in the left navigation.

Anatomy of an iGoogle gadget

Before building gadgets for iGoogle it is useful to first familiarize yourself with the various features of gadgets and how they work together. A helpful guide is the Anatomy of an iGoogle Gadget document.

Writing your first iGoogle gadget

If this is your first gadget, follow the steps listed in the OpenSocial Tutorial to familiarize yourself with the OpenSocial API. This tutorial covers the steps needed to develop a simple gift-giving gadget using the OpenSocial API.

Updating an existing iGoogle gadget

If you have an existing gadget you can enhance it to take advantage of some of the new features offered through the iGoogle sandbox, including:

• Views
• Friends

Using the Google Gadgets Editor to host your gadget

If you do not have access to a server to store your gadget XML files, the Google Gadgets Editor (GGE) is a great tool to quickly edit and host gadgets. To create a quick "Hello World" gadget, make sure that you are logged in with a Google account (or else you cannot save your gadget) and modify the following gadget in GGE. For example, change the message "Hello, world!" to "Hello, iGoogle!":

Use File > Save As to save the file with the name "igoogle-sample.xml." Once you've done this, open your gadget's XML file by clicking on the filename in the top right-hand corner of the editor.

This opens the gadget XML in your browser. You'll need the URL of this file to install your gadget in the next section.

Adding a gadget to iGoogle

Gadgets need to run inside of a container in order to access social network data. iGoogle offers a developer sandbox where you can access the OpenSocial APIs and other new features. You can sign up for the sandbox here.

To add a new gadget:

1. Click the Personalize this page button. This takes you to the iGoogle directory. From the directory you can add an existing gadget, or you can add your own gadget.
2. To add your own gadget (for example, the "Hello World" gadget you created above), click the add feed or gadget link at the bottom of the left nav bar.
3. Type the URL for the gadget into the text field, and click Add.
4. Click the Back to iGoogle home link (upper left corner) to return to the sandbox and see the gadget you just added.

You can also add gadgets through the developer gadget, once you've added the developer tools tab.

Viewing your gadget

The iGoogle sandbox provides two different views for displaying your gadget. The first is the home view. In the home view, your gadget displays in a 3-column format along with any other gadgets you've added:

To see a gadget at its maximum size, you can display it in the canvas view by clicking its link under Home. By default, gadgets only display in their small format. For information on adding a canvas view to your gadget, see Views.

For example, here is a books gadget in the home view. It simply lists the user's reading list, the user's friends' books, and recommended books:

The book gadget's expanded canvas view offers a richer experience, with tabs, more detail about the user's books, and the user's reviews:

The home and canvas views in iGoogle are private, meaning that they cannot be viewed by anyone but the logged in user. This is a key distinction between iGoogle and some other social gadget containers, such as orkut.

Setting up the development environment

To set up your sandbox development environment, log into the sandbox and add the developer gadget and add the Sandbox Profile Editor gadget.

Developer gadget

The developer gadget acts a "command center" for all of the gadgets on your iGoogle page. In addition to listing all the gadgets that you're running, it lets you add, view, and manage gadgets. The developer gadget gives you features that you need if you're doing gadget development. For example, it lets you add gadgets that are "broken," which is useful when you are actively changing a gadget.

In the developer gadget you can click on individual gadget links to view their XML specifications. This is a good way to see how other gadgets are implemented.

One feature that helps you in developing gadgets is the Cached checkbox. By default, gadget specifications are cached. You should uncheck Cached for gadgets while you are working on them. This lets you see the latest version of your gadget instead of the cached version.

Sandbox Profile Editor gadget

The Sandbox Profile Editor gadget lets you edit your iGoogle sandbox profile. Note that the only profile information that is accessible through the API is the user ID, name, location, and thumbnail URL. For more information, see Profile data.

Gadgets

Now that you've learned the basics for installing and updating gadgets, here are some tips and tricks to help you build gadgets that take advantage of the features of the iGoogle sandbox.

OpenSocial gadgets are a new type of gadget, based on gadgets technology, but extended to interact with social data retrieved from a website (also referred to as a container) that supports the OpenSocial API. iGoogle is an example of an OpenSocial container, and this section focuses on the development aspects of working with gadgets within the iGoogle environment.

Views

A view is a location in a container where a gadget is displayed. Different views have different characteristics. For example, a container might have a view that shows gadgets in a small format, and a view that shows gadgets in full page format.

By default in the iGoogle sandbox, a gadget displays in home view mode ("small mode"), meaning that it appears in a column layout among other gadgets. To create a canvas ("big mode") view of your gadget, where the gadget expands horizontally to span the entire gadget area, you must define a <Content> section for the "canvas" view type, as follows:

<Content type="html" view="canvas"> 

Once you define a <Content> section for the canvas view, you must also create a <Content> section to make the gadget display properly in the home view. This can either be "default" or "home". For more discussion of writing gadgets that support multiple <Content> sections, see Multiple Content Sections.

Here is a version of the Hello World gadget that defines <Content> section views for "home" and "canvas". Its width changes according to whether you display it in the home view or the canvas view.

<?xml version="1.0" encoding="UTF-8" ?>
<Module> 
  <ModulePrefs title="Hello World!">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="home">
    <![CDATA[
      Hello, small world!
    ]]>  
  </Content>
  <Content type="html" view="canvas"> 
    <![CDATA[
      Hello, big world!
    ]]> 
  </Content>
</Module>

Concatenating views

Views are supported across OpenSocial containers, but each container may support a different set of views. For example, iGoogle has a small view called home, but the small view in orkut it is called profile.

Suppose you want to write a gadget that had the same display for home on iGoogle and profile on orkut. Instead of creating duplicate <Content> sections, you could concatenate the views for a single <Content> section, as follows:

<Content type="html" view="home,profile">

You can use this technique either across containers or within the same container. For example, gadgets that handle presentation logic for differently sized views in a single <Content> section can extend that support to the canvas page by declaring view="home,canvas".

Determining the current gadget view

In iGoogle, your gadget can be displayed in the canvas and home views. Both views are visible only to the logged-in user.

The easiest way to get the current view is to include the "views" feature in your gadget module preferences:

<ModulePrefs title="Views example"> 
  <Require feature="views" />
</ModulePrefs>

When the views feature is included, you can obtain the current view by calling the gadget.util.getCurrentView() function. This assigns a gadgets.views.View object to the current_view variable. See Available views in iGoogle for a listing of views that may be returned by this call.

The following example demonstrates getting the current view and conditionally executing code against the returned value:

function getViewName() {
  return gadgets.views.getCurrentView().getName();
}

if (getViewName() == "canvas") {
  /* Do canvas specific stuff here */
}

if (getViewName() == "home") {
  /* Do home specific stuff here */
}

Getting all available views

Obtain the available View objects by calling the gadgets.views.getSupportedViews() function.

var supported_views = gadgets.views.getSupportedViews();

The object returned by the getSupportedViews call contains gadgets.views.View objects representing all of the available views in iGoogle, indexed by view name.

Designing for the home view

The gadget's home view shows content and notifications that are the most interesting to the user. It’s a good place for summarizing content, and for providing a quick way for users to complete simple tasks.

• Remember that only the logged in user can see the home view. It is private.
• Gadgets should be flexible in width to accommodate various screen resolutions and maximize space efficiency.
• Recommended minimum width: 260 px (based on a 1024x768 resolution). Note that this is 40 px less due to the new left navigation.
• Height can vary. More concise gadgets tend to be more popular because users sacrifice less space for other gadgets.
• Users can access a gadget’s settings, remove a gadget, or go to canvas view by clicking buttons in a gadget's title bar.
  

Designing for the canvas view

The gadget's canvas view provides an expanded space to allow richer content and greater functionality. Take advantage of this view to engage users, show them what their friends are doing, and allow them to complete complex tasks.

• Remember only the logged in user can see the canvas view. Like the home view, it is private.
• Gadgets should be flexible in width to accommodate various screen resolutions and maximize space efficiency.
• Recommended minimum width: 800 px (based on a 1024x768 resolution).
• Height can vary. Unlike home view, in canvas view only one gadget is being shown so take advantage of the additional space.
• Note that old gadgets will continue to work in the home view. The home view is the default. To benefit from canvas view, we encourage developers to add a canvas view to their existing gadgets, as described in Views.

Navigating to another view

If you wish to provide links to other views, you need to pass a gadgets.views.View object to the gadgets.views.requestNavigateTo() method. You can choose to use one of the objects returned by the getSupportedViews() call described in the Available views in iGoogle. The following code sample demonstrates this method:

  function navigateTo(dest) {
    var supported_views = gadgets.views.getSupportedViews();
    gadgets.views.requestNavigateTo(supported_views[dest]);
  };

  /**
   * When called, this method asks the container to switch to the canvas
   */
  function gotoCanvas() {
    navigateTo("canvas");
  };

  /**
   * When called, this method asks the container to switch to the home
   */
  function gotoHome() {
    navigateTo("home");
  };

An alternative is to create a new View object manually, and then use that to initiate navigation. The following code sample shows creating a new gadgets.views.View object and passing it to the gadgets.views.requestNavigateTo() method:

  /**
   * When called, this method asks the container to switch to the canvas
   */
  function gotoCanvas() {
    var canvas_view = new gadgets.views.View("canvas");
    gadgets.views.requestNavigateTo(canvas_view);
  };

  /**
   * When called, this method asks the container to switch to the home
   */
  function gotoHome() {
    var home_view = new gadgets.views.View("home");
    gadgets.views.requestNavigateTo(home_view);
  };

Here is a complete example based on the "Hello World" gadget:

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs height="100" title="Navigation">
    <Require feature="views" /> 
  </ModulePrefs>
  <Content type="html" view="home">
  <![CDATA[ 
  <div>Hello world Home view</div>
  <script type="text/javascript">
  
    function goToView(dest) {
      var supported_views = gadgets.views.getSupportedViews();
      gadgets.views.requestNavigateTo(supported_views[dest]);
    };
  </script>

  <a href="javascript:goToView('canvas')" >Go to canvas view</a><br><br>

  ]]> 
  </Content>
  <Content type="html" view="canvas">
  <![CDATA[ 
  <div>Hello world Canvas view</div>
  <script type="text/javascript">
  
    function goToView(dest) {
      var supported_views = gadgets.views.getSupportedViews();
      gadgets.views.requestNavigateTo(supported_views[dest]);
    };
  </script>
  <a href="javascript:goToView('home')" >Go to home view</a><br><br>
  ]]> 
  </Content>
  </Module>

Obtaining the gadget's ID

Note: In OpenSocial 0.8, there is no call to return your gadget's ID number. Store this value manually if you wish to use it in your gadget.

Passing data to your gadget through requestNavigateTo()

If you are using the gadgets.views.requestNavigateTo() calls, you may supply an optional parameter containing data to be passed to the new page.

The following code passes two variables: foo and bar to the canvas surface of the current gadget:

  function gotoCanvas(params) {
    var canvas_view = new gadgets.views.View("canvas");
    gadgets.views.requestNavigateTo(canvas_view, params);
  };

  var my_params = {
    foo : 12345,
    bar : "Bar value"
  };

  gotoCanvas(my_params);

In the canvas view, check for these values with the following code:

  var prefs = gadgets.views.getParams();
  var foo = prefs["foo"];
  /* foo contains 12345 */

  var bar = prefs["bar"];
  /* bar contains "Bar value" */

Sharing gadgets

In iGoogle, each gadget has a menu that includes a Share this gadget menu item. Share this gadget launches a popup that lets you select recipients from your list of iGoogle friends. You can also specify unlisted recipients by email address. This is the default mechanism for sharing gadgets.

But suppose you want to customize how your gadget gets shared. For example, maybe you want to display a custom message, or modify the list of potential recipients. You can customize gadget sharing by using the requestShareApp() method.

The requestShareApp() method takes the following parameters:

Name	Type	Description
recipients	opensocial.IdSpec	An IdSpec used to specify which people/groups to send the request to. Note that the maximum number of IDs that can be passed in is 50. Any IDs beyond that number are ignored.
reason	opensocial.Message	The reason the user wants to share the gadget. This reason can be used by the container when prompting the user for permission to share the app. It may also be ignored.
opt_callback	Function	The function to call once the request has been processed; either this callback is called or the gadget is reloaded from scratch. The callback function is not called until after the existing callstack has completed execution. The callback function is passed one parameter, an opensocial.ResponseItem. The error code is set to reflect whether there were any problems with the request. If there was no error, the sharing request was sent. If there was an error, you can use the response item's getErrorCode method to determine how to proceed. The data on the response item is not set. If the container does not support this method, the callback is called with an opensocial.ResponseItem. The response item has its error code set to NOT_IMPLEMENTED.
opt_params	opensocial.NavigationParameters	The optional parameters indicating where to send a user when a request is made, or when a request is accepted; options are of type NavigationParameters.DestinationType.

Example

Here is a simple example that illustrates how requestShareApp() works in iGoogle. It's a gadget that has a button that lets users share the gadget with their friends.

When users click the Share me! button, they see a popup that lets them specify the friends with whom they want to share the gadget.

Here is the code for the sample gadget:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs height="325" title="requestShareApp Example" >
  <Require feature="views" /> 
  <Require feature="opensocial-0.8" />
</ModulePrefs>
<Content type="html" view="home, canvas">
<![CDATA[ 	  
 <script type="text/javascript">
 function shareApp() {
   var recipient = null;	
   var reason = opensocial.newMessage('Install this gadget to help share the love.');	  
   opensocial.requestShareApp(recipient, reason, function(response){
     if (response != null && response.hadError()) {
       alert('requestShareApp Error Code[' + response.getErrorCode() + '] Msg: ' + response.getErrorMessage());
     } else if (response != null) {
       alert ('requestShareApp OK, Data[' + gadgets.json.stringify(response.getData()) + ']');
     } else {
       alert('requestShareApp callback has null response');
     }   });
};     	
 </script>
 <div style="text-align: center">
   <img src="http://gadget-doc-examples.googlecode.com/svn/trunk/images/Trevor.png" />
   <br><br>
   <input type="button" onclick="shareApp()" value="Share me!"/><br><br>
</div>
  ]]>
</Content>
</Module>

Note the following:

• For Google users, the data passed to the callback is an array of ["name", "ID"], where name is the contact's name, and ID is the OpenSocial ID.
• For non-Google users, the data passed to the callback is an array of ["email-fragment", "-1"], where email-fragment is the portion of the user's email before the "@". ID is always -1 in this case.

How do friends receive your invitation?

When you share a gadget with friends, how they receive the invitation depends on whether they have an iGoogle homepage:

• Friends who have a Google Account and an iGoogle homepage receive their invitation on iGoogle. iGoogle lists gadget invitations under the Gadget shares link in the left navigation bar. It also has a link at the top of the page for any new gadget invitations. When users click the links, they go to the Gadget Shares page, where they can install the gadgets.
• Friends who are listed under a non-GMail address receive email informing them that you are sharing a gadget with them. This email message says "I've shared a <gadget name> gadget with you." It includes the link "Click here to see it on your Google homepage!" When they click the link, it takes them to iGoogle and invites them to create an account if they don't already have one.
• Friends who have a Google Account but who have never created an iGoogle homepage also receive an invitation email.

Sharing user preferences

Note: This feature is being deprecated. To create gadgets that allow multiple users to share editable data, we recommend you use requestShareApp() in conjunction with appdata.

You can use the shareable-prefs feature to make it possible for a gadget's user preferences to be edited by multiple users. Thus, users can share the gadget and see each other's edits. For example, family members could share a grocery list gadget, with each person adding his or her favorite items. User preference data is the part of the gadget state that is hosted by iGoogle. For more information about userprefs, see the Gadgets API Developers Guide.

To share a gadget's userprefs across multiple users, the gadget must include the line <optional feature="shareable-prefs"/> in the <ModulePrefs> section. For example, this gadget uses the list data type userpref to populate a grocery list.

Managing Access Control

Previously, gadgets installed in the iGoogle developer sandbox had implicit access to social data, with no way for users to opt-out without uninstalling the gadget. Now gadgets include a feature that allows users to explicitly grant or deny the gadget access to social data. Gadgets that access social data include the opensocial-x.x feature:

<Require feature="opensocial-0.8"/>

When users install gadgets that use social data (indicated by requiring the OpenSocial feature), they are prompted to give permission to access social data. If a gadget is released without social features and is upgraded, users will be prompted for access within the gadget when the new version is first rendered:

Users must grant permission before gadgets are allowed access to social data. Your gadget should have a graceful fallback if users deny access. Check out the Testing iGoogle State gadget for an example of determining whether or not the user has granted permission to access social data.

For a complete list of iGoogle states and how to handle them, refer to this blog post.

Updates

Updates are activities posted to a user's friends about actions that the user has made while interacting with an iGoogle gadget. The built-in Updates view displays a running list of all posted updates (activities), starting with the most recent.

Updates in iGoogle have the following characteristics:

• A given user is allowed to post 3 updates per app, per day.
• An Update can include 2 links maximum in the title and body of the update.
• The format for updates should be: <Name> <verb> <content>. For example: Chris Smith shared <link>a news article from nytimes</link>.

This sample gadget lets you enter an update in a text box and then click Post Update to post it to the user's updates feed:

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs title="Post Updates" >
    <Require feature="opensocial-0.8"/>
  </ModulePrefs> 
  <Content type="html">
  <![CDATA[ 
  <script type="text/javascript">

  // Post an activity and set its title to be the text the user entered in the
  // text box.
  function postUpdate(form) {  
    var text = form.inputbox.value;
    var div = document.getElementById('content_div');
    var params = {};  
    params[opensocial.Activity.Field.TITLE] = text;
    var activity = opensocial.newActivity(params); 
    opensocial.requestCreateActivity(activity, opensocial.CreateActivityPriority.HIGH);	
    div.innerHTML = "Update title is: " + activity.getField(opensocial.Activity.Field.TITLE);
  }        
  
  </script>
  <FORM NAME="myform" ACTION="" METHOD="GET">Add Update: <BR>     
    <INPUT TYPE="text" NAME="inputbox" VALUE=""><P>
    <INPUT TYPE="button" NAME="button" Value="Post Update" onClick="postUpdate(this.form)">
  </FORM>
  <div id="content_div"></div>

  ]]> 
  </Content>
</Module>

The above example only accesses the TITLE field of the Activity object. iGoogle also supports these optional fields: BODY, MEDIA_ITEMS, STREAM_FAVICON_URL, and STREAM_URL.

Profile data

The OpenSocial API provides access to information about iGoogle's users in the form of profile data. This section describes which profile fields are available in iGoogle. The iGoogle sandbox provides the Profile gadget for users to edit their profile data.

Supported fields

iGoogle lets you access the following fields for the current user, through a Person object:

• ID -- getId()
• Name -- getDisplayName()
• Thumbnail URL -- getField(opensocial.Person.Field.THUMBNAIL_URL)
• Location -- getField(opensocial.Person.Field.CURRENT_LOCATION)

Appdata limitations

iGoogle limits how much persistent data (appdata) an individual user instance can store (for more discussion of appdata, see The Persistence API). The limit is 10KB. If an attempted appdata write operation exceeds this quota, it will fail with a "quota exceeded" error.

Publishing a gadget to the iGoogle content directory

Once you have designed, implemented, and tested your gadget, you may decide to submit it to Google to be published in the iGoogle content directory. This section lists the general steps you should follow in preparing any gadget to be published.

Using the Gadget Checker to test your gadget

You can use the Gadget Checker to test your gadget before submitting it to the directory. The Gadget Checker includes the following features:

• Gives you multiple ways to specify the gadget you want to test: Google Gadgets Editor (GGE), URL, or the local file system.
• Lets you upload a local gadget to GGE for hosting, if you're not already hosting the gadget elsewhere.
• Tests the gadget for XML formatting and validity, HTML syntax, client-side latency, and unused features. Flags missing content such as metadata, images, scripts, message bundles, and stylesheets.

The following sections provide detailed guidelines for preparing your gadget to be submitted to the content directory.

Step 1: Provide complete metadata.

The Reference lists all of the <ModulePrefs> attributes that you can use to provide "meta" information about your gadget. Here is the information you should include in your gadget spec:

• title
• description. This attribute is important to let people know what your gadget does, particularly if it is not obvious.
• author
• author_email. This is so that Google and users of your gadget can contact you. You can use any email system, but you should not use a personal email address because of spam. One approach is to use an email address of the form helensmith.feedback+coolgadget@gmail.com in your gadget spec. Gmail drops everything after the plus sign (+), so this email address maps to helensmith.feedback@gmail.com. You can create a Gmail account here.
• screenshot. This is a string that gives the URL for a gadget screenshot. This must be a well-formed URL, not a relative URL. This image must be on a public web site that is not blocked by robots.txt. PNG is the preferred format, though GIF and JPG are also acceptable. Gadget screenshots should be 280 pixels wide. The height of the screenshot should be the "natural" height of the gadget when it's in use. This helps users understand how much space a gadget will consume on their screen before they add it to their page. The screenshot should not have any whitespace above the gadget's blue header bar. Screenshots should show your full gadget, including its title bar, but nothing else. Alternatively, you can screenshot the gadget with the edit window open. Screenshots should not be resized or cropped. For quality and consistency, Google may take its own screenshots of a given gadget.
• thumbnail. Thumbnails are used in the content directory to give users a preview of a gadget. They should capture the main functionality of your gadget without showing it in its entirety. The value for this attribute is a string that gives the URL for a gadget thumbnail. This must be a well-formed URL, not a relative URL. This image must be on a public web site that is not blocked by robots.txt. PNG is the preferred format, though GIF and JPG are also acceptable. Thumbnails should be 120x60 pixels. They should not include title bars.

If you want to be listed on the authors page, you can include these additional fields:

• author_photo. URL to a photo (70x100 PNG format preferred, but JPG/GIF are also supported).
• author_aboutme. A statement about yourself (try to keep to ~500 characters).
• author_link. A link to your website, blog, etc.
• author_quote. A quote you'd like to include (try to keep to ~300 characters).

You can find more information here, and an example here.

Step 2: Make sure that you have written a robust, secure gadget.

Make sure you have coded your gadget in a way that minimizes any security risks.

Step 3: Add any relevant locale information.

You can use <Locale> tags under <ModulePrefs> to specify the locales supported by your gadget. For more information, see ModulePrefs/Locale in the gadgets XML reference.

Step 4: Make it easy for people to add your gadget.

To promote your gadget, consider putting an Add to Google button on it.

Step 5: Submit your gadget to Google.

You can submit your gadget to Google here. See the FAQ for an explanation of how to find your gadget in the directory, and what determines its placement.

Managing Submitted Gadgets

If you have submitted multiple versions of a gadget at different URLs and you want to designate one version as the official one, you can use the igoogle-legacy issue tracker to request the change.

Using the Gadget Dashboard

You can use the gadget dashboard to see analytics on your gadgets and manage them.

The dashboard identifies your gadgets through the ModulePrefs author_email attribute:

<ModulePrefs title="My Gadget" author_email="my_username@gmail.com">
   ...
</ModulePrefs> 

Be sure to include the author_email attribute in your gadgets.

To use the dashboard:

1. Sign into iGoogle.
2. Go to the dashboard.
3. Agree to the Terms and Conditions.
4. Once you're in the dashboard, use the add gadget to dashboard button to add gadgets.

The first time you add a gadget with a new author email address, the dashboard sends you email at that address asking you to verify that you want to add the gadget. You only need to verify each email address once.

The dashboard displays the following information for each gadget you add:

Label	Description
Title	The gadget's title.
Users worldwide	The number of unique users who loaded this gadget in the last 7 days.
Page views	The number of times this gadget has been loaded by users in the last 7 days.
Comments worldwide	The comments your gadget has received from users.
Status	Whether your gadget has been added to the iGoogle directory. If it has not been added, the dashboard gives you the option of adding it.

Creating an "Add to Google" button

You can create an "Add to Google" button and put it on your website to help users find your gadget.

To create an "Add to Google" button for your gadget, go to Add to Google and follow the instructions.

When you generate the HTML to add to your web page, it resembles the following:

<a href="http://fusion.google.com/add?source=atgs
&moduleurl=http%3A//gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/prefs-example.xml">
<img src="http://gmodules.com/ig/images/plus_google.gif" border="0" alt="Add to Google"></a> 

The portion of the HTML snippet highlighted in red is the URL that actually adds the gadget to iGoogle. You can even paste this URL directly into the address field of a browser to add the gadget. You can also manually modify this URL to set initial values for userprefs, as described in the next section.

Setting userprefs in the "Add to Google " URL

If you have a gadget that includes userprefs and you want to add the gadget with settings other than the defaults specified in the gadgets spec, you can append the new userpref settings to the "Add to Google" URL.

The syntax is as follows:

http://fusion.google.com/add?source=atgs&moduleurl=[GADGET_URL]&up_[PREF_NAME]=[PREF_VALUE] 

Note that the [PREF_VALUE] must be properly URL-escaped.

To give a concrete example, the sample prefs gadget includes the following userprefs:

• mycolor: the background color.
• myname: the name to use in the display
• myphoto: the URL for a photo you want to display in the gadget.
• mychoice: whether or not to display the specified photo. This is a boolean, so the value for the URL parameter is either 1 (show photo) or 0 (don't show photo).

Userpref URL parameters are prefixed with up_. So in the "Add to Google" URL, these userprefs become up_mycolor, up_myname, up_myphoto, and up_mychoice. Suppose you want to set myname to "Trevor" and mycolor to orange. You would do this by appending the following to the URL:

&up_myname=Trevor&up_mycolor=Orange 

Here is the full URL for adding the gadget with the background color set to orange, and the name set to "Trevor" (you may have to scroll right to see the full URL). Since the other userprefs (myphoto and mychoice) are not set through this URL, they retain their original default values as specified in the gadget spec.

http://fusion.google.com/add?source=atgs&moduleurl=http%3A//gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/prefs-example.xml&up_myname=Trevor&up_mycolor=Orange 

Note: When you use this technique, note that userpref value can only contain the characters that are in [a-z0-9%. -]. In other words, the userpref value can include alphanumeric characters and also the characters for period (.) , space ( ), dash (-), and percent (%).

Supported languages and countries

For a list of the languages and countries supported by iGoogle, go here. For more information on writing gadgets that can be easily localized for an international audience, see the Gadgets API Developers Guide.

To learn more

To continue learning about the OpenSocial API, check out the additional documentation and materials hosted at the OpenSocial wiki.