duration-tracker-test/README.md

页面元素曝光/时长统计插件

# DurationTracker 使用文档

## 简介

`DurationTracker` 是一个用于统计页面元素曝光时长或页面总浏览时长的 JS 插件。支持自动监听元素进入/离开可视区、页面切换、最小化、关闭、bfcache 等，适合前端埋点、曝光统计等需求。另外还自己封装了请求。

---
## 安装  
Using npm:
```bash  
npm i --save duration-tracker  
```  

## 快速开始

```js  
import { DurationTracker, sendTrackingRequest } from 'duration-tracker';
const tracker = new DurationTracker({
    el: document.querySelectorAll('li'), // [expose类型时必要，totalTime类型时非必要] 需要监听的元素（NodeList/数组/单个元素），注意多个不相关的元素，获取后需要组成数组
    threshold: 0.5,                      // [非必要] 元素可见比例（0~1），默认0.5，当前元素可见的比例，才算在可视区域内。例如 [0, 0.25, 0.5, 0.75, 1] 表示当目标元素可见 0%、25%、50%、75% 或 100%，默认0.5
    interval: 5000,                      // [非必要] 上报间隔，单位ms，默认5000
    takeValueType: 'round',              // [非必要] 时长取整方式：ceil/floor/round，默认round
    resetStayTimeKey: "browse_duration_second", // [非必要] 上报时长字段名，默认stay_time
    resetIdKey: "id",                    // [非必要] 元素唯一标识字段名，默认id，注意：该字段名必须与元素自定义属性一致，如 data-id="99600"
    reportType: ['expose', 'totalTime'], // [非必要] 上报类型，可选['expose']（曝光）、['totalTime']（总时长），或['expose', 'totalTime']，默认['expose']
    callback: function(data, extra) {    // [必要] 记录时长回调 data为上报数据，根据不同的reportType，返回格式不同；extra额外的浏览器信息，其中 pageStatus: true/false 表示当前页面是否可见
        // 接口上报
        sendTrackingRequest('url', data).then(res => { ... })
    }
});
```

---

## 参数说明  
DurationTracker(Object)，返回当前实例

| 参数名              | 说明                                 | 类型         | 默认值      |
|---------------------|--------------------------------------|--------------|-------------|
| el                  | 监听的元素集合                        | NodeList/Array/Element | 可选        |
| threshold           | 可见比例阈值（0~1）                   | Number       | 0.5         |
| interval            | 上报间隔（ms）                        | Number       | 5000        |
| takeValueType       | 时长取整方式（ceil/floor/round）      | String       | 'round'     |
| resetStayTimeKey    | 上报时长字段名                        | String       | 'stay_time' |
| resetIdKey          | 元素唯一标识字段名                    | String       | 'id'        |
| reportType          | 上报类型数组（'expose'/'totalTime'）  | Array        | ['expose']  |
| callback            | 上报回调函数                          | Function     | null        |

---

sendTrackingRequest(url, data, [fetchType])，返回Promise对象  
| 参数名              | 说明                                 | 类型         | 默认值      |
|---------------------- |--------------------------------------|--------------|-------------|
| url                  | 接口                                 | String       | - 必要     |
| data                 | 入参                                 | Object       | - 必要     |
| fetchType            | 请求类型                             | String       | - 可选，beacon:sendBeacon类型，fetch:fetch类型；|

---

## 回调参数
DurationTracker.callback
- `data`：上报的统计数据（数组或对象，视 reportType 而定）
- `extra`：附加信息，包括 baseInfo（设备、浏览器、页面等）、pageStatus（show/hide）  
  
sendTrackingRequest.promise
- `promise`：返回接口结果。如果是sendBeacon，只能返回true/false。如果是fetch，则返回接口结果。
---

## 常用方法

- `tracker.destroyWatch()`  
  停止监听和上报。停止瞬间会返回当前统计的数据。

- `tracker.restartWatch(newElements)`  
  重新启动监听。[newElements]，可选，传入新监听的元素；不传则监听已有元素。

- `tracker.updatedDomWatch(newElements)`  
  更新监听元素（如分页/懒加载后）。元素有变更时，请调用此方法。newElements，必传，监听的所有元素。

- `tracker.runReport()`  
  立即上报一次。

---

## 设备、系统、浏览器信息

插件会自动采集以下信息并在回调 `extra.baseInfo` 中返回：

- 设备类型（device_type）
- 操作系统及版本（os, os_version）
- 浏览器及版本（browser, browser_version）
- 页面URL、referrer、屏幕分辨率、网络类型等

---

## 事件兼容性

- 自动兼容页面切换、最小化、关闭、bfcache 场景，保证数据完整上报。
- 内部已做防抖/节流处理，避免重复上报。
- sendTrackingRequest支持优先使用sendBeacon，如入不支持则降级为fetch，所以建议不配置[fetchType]
---

## 示例

```js
const tracker = new DurationTracker({
    el: [...document.querySelectorAll('li'), document.geElementById('xxx')],
    reportType: ['expose', 'totalTime'],
    callback: function(data, extra) {
        // data: 曝光/时长数据
        // extra: 设备、浏览器、页面等信息
        // 可在此处发起接口上报
        sendTrackingRequest('url', data).then(res => { ... })
    }
});
```  

```html
<ul>
    <li data-id="1"></li>
    <li data-id="2"></li>
</ul>
```
---

## 注意事项

- 如有分页/懒加载，需在新元素渲染后调用 `updatedDomWatch` 方法。
- 销毁监听后如需恢复，调用 `restartWatch`。
- 支持多实例并行使用。  
- 建议用 Navigator.sendBeacon进行接口上报，此方法在关闭页面后仍会把数据发送完成。插件内部封装了 Navigator.sendBeacon和fetch的请求sendTrackingRequest。