Android 專用的 Google Analytics (分析) SDK v1 (舊版)

Google Analytics for Mobile Apps SDK for Android 可讓您在 Android 應用程式中輕鬆導入 Google Analytics (分析)。本文說明如何整合 SDK 與您的應用程式。

SDK 總覽

此 SDK 採用的追蹤模型旨在追蹤傳統網站以及與傳統網頁中小工具的互動。因此,下方使用的字詞符合傳統的網站追蹤模型,且已對應到追蹤行動應用程式。建議您熟悉 Analytics (分析) 追蹤,以瞭解這個 SDK 的運作方式。

透過行動追蹤 SDK 使用下列 Analytics (分析) 互動類型來追蹤手機應用程式:

網頁瀏覽追蹤
網頁瀏覽是評估傳統網站流量的標準做法。由於行動應用程式不包含 HTML 網頁,因此您必須決定觸發網頁瀏覽要求的時機 (以及頻率)。此外,由於網頁瀏覽要求是專為建立目錄結構而設計,因此您必須在 Analytics (分析) 的「內容」報表中為請求提供描述性名稱,以便使用網頁路徑命名。在 Analytics (分析) 報表中,您選擇的名稱會填入網頁路徑,但實際上並不是 HTML 網頁。不過,透過建立路徑為呼叫提供額外分組,即可充分利用這項設定。
事件追蹤
在 Analytics (分析) 中,事件的用途是追蹤使用者與網頁元素 (不同於網頁瀏覽要求) 的互動。您可以使用 Google Analytics (分析) 的事件追蹤功能,在 Analytics (分析) 報表介面的「事件追蹤」部分進行其他呼叫。事件會按類別分組,也可能使用個別事件標籤,以便在報表中提供彈性。舉例來說,多媒體應用程式可以為影片類別執行播放/停止/暫停動作,並為每個影片名稱指派標籤。然後,Google Analytics (分析) 報表就會針對所有標有影片類別的事件匯總事件。如要進一步瞭解事件追蹤,請參閱事件追蹤指南
電子商務追蹤
使用電子商務追蹤功能,追蹤購物車交易和應用程式內購次數。 如要追蹤交易,請使用 Transaction 類別來表示整體的購買資訊,並使用 Item 類別來表示購物車中的各項產品。收集完成後,您就可以在 Google Analytics (分析) 介面的「電子商務」報表部分中查看相關資料。如要進一步瞭解電子商務追蹤,請參閱電子商務追蹤指南
自訂變數
自訂變數是名稱與值的配對,您可以將其插入追蹤程式碼中,以利 Google Analytics (分析) 追蹤。如要進一步瞭解如何使用自訂變數,請參閱自訂變數指南

開始使用

需求條件

為了整合 Google Analytics (分析) 與 Android 應用程式的追蹤功能,您必須符合以下條件:

設定

  • libGoogleAnalytics.jar 新增至專案的 /libs 目錄。
  • 在專案的AndroidManifest.xml資訊清單檔案中加入下列權限:
    • <uses-permission android:name="android.permission.INTERNET" />
    • <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

SDK 含有一個範例應用程式,當中會說明專案設定成功後的外觀。您可以參考這個範本,為自家 Analytics (分析) 整合應用程式建立範本。

使用 SDK

開始使用 SDK 前,您必須先在 www.google.com/analytics 建立免費的帳戶,並使用虛假但描述性的網站網址 (例如 http://mymobileapp.mywebsite.com) 在該帳戶中建立新的網站資源。建立資源後,請記下或記下新建立的資源產生的網站資源 ID。

您必須在應用程式中或服務條款中指明使用者,這代表您有權匿名追蹤並回報使用者在應用程式中的活動。使用 Google Analytics (分析) SDK 時,您也必須遵守《Google Analytics (分析) 服務條款》,您必須在註冊帳戶時同意這些條款。

範例和最佳做法

您可以前往 code.google.com 的 analytics-api-samples 專案底下找到程式碼範例和最佳做法。

EasyTracker 程式庫

提供 EasyTracker 程式庫。並提供應用程式與活動層級追蹤,幾乎不需要任何開發作業。您可以在 analytics-api-samples 專案的「下載」部分找到它。

啟動追蹤器

呼叫 GoogleAnalyticsTracker.getInstance() 取得追蹤器單例模式。然後呼叫其 startNewSession 方法,並傳遞要追蹤的網站資源 ID 和活動。如果您的應用程式只有一個活動,您可以在活動的 onCreate 方法中直接呼叫此方法。例如:

package com.google.android.apps.analytics.sample;

import com.google.android.apps.analytics.GoogleAnalyticsTracker;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;

public class TestActivity extends Activity {

  GoogleAnalyticsTracker tracker;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    tracker = GoogleAnalyticsTracker.getInstance();

    // Start the tracker in manual dispatch mode...
    tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", this);

    // ...alternatively, the tracker can be started with a dispatch interval (in seconds).
    //tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", 20, this);

    setContentView(R.layout.main);
    Button createEventButton = (Button)findViewById(R.id.NewEventButton);
    createEventButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        tracker.trackEvent(
            "Clicks",  // Category
            "Button",  // Action
            "clicked", // Label
            77);       // Value
      }
    });

    Button createPageButton = (Button)findViewById(R.id.NewPageButton);
    createPageButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Add a Custom Variable to this pageview, with name of "Medium" and value "MobileApp" and
        // scope of session-level.
        tracker.setCustomVar(1, "Navigation Type", "Button click", 2);
        // Track a page view. This is probably the best way to track which parts of your application
        // are being used.
        // E.g.
        // tracker.trackPageView("/help"); to track someone looking at the help screen.
        // tracker.trackPageView("/level2"); to track someone reaching level 2 in a game.
        // tracker.trackPageView("/uploadScreen"); to track someone using an upload screen.
        tracker.trackPageView("/testApplicationHomeScreen");
      }
    });

    Button quitButton = (Button)findViewById(R.id.QuitButton);
    quitButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        finish();
      }
    });

    Button dispatchButton = (Button)findViewById(R.id.DispatchButton);
    dispatchButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Manually start a dispatch, not needed if the tracker was started with a dispatch
        // interval.
        tracker.dispatch();
      }
    });
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();
    // Stop the tracker when it is no longer needed.
    tracker.stopSession();
  }
}

如果您的應用程式中有多個活動,則可使用 analytics-api-samples 專案「下載」部分提供的 EasyTracker 程式庫。

追蹤網頁瀏覽和事件

追蹤網頁瀏覽和事件很簡單:只要每次要觸發網頁瀏覽,呼叫追蹤器物件的 trackPageView。呼叫 trackEvent 以記錄事件。如要進一步瞭解網頁瀏覽和事件,請參閱上方的 SDK 總覽

使用自訂變數

新增自訂變數也很簡單,只要使用行動 SDK 提供的 setCustomVar 方法即可。因此,建議您提前規劃將每個自訂變數對應至的索引值,以免覆寫任何現有變數。如要進一步瞭解自訂變數,請參閱自訂變數指南。請注意,setCustomVar 方法不會直接傳送資料。而是與已追蹤的網頁瀏覽或事件一併傳送。追蹤網頁瀏覽或事件前,您必須呼叫 setCustomVar 。請注意,自訂變數的預設範圍是以網頁為範圍。

使用電子商務追蹤

在應用程式中啟用電子商務追蹤的方法有 4 種,分別是:

  • addTransaction
  • addItem
  • trackTransactions
  • clearTransactions

呼叫 addTransactionaddItem 會將交易或項目新增至內部電子商務緩衝區,以便新增更多項目和交易。只有在呼叫 trackTransactions 時,交易和項目才會傳送至調度工具,並排入 Google Analytics (分析)。

如要清除緩衝區,您可以呼叫 clearTransactions 方法。注意:喚回了先前傳送至調度工具的任何交易,以及 Google Analytics (分析) 已收集的任何交易。

下列程式碼範例可協助您開始作業。我們假設在購買交易確認或拒絕時,會呼叫 onPurchaseCompleted 方法。

  /**
   * The purchase was processed.  We will track the transaction and its associated line items
   * now, but only if the purchase has been confirmed.
   *
   * @param purchase A PurchaseObject containing all of the transaction information needed to
   *     send the ecommerce hit to Google Analytics.
   */
  public void onPurchaseCompleted(PurchaseObject purchase) {
    tracker.addTransaction(new Transaction.Builder(
        purchase.getTransactionId(),
        purchase.getTotal())
        .setStoreName(purchase.getStoreName())
        .setTotalTax(purchase.getTotalTax())
        .setShippingCost(purchase.getShippingCost())
        .build());
    for (PurchaseLineItem lineItem : purchase.getLineItems()) {
        tracker.addItem(new Item.Builder(
            purchase.getTransactionId(),
            lineItem.getItemSKU(),
            lineItem.getItemCost(),
            lineItem.getQuantity())
            .setItemName(lineItem.getItemName())
            .setItemCategory(lineItem.getItemCategory())
            .build());
    }
    if (purchase.isConfirmed()) {
      tracker.trackTransactions();
    } else {
      // The purchase was denied or failed in some way.  We need to clear out
      // any data we've already put in the Ecommerce buffer.
      tracker.clearTransactions();
    }
  }

如要進一步瞭解電子商務,請參閱「電子商務追蹤指南」一文。

將 IP 去識別化

如要將使用者 IP 資訊去識別化,請使用 setAnonymizeIp 方法。藉此告知 Google Analytics (分析) 在 IP 儲存前移除 IP 位址的最後八位元,將 SDK 傳送的資訊去識別化。

您隨時可以呼叫 setAnonymizeIp

設定取樣率

您可以使用 setSampleRate 方法設定取樣率。如果您的應用程式會產生大量 Analytics (分析) 流量,設定取樣率可能會導致系統無法使用取樣資料產生報表。只有不重複使用者時,系統會持續進行取樣,因此在啟用取樣率時,趨勢和報表功能都會具有完整性。 setSampleRate 方法可接受一個 int 參數。該參數的有效值是介於 0 到 100 (含) 之間的任何整數。

率為 0 可關閉命中產生功能,100 的比率則將所有資料傳送到 Google Analytics (分析)。 最好在呼叫任何追蹤方法之前,呼叫 setSampleRate

如要進一步瞭解取樣範例,請參閱取樣概念指南

批次命中

為了節省連線和電池負擔,建議您批次處理追蹤要求。您隨時可以提出追蹤物件呼叫 dispatch,藉此手動提出要求,也可以按照特定時間間隔進行呼叫。

已知問題

  • 針對不同的執行緒呼叫 GoogleAnalyticsTracker 方法可能會導致模糊錯誤。請務必透過同一個執行緒發起所有通話。
  • 追蹤廣告活動

    這個 SDK 支援兩種廣告活動追蹤。

    - Google Play 廣告活動追蹤 – 可讓您透過 Google Play 追蹤安裝參照連結網址。
    - 一般廣告活動追蹤:可讓您追蹤將使用者轉介至您應用程式的廣告活動。

    Google Play 廣告活動追蹤

    Android 1.6 OS 版本支援在 Google Play 的下載連結中使用 referrer 網址參數。Google Analytics (分析) SDK for Android 會使用這個參數,在 Google Analytics (分析) 中自動填入您應用程式的廣告活動資訊。這樣就能記錄應用程式安裝來源,並與未來的網頁瀏覽和事件建立關聯,方便您評估應用程式的特定廣告效益。

    為了讓參照連結網址追蹤功能正常運作,您必須在專案的AndroidManifest.xml資訊清單檔案中加入下列程式碼片段:

    <!-- Used for install referrer tracking -->
    <receiver android:name="com.google.android.apps.analytics.AnalyticsReceiver" android:exported="true">
      <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
      </intent-filter>
    </receiver>
    

    如要透過 Google Play 設定 Google Analytics (分析) 廣告活動追蹤,請使用下方的網址產生器產生推薦連結。藉此連到您的應用程式。Analytics (分析) SDK 會自動剖析並記錄推薦連結資訊,然後列在 Analytics (分析) 報表中。

    如要產生推薦連結,可以使用 Google Play 廣告活動網址產生器。「套件名稱」、「廣告活動來源」、「廣告活動媒介」和「廣告活動名稱」為必填欄位。如需每個參數的詳細說明,請參閱下方的表格

    一般廣告活動追蹤

    Google Analytics (分析) SDK for Android 1.3 版現在可以追蹤 Google Play 以外來源的廣告活動。 舉例來說,假設您想知道某個廣告是透過啟動連結的方式啟動的,請在意圖啟動您的應用程式的意圖中,檢查廣告活動參照連結網址資訊,然後將該廣告活動資訊儲存在 Google Analytics (分析) 中。

    如要設定廣告活動參照連結網址資訊,請使用 setReferrer 方法,如下所示:

      tracker.setReferrer(referrer);
    

    使用這項功能有兩項限制。您必須先呼叫 startNewSession 才能呼叫 setReferrer。之所以要做到這點,這是因為 Google Analytics (分析) 使用的 SQLite 資料庫並未在呼叫 startNewSession 之前設定,而 setReferrer 需要該資料庫。如未呼叫 startNewSession,您會收到 IllegalStateException

    第二個限制是,傳遞至 setReferrer 的參照連結網址字串必須符合特定格式。必須使用一組網址參數,且至少須包含 gclid 參數,或是個別 utm_campaign、utm_medium 和 utm_source。如果是後者,則可包含 utm_term 和 utm_content 參數。

    gclid 參數是自動標記功能的一部分,可將 Google Analytics (分析) 連結至 Google Ads。使用自動標記的廣告活動參照連結網址範例:

    referrer = “gclid=gclidValue”;
    

    手動廣告活動參照連結網址字串看起來可能會像這樣:

    referrer = “utm_campaign=campaign&utm_source=source&utm_medium=medium&utm_term=term&utm_content=content”;
    

    如果您傳遞了格式不正確的參照網址字串至 setReferrer,參照資訊就不會變更,您也會收到 false 的傳回值。傳回 true 值表示參照網址已更新,且會新增至日後的每次命中中。

    另請注意,當您呼叫 setReferrer 時,系統會啟動新的工作階段,並傳回 true。

    參數 必填 說明 範例
    utm_campaign 廣告活動名稱;用於關鍵字分析,識別特定產品促銷或策略廣告活動 utm_campaign=spring_sale
    utm_source 廣告活動來源;用來辨識搜尋引擎、電子報或其他來源 utm_source=google
    utm_medium 廣告活動媒介;用來識別電子郵件或單次點擊出價等媒介 utm_medium=cpc
    utm_term 廣告活動字詞;透過付費搜尋提供廣告關鍵字 utm_term=running+shoes
    utm_content 廣告活動內容;用於 A/B 測試和指定內容廣告,以區分指向相同網址的廣告或連結 utm_content=logolink
    utm_content=textlink