DurationTracker 使用文档

简介

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

安装

Using npm:

npm i --save duration-tracker  

快速开始

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]

示例

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 => { ... })
    }
});

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

注意事项

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