---
code: android_sdk_autotrack
name: "自动采集"
wikiToken: SmbqwAQ2XiUNssk6ib0cY1y7nmg
parentWikiToken: J7zFwvYawiv1E6k6TsYc5YzXnLc
updateTime: 1773195492000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=android_sdk_autotrack
---
# 自动采集

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

### 一、介绍

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

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

1. 安装事件：记录 APP 被安装的行为
1. 启动事件：包括打开 APP 和从后台打开APP
1. 关闭事件：包括关闭 APP 和App进入后台，同时收集启动的时长
1. 浏览事件：用户在 APP 中浏览页面（`Activity`）
1. 点击事件：用户在 APP 中点击控件
1. 崩溃事件：APP 发生崩溃时记录崩溃信息
接下来将会详细介绍每种数据的采集方法

### 二、开启自动采集

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

:::: el-tabs

::: el-tab-pane label=Java

```
//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*);
```

:::

::: el-tab-pane label=Kotlin

```
//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 *or TDAnalytics.TDAutoTrackEventType.*APP_END*
*            *or TDAnalytics.TDAutoTrackEventType.*APP_INSTALL *or TDAnalytics.TDAutoTrackEventType.*APP_VIEW_SCREEN *or TDAnalytics.TDAutoTrackEventType.*APP_CLICK*
*            *or TDAnalytics.TDAutoTrackEventType.*APP_CRASH*
)
```

:::

::::

::: tip 提示

 如果您需要采集控件点击事件或者 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 的自动采集功能

:::: el-tabs

::: el-tab-pane label=Java

```
TDAnalytics.trackFragmentAppViewScreen();
```

:::

::: el-tab-pane label=Kotlin

```
TDAnalytics.trackFragmentAppViewScreen()
```

:::

::::

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

:::: el-tabs

::: el-tab-pane label=Java

```
TDAnalytics.trackViewScreen(targetFragment);
```

:::

::: el-tab-pane label=Kotlin

```
TDAnalytics.trackViewScreen(targetFragment)
```

:::

::::

- `targetFragment`可替换为需要上传页面浏览事件的 Fragment
##### 3.4.2 自定义页面浏览事件的属性

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

:::: el-tabs

::: el-tab-pane label=Java

```
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;
    }
}
```

:::

::: el-tab-pane label=Kotlin

```
class MainActivity : AppCompatActivity(), ScreenAutoTracker {

    override fun getScreenUrl(): String {
        return "thinkingdata://page/main";
    }

    override fun getTrackProperties(): JSONObject {
        val jsonObject = JSONObject()
        jsonObject.put("param1", "ABCD")
        jsonObject.put("param2", "thinkingdata")
        return jsonObject
    }
}
```

:::

::::

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

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

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

- 通过`@ThinkingDataFragmentTitle` 方式添加属性
:::: el-tabs

::: el-tab-pane label=Java

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

:::

::: el-tab-pane label=Kotlin

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

:::

::::

- 实现 `ScreenAutoTracker` 接口
:::: el-tabs

::: el-tab-pane label=Java

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

:::

::: el-tab-pane label=Kotlin

```
override fun getTrackProperties(): JSONObject {
    val jsonObject = JSONObject()
    properties.put("#title", "RecyclerViewFragment");
    return jsonObject
}
```

:::

::::

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

:::: el-tabs

::: el-tab-pane label=Java

```
TDAnalytics.setViewID(view,viewID);
```

:::

::: el-tab-pane label=Kotlin

```
TDAnalytics.setViewID(view,viewID)
```

:::

::::

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

:::: el-tabs

::: el-tab-pane label=Java

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

:::

::: el-tab-pane label=Kotlin

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

:::

::::

或者

:::: el-tabs

::: el-tab-pane label=Java

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

:::

::: el-tab-pane label=Kotlin

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

:::

::::

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

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

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

:::: el-tabs

::: el-tab-pane label=Java

```
TDAnalytics.setViewProperties(view,properties);
```

:::

::: el-tab-pane label=Kotlin

```
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`），如果不想传输自动采集事件（包括页面浏览与控件点击事件），可以通过以下方法进行忽略：

:::: el-tabs

::: el-tab-pane label=Java

```
//单页面的忽略
TDAnalytics.ignoreAutoTrackActivity(MainActivity.class);
//多页面的忽略
List<Class<?>> classList = new ArrayList<>();
classList.add(MainActivity.class);
TDAnalytics.ignoreAutoTrackActivities(classList);
```

:::

::: el-tab-pane label=Kotlin

```
//单页面的忽略
TDAnalytics.ignoreAutoTrackActivity(MainActivity::class.*java*)
//多页面的忽略
val classList: MutableList<Class<*>> = ArrayList()
classList.add(MainActivity::class.*java*)
TDAnalytics.ignoreAutoTrackActivities(classList)
```

:::

::::

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

:::: el-tabs

::: el-tab-pane label=Java

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

:::

::: el-tab-pane label=Kotlin

```
//忽略 TestActivity 的页面浏览事件
@ThinkingDataIgnoreTrackAppViewScreen
class TestActivity : AppCompatActivity() {
    ...
}
```

:::

::::

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

:::: el-tabs

::: el-tab-pane label=Java

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

:::

::: el-tab-pane label=Kotlin

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

:::

::::

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

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

:::: el-tabs

::: el-tab-pane label=Java

```
TDAnalytics.ignoreViewType(ignoredClass);
```

:::

::: el-tab-pane label=Kotlin

```
TDAnalytics.ignoreViewType(ignoredClass)
```

:::

::::

- `ignoredClass`即为需要忽略的控件类型，比如`Dialog`、`Checkbox`等
#### 4.3 忽略某个元素（View）的点击事件

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

:::: el-tabs

::: el-tab-pane label=Java

```
TDAnalytics.ignoreView(targetView);
```

:::

::: el-tab-pane label=Kotlin

```
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

异常信息

文本

字符型，记录崩溃时的堆栈轨迹

### 七、可选插件

::: tip 提示

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

 :::

::: tip 提示

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

 :::

安卓分析SDK版本

插件版本

[oldest - 3.0.0)

1.2.0

[3.0.0 - 3.1.0]

2.1.0

(3.1.0 - latest]

2.2.0

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

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

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

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

参数详解：

- debug ：是否打开编译日志，true为打开编译日志，默认为false。
- exclude ：排除扫描某个路径下的类，可以通过设置exclude = ['cn.thinkingdata.android','android.support']。
- useInclude 、include：只想扫描某个路径下的类，可以设置useInclude = true，include= ['cn.thinkingdata.android','android.support']。
- disableAndroidID ：是否禁用调用系统API获取AndroidID，从插件V2.1.0版本开始，可通过设置disableAndroidID = true来配置。
### 八、设置自定义属性

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

:::: el-tabs

::: el-tab-pane label=Java

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

:::

::: el-tab-pane label=Kotlin

```
val properties = JSONObject()
properties.put("auto_self_define_key", "auto_self_define_value")
TDAnalytics.enableAutoTrack(typeList, properties)
```

:::

::::

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

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

:::: el-tabs

::: el-tab-pane label=Java

```
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;
        }
    }
});
```

:::

::: el-tab-pane label=Kotlin

```
TDAnalytics.enableAutoTrack(
    TDAnalytics.TDAutoTrackEventType.*APP_END *or TDAnalytics.TDAutoTrackEventType.*APP_START*,
    object : TDAutoTrackEventHandler {
        override fun getAutoTrackEventProperties(p0: Int, p1: JSONObject?): JSONObject {
            return JSONObject("{\"keykey\":\"value1111\"}");
        }
    })
```

:::

::::
