该文档提供了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 () {@Overridepublic 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 () {@Overridepublic void onSharedPreferenceChanged(SharedPreferences sharedPreferences,String key) {if (key.equals(TRACKING_PREF_KEY)) {GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false));}}});}@Overridepublic 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.appimport android.app.Activity/*** 当Activity给用户显示时,该activity给Google Analytics发送一个屏幕视图*/public class HomeScreen extends Activity {private static final String SCREEN_LABEL = "Home Screen";@Overridepublic 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);}@Overridepublic void onStart() {super.onStart();// Send a screen view when the Activity is displayed to the user. MyApp.getGaTracker().send(MapBuilder.createAppView.build());}}