高级配置 - Android SDK

本文档将大略介绍 Android 版 Google Analytics（分析）SDK v3 的高级配置功能。

概览

Android 版 Google Analytics（分析）SDK 提供了一个 Tracker 类，用于设置并向 Google Analytics（分析）发送数据，并提供了一个 GoogleAnalytics 单例来作为您的实现方案的全局配置值的接口。

初始化

您需要先通过 GoogleAnalytics 单例至少初始化一个跟踪器，然后才能开始衡量数据。在初始化时，您需要提供 Context 和 Google Analytics（分析）媒体资源 ID：

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

现在此跟踪器就可用于设置并向 Google Analytics（分析）发送数据了。

设置和发送数据

为了向 Google Analytics（分析）发送数据，您需要在跟踪器中设置“参数-值”对的映射关系，并通过 set 和 send 方法来发送这些数据：

/*
 * 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“&”符号语法

您可以选择为 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 提供了多种工具，可让您更轻松地进行测试和调试。

Dry Run

SDK 提供了 dryRun 标志，如果设置了此标志，则不会向 Google Analytics（分析）发送任何数据。在您对实现方案进行测试或调试时，如果不想测试数据出现在您的 Google Analytics（分析）报告中，就应当设置 dryRun 标志。

要设置 dryRun 标志，请使用以下代码：

// 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());
  }
}