@fle-sdk/event-tracking-web 1.2.2 → 1.2.4

package/README.md

@@ -1,6 +1,6 @@
 > **构建用户数据体系，让用户行为数据发挥深远的价值。**
 
-**当前版本**: v1.2.0
+**当前版本**: v1.2.4
 
 ## 前言
 
@@ -204,6 +204,15 @@ WebTracking
 | batchSend                         | boolean              | 是否启用批量发送                                             | 否           | false      |
 | batchInterval                     | number               | 批量发送间隔时间(ms)                                         | 否           | 5000       |
 | batchMaxSize                      | number               | 批量发送最大数量                                             | 否           | 10         |
+| trackPartKeyClick                 | boolean              | 是否对带有 data-part-key 属性的元素点击进行上报（即使 autoTrack 为 false） | 否           | false      |
+| pendingRequestsMaxSize            | number               | 待发送请求队列最大数量（防止内存溢出）                       | 否           | 50         |
+| sendMethod                        | string               | 数据发送方式：auto（自动选择）、xhr（XMLHttpRequest）、beacon（sendBeacon） | 否           | auto       |
+| autoTrackPageDurationInterval    | boolean              | 是否定时上报页面停留时长                                     | 否           | false      |
+| pageDurationInterval              | number               | 定时上报页面停留时长的间隔时间（毫秒）                        | 否           | 30000      |
+| autoTrackExposure               | boolean              | 是否启用曝光埋点                                             | 否           | false      |
+| exposureThreshold              | number               | 曝光进入可视区判定阈值（0-1之间）                            | 否           | 0.5        |
+| exposureTime                  | number               | 曝光可见停留时长阈值（毫秒）                                 | 否           | 500        |
+| exposureNum                  | number               | 同一元素允许上报的最大曝光次数（不传则不限制）                | 否           | 不限制     |
 | pageKey                           | string               | 自定义页面唯一标识，如果不传则自动从路由获取                | 否           | 自动生成   |
 
 #### 例子
@@ -266,6 +275,15 @@ export default App;
 | batchSend                         | boolean              | 是否启用批量发送                                         | 否           | false      |
 | batchInterval                     | number               | 批量发送间隔时间(ms)                                     | 否           | 5000       |
 | batchMaxSize                      | number               | 批量发送最大数量                                         | 否           | 10         |
+| trackPartKeyClick                 | boolean              | 是否对带有 data-part-key 属性的元素点击进行上报（即使 autoTrack 为 false） | 否           | false      |
+| pendingRequestsMaxSize            | number               | 待发送请求队列最大数量（防止内存溢出）                   | 否           | 50         |
+| sendMethod                        | string               | 数据发送方式：auto（自动选择）、xhr（XMLHttpRequest）、beacon（sendBeacon） | 否           | auto       |
+| autoTrackPageDurationInterval    | boolean              | 是否定时上报页面停留时长                                 | 否           | false      |
+| pageDurationInterval              | number               | 定时上报页面停留时长的间隔时间（毫秒）                    | 否           | 30000      |
+| autoTrackExposure               | boolean              | 是否启用曝光埋点                                         | 否           | false      |
+| exposureThreshold              | number               | 曝光进入可视区判定阈值（0-1之间）                        | 否           | 0.5        |
+| exposureTime                  | number               | 曝光可见停留时长阈值（毫秒）                             | 否           | 500        |
+| exposureNum                  | number               | 同一元素允许上报的最大曝光次数（不传则不限制）            | 否           | 不限制     |
 | pageKey                           | string               | 自定义页面唯一标识，如果不传则自动从路由获取            | 否           | 自动生成   |
 
 #### 例子
@@ -588,6 +606,64 @@ const Index = () => {
 export default Index;
 ```
 
+### TrackPageDuration
+
+> 手动上报页面停留时长。支持自定义时长或自动计算时长。
+
+#### 参数
+
+| 参数名    | type                      | 描述                                                         | 是否必填 | 默认值 |
+| --------- | ------------------------- | ------------------------------------------------------------ | -------- | ------ |
+| duration  | number                    | 自定义停留时长（毫秒），如果不传则自动计算                   | 否       | -      |
+| options   | TrackPageDurationOptions  | 配置选项                                                     | 否       | -      |
+| resetStartTime | boolean              | 是否重置起始时间（手动上报后重置，定时上报不重置）           | 否       | true   |
+
+#### TrackPageDurationOptions
+
+| 参数名    | type                  | 描述                                                         | 是否必填 | 默认值 |
+| --------- | --------------------- | ------------------------------------------------------------ | -------- | ------ |
+| desc      | string                | 自定义描述                                                   | 否       | "Web 页面浏览时长" |
+| business  | {[key: string]: any} | 自定义业务参数                                               | 否       | {}     |
+| pageKey   | string                | 自定义页面唯一标识                                           | 否       | 当前页面标识 |
+| header    | {[key: string]: any} | 自定义请求头                                                 | 否       | -      |
+
+#### 例子
+
+```jsx
+import React, { useEffect } from "react";
+import WebTracking from "@fle-sdk/event-tracking-web";
+
+const Index = () => {
+  // 手动上报页面停留时长（自动计算）
+  const handleReportDuration = () => {
+    WebTracking.trackPageDuration()
+      .then((res) => console.log("上报成功", res))
+      .catch((err) => console.log("上报失败", err));
+  };
+
+  // 手动上报页面停留时长（自定义时长）
+  const handleReportCustomDuration = () => {
+    WebTracking.trackPageDuration(5000, {
+      desc: "自定义时长上报",
+      business: {
+        customField: "value",
+      },
+    })
+      .then((res) => console.log("上报成功", res))
+      .catch((err) => console.log("上报失败", err));
+  };
+
+  return (
+    <div className="index-wrap">
+      <button onClick={handleReportDuration}>上报停留时长</button>
+      <button onClick={handleReportCustomDuration}>上报自定义时长</button>
+    </div>
+  );
+};
+
+export default Index;
+```
+
 ## 四、完整参数明细
 
 ### 4.1 request 参数明细
@@ -685,6 +761,7 @@ const newDeviceId = WebTracking.resetDeviceId();
 4. 批量发送失败时，数据会自动重新加入队列，避免数据丢失
 5. **数据持久化**：队列数据会自动保存到 LocalStorage，页面刷新或关闭后数据不会丢失
 6. **自动恢复**：重新打开页面时，会自动从 LocalStorage 恢复未发送的数据并继续发送
+7. **数据格式**：批量发送时直接发送数组，不包装在 `events` 参数中
 
 #### 使用示例
 
@@ -699,6 +776,31 @@ WebTracking.init({
 });
 ```
 
+#### 数据格式说明
+
+批量发送时，数据直接以数组形式发送，格式如下：
+
+```json
+[
+  {
+    "event": "CustomTrack",
+    "desc": "自定义上报事件",
+    "itemKey": "218844.page1.event1",
+    "requestTime": 1709524231171,
+    "deviceId": "1dd539cdea9332ebb9d5c087f9d4471f",
+    "privateParamMap": { ... }
+  },
+  {
+    "event": "CustomTrack",
+    "desc": "自定义上报事件",
+    "itemKey": "218844.page1.event2",
+    "requestTime": 1709524231172,
+    "deviceId": "1dd539cdea9332ebb9d5c087f9d4471f",
+    "privateParamMap": { ... }
+  }
+]
+```
+
 #### 数据持久化说明
 
 - **自动保存**：每次添加数据到队列时，会自动保存到 LocalStorage
@@ -745,11 +847,273 @@ SDK 会自动过滤敏感字段，保护用户隐私。默认会过滤以下字
 
 如果需要自定义敏感字段列表，可以在代码中扩展 `filterSensitiveData` 方法。
 
+### 5.5 数据发送方式
+
+SDK 支持三种数据发送方式，可通过 `sendMethod` 参数配置。
+
+#### 配置参数
+
+- `sendMethod`: 数据发送方式（默认：auto）
+  - `auto`: 自动选择（推荐）
+    - 优先使用 `sendBeacon`（页面卸载时、无自定义请求头时）
+    - 否则使用 `XMLHttpRequest`
+  - `xhr`: 强制使用 `XMLHttpRequest`
+  - `beacon`: 强制使用 `sendBeacon`
+
+#### 工作原理
+
+1. **auto 模式（推荐）**：
+   - 支持自定义请求头时使用 `XMLHttpRequest`
+   - 不支持自定义请求头时优先使用 `sendBeacon`
+   - 页面卸载时自动切换到 `sendBeacon` 确保数据发送
+   - `sendBeacon` 失败时自动降级到 `XMLHttpRequest`
+
+2. **xhr 模式**：
+   - 始终使用 `XMLHttpRequest` 发送数据
+   - 支持自定义请求头
+   - 支持超时控制
+   - 页面卸载时可能被取消
+
+3. **beacon 模式**：
+   - 始终使用 `sendBeacon` 发送数据
+   - 不支持自定义请求头
+   - 页面卸载时也能可靠发送
+   - 无法获取发送结果
+
+#### 使用示例
+
+```jsx
+WebTracking.init({
+  appKey: "218844",
+  serverUrl: "https://xxx/push",
+  // 使用自动模式（推荐）
+  sendMethod: "auto",
+  // 或者强制使用 XMLHttpRequest
+  // sendMethod: "xhr",
+  // 或者强制使用 sendBeacon
+  // sendMethod: "beacon",
+});
+```
+
+### 5.6 元素点击追踪
+
+SDK 提供了灵活的元素点击追踪方式，支持全埋点和部分埋点两种模式。
+
+#### 配置参数
+
+- `autoTrack`: 是否开启全埋点（包括页面浏览、元素点击事件自动上报）
+- `trackPartKeyClick`: 是否对带有 `data-part-key` 属性的元素点击进行上报（即使 `autoTrack` 为 false）
+
+#### 工作原理
+
+1. **全埋点模式（autoTrack: true）**：
+   - 自动追踪所有元素点击事件
+   - 自动上报页面浏览事件
+   - 支持单页面应用路由变化追踪
+
+2. **部分埋点模式（trackPartKeyClick: true）**：
+   - 只追踪带有 `data-part-key` 属性的元素点击
+   - 适用于需要精确控制埋点范围的场景
+   - 可与 `autoTrack: false` 配合使用
+
+#### 使用示例
+
+```jsx
+// 全埋点模式：追踪所有点击
+WebTracking.init({
+  appKey: "218844",
+  serverUrl: "https://xxx/push",
+  autoTrack: true,
+});
+
+// 部分埋点模式：只追踪带有 data-part-key 的元素
+WebTracking.init({
+  appKey: "218844",
+  serverUrl: "https://xxx/push",
+  autoTrack: false,
+  trackPartKeyClick: true,
+});
+
+// HTML 中使用 data-part-key
+<button data-part-key="recharge_btn" data-desc="显示充值弹窗">
+  充值
+</button>
+```
+
+### 5.7 页面停留时长定时上报
+
+SDK 支持定时上报页面停留时长，适用于需要持续监控用户停留时长的场景。
+
+#### 配置参数
+
+- `autoTrackPageDurationInterval`: 是否定时上报页面停留时长（默认：false）
+- `pageDurationInterval`: 定时上报间隔时间，单位毫秒（默认：30000，即30秒）
+
+#### 工作原理
+
+1. 启用定时上报后，SDK 会启动定时器
+2. 每隔指定时间间隔自动上报页面停留时长
+3. 只在页面可见时上报（避免后台上报）
+4. 定时上报不重置起始时间，数据工程师会进行数据清洗
+5. 页面卸载时自动停止定时器
+
+#### 使用示例
+
+```jsx
+WebTracking.init({
+  appKey: "218844",
+  serverUrl: "https://xxx/push",
+  // 启用定时上报页面停留时长
+  autoTrackPageDurationInterval: true,
+  // 每30秒上报一次
+  pageDurationInterval: 30000,
+});
+```
+
+#### 手动上报 vs 定时上报
+
+- **手动上报**：使用 `trackPageDuration()` 方法，适合在特定时机上报（如页面离开时）
+- **定时上报**：使用配置项自动上报，适合持续监控场景
+
+两种方式可以同时使用，互不冲突。
+
+### 5.8 元素曝光埋点
+
+SDK 支持自动监听元素曝光事件，适用于需要追踪元素可见性的场景（如商品卡片曝光、广告曝光等）。
+
+#### 触发条件
+
+仅对包含 `data-exposure="true"` 的 DOM 元素做曝光监听与上报（区分大小写，建议统一为字符串 "true"）。
+
+#### 配置参数
+
+- `autoTrackExposure`: 是否启用曝光埋点（默认：false）
+- `exposureThreshold`: 曝光进入可视区判定阈值，0-1之间（默认：0.5）
+- `exposureTime`: 曝光可见停留时长阈值，单位毫秒（默认：500）
+- `exposureNum`: 同一元素允许上报的最大曝光次数（默认：不限制）
+
+#### 工作原理
+
+1. 使用 `IntersectionObserver` API 判定元素是否进入可视区
+2. 元素进入可视区后开始计时
+3. 元素离开可视区时，如果可见时长达到 `exposureTime` 阈值，则上报曝光事件
+4. 如果设置了 `exposureNum`，同一元素超过该次数后不再上报
+
+#### 上报参数提取
+
+从目标元素（或其祖先节点，按"就近原则"）提取所有 `data-*` 属性作为埋点业务参数，规则如下：
+
+- 属性名从 `data-xxx-yyy` 转为 `xxxYyy`（camelCase）
+- 示例：`data-goods-id` → `goodsId`，`data-list-id` → `listId`
+- 排除属性：`data-exposure`、`data-part-key`、`data-desc`
+
+#### 使用示例
+
+```jsx
+WebTracking.init({
+  appKey: "218844",
+  serverUrl: "https://xxx/push",
+  // 启用曝光埋点
+  autoTrackExposure: true,
+  // 元素进入可视区 50% 时判定为可见
+  exposureThreshold: 0.5,
+  // 元素连续可见 500ms 才算一次有效曝光
+  exposureTime: 500,
+  // 同一元素最多上报 3 次曝光
+  exposureNum: 3,
+});
+```
+
+#### HTML 使用示例
+
+```jsx
+<div className="goods-list">
+  <div
+    data-exposure="true"
+    data-part-key="goods_card"
+    data-desc="商品卡片曝光"
+    data-goods-id="12345"
+    data-goods-name="测试商品"
+    data-list-id="home_list"
+  >
+    <img src="goods.jpg" alt="商品图片" />
+    <h3>商品名称</h3>
+  </div>
+
+  <div
+    data-exposure="true"
+    data-part-key="ad_banner"
+    data-desc="广告横幅曝光"
+    data-ad-id="999"
+    data-ad-position="top"
+  >
+    <img src="ad.jpg" alt="广告图片" />
+  </div>
+</div>
+```
+
+#### 上报数据示例
+
+```json
+{
+  "event": "WebExposure",
+  "desc": "商品卡片曝光",
+  "itemKey": "218844.home_page.goods_card",
+  "requestTime": 1709524231171,
+  "deviceId": "1dd539cdea9332ebb9d5c087f9d4471f",
+  "privateParamMap": {
+    "business": {
+      "goodsId": "12345",
+      "goodsName": "测试商品",
+      "listId": "home_list"
+    }
+  }
+}
+```
+
+#### 注意事项
+
+1. **浏览器兼容性**：需要浏览器支持 `IntersectionObserver` API，不支持时会自动禁用曝光埋点
+2. **性能优化**：SDK 会自动去重，避免重复监听同一元素
+3. **动态元素**：如果页面中有动态添加的元素，需要手动调用 `observeExposureElements()` 方法（暂未公开）
+4. **数据提取**：`data-*` 属性会从目标元素向上遍历到 BODY 标签，按"就近原则"提取
+
 ---
 
 ## 六、版本更新日志
 
-### v1.2.0 (最新)
+### v1.2.4 (最新)
+
+- ✨ 新增元素曝光埋点功能
+  - `autoTrackExposure` - 是否启用曝光埋点
+  - `exposureThreshold` - 曝光进入可视区判定阈值（0-1之间）
+  - `exposureTime` - 曝光可见停留时长阈值（毫秒）
+  - `exposureNum` - 同一元素允许上报的最大曝光次数
+  - 使用 `IntersectionObserver` API 判定元素可见性
+  - 自动提取 `data-*` 属性作为业务参数
+  - 支持自定义曝光次数限制
+
+### v1.2.3
+
+- 🐛 修复批量发送数据格式问题
+  - 批量发送时直接发送数组，不再包装在 `events` 参数中
+- ✨ 新增页面停留时长手动上报功能
+  - `trackPageDuration()` - 手动上报页面停留时长
+  - 支持自定义时长或自动计算时长
+  - 支持自定义页面标识和业务参数
+- ✨ 新增页面停留时长定时上报功能
+  - `autoTrackPageDurationInterval` - 是否定时上报页面停留时长
+  - `pageDurationInterval` - 定时上报间隔时间（默认30秒）
+  - 只在页面可见时上报，避免后台上报
+- ✨ 新增数据发送方式配置
+  - `sendMethod` - 支持 auto、xhr、beacon 三种模式
+  - auto 模式自动选择最佳发送方式（推荐）
+  - 页面卸载时自动使用 sendBeacon 确保数据发送
+- ✨ 新增元素点击追踪配置
+  - `trackPartKeyClick` - 只追踪带有 data-part-key 属性的元素点击
+  - 支持与 autoTrack 配合使用，实现灵活的埋点策略
+
+### v1.2.0
 
 - ✨ 新增设备 ID 管理功能（基于浏览器指纹技术）
   - `getDeviceId()` - 获取设备唯一标识