小工具追蹤

本文件說明如何使用新的小工具 API 追蹤 Analytics (分析) 小工具。這個 API 提供經過改良的資料模型和效能追蹤功能，可以收集小工具的 Analytics (分析) 報表統計資料。

  1. 事前準備
  2. 追蹤小工具
  3. 追蹤方法
  4. 使用注意事項
  5. 使用提示
 

事前須知

在 Google Analytics (分析) 中，您在帳戶中新增的每個不重複網站網域或子網域都會以個別資料檢視 (設定檔) 進行追蹤，並指派不同的網域 ID。因為每個小工具是在 gmodules.com 代管網站上的專屬子網域上運作，因此您必須分別在其檢視畫面 (設定檔) 中和具備專屬網域 ID 建立的每個小工具。

最簡單的做法是讓 Google Analytics (分析) 為您產生專屬 ID。

  1. 首先，請登入 Google Analytics (分析) 或註冊 Google Analytics (分析) 帳戶。
    • 新使用者應該會看見新帳戶申請頁面。
    • 現有使用者請前往「Analytics (分析) 設定」頁面，然後按一下「新增網站資料檢視 (設定檔)」。(請務必選擇新網域)。
  2. 從其中一個網頁輸入任何有效的網站網址。
    3. 網站網址是 Google Analytics (分析) 軟體與你的網域 ID 配對的字串，因此網址可以是任何有效的網站網址字串，無論字串是否為真網址。您完全不需要在任何網頁上安裝追蹤程式碼，也不需要存取任何網頁。
  3. 按一下按鈕即可前往下一個畫面。
    4. 顯示追蹤程式碼片段後，請將專屬網域 ID 複製到刮痕。系統自動產生的程式碼片段包含 UA-123456-1 格式的這個網域 ID。
  4. 按一下「Finish」按鈕。
    5. 你應該會在資料檢視 (設定檔) 清單中看到網站網址的名稱。您也可以將資料檢視 (設定檔) 名稱改為有意義的名稱，方法是按一下該帳戶 (設定檔) 的 [編輯] 連結，然後再次點選 [編輯]。
  5. 在小工具追蹤程式碼中使用產生的網域 ID，
    6. Analytics (分析) 網域 ID 的格式為：
    UA-123456-1
 

追蹤小工具

追蹤小工具的過程必須包含三個新增小工具程式碼的地方：

  1. 啟用此功能。
  2. 建立追蹤器物件。
  3. 使用其中一種方法追蹤小工具。

下列小工具程式碼範例顯示這些新增程式碼的各個新增項目，我們會在下方說明。您可以使用這個範例檔案建立自己的小工具。

<?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. 啟用功能

首先，使用特徵命名空間匯入 Analytics (分析) 程式庫，以啟用此功能：

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

2. 建立追蹤器物件

Analytics (分析) 追蹤 API 使用 ga.js 追蹤程式碼相同的物件導向模型。因此，在追蹤小工具之前，請先建立追蹤器物件：

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

請在這裡插入上述步驟產生的網域 ID。

您必須使用完整的網域 ID，並在結尾處加上單一數字，否則追蹤物件呼叫會失敗。

3. 追蹤小工具

小工具 API 提供兩種追蹤小工具互動的方法：

  • 虛擬網址方法
    • ga.reportPageview(path);

    這個方法會將小工具統計資料視為特殊的網頁瀏覽來追蹤，與舊版 Analytics (分析) 小工具 API 中的方法相同。您可以使用這個方法更新任何既有的小工具追蹤程式碼，而不會影響現有的 Analytics (分析) 報表版面配置。查看小工具的報表資料的方式，就像查看網頁報表資料一樣。

    如果您使用虛擬網址方法追蹤小工具互動，每次呼叫都會記錄為網頁要求，其中包含您提供給 方法的參數。您可以利用這個行為傳送產生的網址路徑，這樣就能在 Google Analytics (分析) 介面中查看小工具的報表，就像網站網頁報告一樣。例如，您可以使用不同的路徑來追蹤小工具的檢視和小工具互動：

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

  • 事件追蹤方法
    • ga.reportEvent(name, action, [[]label], [[]value]);

    這個方法僅適用於新版 Analytics (分析) 小工具 API。使用這個方法時，您可以單獨追蹤網頁瀏覽量 (例如小工具顯示)，以及與小工具中的使用者互動。

    注意：事件追蹤目前在 Beta 版封閉測試階段。如果您無法存取事件追蹤，請使用虛擬網址方法。

    事件方法會提供一種可用於小工具追蹤的不同模型。首先，事件呼叫會與網頁瀏覽呼叫分開計算，結果資料會另外顯示在 Google Analytics (分析) 內容報表中。因此，您可以在不涉及使用者互動的情況下，透過使用者在小工具上的互動動作追蹤小工具的檢視情形，而不需與使用者互動，就能增加小工具檢視的總數。第二，這個方法採用事件追蹤模型，這種模型的結構專為分析使用者在小工具上的互動而設計。在此模型中，標籤和值都是選用參數。

    以計數器範例來說，我們可以使用 事件方法來追蹤會觸發的小工具函式，而且我們可以傳遞控制項類型 (兩種情況下為按鈕)。

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

    以上範例十分簡單，但事件追蹤模型的結構相當靈活，您也可以根據小工具的獨特追蹤需求加以調整。詳情請參閱「追蹤事件」說明文件。

 

追蹤方式

Analytics (分析) 功能目前提供下列方法。我們會在上方討論其用途。

  • reportPageview()
    • 需要字串才能正確填入內容報表。此字串通常會採用您為報表定義的路徑格式。傳遞至這個方法的值會透過 utmp 變數在 GIF 要求中傳送。這個方法可用於追蹤小工具載入和小工具互動。 
    ga.reportPageview("/view/gadgetName");
    parameters
    String  path 要為此元素虛擬網址提供的路徑。

  • reportEvent()
    • 必須有小工具和動作參數的名稱，才能正確在事件追蹤報表中插入追蹤資料。其他參數則為選用參數。透過這個方法傳遞的值會在 GIF 要求中查看 utme 變數 U。

    parameters
    String  name  必要。「事件追蹤」報表頂層使用的字串。舉例來說，如果您要追蹤多個小工具元素的互動，建議您在這個參數中使用小工具名稱，這樣一來，小工具的所有互動追蹤都會彙整在 Google Analytics (分析) 報告的相同區段中。

    String  action  必填。用來在「事件追蹤」報表中進一步區隔小工具互動的字串。詳情請參閱「追蹤事件」說明文件。

    String  label  選填。可做為小工具次要區段的字串。

    Int  value  選填。您可以為小工具互動提供的值。每次叫用這個方法時，這個數字都會匯總。

 

使用注意事項

Google Analytics (分析) 小工具 API 有幾點使用上的考量：

  • 支援的容器
    • Google Analytics (分析) 小工具 API 支援許多類型的容器，包括但不限於：
    • iGoogle
    • 開啟聯合發布
    • Open Social
    • 電子產品
  • 不支援的小工具類型
    • Google Analytics (分析) 小工具 API「不」支援下列小工具類型：
    • 內嵌小工具 (type=html-inline)
    • 地圖小工具
    • 網址類型小工具 (type-url)
    • Google AdSense 互動廣告
  • 網域注意事項
    • 如果小工具必須使用 Analytics (分析) 功能，小工具會重新導向至 <subdomain>.gmodules.com，其中 <subdomain> 是隨機的專屬子網域。因此，小工具中的所有內容都會顯示在該子網域下。範例：3nvma227-a.gmodules.com。此外，所有 Google Analytics (分析) 追蹤 Cookie 都會設為專屬子網域。因此，Analytics (分析) 追蹤功能不支援地圖小工具，您必須特別允許 Flash 內容使用追蹤功能 (請見下方說明)。
  • 使用 Flash 內容的小工具
    • 使用 Flash 內容的小工具必須將 allowScriptAccess 參數設為一律啟用，藉此啟用 Flash 網址和小工具網址之間的通訊。 
    _IG_EmbedFlash("example.swf", "wrapper", {allowScriptAccess: "always"});
 

提示

虛擬網址方法的最佳使用方式

如果您無法使用小工具的事件追蹤方法，請按照下列建議，透過虛擬網址方法追蹤小工具：

  • 自行區隔小工具載入方式。
    • 您可以在小工具載入時呼叫 ga.reportPageview()，以提供區隔小工具載入/檢視統計資料和小工具互動指標的路徑。如此一來，小工具的內容報表資料會與小工具互動在個別的「目錄」中保存，以便您可以分別查看小工具的整體觀看次數和互動次數。舉例來說，您可以在小工具中使用下列程式碼片段，顯示載入小工具的所有統計資料： 
      ga.reportPageview('/view/gadgetName');
  • 區隔不同的互動類型。
    • 使用區隔不同使用者互動的路徑來呼叫 ga.reportPageview()。如此一來，您可以針對想要追蹤互動資料的小工具連結、小工具按鈕或其他小工具，取得個別的內容報告。例如：
    • ga.reportPageview('/link/click');
    • ga.reportPageview('/link/submit');

使用事件追蹤方法

如果您可以在 Google Analytics (分析) 報表中使用事件追蹤功能，就能使用高度彈性的資料模式來提高追蹤物件的成效。以下提供幾項訣竅：

  • 使用 ga.reportPageview() 追蹤小工具檢視或曝光，並使用 ga.reportEvent() 追蹤小工具互動情形。
    • 小工具檢視畫面會顯示在網頁資料的「內容」部分，小工具互動則會顯示在「內容」報表下方的「事件」部分。
  • 使用 document.referrer 做為參數，瞭解小工具的位置。
    • 在小工具中，document.referrer 通常是容器的網頁網址，因此您可以在 ga.reportEvent() 方法中，以標籤參數的形式傳入：
    var containerPage = document.referrer;
ga.reportEvent("Counter Gadget", "Increment", containerPage, 0);

疑難排解

您可以使用第三方工具分析小工具的 GIF 要求字串，確認資料會以您預期的方式傳送至 Google Analytics (分析) 報表。將小工具正確代管並在測試頁中運作後，請依下列方式分析 GIF 要求字串：

  • 網頁瀏覽方式
    • 在 GIF 要求參數中找出 utmp 變數。與該變數相關聯的資訊會傳送至 Google Analytics (分析) 報表，做為小工具的「路徑」。
  • 事件追蹤方法
    • 在 GIF 要求參數中找出 utme 變數。這項資訊的格式應為 5(object*action*label)(value)。

如要進一步瞭解如何排解追蹤程式碼的問題，請參閱 GATC 疑難排解指南。