English | Site Directory

Publishing Your Gadget

This document describes the different options for publishing your gadget. If you use the Google Gadgets Editor (GGE) to create and host your gadgets, it makes publishing your gadgets much easier.

Contents

  1. Where Can I Put My Gadget?
  2. Preparing for Publication
    1. Testing Height and Width
    2. Improving Gadget Performance
  3. Publishing to Other Google Properties
    1. Compatibility
    2. Adding Gadgets to Google Desktop
    3. Adding Gadgets to Google Toolbar
  4. Publishing to the Content Directory
    1. Managing Submitted Gadgets
  5. Publishing through Syndication
    1. Creating a Gadget for Syndication
    2. Example
    3. Testing Under Syndication
    4. Submitting for Syndication

Where Can I Put My Gadget?

You can put your gadgets in any of the following places:

  • On your own and your friends' iGoogle pages.
  • In other Google properties, such as Google Toolbar and Google Desktop.
  • On any web page, using syndication.
  • The iGoogle Content Directory. Submitting your gadget to the content directory makes it available to a wider audience.

Not every gadget is suited to every environment. The following table lists the requirements for each environment:

Target Environment Requirements
iGoogle There are no special requirements or limitations for users adding gadgets to iGoogle.
Other Google properties, such as Google Toolbar and Google Desktop For some properties the userprefs edit box is not exposed to users, so in those cases the gadget functionality should not be contingent on each user setting preferences in the edit box.
iGoogle Content Directory Developers submitting gadgets to the content directory should follow the guidelines listed in Publishing to the Content Directory.
Syndication The dynamic height and setprefs features do not work under syndication. The userprefs edit box is not exposed to users, so the gadget functionality should not be contingent on each user setting preferences in the edit box.

Preparing for Publication

Before publishing your gadget, you should test it, bearing in mind the requirements and limitations of the target environment in which the gadget will run.

You should do the following tests for all gadgets:

  • Try all combinations of UserPref values.
  • Run it in different sized screens, from 800x600 to as wide as you can. Link to the Firefox web developer extension, which makes it easy to resize Firefox to a specific size.
  • Test your gadget in different sizes, as described in Testing Width and Height.
  • Test your gadget in every environment in which it might run (iGoogle, Gadgets for Your Webpage, Google Desktop, and so on).
  • Test your gadget on the following browsers: IE 7, IE 6, Firefox 2.x, Firefox 1.5.x, IE 7, IE 6, Opera 9.x, and Safari 2.x.
  • Try different font sizes:
    • To change your font size in Firefox, choose Tools > Options > Content. Click Advanced in the "Fonts & Colors" area. Change the font settings, and uncheck "Allow pages to choose their own fonts, instead of my selections above."
    • To change your font size in Internet Explorer, choose Tools > Internet Options > General. Use the Fonts and Accessibility dialogs to change your font settings.

If you are using _IG_FetchContent(), test what happens if the data source is down or returns an error. You can simulate this by changing the URL temporarily to another URL.

Testing Width and Height

How a gadget is sized depends to a large extent on where it runs. When gadgets run under syndication, their specified height and width are simply suggestions for site owners, who are free to change them. For iGoogle, width settings are ignored, and the gadget's width is automatically set to 32%.

Dynamic height only works on iGoogle, so you should test your gadget with various sizes under syndication. You can test your gadget in the syndication creator page using a URL with this format: 

http://gmodules.com/ig/creator?synd=open&url=[gadget-url]

In designing and testing your gadgets, be prepared for arbitrary widths from 200 pixels to as wide as 600 pixels. For certain gadgets, the width should be even larger. As a general rule, design the gadget to display properly if it's given extra space. For example, maps gadgets should fill their areas, picture gadgets should center themselves in the frame, and text gadgets should float their text to the top (for example, click-for-more-details links that are typically at the bottom should stay close to the content rather than floating to the bottom of the gadget window).

As a general guideline, your gadget should be 180-200px wide for blogs and Google Desktop, and 250px wide for iGoogle. For maximum versatility, your gadget width should scale up to at least 250px for blogs and Google Desktop, and 600px for iGoogle.

Improving Gadget Performance

If you write a gadget that you expect to experience heavy traffic, there are steps you can take to ensure availability and good performance. If your gadget gets more than 200,000 views per day, or approximately 1-2 requests per second, you should consider following the tips in this section. Even a 50 KB gadget that receives 200,000 requests per day consumes around 300 GB per month in bandwidth.

There are different reasons a gadget might attract a lot of users. It might simply become popular in the content directory. Or, if the gadget is used in a special promotion or advertisement, that might cause it to experience heavy traffic.

Your goal for a high traffic gadget should be to get it to render in 0.25 seconds (250 milliseconds) or less. Use Firebug (Firefox only) to measure this. Improving the responsiveness of your gadget is a sure way to make a positive impact on the user's experience. For tips on optimizing gadget performance, see Optimizing for Heavy Traffic. For management tips, see Managing Heavy Traffic. The general testing guidelines are also especially important for highly popular gadgets.

Optimizing for Heavy Traffic

If you think that your gadget might experience heavy traffic, follow these guidelines:

  • Avoid using external JavaScript or CSS files (files referenced by the "src" or "href" attributes in your HTML tags) because this incurs the cost of another network connection. Instead, put your JavaScript and CSS code inline in the gadget spec.
  • Use a type=html gadget. Gadgets that are type=url generally render more slowly than type=html gadgets because of the poor performance and poor cache support of other hosting servers.
  • The_IG_FetchContent(), _IG_FetchXmlContent() and_IG_Get... functions cache your content for approximately 1-2 hours by default. You can use the refreshInterval parameter with these functions to refresh the cache more often. However, caching helps gadget performance by minimizing the number of requests sent to remote servers hosting content. Do not request greater freshness than needed from the cache, or you will reduce the percentage of requests that are served from the cache. See Refreshing the Cache for more discussion of this topic.
  • Use Firebug (Firefox only) to fine-tune your gadget performance. For other browsers you can use Fiddler.
  • Avoid using Google Analytics if possible, because it incurs an additional server connection. Instead of Analytics, use http://www.google.com/ig/directory?url=<gadget-url> to see the weekly pageviews for your gadget.
  • Specify height and width for all <img> tags in your gadget's HTML. This makes your gadget render faster. If you're using _IG_GetImage()(see code example) and inserting the image element directly into the DOM, you don't need to set the width and height properties.
  • Instead of linking directly to your hosting provider (or to Google Code), use the _IG_Get... functions to cache all embedded images and Flash content. Here is an example of a gadget that pre-loads images using _IG_GetImage(url):

Here is the code for the sample gadget:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Zombies!" height="350" />
  <Content type="html">
  <![CDATA[
  <div id="zombiecontainer"
    style="text-align:center;">
  </div>
  <script type="text/javascript">
  var counter = 0;
  // Preload the images using _IG_GetImage().
  var images = new Array();
  images[0] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-0.jpg");
  images[1] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-1.jpg");
  images[2] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-2.jpg");
  images[3] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-3.jpg");
  images[4] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-4.jpg");
  images[5] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-5.jpg");
  images[6] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-6.jpg");

  // Browse through photos sequentially. When you get to the end of the array, start over.
  function browse(){
    if (counter == images.length)
    {
      counter = 0;
    }
    _gel("zombiecontainer").innerHTML = "";
    _gel("zombiecontainer").appendChild(images[counter]);
    counter++;
  }
  browse();
  </script>
  <br />
  <div style="text-align: center;">
    <input type=submit value="Next ->" onClick="browse()">
  </div>
  ]]>
  </Content>
</Module>

Managing High Traffic

These guidelines can help you manage a high volume gadget:

  • If you are receiving large quantities of email from your gadget users, use Gmail and set up filters to manage the volume. We recommend using an address of the form <username>.feedback+<gadgetname>@gmail.com in your gadget spec. This helps you to filter the messages you receive from gadget users. Gmail drops everything after the plus sign (+), so this email address maps to <username>.feedback@gmail.com. Note that Gmail has a high quality spam filter.
  • If you submit your gadget to the iGoogle content directory, check your gadget description page periodically for user comments. Users frequently leave valuable feedback, feature requests, and reports of bugs they've run into when using your gadget. It's good to stay abreast of their comments and engage with them.

Publishing to Other Google Properties

One of the best things about gadgets is that you can write and test them on iGoogle and then use them on other properties, such as Google Desktop and Google Toolbar. Alternatively, you can use syndication to deploy gadgets on Blogger or on your own HTML pages. See Publishing through Syndication for details.

Compatibility

You can add most gadgets to Google Desktop. However, gadgets are not completely interchangeable with Desktop gadgets. To add gadgets to Desktop, you go to the Desktop content directory and add the gadget by its gadget spec URL, as described below.

Google Toolbar gadgets take a different approach. See Adding Gadgets to Google Toolbar for more information.

Adding Gadgets to Google Desktop

To add a gadget the Desktop via the Desktop Sidebar:

  1. At the top of the Sidebar, click Add.
  2. Type the URL for a gadget spec into the Search gadgets text field and then click Search gadgets. If the gadget is found, its title is displayed next to an Add button. Click Add.

Adding Gadgets to Google Toolbar

You can add gadgets to Google Toolbar through the Toolbar gallery. You can access the gallery in any of the following ways:

  • Click the Add buttons to your Toolbar button on the Toolbar
  • Right-click on the Toolbar, and choose Get more buttons from the drop-down menu.
  • Right-click on the Toolbar, choose Google Toolbar Options, display the Custom Buttons tab, and then click on the Add more buttons link in the upper right corner.
  • Go directly to the Toolbar gallery.

For information on developing Toolbar gadgets, see the Google Toolbar API documentation. A Toolbar gadget is actually a Toolbar custom button that includes a <gadget> tag that references a gadget spec.

Publishing to the Content Directory

Once you have designed, implemented, and tested your gadget, you may decide to submit it to Google to be published in the content directory. The submission process is the same if you want your gadget to be listed in the syndication directory. See Syndicated Gadgets for more information. This section lists the general steps you should follow in preparing any gadget to be published.

Step 1: Set your gadget preferences.

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.
  • author_location
  • author_affiliation
  • title_url. You use this attribute to link your gadget title to an external HTML page. For example, if your gadget is a front end for a service, you can link the gadget title to that service's website.
  • directory_title (required if title contains user preference substitution variables).

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 compatibility requirements.

Not all gadgets can run in all environments. A gadget may require a particular browser or software. You can use the <MayRequire> tag under <ModulePrefs> to provide information about special requirements of your gadget. For more information, see Specifying Compatibility Requirements.

Step 4: Add any relevant locale information.

You can use <Locale> tags under <ModulePrefs> to specify the locales supported by your gadget. For more information, see Specifying Locales.

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

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

Step 6: Submit your gadget to Google.

You can submit your gadget to Google here. You can also submit your gadget to the content directory using the GGE File > Publish command. See the FAQ for an explanation of how to find your gadget in the directory, and what determines its placement. For instructions on how to prepare a gadget for syndication, which means that it can run on third party web pages, see Syndicated Gadgets.

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.

Publishing through Syndication

Syndication (Gadgets for Your Webpage) makes it possible to deploy gadgets on third party web pages. For example, here is a live gadget running right in this web page:

How was this accomplished? Simply by adding a <script src ="http://gadget-URL..." </script> statement to the HTML of this page. For details, read on.

You can open this gadget in the creator page by clicking here. The easiest way to publish a gadget through syndication is by using the GGE File > Publish command, but you can also use the creator page directly.

See the syndication content directory for examples of syndicated gadgets you can add to any web page.

Creating a Gadget for Syndication

You don't have to do anything special to a gadget to prepare it for syndication. However, to be eligible for syndication, a gadget must conform to the following guidelines:

  • It cannot store state. For example, a syndicated gadget cannot be a to-do list that stores personal list items for each user.
  • It cannot use the dynamic height feature. For example, it cannot get bigger or smaller depending on the amount of content.
  • Its functionality should not be dependent on each user specifying different user preferences.

    There is currently no easy way for users to edit userprefs in a syndicated gadget. Site owners can edit the userprefs before deploying the gadget on a web page, but once the gadget is deployed, the userprefs are no longer editable. So, for example, suppose you have a gadget that displays information based on each user entering the name of a city. You would have to give users a way of supplying this information through the gadget UI rather than through userprefs.

  • You should try to avoid making userprefs required, because this forces site owners to edit the gadget in the creator page before they can even see what it looks like.

Example

This document uses the following example gadget. The gadget displays a user profile that includes a photo, age, and hobbies. It also lets you set the background color:

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs title="Card for __UP_myname__" height="400" />
  <UserPref 
    name="myname" 
    display_name="Name" 
    default_value="Touki" />
  <UserPref 
    name="myphoto" 
    display_name="Photo" 
    default_value="http://doc.examples.googlepages.com/touki.jpg" />
  <UserPref 
    name="myage" 
    display_name="Age" 
    default_value="5" />
  <UserPref 
    name="myhobby" 
    display_name="Hobbies" 
    default_value="agility, swimming" />
  <UserPref 
    name="mycolor" 
    display_name="Color" 
    default_value="Pink" 
    datatype="enum" >
      <EnumValue value="Pink" />
      <EnumValue value="Red" />
      <EnumValue value="Aqua" />
      <EnumValue value="Lime" />
      <EnumValue value="Yellow" />
      <EnumValue value="Orange" />
      <EnumValue value="White" />
  </UserPref>
  <Content type="html"> 
  <![CDATA[ 
  <div id="content_div" style="font-size:12pt; font-family:Arial, Helvetica; text-align:center; padding:5px;">
  <script type="text/javascript">
    // Get userprefs
    var prefs = new _IG_Prefs();
    showCard();    
    // Display the card showing the user profile   
    function showCard (){
      // Apply userpref-specified background color to the div
      var element = document.getElementById('content_div');
      element.style.backgroundColor = prefs.getString("mycolor");
      // Build HTML string used to display content
      var html = "";
      html += '<img src="' + prefs.getString("myphoto") + '">';
      html += "<br><b>Age: </b>" + prefs.getString("myage");
      html += "<br><b>Hobbies: </b>" + prefs.getString("myhobby");
      // render HTML string in the div
      _gel("content_div").innerHTML = html;
    }
  </script>
  ]]> 
  </Content>
</Module>

Testing Under Syndication

To test a gadget under syndication:

  • Test your gadget on as many different browsers as possible, because third-party web pages get visited by a wider variety of users. You should minimally test on Firefox, Internet Explorer, Safari, and Opera. If you need help testing on any of these browsers, ask for assistance on the developer forum.
  • Test your gadget in the creator page with a URL of this form:
http://gmodules.com/ig/creator?synd=open&url=[gadget-url]

For example, you can view the sample gadget in the creator page with this URL:

http://gmodules.com/ig/creator?synd=open&url=http://doc.examples.googlepages.com/baseball-card.xml

The easiest way to test your gadget in the creator page is by hosting your gadget in GGE, and using the GGE File > Publish command.

For testing purposes, if you want to disable caching, you can add the &nocache=1 parameter to your URL. However, you should not use &nocache=1 to deploy live gadgets, because it can degrade performance.

http://gmodules.com/ig/creator?synd=open&nocache=1&url=http://doc.examples.googlepages.com/baseball-card.xml

Using the Creator Page

The creator page is the tool that site owners use to:

  • View a gadget they want to add to their web pages.
  • Specify the desired values for the gadget's userprefs, set its height and width, and set a border for the gadget.
  • Generate code that they can add to their web pages to deploy the live gadget.

If you're not hosting your gadget in GGE (where you can use the File > Publish command to open your gadget in the creator page), you can use this gadget to open a gadget in the creator page. Enter the URL for your gadget in the text field, and click Syndicate:

When you click here to open the creator page for the sample gadget, this is what you see:

Page Creator

Note the following:

  • The creator page displays the gadget with the default values provided in the gadget spec. The Title field uses the __UP_myname__ substitution variable, discussed here.
  • If you don't want the title to appear on the target web page, just make the Title field blank.
  • Site owners can use the Width and Height fields to set the width and height (in pixels) of the gadget. The default values are 320 for width and 200 for height. In the sample gadget spec the height is set to 400, so that is the value displayed in the creator page.
  • You can select the border that you want to place around the gadget on the target web page.
  • Click Preview Changes to see the effect of your changes.
  • When you are done configuring the gadget for display on the target web page, click Get the Code. This opens a text box containing the text string to paste into the HTML of the target web page. For example:
<script src="http://gmodules.com/ig/ifr?url=http://doc.examples.googlepages.com/baseball-card.xml&up_myname=Touki
&up_myphoto=&up_myage=&up_myhobby=&up_mycolor=Pink&synd=open&w=320&h=400&title=Card+for+__UP_myname__
&border=%23ffffff%7C3px%2C1px+solid+%23999999&output=js"></script>

This URL includes the following parameters:

  • The userprefs. Userpref parameters are prefixed with up_.
  • Height (h) and width (w) parameters. The value of these parameters is typically the number of pixels. However, you can set the gadget width to fill the containing space by using w=auto. This is useful for flexible layouts where you don't know the number of pixels beforehand.
  • The title parameter. If you blank out the Title field in the creator page, the title parameter is set to &title=. The effect in the deployed gadget is that the border is clean and there is no title bar.
  • The border parameter.
  • The output parameter, which indicates how the syndicated gadget is rendered. Possible values are js for JavaScript if the gadget uses <script> tags, and html for everything else.

You can test your gadget in Blogger. To display a syndicated gadget in Blogger, you must add it to the template, not to the HTML of a particular page. Blogger may truncate the height, so you may have better results with smaller gadgets.

Localization Settings

If your gadget includes <Locale> elements, as described in Internationalization, the creator page includes a Language menu that contains all of the languages your gadget supports. When you choose a language, it's added to the gadget's syndication URL with the &lang parameter. A &country parameter is included too, and its default setting is ALL:

<script src="http://gmodules.com/ig/ifr?url=http://examples.com/hello-i18n.xml...&amp;lang=zh-CN&amp;country=ALL...</script>

To change the setting for &country, you manually modify the URL. If you try to add a language or country for which your gadget has no corresponding <Locale> element, changing the URL has no effect.

For a list of the languages and countries supported by iGoogle, see Supported Languages and Countries.

Borders

In the creator page, you can select the border that you want to display around your border on the target web page. There are two possible types of borders: image-based, and CSS-based.

Image-based Borders

An image-based border is referenced by a URL with with this format http://hostname/some/path/ (must end in a slash). Such borders use a set of 9 images:

  • tl.gif, tr.gif, bl.gif, br.gif -- for the 4 corners
  • l.gif, r.gif, b.gif -- sides and bottom
  • tt.gif -- top, when there's a title
  • tn.gif -- top, when there's no title

The "width x height" dimensions are as follows :

  • 1x28: b.gif, tt.gif
  • 1x12: tn.gif
  • 8x1: l.gif, r.gif
  • 8x28: bl.gif, br.gif, tl.gif, tr.gif

The default set are in http://www.google.com/ig/images/..., for example, http://www.google.com/ig/images/br.gif.

CSS-based Borders

Some of the borders provided in the creator page are based on CSS definitions. These borders consist of a set of lines described by CSS parameters, whose format is as follows:

<bgcolor>|<n>px, <n>px <linetype> <color>|<n>px, <n>px <linetype> <color>|...

where colors are either plain names like "black" or RGB values like #000000, and linetypes are standard CSS linetypes, as explained here.

For example, this border prints two black lines against a white background (note that it uses URL escaping):

 &border=%23ffffff%7C1px%2C1px+solid+black%7C1px%2C1px+solid+black%7C0px%2C1px+black

Submitting for Syndication

You submit a gadget to the syndication directory just as you would submit a gadget to the regular content directory, as described here. Just remember that to be eligible for syndication, a gadget cannot store state.

Back to top