# 自动采集

> 来源：https://help.gravity-engine.com/docs/client-sdk/web/automatic-tracking
> 介绍 Gravity Engine Web SDK 支持自动采集的基础事件、开启方式及相关配置。



## 1. 介绍 [#1-介绍]

引力引擎 SDK 提供了自动采集功能，支持自动采集一些基础行为事件，目前主要有以下几种事件支持自动采集：

1. `展示（$WebPageShow）`：开启页面展示事件
2. `进入后台（$WebPageHide）`：并记录本次访问（展示至隐藏）的时间

本文将会对每种类型的自采集事件做详细介绍。

## 2. 监控 HTML 元素点击事件 [#2-监控-html-元素点击事件]

如果您想要追踪页面上元素的点击事件，可以使用 `trackLink` 对 HTML 元素进行批量监控：

```js
ge.trackLink(
  {
    tag: ["a", "button"], // HTML 标签
    class: ["class1", "class2"], // 自定义的 Class 名称
    id: ["id1", "id2"], // 自定义的 ID 名称
  }, // 监控元素的规则
  "click", // 追踪事件的名称
  {
    production: "产品名",
    name: "元素标识名",
  } // 事件的属性
);
```

* 第一个参数是您需要监控的元素，类型是 `JSON` 对象，支持根据 HTML 标签、Class 以及 id 追踪需要监控的页面元素。对于满足规则的元素，会通过事件监听器的方式监控元素的点击事件，当监听元素被点击时，将会上报一个事件，事件名和事件属性取后续两个参数的值。
* 第二个参数是事件的名称，为 `string` 类型，必须填写。
* 第三个参数是事件的属性，类型是 `JSON` 对象，如果没有需要上报的属性，可传入空 `JSON`。
* 事件属性 `name` 为元素的标识，如果参数三中没有设置事件属性 `name`，我们将会根据被监控元素的属性值作为元素标识，取值优先级如下：

  1. 取值元素的自定义属性 `ge-name`
  2. 元素的 `innerHTML`
  3. 元素的 `value`
  4. 如果都没有取到则传 `未获取标识`

`trackLink` 在被调用时会为符合规则的元素设置事件监听器。在调用接口后元素的标识发生变化，或者新生成了符合规则的元素，监听器上报的事件不会做出相应的改变。如果需要监控新生成元素，可在元素生成后调用 `trackLink`。

## 3. 开启页面自动采集 [#3-开启页面自动采集]

在初始化时的 `config` 中，参数 `autoTrack` 中的元素表示每个自动采集事件的开关，设置为 `true` 为开启对应事件的自动采集：

```js
const config = {
  autoTrack: {
    pageShow: true, // 开启页面展示事件
    pageHide: true, // 开启页面隐藏事件
  },
};
```

> 为了更好地在引力引擎平台做后向数据分析，建议您全部开启。

## 4. 详细介绍 [#4-详细介绍]

### 4.1 展示事件 [#41-展示事件]

* 英文事件名：`$WebPageShow`
* 触发时机：启动之后首次展示或后台调回前台时触发。
* 自动采集属性：
  * `$referrer`，页面来源
  * `$referrer_host`，页面来源 host
  * `$url`，页面 url
  * `$url_path`，页面路径
  * `$title`，页面 title

### 4.2 进入后台事件 [#42-进入后台事件]

* 英文事件名：`$WebPageHide`
* 触发时机：在进入后台时触发，并记录本次使用的时长。
* 自动采集属性：
  * `$referrer`，页面来源
  * `$referrer_host`，页面来源 host
  * `$url`，页面 url
  * `$url_path`，页面路径
  * `$title`，页面 title
  * `$event_duration`，数值型，表示本次启动（`$WebPageShow`）到进入后台的持续时长，单位为秒

Web 隐藏事件会记录使用时长（单位为秒），因此可以直接计算用户使用总时长以及人均时长，也可以除以启动次数计算单次使用时长。

## 5. 页面浏览事件 [#5-页面浏览事件]

引力提供自动采集页面浏览事件的接口。您只需使用以下代码，JS SDK 将会自动上传用户浏览页面的事件，事件名称为 `$WebPageView`：

```js
ge.quick("autoTrack");
```

该接口已支持自定义属性，请参考如下调用：

```js
// 该接口在调用时，会立即上报一次页面浏览事件
ge.quick("autoTrack", {
  name: "test_name",
  pro: [1, 2, 3, 4],
});
```