Publish Your Gadget

This document describes the different options for publishing your gadget.

Where Can I Put My Gadget?

Gadgets run in a variety of applications and environments. The API Overview page lists some of the more popular choices.

Not every gadget is suited to every environment. See the documentation for your container, application, or site for details about what features are supported in that environment.

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.
Test your gadget on the following browsers: IE 6+, Firefox 3.0+, Google Chrome 5.0+, Safari 4.0+.
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 makeRequest(), 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. See the documentation for your container or site for details.

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).

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. The Latency Measurement guide can help you with the details of measuring your gadget's performance. 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 makeRequest() method caches 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. Also, do not use cache-busting techniques such as including random numbers or timestamps in fetch URLs, because this can overload the systems that respond to those URLs. See Refreshing the Cache for details on how to set a refresh interval.
Cache frequently used content or values by using one or more of the following techniques:
- Hidden UserPref
  Pros
  - Fast, loads with the gadget and requires no additional server-client round-trip
  - No browser requirements
  Cons
  - Data is passed in via URL, and subject to URL length restrictions (there is a lot of data passed into gadget URLs, so this makes the practical size of data low, a few hundred characters max)
- HTML5 WebDatabases
  Pros
  - Fast
  - Effectively unlimited storage
  Cons
  - Requires browser support
- OpenSocial AppData
  Pros
  - No browser requirements
  - About 10 KB of storage space (including keys, and depending on per-container restrictions)
  Cons
  - Requires a second request once the gadget loads to fetch data
  - Any data stored in AppData is potentially visible to other people within the user's social graph
Check out the Latency Measurement guide for ways to observe your gadget's performance. Then eliminate the bottlenecks.
Specify height and width for all <img> tags in your gadget's HTML. This makes your gadget render faster. If you're using gadgets.io.getProxyUrl() 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, use the gadgets.io.getProxyUrl() functions to cache all embedded images, and embedCachedFlash() to cache Flash content. Below is an example of a gadget that pre-loads images using gadgets.io.getProxyUrl():

Here is a sample gadget that illustrates how to use gadgets.io.getProxyUrl():

<?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 gadgets.io.getProxyUrl()
  function load(imageList) {
    var ret = [];
    for (var i = 0, j = imageList.length; i < j; ++i) {
      var img = document.createElement("img");
      img.src = gadgets.io.getProxyUrl(imageList[i]);
      ret.push(img);
    }
    return ret;
  }

  var files = [
    "http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-0.jpg",
    "http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-1.jpg",
    "http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-2.jpg",
    "http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-3.jpg",
    "http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-4.jpg",
    "http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-5.jpg",
    "http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-6.jpg"
  ];

  var images = load(files);
  browse();

  // Browse through photos sequentially. When you get to the end of the array, start over.
  function browse(){
    if (counter == images.length)
    {
      counter = 0;
    }
    document.getElementById("zombiecontainer").innerHTML = "";
    document.getElementById("zombiecontainer").appendChild(images[counter]);
    counter++;
  }

  </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.