# 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 为直接开启。

# 3.3 APP 关闭事件

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

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

# 3.4 APP 浏览页面事件

APP 浏览页面事件将会在用户浏览页面(Activity)时,将会触发浏览页面事件,详细的事件介绍如下:

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

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

# 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的标题,取值为Activitytitle属性的值
  • #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,为设置的自定义属性,当上传该控件的点击事件时,将会添加这些属性。

另外,对于ExpandableListViewListViewGridView,还可以通过 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;
}
  • ListViewGridView需实现ThinkingAdapterViewItemTrackProperties接口
public interface ThinkingAdapterViewItemTrackProperties {
    /**
     * 增加点击 position 处 item 时的属性
     * @param position
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingItemTrackProperties(int position) throws JSONException;
}

# 3.5.3 对AlertDialog的点击事件增加页面(Activity)信息

对于AlertDialogandroid.app.AlertDialogandroid.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);

也可以在ActivityFragment前添加注解@ThinkingDataIgnoreTrackAppViewScreen,忽略某个ActivityFragment的页面浏览事件

//忽略 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即为需要忽略的控件类型,比如DialogCheckbox

# 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的标题,取值为Activitytitle属性的值
#screen_name 页面名称 为控件所属Activity的包名.类名
#url 页面地址 当前页面的地址,需要调用getScreenUrl进行 url 的设置
#referrer 前向地址 跳转前页面的地址,跳转前页面需要调用getScreenUrl进行 url 的设置
  • APP 控件点击事件(ta_app_click)的预置属性
属性名 中文名 说明
#title 页面标题 为控件所属Activity的标题,取值为Activitytitle属性的值
#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-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'
    }
}