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

package/README.md

@@ -1,6 +1,6 @@
 > **构建用户数据体系，让用户行为数据发挥深远的价值。**
 
-**当前版本**: v1.2.0
+**当前版本**: v1.2.3
 
 ## 前言
 
@@ -204,6 +204,11 @@ 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      |
 | pageKey                           | string               | 自定义页面唯一标识，如果不传则自动从路由获取                | 否           | 自动生成   |
 
 #### 例子
@@ -266,6 +271,11 @@ 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      |
 | pageKey                           | string               | 自定义页面唯一标识，如果不传则自动从路由获取            | 否           | 自动生成   |
 
 #### 例子
@@ -588,6 +598,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 +753,7 @@ const newDeviceId = WebTracking.resetDeviceId();
 4. 批量发送失败时，数据会自动重新加入队列，避免数据丢失
 5. **数据持久化**：队列数据会自动保存到 LocalStorage，页面刷新或关闭后数据不会丢失
 6. **自动恢复**：重新打开页面时，会自动从 LocalStorage 恢复未发送的数据并继续发送
+7. **数据格式**：批量发送时直接发送数组，不包装在 `events` 参数中
 
 #### 使用示例
 
@@ -699,6 +768,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 +839,161 @@ 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()` 方法，适合在特定时机上报（如页面离开时）
+- **定时上报**：使用配置项自动上报，适合持续监控场景
+
+两种方式可以同时使用，互不冲突。
+
 ---
 
 ## 六、版本更新日志
 
-### v1.2.0 (最新)
+### v1.2.3 (最新)
+
+- 🐛 修复批量发送数据格式问题
+  - 批量发送时直接发送数组，不再包装在 `events` 参数中
+- ✨ 新增页面停留时长手动上报功能
+  - `trackPageDuration()` - 手动上报页面停留时长
+  - 支持自定义时长或自动计算时长
+  - 支持自定义页面标识和业务参数
+- ✨ 新增页面停留时长定时上报功能
+  - `autoTrackPageDurationInterval` - 是否定时上报页面停留时长
+  - `pageDurationInterval` - 定时上报间隔时间（默认30秒）
+  - 只在页面可见时上报，避免后台上报
+- ✨ 新增数据发送方式配置
+  - `sendMethod` - 支持 auto、xhr、beacon 三种模式
+  - auto 模式自动选择最佳发送方式（推荐）
+  - 页面卸载时自动使用 sendBeacon 确保数据发送
+- ✨ 新增元素点击追踪配置
+  - `trackPartKeyClick` - 只追踪带有 data-part-key 属性的元素点击
+  - 支持与 autoTrack 配合使用，实现灵活的埋点策略
+
+### v1.2.0
 
 - ✨ 新增设备 ID 管理功能（基于浏览器指纹技术）
   - `getDeviceId()` - 获取设备唯一标识