Android SDK 自动采集指南

一、自动采集介绍

TA 系统提供自动化收集数据的接口，您可根据业务需求自行选择需要自动收集的数据。

目前支持的自动采集事件类型有：

1. APP 安装，记录 APP 被安装的日志
2. APP 启动，包括打开 APP 和从后台唤醒
3. APP 关闭，包括关闭 APP 和调入后台，同时收集启动的时长
4. 用户在 APP 中浏览页面（Activity）
5. 用户在 APP 中点击控件
6. APP 发生崩溃时记录崩溃信息

接下来将会详细介绍每种数据的采集方法

二、开启自动采集

您可以调用enableAutoTrack，打开自动采集功能：

List<ThinkingAnalyticsSDK.AutoTrackEventType> eventTypeList = new ArrayList<>();

//APP安装事件
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL);

//APP启动事件
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START);

//APP关闭事件
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END);

//APP浏览页面事件
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_VIEW_SCREEN);

//APP点击控件事件
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CLICK);

//APP崩溃事件
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CRASH);

//开启自动采集事件
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).enableAutoTrack(eventTypeList);

可根据业务需要，开启自动采集的事件。

提示

如果您需要采集控件点击事件或者 Fragment 浏览事件，需要集成自动采集插件.

如需设置公共事件属性或设置自定义访客 ID，请确保在开启自动采集之前调用 setSuperProperties() 或 identify()

代码样例：

// 初始化 SDK
ThinkingAnalyticsSDK.sharedInstance(this, "TA_APP_ID","TA_SERVER_URL");

// 设置访客 ID
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).identify("123456789ABCabc");

// 设置公共事件属性
try {
    JSONObject superProperties = new JSONObject();
    superProperties.put("Channel","B1");
    ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setSuperProperties(superProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

//设置完访客ID与公共属性后，再开启自动采集
List<ThinkingAnalyticsSDK.AutoTrackEventType> eventTypeList = new ArrayList<>();
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_VIEW_SCREEN);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CLICK);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CRASH);

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).enableAutoTrack(eventTypeList);

三、自动采集事件详解

3.1 APP 安装事件

APP 安装事件将会记录 APP 的实际安装，在 APP 启动时上报，事件触发时间是 APP 安装后首次启动的时间，APP 升级并不会触发安装事件，而删除重装后会上报安装事件。

• 事件名：ta_app_install

3.2 APP 启动事件

APP 启动事件将会在用户开启 APP，或从后台唤醒 APP 时触发，详细的事件介绍如下：

• 事件名：ta_app_start
• 预置属性：#resume_from_background，布尔型，表示 APP 是用户开启还是从后台唤醒，取值为 true 表示从后台唤醒，false 为直接开启。
• 需要注意的是，从V2.8.1开始，SDK默认不再允许后台静默启动(如直接启动后台服务或者推送)触发的start事件，可在res/values下通过资源文件配置来开启

<!-- 是否允许后台触发Start事件 -->
<!--    <bool name="TAEnableBackgroundStartEvent">true</bool>-->

3.3 APP 关闭事件

APP 关闭事件将会在用户关闭 APP，或将 APP 调至后台时触发，详细的事件介绍如下：

• 事件名：ta_app_end
• 预置属性：#duration，数值型，表示该次 APP 访问（自启动至结束）的时长，单位是秒。

3.4 APP 浏览页面事件

APP 浏览页面事件将会在用户浏览页面（Activity）时，将会触发浏览页面事件，详细的事件介绍如下：

• 事件名：ta_app_view
• 预置属性：
• #screen_name，字符串型，为Activity的包名.类名
• #title，字符串型，为Activity的标题，取值为Activity的title属性的值

页面浏览事件中可以加入其它属性以扩展其分析价值，以下是自定义浏览页面事件的属性的方法

3.4.1 开启自动采集 Fragment 的页面浏览事件

对于android.support.v4.app.Fragment的 Fragment，可以使用以下方法自动采集页面浏览事件：

在 SDK 初始化完成后，调用以下方法启动 Fragment 的自动采集功能

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).trackFragmentAppViewScreen();

对于android.app.Fragment的 Fragment，可以通过以下方法自行调用页面浏览事件：

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).trackViewScreen(targetFragment);

• targetFragment可替换为需要上传页面浏览事件的 Fragment

3.4.2 自定义页面浏览事件的属性

对于Activity的页面浏览事件，可以通过实现接口ScreenAutoTracker的方法增加属性，通过复写以下两方法，可以为页面浏览事件增加页面 URL 信息，以及其他自定义属性：

public class MainActivity extends AppCompatActivity implements ScreenAutoTracker {
    private Context mContext;

    @Override
    public String getScreenUrl() {
        return "thinkingdata://page/main";
    }

    @Override
    public JSONObject getTrackProperties() throws JSONException {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("param1", "ABCD");
        jsonObject.put("param2", "thinkingdata");
        return jsonObject;
    }
}

其中getScreenUrl的返回值将作为该Activity的 URL Schema，当触发该页面的浏览事件时，将会加入预置属性#url，取值即为当前页面的 URL Schema，同时 SDK 会取跳转前页面的 URL Schema，如果能取到则会加入到预置属性#referrer中则为前向地址。

getTrackProperties的返回值是该页面的浏览事件的自定义属性，将会自动加入到该页面的浏览事件中

2.对于Fragment的页面浏览事件，可以

通过对 Fragment 类添加注解 @ThinkingDataFragmentTitle ，例如

@ThinkingDataFragmentTitle(title = "myFragment")
public class ListViewFragment extends BaseFragment {
  // your fragment implementations
}

通过 Fragment 实现 ScreenAutoTracker 接口，在自定义属性中增加 #title 属性

  @Override
  public JSONObject getTrackProperties() {
      try {
          JSONObject properties = new JSONObject();
          properties.put("#title", "RecyclerViewFragment");
          return properties;
      } catch (JSONException e) {
          // ignore
      }
      return null;
  }

3.5 APP 控件点击事件

APP 控件点击事件将会在用户点击控件（view）时触发

• 事件名：ta_app_click
• 预置属性：
• #screen_name，字符串型，为控件所属Activity的包名.类名
• #title，字符串型，为控件所属Activity的标题，取值为Activity的title属性的值
• #element_content，字符串型，为控件的内容
• #element_type，字符串型，为控件的类型
• #element_id，字符串型，为控件的 ID，默认使用android:id
• #element_position，字符串型，当控件存在position时才会上传
• #element_selector，字符串型，为控件的viewPath的拼接

对于页面上 View 的点击事件，有以下多种方式来设置更多属性，以扩展其分析价值：

3.5.1 自定义控件 ID

控件的 ID 默认使用android:id，如果该属性无法取到，或者希望自定义控件 ID，可以使用以下方法覆盖#element_id属性

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setViewID(view,viewID);

对于 Dialog，可以使用如下方法：

//android.app.Dialog
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setViewID(view,viewID);

或者

//android.support.v7.app.AlertDialog
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setViewID(view,viewID);

参数view为需要设置控件 ID 的 view，参数viewID为设置的控件 ID，当上传该控件的点击事件时，#element_id的取值即为此处的传入值

3.5.2 自定义控件点击事件的属性

您可以通过以下方法，为某控件（view）的点击事件增加自定义属性：

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setViewProperties(view,properties);

参数view为需要设置自定义属性的 view，参数properties，类型为JSONObject，为设置的自定义属性，当上传该控件的点击事件时，将会添加这些属性。

另外，对于ExpandableListView、ListView与GridView，还可以通过 Adapter 实现接口的方式，来增加点击某 item 时的自定义属性。

• ExpandableListView需实现ThinkingExpandableListViewItemTrackProperties接口

public interface ThinkingExpandableListViewItemTrackProperties {
    /**
     * 增加点击 groupPosition、childPosition 处 item 时的属性
     * @param groupPosition
     * @param childPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingChildItemTrackProperties(int groupPosition, int childPosition) throws JSONException;

    /**
     * 增加点击 groupPosition 处 item 时的属性
     * @param groupPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingGroupItemTrackProperties(int groupPosition) throws JSONException;
}

• ListView与GridView需实现ThinkingAdapterViewItemTrackProperties接口

public interface ThinkingAdapterViewItemTrackProperties {
    /**
     * 增加点击 position 处 item 时的属性
     * @param position
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingItemTrackProperties(int position) throws JSONException;
}

3.5.3 对AlertDialog的点击事件增加页面（Activity）信息

对于AlertDialog（android.app.AlertDialog与android.support.v7.app.AlertDialog）的点击事件，可以通过以下方法绑定所属页面（Activity），在其点击事件中将会加入所属页面的 #screen_name 与 #title 属性。

• 通过调用dialog.show()显示 dialog，请使用以下方法：

dialog.setOwnerActivity(targetActivity);

• 通过调用builder.show()显示 dialog，请使用以下方法:

builder.show().setOwnerActivity(activity);

3.5.4 通过注解@ThinkingDataTrackViewOnClick上传控件点击事件

如果您使用的是android:onclick为控件（view）添加点击事件的调用方法，则可以在调用方法上添加注解@ThinkingDataTrackViewOnClick，当该调用方法被执行时，SDK 将会上传控件点击事件

@ThinkingDataTrackViewOnClick
public void buttonOnClick(View v){}

如果方法buttonOnClick被调用，则会上传控件点击事件

3.6 APP 崩溃事件

当 APP 出现未捕获异常时，会上报 APP 崩溃事件

• 事件名：ta_app_crash
• 预置属性：
• #app_crashed_reason，字符型，记录崩溃时的堆栈轨迹

四、忽略自动采集事件

您可以通过以下方式，忽略某页面或控件的自动采集事件

4.1 忽略页面的自动采集事件

对于某些页面（Activity），如果不想传输自动采集事件（包括页面浏览与控件点击事件），可以通过以下方法进行忽略：

//单页面的忽略
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreAutoTrackActivity(MainActivity.class);

//多页面的忽略
List<Class<?>> classList = new ArrayList<>();
classList.add(MainActivity.class);
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreAutoTrackActivities(classList);

也可以在Activity或Fragment前添加注解@ThinkingDataIgnoreTrackAppViewScreen，忽略某个Activity或Fragment的页面浏览事件

//忽略 TestActivity 的页面浏览事件
@ThinkingDataIgnoreTrackAppViewScreen
public class TestActivity extends AppCompatActivity {
    ...
}

在Activity前添加注解@ThinkingDataIgnoreTrackAppViewScreenAndAppClick，忽略某个Activity页面浏览事件与该页面下的控件点击事件

//忽略 TestActivity 的页面浏览事件与该页面下的控件点击事件
@ThinkingDataIgnoreTrackAppViewScreenAndAppClick
public class TestActivity extends AppCompatActivity {
    ...
}

4.2 忽略某个类型控件的点击事件

如果需要忽略某个类型控件的点击事件，可以使用以下方法进行忽略

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreViewType(ignoredClass);

• ignoredClass即为需要忽略的控件类型，比如Dialog、Checkbox等

4.3 忽略某个元素（View）的点击事件

如果希望忽略某个元素（View）的点击事件，可以使用以下方法进行忽略

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreView(targetView);

• targetView即为需要忽略的 View

五、使用注解快速设置事件

如果需要监控某个方法的调用次数，或者某方法一经调用即需要上传一个事件，则可以使用注解@ThinkingDataTrackEvent快速设置需要上传的事件，需要注意的是，属性无法传入变量，因此只适合上传简单的事件

//使用注解
@ThinkingDataTrackEvent(eventName = "event_name", properties = "{\"paramString\":\"value\",\"paramNumber\":123,\"paramBoolean\":true}")
public void fun(){}

此时如果方法fun被调用，则会上传一个事件名为event_name，属性为"paramString":"value"、"paramNumber":123 与 "paramBoolean":true 的事件

六、自动采集事件的预置属性

以下预置属性，是各个自动采集事件中所特有的预置属性

• APP 启动事件（ta_app_start）的预置属性

属性名	中文名	说明
#resume_from_background	是否从后台唤醒	表示 APP 是被开启还是从后台唤醒，取值为 true 表示从后台唤醒，false 为直接开启

• APP 关闭事件（ta_app_end）的预置属性

属性名	中文名	说明
#duration	事件时长	表示该次 APP 访问（自启动至结束）的时长，单位是秒

• APP 浏览页面事件（ta_app_view）的预置属性

属性名	中文名	说明
#title	页面标题	为控件所属 Activity 的标题，取值为 Activity 的 title 属性的值
#screen_name	页面名称	为控件所属 Activity 的包名.类名
#url	页面地址	当前页面的地址，需要调用 getScreenUrl 进行 url 的设置
#referrer	前向地址	跳转前页面的地址，跳转前页面需要调用 getScreenUrl 进行 url 的设置

• APP 控件点击事件（ta_app_click）的预置属性

属性名	中文名	说明
#title	页面标题	为控件所属 Activity 的标题，取值为 Activity 的 title 属性的值
#screen_name	页面名称	为控件所属 Activity 的包名.类名
#element_id	元素 ID	控件的 ID，默认使用 android:id ，可调用 setViewID 进行设置
#element_type	元素类型	控件的类型
#element_selector	元素选择器	为控件的 viewPath 的拼接
#element_position	元素位置	控件的位置信息，当控件存在 position 属性时才会上传
#element_content	元素内容	控件上的内容

• APP 崩溃事件（ta_app_crash）的预置属性

属性名	中文名	说明
#app_crashed_reason	异常信息	字符型，记录崩溃时的堆栈轨迹

七、集成自动采集功能插件（可选）

提示

只有当您需要开启控件点击事件和 Fragment 页面浏览事件时，才需要集成此插件。

apply plugin: 'cn.thinkingdata.android'

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'cn.thinkingdata.android:android-gradle-plugin2:1.0.5'
    }
}

可以在项目build.gradle文件中配置插件相关参数

apply plugin: 'cn.thinkingdata.android'
android {

}
ThinkingAnalytics {
    debug = true
    disableJar = true
    exclude = []
    excludeSensitive = []
}

如果想打开编译日志，可以设置debug = true，默认为false

如果想禁止扫描jar中的类，可以设置disableJar = true，默认是false

如果不想扫描某个路径下的类，可以通过设置exclude = ['cn.thinkingdata.android','android.support']

从插件V1.0.5版本开始，支持配置敏感属性(如AndroidID)的代码隔离，可通过设置excludeSensitive = ['AndroidID']来配置，该功能需要主SDK版本V2.8.1及以上支持。

提示

2.7.6.1以下版本的SDK请集成老版本的插件

SDK版本为2.0.0-2.7.6， 请使用如下插件：

apply plugin: 'cn.thinkingdata.android'

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'cn.thinkingdata.android:android-gradle-plugin:2.0.2'
    }
}

2.0.0 之前版本的 SDK，请使用如下插件：

apply plugin: 'com.thinkingdata.analytics.android'

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'com.thinking.analyselibrary.plugin:android-gradle-plugin:1.2.0'
    }
}

八、自动采集事件设置自定义属性

您可以调用 enableAutoTrack(List<ThinkingAnalyticsSDK.AutoTrackEventType>, JSONObject)，打开自动采集功能，同时设置自定义属性

JSONObject properties = new JSONObject();
try {
    properties.put("auto_self_define_key", "auto_self_define_value");
} catch (Exception e) {
    e.printStackTrace();
}
ThinkingAnalyticsSDK.enableAutoTrack(typeList, properties);

您也可以调用 setAutoTrackProperties(List<ThinkingAnalyticsSDK.AutoTrackEventType>, JSONObject)，设置或者更新自定义属性

JSONObject properties = new JSONObject();
try {
    properties.put("auto_self_define_key", "auto_self_define_value");
} catch (Exception e) {
    e.printStackTrace();
}
ThinkingAnalyticsSDK.setAutoTrackProperties(typeList, properties);

九、自动采集事件设置回调

在V2.7.5版本之后，您可以通过设置回调，在已开启的自动采集事件发生时，获取到当前事件的事件类型以及所携带的事件属性，并且可以通过设置返回值的方式为该事件增加额外需要上报的属性。

List<ThinkingAnalyticsSDK.AutoTrackEventType> typeList = new ArrayList<>();
typeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START);
typeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL);
typeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END);

mInstance.enableAutoTrack(typeList, new ThinkingAnalyticsSDK.AutoTrackEventListener() {
    @Override
    public JSONObject eventCallback(ThinkingAnalyticsSDK.AutoTrackEventType eventType, JSONObject properties) {
        try {
            return new JSONObject("{\"keykey\":\"value1111\"}");
        } catch (JSONException e) {
            e.printStackTrace();
            return null;
        }
    }
});