此页面由 Cloud Translation API 翻译。

Google 小工具跟踪

本文档将介绍如何使用新的小工具 API 来跟踪 Google Analytics（分析）小工具。此 API 提供了改进的数据模型和效果跟踪功能，可收集 Google 小工具的 Google Analytics（分析）报告统计信息。

准备工作
跟踪小工具
跟踪方法
使用注意事项
提示

开始之前

在 Google Analytics（分析）中，您添加到账户的每个唯一网域或子域都会在单独的数据视图（配置文件）中进行跟踪并会分配一个单独的“网域 ID”。由于每个小工具在 gmodules.com 托管网站上都有自己的子网域运行，因此您需要使用唯一的网域 ID 在每个小工具的数据视图（配置文件）中跟踪您创建的每个小工具。

实现此目的最简单的方法是让 Google Analytics（分析）为您生成一个唯一 ID。

要开始操作，请登录 Google Analytics（分析）或注册 Google Analytics（分析）帐号。
- 新用户应该能够看到一个“新账户注册”页。
- 现有用户应转到“Google Analytics（分析）设置”页，并点击“添加网站数据视图（配置文件）”。（请务必选择“新网域”。）
在这两个网页中的任意一个，输入任何有效的网站网址。

由于网站网址只是 Google Analytics（分析）软件用来与您的网域 ID 配对的字符串，因此此网址可以是任何有效的网站网址字符串，无论是虚构的还是真实的。您无需在任何网页上安装跟踪代码，也不需要访问任何网站网页。

点击该按钮继续访问下一个屏幕。

当跟踪代码段出现后，将唯一的网域 ID 复制到便笺本。自动生成的代码段包含此网域 ID，格式为 UA-123456-1。

点击 Finish 按钮。

您应该会在数据视图（配置文件）列表中看到网站网址的名称。您还可以将数据视图（配置文件）的名称更改为更有意义的名称，方法是点击该数据视图（配置文件）的修改链接，然后再次点击修改。

在您的小工具跟踪代码中使用生成的域 ID。

Google Analytics（分析）网域 ID 采用以下格式：
UA-123456-1

返回页首

跟踪 Google 小工具

跟踪 Google 小工具的过程涉及向您的小工具添加三段代码：

启用该功能。
创建一个跟踪器对象。
使用两种方法之一跟踪您的 Google 小工具。

以下 Google 小工具代码示例显示了所要添加的每段代码，并在下文中进行了解释。您可以使用此示例文件来开始制作自己的 Google 小工具。

<?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>

返回页首

1. 启用功能

首先，通过使用该功能的命名空间导入 Google Analytics（分析）库来启用此功能：

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

2. 创建一个跟踪器对象

Google Analytics（分析）跟踪 API 采用与 ga.js 跟踪代码相同的面向对象的模型。因此，在跟踪您的 Google 小工具之前，先创建一个跟踪器对象的实例：

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

您将在此处插入通过以上步骤生成的网域 ID。

您必须使用末尾带有单个数字的完整网域 ID；否则将无法调用跟踪对象。

3. 跟踪 Google 小工具

Google 小工具 API 提供了两种用于跟踪 Google 小工具互动的方法：

虚拟网址方法

ga.reportPageview(path);

此方法会像跟踪特定网页浏览量那样跟踪 Google 小工具的统计信息，与以前版本的 Google Analytics（分析）小工具 API 中使用的方法相同。使用此方法，您可以更新任何原有的 Google 小工具跟踪代码，而不会影响现有的 Google Analytics（分析）报告布局。查看 Google 小工具的报告数据就像查看网页的报告数据一样。

在使用虚拟网址方法跟踪 Google 小工具互动时，每次调用都会被记录为针对您作为参数提供给此方法的字符串的一个网页请求。您可以利用此行为传递一个虚构网址路径，以便可以像查看网站网页的报告那样在 Google Analytics（分析）界面中查看 Google 小工具的报告。例如，您可以使用单独的路径跟踪 Google 小工具浏览次数和小工具互动次数：

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

事件跟踪方法

ga.reportEvent(name, action, [[]label], [[]value]);

此方法只能在新的 Google Analytics（分析）小工具 API 中使用。使用此方法，您可以将 Google 小工具的页面浏览量（例如 Google 小工具呈现）和用户互动次数分开跟踪。

请注意：目前，事件跟踪只在封闭测试版本中提供。如果您没有权限使用事件跟踪，请使用虚拟网址方法。

事件方法是用于跟踪 Google 小工具的另一种模式。首先，事件调用次数与浏览量调用次数分开计算，前者的结果数据会显示在 Google Analytics（分析）内容报告的单独部分中。这样，您可以独立于 Google 小工具的用户互动次数跟踪 Google 小工具的浏览情况，避免用户互动抬高 Google 小工具的总体浏览次数。其次，此方法采用了事件跟踪模型，其结构专门为分析 Google 小工具的用户互动而设计。在此模型中，标签和值都是可选参数。

以计数器为例，我们可以使用事件方法跟踪哪些 Google 小工具功能被触发，并且可以传递控件类型，在两种情况下，此类控件都是一个按钮。

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

这是一个非常简单的示例，但事件跟踪模型是一种非常灵活的结构，您可以通过优化来满足您的 Google 小工具独特的跟踪需求。有关详情，请参阅跟踪事件文档。

返回页首

跟踪方法

目前，Google Analytics（分析）功能提供以下方法。其用法已在上文讨论。

reportPageview()

需要使用字符串才能正确填充内容报告。通常，此字符串使用您为报告定义的路径格式。传入此方法的值通过 utmp 变量在 GIF 请求中发送。使用此方法可跟踪小工具加载和小工具互动。

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

parameters
String path 为此元素的虚拟网址提供的路径。

reportEvent()

需要小工具名称和操作参数，以便将跟踪的数据正确插入事件跟踪报告中。其他参数是可选的。通过此方法传递的值通过 utme 变量在 GIF 请求中发送。

parameters
String name 必需。在事件跟踪报告的顶级使用的字符串。例如，如果您跟踪多个 Google 小工具元素的互动情况，则可能希望将 Google 小工具本身的名称用于此参数，这样该 Google 小工具的所有互动跟踪都将汇总到 Google Analytics（分析）报告中相同的部分。

String action 必需。在事件跟踪报告中进一步细分 Google 小工具互动的字符串。有关详情，请参阅跟踪事件文档。

String label 可选。可用作 Google 小工具次级细分的字符串。

Int value 可选。可作为 Google小工具互动值提供的数字。每次调用此方法时都会汇总此数字。

使用注意事项

使用 Google Analytics（分析）小工具 API 时有许多注意事项：

支持的容器

Google Analytics（分析）小工具 API 支持许多类型的容器，包括但不限于：

iGoogle
Open Syndication
Open Social
小工具

不支持的小工具类型

Google Analytics（分析）小工具 API 不支持以下 Google 小工具类型：

内嵌小工具 (type=html-inline)
Mapplet
网址类型小工具 (type-url)
Google AdSense 上的互动广告

网域注意事项

当您需要在 Google 小工具中使用 Analytics 功能时，您的小工具将重定向到 <subdomain>.gmodules.com，其中 <subdomain> 是唯一的随机子网域。因此，Google 小工具的所有内容都会显示在该子域下。示例：3nvma227-a.gmodules.com。此外，所有 Google Analytics（分析）跟踪 Cookie 都会设置到此唯一子域。因此，Google Analytics（分析）跟踪功能不支持 Mapplet，而您必须专门授予 Flash 内容对跟踪功能的特别访问权（参见下文）。

使用 Flash 内容的 Google 小工具

使用 Flash 内容的小工具必须通过将 allowScriptAccess 参数设置为“always”来专门启用 Flash 网址和小工具网址之间的通信。

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

返回页首

提示

如何最有效地使用虚拟网址方法

如果您没有权限使用 Google 小工具的事件跟踪方法，请按照以下建议使用虚拟网址方法跟踪您的 Google 小工具。

明确细分您的小工具载入。

您可以在小工具加载时调用 ga.reportPageview()，并提供一个路径，该路径独立于 Google 小工具互动指标细分 Google 小工具加载/浏览统计信息。这可以确保 Google 小工具的内容报告数据和 Google 小工具的互动数据位于相互独立的“目录”中，从而可以独立于 Google 小工具自身的互动次数查看总体浏览次数。例如，可以在您的小工具中使用以下代码段来显示小工具加载的所有统计信息：

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

细分不同的互动类型。

使用细分不同用户互动的路径调用 ga.reportPageview()。这样，您就可以获取 Google 小工具链接、Google 小工具按钮或者可能需要跟踪互动数据的其他窗口小部件的独立内容报告。例如：

ga.reportPageview('/link/click');
ga.reportPageview('/link/submit');

使用事件跟踪方法

如果您可以在 Google Analytics（分析）报告中使用事件跟踪功能，则可以利用高度灵活的数据模型来充分获取跟踪对象中包含的信息。请参考以下提示：

使用 ga.reportPageview() 跟踪 Google 小工具浏览次数或展示次数，使用 ga.reportEvent() 跟踪 Google 小工具互动次数。

Google 小工具浏览次数将显示在网页数据的内容部分中，小工具互动次数将显示在内容报告下的“事件”部分中。

使用 document.referrer 作为参数可了解小工具的放置位置。

在小工具中，document.referrer 通常是容器的网页网址，因此您可以在 ga.reportEvent() 方法中将其作为标签参数传入：

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

问题排查

您可以使用第三方工具来分析 Google 小工具的 GIF 请求字符串，以验证数据可以按您预期的方式发送到 Google Analytics（分析）报告。正确托管 Google 小工具并在测试网页中运行之后，请按如下方式分析 GIF 请求字符串：

浏览量方法

在 GIF 请求参数中查找 utmp 变量。与该变量关联的信息就是作为 Google 小工具的“路径”发送到 Google Analytics（分析）报告的信息。

事件跟踪方法

在 GIF 请求参数中查找 utme 变量。此信息的格式应为 5(object*action*label)(value)。

有关排查跟踪代码问题的详情，请参阅 Google Analytics（分析）跟踪代码 (GATC) 问题排查指南。

返回页首