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

package/README.md

@@ -1,5 +1,7 @@
 > **构建用户数据体系，让用户行为数据发挥深远的价值。**
 
+**当前版本**: v1.2.0
+
 ## 前言
 
 **WEB 数据埋点 sdk，开始之前请确保了解埋点的架构和基础知识**
@@ -176,7 +178,10 @@ WebTracking
 - track() ---自定义代码埋点上报
 - getDeviceId() ---获取设备唯一标识
 - resetDeviceId() ---重置设备唯一标识
+- setPageKey() ---设置自定义页面唯一标识
+- getPageKey() ---获取当前页面唯一标识
 - clearBatchTimer() ---清理批量发送定时器
+- clearBatchQueue() ---清空批量队列（包括 LocalStorage 中的数据）
 
 ### Init
 
@@ -199,6 +204,7 @@ WebTracking
 | batchSend                         | boolean              | 是否启用批量发送                                             | 否           | false      |
 | batchInterval                     | number               | 批量发送间隔时间(ms)                                         | 否           | 5000       |
 | batchMaxSize                      | number               | 批量发送最大数量                                             | 否           | 10         |
+| pageKey                           | string               | 自定义页面唯一标识，如果不传则自动从路由获取                | 否           | 自动生成   |
 
 #### 例子
 
@@ -228,6 +234,8 @@ const App = () => {
       batchSend: true,
       batchInterval: 5000,
       batchMaxSize: 10,
+      // 自定义页面标识（可选）
+      pageKey: "custom_page_key",
     });
   }, []);
 
@@ -258,6 +266,7 @@ export default App;
 | batchSend                         | boolean              | 是否启用批量发送                                         | 否           | false      |
 | batchInterval                     | number               | 批量发送间隔时间(ms)                                     | 否           | 5000       |
 | batchMaxSize                      | number               | 批量发送最大数量                                         | 否           | 10         |
+| pageKey                           | string               | 自定义页面唯一标识，如果不传则自动从路由获取            | 否           | 自动生成   |
 
 #### 例子
 
@@ -286,6 +295,8 @@ const App = () => {
       batchMaxSize: 10,
       // 设置采样率为 90%
       sampleRate: 0.9,
+      // 自定义页面标识（可选）
+      pageKey: "home_page",
     });
   }, []);
 
@@ -423,6 +434,110 @@ const Test = () => {
 export default Test;
 ```
 
+### ClearBatchQueue
+
+#### 描述
+
+> 清空批量队列。清除内存中的队列数据和 LocalStorage 中持久化的队列数据。适用于需要重置批量发送队列的场景。
+
+#### 例子
+
+```jsx
+import React from "react";
+import WebTracking from "@fle-sdk/event-tracking-web";
+
+const Test = () => {
+  const handleClearQueue = () => {
+    // 清空批量队列（包括 LocalStorage 中的数据）
+    WebTracking.clearBatchQueue();
+  };
+
+  return (
+    <div className="Test">
+      <button onClick={handleClearQueue}>清空队列</button>
+    </div>
+  );
+};
+
+export default Test;
+```
+
+### SetPageKey
+
+#### 描述
+
+> 设置自定义页面唯一标识。设置后，路由变化时不会自动更新 pageKey（除非设置 `autoUpdate: true`）。
+
+#### 参数
+
+| 参数名    | type           | 描述                                                         | 是否必填 | 默认值 |
+| --------- | -------------- | ------------------------------------------------------------ | -------- | ------ |
+| pageKey   | string \| null | 页面唯一标识，如果传入 null 或空字符串，则恢复自动生成       | 是       | -      |
+| autoUpdate | boolean        | 路由变化时是否自动更新（默认：false，使用自定义值后不再自动更新） | 否       | false  |
+
+#### 例子
+
+```jsx
+import React from "react";
+import WebTracking from "@fle-sdk/event-tracking-web";
+
+const Test = () => {
+  // 设置自定义页面标识
+  const handleSetPageKey = () => {
+    WebTracking.setPageKey("custom_page_001");
+  };
+
+  // 设置自定义页面标识，并允许路由变化时自动更新
+  const handleSetPageKeyWithAutoUpdate = () => {
+    WebTracking.setPageKey("custom_page_001", true);
+  };
+
+  // 恢复自动生成页面标识
+  const handleResetPageKey = () => {
+    WebTracking.setPageKey(null);
+  };
+
+  return (
+    <div className="Test">
+      <button onClick={handleSetPageKey}>设置自定义页面标识</button>
+      <button onClick={handleSetPageKeyWithAutoUpdate}>设置并允许自动更新</button>
+      <button onClick={handleResetPageKey}>恢复自动生成</button>
+    </div>
+  );
+};
+
+export default Test;
+```
+
+### GetPageKey
+
+#### 描述
+
+> 获取当前页面唯一标识。
+
+#### 返回值
+
+- `string` - 当前页面唯一标识
+
+#### 例子
+
+```jsx
+import React, { useEffect } from "react";
+import WebTracking from "@fle-sdk/event-tracking-web";
+
+const Test = () => {
+  useEffect(() => {
+    // 获取当前页面标识
+    const pageKey = WebTracking.getPageKey();
+    console.log("当前页面标识:", pageKey);
+  }, []);
+
+  return <div className="Test"></div>;
+};
+
+export default Test;
+```
+
 ### Track
 
 > 手动代码埋点上报
@@ -568,6 +683,8 @@ const newDeviceId = WebTracking.resetDeviceId();
 2. 当队列达到 `batchMaxSize` 时，立即批量发送
 3. 或者每隔 `batchInterval` 毫秒自动发送一次
 4. 批量发送失败时，数据会自动重新加入队列，避免数据丢失
+5. **数据持久化**：队列数据会自动保存到 LocalStorage，页面刷新或关闭后数据不会丢失
+6. **自动恢复**：重新打开页面时，会自动从 LocalStorage 恢复未发送的数据并继续发送
 
 #### 使用示例
 
@@ -582,6 +699,14 @@ WebTracking.init({
 });
 ```
 
+#### 数据持久化说明
+
+- **自动保存**：每次添加数据到队列时，会自动保存到 LocalStorage
+- **自动恢复**：初始化时（如果启用了批量发送），会自动从 LocalStorage 恢复未发送的数据
+- **页面卸载保护**：页面关闭或刷新时，会自动保存队列数据，确保数据不丢失
+- **存储限制**：如果队列数据超过 4MB，会自动截断保留最新的 80% 数据
+- **存储位置**：LocalStorage key 为 `web_tracking_batch_queue`
+
 ### 5.3 数据采样
 
 当数据量过大时，可以使用数据采样功能来控制上报的数据量，节省服务器资源。
@@ -627,11 +752,33 @@ SDK 会自动过滤敏感字段，保护用户隐私。默认会过滤以下字
 ### v1.2.0 (最新)
 
 - ✨ 新增设备 ID 管理功能（基于浏览器指纹技术）
+  - `getDeviceId()` - 获取设备唯一标识
+  - `resetDeviceId()` - 重置设备唯一标识
+- ✨ 新增页面标识自定义功能
+  - `pageKey` - 支持在 init 和 preset 中自定义页面标识
+  - `setPageKey()` - 动态设置页面标识
+  - `getPageKey()` - 获取当前页面标识
+  - 支持恢复自动生成模式
 - ✨ 新增批量发送功能，支持批量上报埋点数据
+  - `batchSend` - 启用批量发送
+  - `batchInterval` - 批量发送间隔时间
+  - `batchMaxSize` - 批量发送最大数量
+  - **LocalStorage 持久化**：队列数据自动保存，页面刷新不丢失
+  - **自动恢复**：重新打开页面时自动恢复未发送的数据
+  - `clearBatchQueue()` - 清空批量队列
 - ✨ 新增数据采样功能，支持按比例采样上报
+  - `sampleRate` - 数据采样率（0-1之间）
 - ✨ 新增敏感数据自动过滤功能
+  - 自动过滤 password、token、secret、key 等敏感字段
 - 🔧 优化类型系统，提升类型安全性
-- 🔧 优化错误处理机制，批量发送失败时自动重试
+  - 完善 TypeScript 类型定义
+  - 新增工具类型和接口
+- 🔧 优化错误处理机制
+  - 批量发送失败时自动重试
+  - 添加队列大小限制，防止内存溢出
+- 🔧 优化页面卸载处理
+  - 使用 `visibilitychange` 和 `beforeunload` 事件保护数据
+  - 支持 `sendBeacon` API 优先发送
 - 📝 完善文档和代码注释
 
 ### v1.1.0