Gadget Tracking

This document describes how to use the new gadget API for Analytics gadget tracking. This API offers an improved data model and performance tracking to collect Analytics reports statistics for your gadgets.

1. Before You Begin
2. Tracking Your Gadget
3. Tracking Methods
4. Usage Considerations
5. Tips

 

Before You Begin

In Google Analytics, each unique website domain or sub-domain you add to your account is tracked in a separate view (profile) and assigned a separate domain ID. Because each gadget operates on its own sub-domain on the gmodules.com host site, you will want to track each gadget you create in its own view (profile), and with a unique domain ID.

The simplest way to do this is to let Google Analytics generate a unique ID for you.

1. To begin, sign into Google Analytics or sign up for a Google Analytics account.
   • New users should see a New Account Sign Up page.
   • Existing users should go to the Analytics Settings page and click on Add Website View (Profile). (Be sure to choose new domain.)
2. From either of these pages, enter any valid website URL.
Because the website URL is only a string that the Google Analytics software pairs with your domain ID, this URL can be any valid website URL string, whether fabricated or real. You are not going to install the tracking code on any web pages at all, and will not need access to any website pages.
3. Click the button to continue to the next screen.
When the tracking code snippet appears, copy the unique domain ID to a scratch pad. The automatically generated code snippet contains this domain ID in the form of UA-123456-1.
4. Click the Finish button.
You should see the name of your website URL in the view (profile) list. You can also change the view (profile) name to something more meaningful by clicking the Edit link for that view (profile), and then clicking Edit again.
5. Use the generated domain ID in your gadget tracking code.
Analytics domain IDs take the form of:
UA-123456-1

Back to Top

 

Tracking Your Gadget

The process of tracking your gadget involves three additions to your gadget code:

1. Enabling the feature.
2. Creating a tracker object.
3. Tracking your gadget using one of two methods.

The following gadget code sample shows each of these code additions, which are then explained below. You can use this sample file to start your own gadget.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Analytics Test">
     <!-- Sets the feature -->
     <Require feature="com.google.gadgets.analytics" /> 
     <Require feature="setprefs" /> 
  </ModulePrefs>
  <UserPref 
      name="counter"
      datatype="hidden"
      default_value="0" />
  <Content type="html"> 
  <![CDATA[ 
      <script>
      // Track this gadget using Google Analytics.

      // Creates a tracking object and uses reportPageview method to call gadget view
      var ga = new _IG_GA("UA-00000-1");
      ga.reportPageview('/view/counterGadget');

      // Suppose, for example, you have a gadget with two counter buttons.
      // You can track interactions with those counters via Analytics.

      // Increment value of "counter" user preference
      function incrementCounter() {
         var count = prefs.getInt("counter");

         prefs.set("counter", count + 1);

         // Tracks button click as an event
         ga.reportEvent("Counter Gadget", "Increment", "Button", 0);
      }

      // Reset value of "counter" userpref to 0
      function resetCounter(){
         prefs.set("counter", 0);

         // Tracks button click as an event
         ga.reportEvent("Counter Gadget", "Reset", "Button", 0);
      }
      </script>
      <form name="counter">
      <input type=button value="Reset" name="reset" onClick="resetCounter()">
      <input type=button value="Count" name="count" onClick="incrementCounter()">
      </form>
  ]]>
  </Content>
</Module>
  

Back to Top

1. Enabling the feature

First, enable the feature by importing the Analytics library using the feature namespace:

 <Require feature="com.google.gadgets.analytics" /> 

2. Creating a Tracker Object

The Analytics tracking API adheres to the same object-oriented model of the ga.js tracking code. So, before tracking your gadget, instantiate a tracker object:

var ga = new _IG_GA("UA-123456-1");

This is where you will insert the domain ID generated by following the steps above.

You must use the full domain ID with the ending single numeral; otherwise the tracking object call will fail.

3. Tracking Your Gadget

The gadget API provides two methods that you can use to track interaction on your gadgets:

• The virtual URL method
ga.reportPageview(path);

This method tracks gadget statistics as special page views, and is the same method used in the earlier version of the Analytics gadget API. Using this method, you can update any pre-existing gadget tracking code without impacting your existing Analytics reports layout. You view reporting data on your gadgets just like you view reporting data for web pages.

When you use the virtual URL method to track gadget interaction, each call is recorded as a page request for the string that you provide as a parameter to the method. You can take advantage of this behavior to pass in a fabricated URL path so you can view reports for gadgets in the Google Analytics interface just like you would website page reports. For example, you could use separate paths to track both gadget views and gadget interactions:

ga.reportPageview('/view/counterGadget');
ga.reportPageview('/click/increment');
ga.reportPageview('/click/reset');



• The event tracking method
ga.reportEvent(name, action, [[]label], [[]value]);

This method is available only in the new Analytics gadget API. Using this method, you can track page views (e.g. gadget rendering) separately from user interactions on your gadget.

Note: At this time, Event Tracking is in closed beta release. Use the virtual URL method if you do not have access to Event Tracking.

The event method provides a different model for you to use with gadget tracking. First, event calls are calculated separately from page view calls, and the resulting data is displayed in a separate part of the Google Analytics Content reports. Thus, you could track the view of a gadget sepately from user interactions on the gadget, without having user interaction inflate the overall numbers for gadget views. Secondly, this method employs the event tracking model, whose structure is specifically designed to analyze user interaction on gadgets. In this model, both label and value are optional parameters.

Using the counters example, we can use the event method to track which gadget functions are triggered, and we can pass in the type of control, which is a button in both cases.

ga.reportEvent("Counter Gadget", "Increment", "Button");
ga.reportEvent("Counter Gadget", "Reset", "Button");

This is a very simple example, but the event tracking model is a highly flexible structure that you can refine to take advantage of the unique tracking requirements of your gadget. For more information, see the Tracking Events documentation.

Back to Top

 

Tracking Methods

Currently, the Analytics feature offers the following methods. Their usage is discussed above.

• reportPageview()
Requires a string in order to correctly populate the content reports. Typically this string is in the form of a path that you define for your reporting purposes. The value passed into this method is sent in the GIF request via the utmp variable. Use this method to track gadget loads and gadget interactions.
ga.reportPageview("/view/gadgetName");
parameters
String  path  Path to provide for the virtual URL of this element.


• reportEvent()
Requires the name of the gadget and action parameter in order to correctly insert tracked data into Event Tracking reports. The other parameters are optional. The values passed via this method are sent in the GIF request view the utme variableU.

parameters
String  name  Required.  A string used at the top level of the Event Tracking reports. For example, if you were tracking interaction on a number of gadget elements, you would likely use the name of the gadget itself for this parameter, so that all interaction tracking for the gadget would be aggregated in the same section of the Google Analytics reports.

String  action  Required. String to further segment gadget interaction in the Event Tracking reports. For more information, see the Tracking Events documentation.

String  label  Optional. String you can use as a secondary segment for your gadget.

Int  value  Optional. Number that you can supply as a value for the gadget interaction. This number is aggregated for each time the method is invoked.

 

Usage Considerations

The Google Analytics gadget API has a number of usage considerations:

• Supported Containers
Many types of containers are supported with the Google Analytics gadget API, including, but not limited to:
• iGoogle
• Open Syndication
• Open Social
• Gadgets
• Unsupported Gadget Types
The Google Analytics gadget API does not support the following gadget types:
• Inlined gadgets (type=html-inline)
• Mapplets
• URL type gadgets (type-url)
• Gadget Ads on Google AdSense
• Domain considerations
When you require the Analytics feature for your gadget, your gadget will redirect to <subdomain>.gmodules.com, where <subdomain> is a unique, random sub-domain. Hence, all content in the gadget is displayed under that sub-domain. Example: 3nvma227-a.gmodules.com. Additionally, all the Google Analytics tracking cookies are set to this unique subdomain. For this reason, mapplets are not supported by the Analytics tracking feature, and you must specifically allow Flash content special access to the tracking feature (see below).
• Gadgets using Flash content
Gadgets using Flash content must specifically enable communication between the Flash URL and the gadgets URL by setting the allowScriptAccess parameter to always.

_IG_EmbedFlash("example.swf", "wrapper", {allowScriptAccess: "always"});

Back to Top

 

Tips

How Best to Use the Virtual URL Method

If you do not have access to the event tracking method for your gadgets, follow these recommendations for tracking your gadgets with the virtual URL method:

• Segment your gadget load distinctly.
You can call the ga.reportPageview() on gadget load supplying a path that segments the gadget load/view statistics separately from the gadget interaction metrics. This will keep the content reporting data for the gadget in a separate "directory" from the interactions on the gadget, so that you can see your overall views separately from the number of interactions on the gadget itself. For example, the following code snippet could be used in your gadget to display all statistics for your gadget load:

  ga.reportPageview('/view/gadgetName');

• Segment different interaction types from each other.
Call the ga.reportPageview() with a path that segments different user interactions. In this way, you can get separate content reporting for gadget links, gadget buttons, or other widgets you might want to track for interaction data. For example:
• ga.reportPageview('/link/click');
• ga.reportPageview('/link/submit');

Using the Event Tracking Method

If you have access to the Event Tracking feature in the Google Analytics reports, you can take advantage of the highly flexible data model to get the most out of tracking your objects. Here are some tips:

• Track the gadget view or impression using ga.reportPageview(), and track gadget interaction using ga.reportEvent().
Gadget views will be displayed in the Content section for page data, and gadget interactions will be displayed in the Events section under the Content reports.
• Use document.referrer as a parameter to learn where your gadget has been placed.
In the gadget, document.referrer is usually the container’s page URL, so you could pass it in as a label parameter in the ga.reportEvent() method:


var containerPage = document.referrer;
ga.reportEvent("Counter Gadget", "Increment", containerPage, 0);

Troubleshooting

You can use 3rd-party tools to analyze the GIF request string for your gadget in order to verify that data will be sent to the Google Analytics reports in the way you expect. Once you have the gadget properly hosted and working in your test page, analyze the GIF request string as follows:

• Page view method
Look for the utmp variable in the GIF request parameters. The information associated with that variable is what will be sent to the Google Analytics reports as the "path" for the gadget.
• Event Tracking method
Look for the utme variable in the GIF request parameters. This information should be of the form 5(object*action*label)(value).

For more information on troubleshooting the tracking code, see the GATC Troubleshooting Guide.

Back to Top