# Android SDK 自动采集指南
# 一、自动采集介绍
TA 系统提供自动化收集数据的接口，您可根据业务需求自行选择需要自动收集的数据。
目前支持的自动采集事件类型有：
- APP 安装，记录 APP 被安装的日志
- APP 启动，包括打开 APP 和从后台唤醒
- APP 关闭，包括关闭 APP 和调入后台，同时收集启动的时长
- 用户在 APP 中浏览页面（Activity）
- 用户在 APP 中点击控件
- 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 为直接开启。
# 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 页面浏览事件时，才需要集成此插件。
如果想要支持lambda表达式，以及解决编译过程中的报错，可以使用最新版本插件，需要集成的sdk版本不得低于2.7.6
apply plugin: 'cn.thinkingdata.android'
buildscript {
repositories {
google()
jcenter()
}
dependencies {
classpath 'cn.thinkingdata.android:android-gradle-plugin2:1.0.1'
}
}
可以在项目build.gradle文件中配置插件相关参数
apply plugin: 'cn.thinkingdata.android'
android {
}
ThinkingAnalytics {
debug = true
disableJar = true
exclude = []
}
如果想打开编译日志，可以设置debug = true，默认为false
如果想禁止扫描jar中的类，可以设置disableJar = true，默认是false
如果不想扫描某个路径下的类，可以通过设置exclude = ['cn.thinkingdata.android','android.support']
老版本插件
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;
}
}
});