自动采集

Android SDK 支持包括安装、启动、关闭等在内事件的自动采集。

一、介绍

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

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

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

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

二、开启自动采集

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

//APP安装事件 TDAnalytics.TDAutoTrackEventType.APP_INSTALL
//APP启动事件 TDAnalytics.TDAutoTrackEventType.APP_START
//APP关闭事件 TDAnalytics.TDAutoTrackEventType.APP_END
//APP浏览页面事件 TDAnalytics.TDAutoTrackEventType.APP_VIEW_SCREEN
//APP点击控件事件 TDAnalytics.TDAutoTrackEventType.APP_CLICK
//APP崩溃事件 TDAnalytics.TDAutoTrackEventType.APP_CRASH
//开启自动采集事件
TDAnalytics.enableAutoTrack(TDAnalytics.TDAutoTrackEventType.APP_START | TDAnalytics.TDAutoTrackEventType.APP_END
        | TDAnalytics.TDAutoTrackEventType.APP_INSTALL | TDAnalytics.TDAutoTrackEventType.APP_VIEW_SCREEN | TDAnalytics.TDAutoTrackEventType.APP_CLICK
        | TDAnalytics.TDAutoTrackEventType.APP_CRASH);

提示

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

三、详细介绍

3.1 安装事件

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

• 事件名：ta_app_install

3.2 启动事件

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

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

<?xml version="1.0" encoding="utf-8"?>
<resources>
   <bool name="TAEnableBackgroundStartEvent">true</bool>
</resources>

3.3 关闭事件

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

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

3.4 浏览页面事件

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

• 事件名：ta_app_view
• 预置属性：

#screen_name，字符串型，为Activity的包名.类名

#title，字符串型，为Activity的标题，取值为Activity的title属性的值

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

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

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

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

TDAnalytics.trackFragmentAppViewScreen();

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

TDAnalytics.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;
    }
}

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

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

对于Fragment的页面浏览事件，我们提供两种方式添加属性

• 通过@ThinkingDataFragmentTitle 方式添加属性

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

• 实现 ScreenAutoTracker 接口

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

3.5 点击事件

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属性

TDAnalytics.setViewID(view,viewID);

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

//android.app.Dialog
TDAnalytics.setViewID(view,viewID);

或者

//android.support.v7.app.AlertDialog
TDAnalytics.setViewID(view,viewID);

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

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

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

TDAnalytics.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 崩溃事件

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

四、忽略自动采集事件

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

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

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

//单页面的忽略
TDAnalytics.ignoreAutoTrackActivity(MainActivity.class);
//多页面的忽略
List<Class<?>> classList = new ArrayList<>();
classList.add(MainActivity.class);
TDAnalytics.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 忽略某个类型控件的点击事件

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

TDAnalytics.ignoreViewType(ignoredClass);

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

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

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

TDAnalytics.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 为直接开启
#start_reason	应用启动来源	文本	内容为JSON字符串；应用使用url或者intent方式打开APP时，自动记录url内容以及intent中的data数据，样例参考:{url:"thinkingdata://","data":{}}
#background_duration	后台停留时长	数值	记录两次start事件发生区间内，应用处于后台的时长， 单位:秒

- 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 页面浏览事件时，才需要集成此插件。

提示

如果您集成的数据采集SDK版本低于3.0.0，需要使用1.1.0版本。

从2.1.0版本开始，兼容Gradle8.0。

apply plugin: 'cn.thinkingdata.android'

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

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

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

}
ThinkingAnalytics {
    debug = true
    exclude = []
    sdk{
        disableAndroidID = false
    }
}

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

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

从插件V2.1.0版本开始，支持配置敏感属性(如AndroidID)的代码隔离，可通过设置disableAndroidID = true来配置。

八、设置自定义属性

您可以调用 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();
}
TDAnalytics.enableAutoTrack(typeList, properties);

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

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

TDAnalytics.enableAutoTrack(TDAnalytics.TDAutoTrackEventType.APP_END | TDAnalytics.TDAutoTrackEventType.APP_START, new TDAnalytics.TDAutoTrackEventHandler() {
    @Override
    public JSONObject getPropertiesWithEventType(int eventType, JSONObject properties) {
        try {
            return new JSONObject("{\"keykey\":\"value1111\"}");
        } catch (JSONException e) {
            e.printStackTrace();
            return null;
        }
    }
});