Android SDK 自动采集指南

1. 自动采集介绍

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

现在支持的自动化收集数据有：

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

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

2. 开启自动采集

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

自动采集插件，可以提供 Fragment 浏览和控件点击等自动采集事件

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'
    }
}

2.2 开启自动采集

您可以调用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);

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

ThinkingAnalyticsSDK.sharedInstance("APPID","SERVER_URL");

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. 自动采集事件详解

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. 忽略自动采集事件

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

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

5. 使用注解快速设置事件

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

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

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

6. 自动采集事件的预置属性

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

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

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

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

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

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