進階設定 - Android SDK

本文件概要說明 Android v3 專用的 Google Analytics (分析) SDK 部分進階設定。

總覽

Android 版 Google Analytics (分析) SDK 提供 Tracker 類別，可用於設定資料並傳送至 Google Analytics (分析)，以及 GoogleAnalytics 單例模式，用來連結至導入項目的全域設定值。

初始化

必須先提供 Context 和 Google Analytics (分析) 資源 ID，才能透過 GoogleAnalytics 單例模式初始化至少一個追蹤器，才能開始評估資料：

// Initialize a tracker using a Google Analytics property ID.
GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y")

現在，這個追蹤程式可用於設定資料並傳送至 Google Analytics (分析)。

設定和傳送資料

系統會在追蹤器上設定參數/值組合的對應關係，並透過 set 和 send 方法傳送資料，藉此將資料傳送至 Google Analytics (分析)：

/*
 * Send a screen view to Google Analytics by setting a map of parameter
 * values on the tracker and calling send.
 */
Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y");

HashMap<String, String> hitParameters = new HashMap<String, String>();
hitParameters.put(Fields.HIT_TYPE, "appview");
hitParameters.put(Fields.SCREEN_NAME, "Home Screen");

tracker.send(hitParameters);

MapBuilder 類別簡化了建立命中程序，建議用於大多數用途。我們可以傳送相同的畫面檢視畫面，減少行數：

// Sending the same screen view hit using MapBuilder.createAppView()
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "Home Screen")
  .build()
);

Measurement Protocol Ampersand 語法

您也可針對單次命中設定值，方法是在 Builder 上設定值；針對所有後續命中值，則可使用 Measurement Protocol 與語法在追蹤程式物件上設定該值：

// Setting the content description field on a single hit using ampersand syntax.
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "Home Screen")
  .build()
);

如需可用 Measurement Protocol 參數的完整清單，請參閱 Measurement Protocol 參數參考資料。

將值套用至多次命中

系統會保留直接在追蹤程式上設定的任何值，並套用至多個命中，如以下範例所示：

// Set screen name on the tracker to be sent with all hits.
tracker.set(Fields.SCREEN_NAME, "Home Screen");

// Send a screen view for "Home Screen"
tracker.send(MapBuilder
    .createAppView()
    .build()
);

// This event will also be sent with &cd=Home%20Screen.
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

// Clear the screen name field when we're done.
tracker.set(Fields.SCREEN_NAME, null);

請只在追蹤程式上直接設定想要在多次命中中保留的值。在追蹤程式上設定畫面名稱很合理，因為相同的值可套用至後續的畫面瀏覽和事件命中。不過，我們不建議您在追蹤程式上設定命中類型這類欄位，因為這個欄位可能會隨每次命中而改變。

使用多個追蹤器

單一導入方式可使用多個追蹤程式，這個方式在將資料傳送至多個資源時相當實用：

Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1");

// Trackers may be named. By default, name is set to the property ID.
Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("altTracker", "UA-XXXX-2";

t1.set(Fields.SCREEN_NAME, "Home Screen");
t2.set(Fields.SCREEN_NAME, getClass().toString());

// Send screen view to UA-XXXX-1.
t1.send(MapBuilder
   .createAppView()
   .build()
);

// Send screen view to UA-XXXX-2.
t2.send(MapBuilder
   .createAppView()
   .build()
);

自動評估功能 (例如自動螢幕和未偵測到的例外狀況評估) 只會使用一個追蹤器傳送資料至 Google Analytics (分析)。如果您正在使用這些功能，並希望使用其他追蹤器傳送資料，則必須手動進行。

使用預設追蹤器

Google Analytics (分析) 會保留預設追蹤程式。第一個初始化的追蹤器會成為預設追蹤程式，但可能會遭到覆寫：

// Tracker t1 becomes the default tracker because it is initialized first.
Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1");
Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-2");


// Returns tracker t1.
Tracker defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

// Hit sent to UA-XXXX-1.
defaultTracker.send(MapBuilder
    .createAppView()
    .set(Fields.SCREEN_NAME, "Home Screen")
    .build()
);

// Override the default tracker.
GoogleAnalytics.getInstance(this).setDefaultTracker(t2);

// Now this call returns tracker t2.
defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

// Hit sent to UA-XXXX-2.
defaultTracker.send(MapBuilder
    .createAppView()
    .set(Fields.SCREEN_NAME, getClass().toString())
    .build()
);

取樣

您可以啟用用戶端取樣功能，限制傳送至 Google Analytics (分析) 的命中次數。如果應用程式的使用者人數較多，或是以其他方式傳送大量資料至 Google Analytics (分析)，啟用取樣功能可確保報表資料不會中斷。

舉例來說，如果想透過 EasyTracker 和 XML 以 50% 的速率啟用用戶端取樣，請在 analytics.xml 檔案中使用以下參數：

<string name="ga_sampleFrequency">50.0</string>

如何以程式輔助方式啟用追蹤器的用戶端取樣功能：

mTracker.set(Fields.SAMPLE_RATE, 50.0d);

在應用程式層級選擇不採用

您可以啟用應用程式層級的選擇不採用標記，藉此停用整個應用程式的 Google Analytics (分析)。請注意，每次啟動應用程式時，都必須設定這個標記，並將預設值預設為 NO。

如要取得應用程式層級的停用設定，請使用：

boolean isOptedOut = GoogleAnalytics.getInstance(this).getAppOptOut();

如要設定應用程式層級的選擇不採用功能，請使用：

GoogleAnalytics.getInstance(this).setAppOptOut(true);

在一般導入作業中，應用程式可能會監聽 SharedPreferences 的變更，並據此更新 Google Analytics (分析) 選擇不採用設定：

SharedPreferences userPrefs = PreferenceManager.getDefaultSharedPreferences(this);

userPrefs.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener () {

  @Override
  public void onSharedPreferenceChanged(SharedPreferences sharedPreferences,
      String key) {

    if (key.equals(TRACKING_PREF_KEY)) {
      GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false));
    } else {
    // Any additional changed preference handling.
    }
  }
});

測試和偵錯

Android 版 Google Analytics (分析) SDK 提供多項工具，協助您輕鬆進行測試和偵錯。

模擬測試

SDK 提供 dryRun 旗標，設定後可防止任何資料傳送至 Google Analytics (分析)。每次測試或偵錯導入時，都應設定 dryRun 標記，但不希望測試資料顯示在 Google Analytics (分析) 報表中。

如要設定模擬測試標記，請按照下列步驟操作：

// When dry run is set, hits will not be dispatched, but will still be logged as
// though they were dispatched.
GoogleAnalytics.getInstance(this).setDryRun(true);

Logger

提供 Logger 介面，以處理 SDK 在這些詳細程度層級的實用訊息：error、warning、info 和 verbose。

SDK 會初始化標準 Logger 實作，根據預設，系統只會將警告或錯誤訊息記錄到控制台。這些訊息會出現在 logcat 中。如要設定 Logger 的詳細程度：

// Set the log level to verbose.
GoogleAnalytics.getInstance(this).getLogger()
    .setLogLevel(LogLevel.VERBOSE);

您也可以使用 Logger 的自訂實作項目：

// Provide a custom logger.
GoogleAnalytics.getInstance(this).setLogger(new CustomLogger ());

完整範例

以下範例說明初始化 Google Analytics (分析) 導入作業，並傳送單一畫面檢視畫面所需的程式碼。

package com.example.app;

import com.google.analytics.tracking.android.GAServiceManager;
import com.google.analytics.tracking.android.GoogleAnalytics;
import com.google.analytics.tracking.android.Tracker;

import android.app.Application;
import android.content.SharedPreferences;
import android.preference.PreferenceManager;


/*
 * An advanced Google Analytics implementation may be initialized
 * in a subclass of Application. Note that this example assumes data
 * only needs to be sent to a single Google Analytics property ID.
 */
public class MyApp extends Application {

  private static GoogleAnalytics mGa;
  private static Tracker mTracker;

  /*
   * Google Analytics configuration values.
   */
  // Placeholder property ID.
  private static final String GA_PROPERTY_ID = "UA-XXXX-Y";

  // Dispatch period in seconds.
  private static final int GA_DISPATCH_PERIOD = 30;

  // Prevent hits from being sent to reports, i.e. during testing.
  private static final boolean GA_IS_DRY_RUN = false;

  // GA Logger verbosity.
  private static final LogLevel GA_LOG_VERBOSITY = LogLevel.INFO;

  // Key used to store a user's tracking preferences in SharedPreferences.
  private static final String TRACKING_PREF_KEY = "trackingPreference";


  /*
   * Method to handle basic Google Analytics initialization. This call will not
   * block as all Google Analytics work occurs off the main thread.
   */
  private void initializeGa() {
    mGa = GoogleAnalytics.getInstance(this);
    mTracker = mGa.getTracker(GA_PROPERTY_ID);

    // Set dispatch period.
    GAServiceManager.getInstance().setLocalDispatchPeriod(GA_DISPATCH_PERIOD);

    // Set dryRun flag.
    mGa.setDryRun(GA_IS_DRY_RUN);

    // Set Logger verbosity.
    mGa.getLogger().setLogLevel(GA_LOG_VERBOSITY);

    // Set the opt out flag when user updates a tracking preference.
    SharedPreferences userPrefs = PreferenceManager.getDefaultSharedPreferences(this);
    userPrefs.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener () {
      @Override
      public void onSharedPreferenceChanged(SharedPreferences sharedPreferences,
          String key) {
        if (key.equals(TRACKING_PREF_KEY)) {
          GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false));
        }
      }
    });
  }

  @Override
  public void onCreate() {
    super.onCreate();
    initializeGa();
  }

  /*
   * Returns the Google Analytics tracker.
   */
  public static Tracker getGaTracker() {
    return mTracker;
  }

  /*
   * Returns the Google Analytics instance.
   */
  public static GoogleAnalytics getGaInstance() {
    return mGa;
  }
}

接著，系統會在使用者看到第一個畫面時評估一次畫面瀏覽：

package com.example.app

import android.app.Activity

/**
 * A simple Activity that sends a screen view to Google Analytics
 * when it is displayed to the user.
 */
public class HomeScreen extends Activity {

  private static final String SCREEN_LABEL = "Home Screen";

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

    // Fields set on a tracker persist for all hits, until they are
    // overridden or cleared by assignment to null.
    MyApp.getGaTracker().set(Fields.SCREEN_NAME, SCREEN_LABEL);
  }

  @Override
  public void onStart() {
    super.onStart();

    // Send a screen view when the Activity is displayed to the user.
    MyApp.getGaTracker().send(MapBuilder
        .createAppView.build());
  }
}