Google Analytics Advanced Configuration

      该文档提供了Android SDK v3的部分元素的高级配置说明。

Overview - 概述

      Android Google Analytics SDK提供了Tracker类，应用可以用它给Google Analytics设置和发送数据，GoogleAnalytics的单例为你实现的全局配置值提供了接口。

Initialization - 初始化

      在开始检测数据之前，你必须通过GoogleAnalytics单例实现至少一个跟踪，你需要提供的参数有Context和Google Analytics的属性ID。

      // 使用Google Analytics的属性ID来初始化一个跟踪

      GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y")

      现在，这个tracker可以给Google Analytics设置和发送数据了。

Setting and Sending Data - 设置和发送数据

      通过tracker的set方法把发送给Google Analytics的数据设置为键-值对的形式，然后通过send方法把数据发送给Google Analytics。

/*

 * 在tracker上设置map的参数值，并通过调用send方法把屏幕上的视图发送给Google Analytics

 */

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类简化了构建页面元素点击的进程，在大多数用户安全中，这种方式是推荐的。你可以使用它来发送同样的屏幕视图，但是使用的代码更少：

        

// 使用MapBuilder.createAppView()方法来发送同样的屏幕视图的点击事件

tracker.(MapBuilder

  .createAppView()

  .set(Fields.SCREEN_NAME, "Home Screen")

  .build()

);

Applying Values to Multiple Hits - 给多个屏幕的页面元素应用值

      直接设置在tracker上的值将会保持住，并将其应用给多个点击事件，例如：

// 在tracker上设置的屏幕名称，将在发送所有的点击事件时都被应用

tracker.set(Fields.SCREEN_NAME, "Home Screen");

 

// 为"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()

);

 

// 清理我们曾经设置过的屏幕名称字段

tracker.set(Fields.SCREEN_NAME, null);

      仅仅当你想在多个页面元素上保持某个值时，你才需要把它直接设置在tracker上。在tracker上设置屏幕名称是有意义的，因为同样的值可以被应用给随后发生的子视图和点击事件上。但是，不建议在tracker上设置类似于点击类型的字段，因为它极有可能在每次点击时改变。

Using Multiple Tracker - 使用多个Tracker

      在同一个单个的实例里，可以使用多个tracker，这样的做法在把数据发送给多个属性时很有用。

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

 


// tracker可以被命名。默认地，名称为要被设置的属性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());

 

//给 UA-XXXX-1发送屏幕视图

t1.send(MapBuilder

   .createAppView()

   .build()

);

 

// 给UA-XXXX-2发送屏幕视图

t2.send(MapBuilder

   .createAppView()

   .build()

);

      像动态屏幕检测和未捕获的异常检测一样，自动检测元素将不仅仅使用一个tracker给Google Analytics发送数据。如果你使用了这些元素并想使用其它tracker发送数据时，你需要手动的做这些。

Using the Default Tracker - 使用默认的Tracker

      Google Analytics包含默认的tracker。被第一个初始化的tracker就会成为默认的tracker，但是它可以被重写。

// Tracker t1成为默认的tracker，因为它是首先被实例化的

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

Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-2");

 

 

//返回tracker t1.

Tracker defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

 

// 点击事件发送给UA-XXXX-1.

defaultTracker.send(MapBuilder

    .createAppView()

    .set(Fields.SCREEN_NAME, "Home Screen")

    .build()

);

 

// 重写默认的tracker.

GoogleAnalytics.getInstance(this).setDefaultTracker(t2);

 

// 现在该调用会返回tracker t2.

defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

 

// 点击事件发送给UA-XXXX-2.

defaultTracker.send(MapBuilder

    .createAppView()

    .set(Fields.SCREEN_NAME, getClass().toString())

    .build()

);

Sampling - 抽样

      你可以启动客户端抽样来限制发送给Google Analytics点击事件的数量。如果你的应用有大量的用户或者给Google Analytics发送了大量的数据，启动抽样可以确保不间断的汇报。

      例如，通过EasyTracker和XML启动客户端50%的抽样率：

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

      以编辑的方式给tracker启用客户端的采样率：

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

      为了防止汇报矛盾，你应用的每个视图都应该以相同的抽样进行数据的收集。如果你应用的不同版本使用不同的抽样频率，在你单个应用的不同版本里，为给不同应用版本范围保存各自的数据，你需要配置视图(profile)。

App-level Opt Out - 暴露的应用级别选项

      你可以使用暴露出的应用级别的选项，使用它们可以在整个应用里禁用Google Analytics。注意：在应用每次启动时你都需要设置该标识，它的默认值是false。

      为了获取暴露的应用级别选项，你可以这样做：

      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 {

    // 其它的代码

    }

  }

});

Testing and Debugging - 测试和调试

      Android Google Analytics SDK提供了更简单进行测试和调试的工具。

Dry Run

      SDK提供了dryRun标识，如果设置了它，那么就会阻止任何发送给Google Analytics的数据。在你测试或是调试一个实现时，并不想让这些数据出现在你Google Analytics的汇报里，那你应该设置该标识。

      // When dry run is set, hits will not be dispatched, but will still be logged as

      // though they were dispatched.

      GoogeAnalytics.getInstance(this).setDryRun(true);

Logger

      Logger接口将会从SDK里处理有用的信息，一共有几个级别：error，warning，info，verbose。

      SDK会初始化一个标准的Logger实现，它默认仅仅只会读取打印到console控制台的warning和error类型的信息。这些信息在logcat里是可用的。

      // 把日志的级别设置为verbose

      GoogleAnalytics.getInstance(this).getLogger().setLogLevel(LogLevel.VERBOSE);

      可以使用自定义的Logger的实现：

      // 提供自定义的logger

      GoogleAnalytics.getInstance(this).setLogger(new CustomLogger ());

Complete Example - 完整的例子

      下面的代码展示了初始化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;

 

 

/*

 * 在Application的子类里初始化的Google Analytics的进阶实现。

 * 注意：该例假设只给一个Google Analytics属性ID发送属性。

 */

public class MyApp extends Application {

 

  private static GoogleAnalytics mGa;

  private static Tracker mTracker;

 

  /*

   * Google Analytics配置值.

   */

  // 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";

 

 

  /*

   * 处理基本Google Analytics初始化的方法。   

   * 因为所有的Google Analytics的工作都发生在主线程之外，因此该调用不会阻塞主线程

   */

  private void initializeGa() {

    mGa = GoogleAnalytics.getInstance(this);

    mTracker = mGa.getTracker(GA_PROPERTY_ID);

 

    // 设置调试周期

    GAServiceManager.getInstance().setLocalDispatchPeriod(GA_DISPATCH_PERIOD);

 

    // 设置dryRun标识

    mGa.setDryRun(GA_IS_DRY_RUN);

 

    // 设置Logger级别

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

  }

 

  /*

   * 返回Google Analytics tracker

   */

  public static Tracker getGaTracker() {

    return mTracker;

  }

 

  /*

   * 返回Google Analytics实例

   */

  public static GoogleAnalytics getGaInstance() {

    return mGa;

  }

}

      接着，当第一个屏幕显示给用户时，屏幕视图被检测。

package com.example.app

 

import android.app.Activity

 

/**

 * 当Activity给用户显示时，该activity给Google Analytics发送一个屏幕视图

 */

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

  }

}