@fle-sdk/event-tracking-web 1.2.0-beta.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +340 -112
  2. package/lib/index.esm.js +1979 -16
  3. package/lib/index.esm.min.js +1 -0
  4. package/lib/index.js +1987 -16
  5. package/lib/index.min.js +1 -0
  6. package/lib/types/index.d.ts +132 -85
  7. package/lib/types/tools.d.ts +209 -109
  8. package/lib/types/type.d.ts +466 -228
  9. package/package.json +9 -6
  10. package/lib/index.ems.js +0 -16
  11. package/lib/index.ems.js.map +0 -1
  12. package/lib/index.esm.js.map +0 -1
  13. package/lib/index.js.map +0 -1
package/README.md CHANGED
@@ -1,16 +1,18 @@
1
1
  > **构建用户数据体系，让用户行为数据发挥深远的价值。**
2
2
 
3
-
4
3
  ## 前言
5
- **WEB数据埋点sdk，开始之前请确保了解埋点的架构和基础知识**
4
+
5
+ **WEB 数据埋点 sdk，开始之前请确保了解埋点的架构和基础知识**
6
+
6
7
  > 埋点中比较重要的组成部分就是每个事件的 key，注意的是 key 至少由两部分组成。
7
8
  > 完整的 key 由这几部分组成：appkey.pagekey.partkey 通过“.”来分割
8
9
 
9
- - appkey：APP应用唯一标识
10
+ - appkey：APP 应用唯一标识
10
11
  - pagekey：页面唯一标识，默认取当前路由
11
12
  - partkey：控件/自定义事件唯一标识，可通过接口获取或自定义
12
13
 
13
14
  ## 一、下载
15
+
14
16
  ```jsx
15
17
  // npm
16
18
  npm install @fle-sdk/event-tracking-web --save-dev
@@ -20,6 +22,7 @@ yarn add @fle-sdk/event-tracking-web
20
22
  ```
21
23
 
22
24
  ## 二、全埋点
25
+
23
26
  > 全埋点包括三种事件：Web 页面浏览、Web 元素点击、Web 页面留存时长，对应的配置如下：
24
27
 
25
28
  ```jsx
@@ -33,8 +36,11 @@ WebTracking.init({
33
36
  serverUrl: "https://xxx/push",
34
37
  });
35
38
  ```
36
- ###
39
+
40
+ ###
41
+
37
42
  ### 2.1 元素点击
43
+
38
44
  > 元素的点击事件上报 attr 属性中必须含有 **data-part-key** ，否则会被过滤。
39
45
 
40
46
  ```jsx
@@ -44,8 +50,8 @@ WebTracking.init({
44
50
  </button>
45
51
  ```
46
52
 
47
-
48
53
  ### 2.2 全埋点参数示例
54
+
49
55
  > 全埋点三种类型的上报参数示例，建议都了解一下
50
56
 
51
57
  ```json
@@ -62,7 +68,7 @@ WebTracking.init({
62
68
  "pageHeight": 672,
63
69
  "screenWidth": 414,
64
70
  "screenHeight": 672,
65
- "sdkVersion": "1.1.0",
71
+ "sdkVersion": "1.2.0",
66
72
  "systemsInfo": {
67
73
  "language": "zh-CN",
68
74
  "client": "iPhone, iOS 11.0, WeChat 8.0.5",
@@ -80,6 +86,7 @@ WebTracking.init({
80
86
  }
81
87
  }
82
88
  ```
89
+
83
90
  ```json
84
91
  {
85
92
  "desc": "Web 元素点击",
@@ -92,10 +99,7 @@ WebTracking.init({
92
99
  "id": "",
93
100
  "nodeName": "H1",
94
101
  "className": "",
95
- "position": [
96
- 66,
97
- 108
98
- ]
102
+ "position": [66, 108]
99
103
  },
100
104
  "pointerType": "",
101
105
  "currentUrl": "http://localhost:9999/main?a=1",
@@ -104,7 +108,7 @@ WebTracking.init({
104
108
  "pageHeight": 672,
105
109
  "screenWidth": 414,
106
110
  "screenHeight": 672,
107
- "sdkVersion": "1.1.0",
111
+ "sdkVersion": "1.2.0",
108
112
  "systemsInfo": {
109
113
  "language": "zh-CN",
110
114
  "client": "iPhone, iOS 11.0, WeChat 8.0.5",
@@ -124,6 +128,7 @@ WebTracking.init({
124
128
  }
125
129
  }
126
130
  ```
131
+
127
132
  ```json
128
133
  {
129
134
  "desc": "Web 页面浏览时长",
@@ -136,7 +141,7 @@ WebTracking.init({
136
141
  "pageHeight": 672,
137
142
  "screenWidth": 414,
138
143
  "screenHeight": 672,
139
- "sdkVersion": "1.1.0",
144
+ "sdkVersion": "1.2.0",
140
145
  "systemsInfo": {
141
146
  "language": "zh-CN",
142
147
  "client": "iPhone, iOS 11.0, WeChat 8.0.5",
@@ -161,8 +166,8 @@ WebTracking.init({
161
166
 
162
167
  ---
163
168
 
164
-
165
169
  ## 三、API
170
+
166
171
  WebTracking
167
172
 
168
173
  - init() ---初始化
@@ -170,24 +175,33 @@ WebTracking
170
175
  - login() ---用户登录
171
176
  - track() ---自定义代码埋点上报
172
177
  - getDeviceId() ---获取设备唯一标识
178
+ - resetDeviceId() ---重置设备唯一标识
179
+ - clearBatchTimer() ---清理批量发送定时器
173
180
 
174
181
  ### Init
182
+
175
183
  #### 参数
176
- | **参数名** | **type** | **描述** | **是否必填** | **默认值** |
177
- | --- | --- | --- | --- | --- |
178
- | appKey | string | 应用唯一标识（由接口生成） | 是 | - |
179
- | serverUrl | string | 数据接收地址 | 是 | - |
180
- | autoTrack | boolean | 是否开启全埋点（指的是：页面浏览、元素点击事件自动上报） | 否 | false |
181
- | showLog | boolean | 是否在网页控制台打印发送的数据 | 否 | false |
182
- | sendTimeout | number | 接口发送超时时长，超过该时长未发送成功将强制取消 | 否 | 3000 |
183
- | isTrackSinglePage | boolean | 是否采集单页面应用的路由变化 | 否 | false |
184
- | contentType | string | application/json
185
- application/x-www-form-urlencoded | 否 | application/x-www-form-urlencoded |
186
- | business | {[key: string]: any} | 全局自定义业务参数（如果后续手动上报了业务字段，会进行合并） | 否 | - |
187
- | platform | string | 手动指定应用平台类型 | 否 | - |
188
184
 
185
+ | **参数名** | **type** | **描述** | **是否必填** | **默认值** |
186
+ | --------------------------------- | -------------------- | ------------------------------------------------------------ | ------------ | ---------- |
187
+ | appKey | string | 应用唯一标识（由接口生成） | 是 | - |
188
+ | serverUrl | string | 数据接收地址 | 是 | - |
189
+ | autoTrack | boolean | 是否开启全埋点（指的是：页面浏览、元素点击事件自动上报） | 否 | false |
190
+ | showLog | boolean | 是否在网页控制台打印发送的数据 | 否 | false |
191
+ | sendTimeout | number | 接口发送超时时长，超过该时长未发送成功将强制取消 | 否 | 3000 |
192
+ | isTrackSinglePage | boolean | 是否采集单页面应用的路由变化 | 否 | false |
193
+ | contentType | string | application/json |
194
+ | application/x-www-form-urlencoded | 否 | application/x-www-form-urlencoded |
195
+ | business | {[key: string]: any} | 全局自定义业务参数（如果后续手动上报了业务字段，会进行合并） | 否 | - |
196
+ | platform | string | 手动指定应用平台类型 | 否 | - |
197
+ | header | {[key: string]: any} | 自定义请求头 | 否 | - |
198
+ | sampleRate | number | 数据采样率，0-1 之间，1 表示 100%采样 | 否 | 1 |
199
+ | batchSend | boolean | 是否启用批量发送 | 否 | false |
200
+ | batchInterval | number | 批量发送间隔时间(ms) | 否 | 5000 |
201
+ | batchMaxSize | number | 批量发送最大数量 | 否 | 10 |
189
202
 
190
203
  #### 例子
204
+
191
205
  > 初始化 sdk 例子，建议在 src/App.js 中初始化，且需在**useLayoutEffect**中初始化。
192
206
 
193
207
  ```jsx
@@ -201,12 +215,19 @@ const App = () => {
201
215
  appKey: "218844",
202
216
  showLog: true,
203
217
  autoTrack: true,
204
- platform: 'h5',
218
+ platform: "h5",
205
219
  isTrackSinglePage: true,
206
- serverUrl: "https://qa-gateway.fxqifu.net/pangu/buriedpoint/record/push",
220
+ serverUrl: "https://qa-gateway.fxqifu.net/pangu/buriedpoint/v2/record/push",
221
+ contentType: "application/json",
207
222
  business: {
208
223
  appId: "1000010",
209
- }
224
+ },
225
+ // 数据采样率：0.8 表示 80% 的数据会被上报
226
+ sampleRate: 0.8,
227
+ // 启用批量发送：每 5 秒或达到 10 条数据时批量发送
228
+ batchSend: true,
229
+ batchInterval: 5000,
230
+ batchMaxSize: 10,
210
231
  });
211
232
  }, []);
212
233
 
@@ -217,21 +238,29 @@ export default App;
217
238
  ```
218
239
 
219
240
  ### Preset
220
- > 除了不可配置appKey、serverUrl，本质上和init差不多，这么做是为了更好的区分使用场景，不产生歧义。
241
+
242
+ > 除了不可配置 appKey、serverUrl，本质上和 init 差不多，这么做是为了更好的区分使用场景，不产生歧义。
221
243
 
222
244
  #### 参数
223
- | **参数名** | **type** | **描述** | **是否必填** | **默认值** |
224
- | --- | --- | --- | --- | --- |
225
- | autoTrack | boolean | 是否开启全埋点（指的是：页面浏览、元素点击事件自动上报） | 否 | false |
226
- | showLog | boolean | 是否在网页控制台打印发送的数据 | 否 | false |
227
- | sendTimeout | number | 接口发送超时时长，超过该时长未发送成功将强制取消 | 否 | 3000 |
228
- | isTrackSinglePage | boolean | 是否采集单页面应用的路由变化 | 否 | false |
229
- | contentType | string | application/json
230
- application/x-www-form-urlencoded | 否 | application/x-www-form-urlencoded |
231
- | business | {[key: string]: any} | 手动埋点参数 | 否 | {} |
232
- | platform | string | 手动指定应用平台类型 | 否 | - |
245
+
246
+ | **参数名** | **type** | **描述** | **是否必填** | **默认值** |
247
+ | --------------------------------- | -------------------- | -------------------------------------------------------- | ------------ | ---------- |
248
+ | autoTrack | boolean | 是否开启全埋点（指的是：页面浏览、元素点击事件自动上报） | 否 | false |
249
+ | showLog | boolean | 是否在网页控制台打印发送的数据 | 否 | false |
250
+ | sendTimeout | number | 接口发送超时时长，超过该时长未发送成功将强制取消 | 否 | 3000 |
251
+ | isTrackSinglePage | boolean | 是否采集单页面应用的路由变化 | 否 | false |
252
+ | contentType | string | application/json |
253
+ | application/x-www-form-urlencoded | 否 | application/x-www-form-urlencoded |
254
+ | business | {[key: string]: any} | 手动埋点参数 | 否 | {} |
255
+ | platform | string | 手动指定应用平台类型 | 否 | - |
256
+ | header | {[key: string]: any} | 自定义请求头 | 否 | - |
257
+ | sampleRate | number | 数据采样率，0-1 之间，1 表示 100%采样 | 否 | 1 |
258
+ | batchSend | boolean | 是否启用批量发送 | 否 | false |
259
+ | batchInterval | number | 批量发送间隔时间(ms) | 否 | 5000 |
260
+ | batchMaxSize | number | 批量发送最大数量 | 否 | 10 |
233
261
 
234
262
  #### 例子
263
+
235
264
  ```jsx
236
265
  import React, { useLayoutEffect } from "react";
237
266
  import WebTracking from "@fle-sdk/event-tracking-web";
@@ -243,22 +272,28 @@ const App = () => {
243
272
  appKey: "xxxxxx", // 由接口生成，应用唯一标识
244
273
  serverUrl: "https://www.serverHost.com/serverApi/push",
245
274
  });
246
-
275
+
247
276
  // 配置全局参数，初始化后预置属性用该方法。
248
277
  // 注意：如果配置的全局属性初始化已配置，将覆盖
249
278
  WebTracking.preset({
250
279
  autoTrack: true,
251
280
  showLog: true,
252
281
  isTrackSinglePage: true,
253
- sendTimeout: 10000
254
- })
282
+ sendTimeout: 10000,
283
+ // 启用批量发送
284
+ batchSend: true,
285
+ batchInterval: 5000,
286
+ batchMaxSize: 10,
287
+ // 设置采样率为 90%
288
+ sampleRate: 0.9,
289
+ });
255
290
  }, []);
256
-
291
+
257
292
  const pageHandle = () => {
258
- WebTracking.preset({
293
+ WebTracking.preset({
259
294
  autoTrack: false, // 关闭全埋点
260
- })
261
- }
295
+ });
296
+ };
262
297
 
263
298
  return <div className="App" onClick={pageHandle}></div>;
264
299
  };
@@ -267,24 +302,29 @@ export default App;
267
302
  ```
268
303
 
269
304
  ### Login
305
+
270
306
  #### 参数
271
- | 参数名 | type | 描述 | 是否必填 | 默认值 |
272
- | --- | --- | --- | --- | --- |
273
- | params | {[key: string]: any} | 用户信息 | 是 | - |
307
+
308
+ | 参数名 | type | 描述 | 是否必填 | 默认值 |
309
+ | ------ | -------------------- | -------- | -------- | ------ |
310
+ | params | {[key: string]: any} | 用户信息 | 是 | - |
274
311
 
275
312
  #### 例子
313
+
276
314
  ```jsx
277
315
  import React, { useEffect } from "react";
278
316
  import WebTracking from "@fle-sdk/event-tracking-web";
279
317
  import { LoginStore } from "store";
280
318
 
281
319
  const Test = () => {
282
- const getUserInfo = () => {
283
- const userInfo = await LoginStore.getUserInfo();
284
- WebTracking.Login(userInfo);
285
- }
320
+ const getUserInfo = async () => {
321
+ const userInfo = await LoginStore.getUserInfo();
322
+ // 注意：方法名是 login，不是 Login
323
+ WebTracking.login(userInfo);
324
+ };
325
+
286
326
  useEffect(() => {
287
- getUserInfo()
327
+ getUserInfo();
288
328
  }, []);
289
329
 
290
330
  return <div className="Test"></div>;
@@ -293,19 +333,27 @@ const Test = () => {
293
333
  export default Test;
294
334
  ```
295
335
 
336
+ ### GetDeviceId
337
+
338
+ #### 描述
339
+
340
+ > 获取设备唯一标识。SDK 会基于浏览器指纹技术自动生成设备 ID，并存储在 Cookie 和 LocalStorage 中，确保同一设备在不同会话中保持相同的设备 ID。
341
+
342
+ #### 返回值
343
+
344
+ - `string` - 设备唯一标识字符串
296
345
 
297
- ### GetDistinctId
298
346
  #### 例子
299
- > 获取设备唯一标识，当用户没有登录时即用户唯一标识
300
347
 
301
348
  ```jsx
302
349
  import React, { useEffect } from "react";
303
350
  import WebTracking from "@fle-sdk/event-tracking-web";
304
- import { LoginStore } from "store";
305
351
 
306
352
  const Test = () => {
307
353
  useEffect(() => {
308
- WebTracking.getDistinctId();
354
+ // 获取设备ID
355
+ const deviceId = WebTracking.getDeviceId();
356
+ console.log("设备ID:", deviceId);
309
357
  }, []);
310
358
 
311
359
  return <div className="Test"></div>;
@@ -314,19 +362,82 @@ const Test = () => {
314
362
  export default Test;
315
363
  ```
316
364
 
365
+ ### ResetDeviceId
366
+
367
+ #### 描述
368
+
369
+ > 重置设备唯一标识。清除已存储的设备 ID 并重新生成新的设备 ID。适用于用户切换账号或需要重新标识设备的场景。
370
+
371
+ #### 返回值
372
+
373
+ - `string` - 新的设备唯一标识字符串
374
+
375
+ #### 例子
376
+
377
+ ```jsx
378
+ import React from "react";
379
+ import WebTracking from "@fle-sdk/event-tracking-web";
380
+
381
+ const Test = () => {
382
+ const handleResetDevice = () => {
383
+ // 重置设备ID
384
+ const newDeviceId = WebTracking.resetDeviceId();
385
+ console.log("新设备ID:", newDeviceId);
386
+ };
387
+
388
+ return (
389
+ <div className="Test">
390
+ <button onClick={handleResetDevice}>重置设备ID</button>
391
+ </div>
392
+ );
393
+ };
394
+
395
+ export default Test;
396
+ ```
397
+
398
+ ### ClearBatchTimer
399
+
400
+ #### 描述
401
+
402
+ > 清理批量发送定时器。当需要手动触发批量发送或清理定时器时使用。
403
+
404
+ #### 例子
405
+
406
+ ```jsx
407
+ import React from "react";
408
+ import WebTracking from "@fle-sdk/event-tracking-web";
409
+
410
+ const Test = () => {
411
+ const handleClearTimer = () => {
412
+ // 清理批量发送定时器
413
+ WebTracking.clearBatchTimer();
414
+ };
415
+
416
+ return (
417
+ <div className="Test">
418
+ <button onClick={handleClearTimer}>清理定时器</button>
419
+ </div>
420
+ );
421
+ };
422
+
423
+ export default Test;
424
+ ```
317
425
 
318
426
  ### Track
427
+
319
428
  > 手动代码埋点上报
320
429
 
321
430
  #### 上报参数
322
- | **参数名** | **type** | **描述** | **是否必填** | **默认值** |
323
- | --- | --- | --- | --- | --- |
324
- | partkey | numberstring | 上报事件 Key（由前后端协商定义或由后端接口生成，该应用下需唯一且具有一定意义，例：goods_detail_pv） | 是 | - |
325
- | desc | string | 上报事件描述 | 否 | 自定义上报事件 |
326
- | business | {[key: string]: any} | 上报的业务参数 | 否 | - |
327
431
 
432
+ | **参数名** | **type** | **描述** | **是否必填** | **默认值** |
433
+ | ---------- | -------------------- | --------------------------------------------------------------------------------------------------- | ------------ | -------------- |
434
+ | partkey | numberstring | 上报事件 Key（由前后端协商定义或由后端接口生成，该应用下需唯一且具有一定意义，例：goods_detail_pv） | 是 | - |
435
+ | desc | string | 上报事件描述 | 否 | 自定义上报事件 |
436
+ | business | {[key: string]: any} | 上报的业务参数 | 否 | - |
437
+ | header | {[key: string]: any} | 自定义请求头 | 否 | - |
328
438
 
329
439
  #### 例子
440
+
330
441
  ```jsx
331
442
  import React, { useEffect } from "react";
332
443
  import WebTracking from "@fle-sdk/event-tracking-web";
@@ -335,10 +446,10 @@ const Index = () => {
335
446
  const history = useHistory();
336
447
 
337
448
  const tracking = () => {
338
- WebTracking.track({ desc: "我是描述", partkey: "xxx" })
449
+ WebTracking.track({ desc: "我是描述", partkey: "xxx" })
339
450
  .then((res) => console.log(res || "上报成功！"))
340
451
  .catch((err) => console.log(err || "上报失败！"));
341
- }
452
+ };
342
453
 
343
454
  // 手动上报商品详情浏览量示例
344
455
  useEffect(() => {
@@ -363,51 +474,168 @@ export default Index;
363
474
  ```
364
475
 
365
476
  ## 四、完整参数明细
366
- ### 4.1 request参数明细
367
- | **参数名** | **type** | **描述** | **示例值** |
368
- | --- | --- | --- | --- |
369
- | event | string | 有四种类型的值：
370
- PageViewPageRetainedCustomTrackWebClick | - |
371
- | desc | string | 埋点事件描述 | - |
372
- | itemKey | string | 当前埋点事件Key | appkey.pagekey.partkey |
373
- | requestTime | number | 发送请求事件 | - |
374
- | privateParamMap | object | 私有参数 | [查看详情](#mWMBL) |
375
- | deviceId | string | 设备ID | 9ce0159574b00867c7d2c5b200bd2f60 |
376
-
377
- #### 4.2.1 privateParamMap参数明细
378
- | **参数名** | **type** | **描述** | **示例值** |
379
- | --- | --- | --- | --- |
380
- | currentUrl | string | 当前URL | http://localhost:9999/main |
381
- | targetUrl | string | 目标URL | http://localhost:9999/app/other |
382
- | business | {[key: string]: any} | 手动埋点参数 | - |
383
- | targetEle | TargetEleProps | 触发元素属性 | [查看详情](#YC74u) |
384
- | pageWidth | number | 页面可视区宽度 | 1440 |
385
- | pageHeight | number | 页面可视区高度 | 860 |
386
- | screenWidth | number | 显示屏宽度 | 1440 |
387
- | screenHeight | number | 显示屏高度 | 860 |
388
- | pointerType | string | 手动触发的指针类型 | mouse、touch、pen |
389
- | elementSelector | string | 触发元素链路 | #root > div:nth-of-type(1) > div:nth-of-type(1) > h1:nth-of-type(1) |
390
- | userInfo | {[key: string]: any} | 用户信息 | {userName: "啊盛", userId: 1001} |
391
- | urlParams | string | 路由参数 | - |
392
- | systemsInfo | SystemsInfoTypes | 系统信息 | [查看详情](#VHfQH) |
393
- | sdkVersion | string | 埋点SDk版本 | 1.0.0 |
394
- | retainedDuration | number | 页面停留时长（毫秒） | 2000 |
395
-
396
- #### 4.2.2 TargetEleProps参数明细
397
- | **参数名** | **type** | **描述** | **示例值** |
398
- | --- | --- | --- | --- |
399
- | nodeName | string | dom节点名称 | BUTTON |
400
- | id | string | id类名 | main_btn |
401
- | className | string | class类名 | fx-primary-btn |
402
- | position | [number, number] | 元素触发位置：[x, y] | [100, 200] |
403
-
404
- #### 4.2.3 SystemsInfoTypes参数明细
405
- | **参数名** | **type** | **描述** | **示例值** |
406
- | --- | --- | --- | --- |
407
- | language | string | 系统语言 | zh-CN |
408
- | network | string | 网络类型 | - |
409
- | ua | string | userAgent | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.64 Safari/537.36 |
410
- | client | string | 客户端（Mac/Android/iPhone/iPad/iPod/WeChat） | Mac, MacOS 10.15.7 |
411
- | platform | string | 应用平台类型，如不传会自动获取
412
- 枚举：h5iPadpcother | h5 |
413
477
 
478
+ ### 4.1 request 参数明细
479
+
480
+ | **参数名** | **type** | **描述** | **示例值** |
481
+ | --------------------------------------- | -------- | ---------------- | -------------------------------- |
482
+ | event | string | 有四种类型的值： |
483
+ | PageViewPageRetainedCustomTrackWebClick | - |
484
+ | desc | string | 埋点事件描述 | - |
485
+ | itemKey | string | 当前埋点事件 Key | appkey.pagekey.partkey |
486
+ | requestTime | number | 发送请求事件 | - |
487
+ | privateParamMap | object | 私有参数 | [查看详情](#mWMBL) |
488
+ | deviceId | string | 设备 ID | 9ce0159574b00867c7d2c5b200bd2f60 |
489
+
490
+ #### 4.2.1 privateParamMap 参数明细
491
+
492
+ | **参数名** | **type** | **描述** | **示例值** |
493
+ | ---------------- | -------------------- | -------------------- | ------------------------------------------------------------------- |
494
+ | currentUrl | string | 当前 URL | http://localhost:9999/main |
495
+ | targetUrl | string | 目标 URL | http://localhost:9999/app/other |
496
+ | business | {[key: string]: any} | 手动埋点参数 | - |
497
+ | targetEle | TargetEleProps | 触发元素属性 | [查看详情](#YC74u) |
498
+ | pageWidth | number | 页面可视区宽度 | 1440 |
499
+ | pageHeight | number | 页面可视区高度 | 860 |
500
+ | screenWidth | number | 显示屏宽度 | 1440 |
501
+ | screenHeight | number | 显示屏高度 | 860 |
502
+ | pointerType | string | 手动触发的指针类型 | mouse、touch、pen |
503
+ | elementSelector | string | 触发元素链路 | #root > div:nth-of-type(1) > div:nth-of-type(1) > h1:nth-of-type(1) |
504
+ | userInfo | {[key: string]: any} | 用户信息 | {userName: "啊盛", userId: 1001} |
505
+ | urlParams | {[key: string]: any} | 路由参数 | - |
506
+ | systemsInfo | SystemsInfoTypes | 系统信息 | [查看详情](#VHfQH) |
507
+ | sdkVersion | string | 埋点 SDK 版本 | 1.2.0 |
508
+ | retainedDuration | number | 页面停留时长（毫秒） | 2000 |
509
+ | deviceId | string | 设备唯一标识 | fp_xxx... |
510
+
511
+ #### 4.2.2 TargetEleProps 参数明细
512
+
513
+ | **参数名** | **type** | **描述** | **示例值** |
514
+ | ---------- | ---------------- | -------------------- | -------------- |
515
+ | nodeName | string | dom 节点名称 | BUTTON |
516
+ | id | string | id 类名 | main_btn |
517
+ | className | string | class 类名 | fx-primary-btn |
518
+ | position | [number, number] | 元素触发位置：[x, y] | [100, 200] |
519
+
520
+ #### 4.2.3 SystemsInfoTypes 参数明细
521
+
522
+ | **参数名** | **type** | **描述** | **示例值** |
523
+ | ------------------- | -------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
524
+ | language | string | 系统语言 | zh-CN |
525
+ | network | string | 网络类型 | - |
526
+ | ua | string | userAgent | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.64 Safari/537.36 |
527
+ | client | string | 客户端（Mac/Android/iPhone/iPad/iPod/WeChat） | Mac, MacOS 10.15.7 |
528
+ | platform | string | 应用平台类型，如不传会自动获取 |
529
+ | 枚举：h5iPadpcother | h5 |
530
+
531
+ ---
532
+
533
+ ## 五、新功能说明
534
+
535
+ ### 5.1 设备 ID 管理
536
+
537
+ SDK 1.2.0 版本新增了基于浏览器指纹技术的设备 ID 生成和管理功能。
538
+
539
+ #### 特性
540
+
541
+ - **自动生成**：基于浏览器指纹信息（UserAgent、屏幕信息、Canvas、WebGL 等）自动生成唯一设备 ID
542
+ - **持久化存储**：设备 ID 存储在 Cookie（2 年过期）和 LocalStorage 中，确保同一设备在不同会话中保持相同的设备 ID
543
+ - **隐私保护**：所有敏感数据（如 password、token、secret、key 等）会自动过滤为 `***`
544
+
545
+ #### 使用示例
546
+
547
+ ```jsx
548
+ // 获取设备ID
549
+ const deviceId = WebTracking.getDeviceId();
550
+
551
+ // 重置设备ID（适用于用户切换账号等场景）
552
+ const newDeviceId = WebTracking.resetDeviceId();
553
+ ```
554
+
555
+ ### 5.2 批量发送
556
+
557
+ 当埋点数据量较大时，可以使用批量发送功能来减少网络请求次数，提升性能。
558
+
559
+ #### 配置参数
560
+
561
+ - `batchSend`: 是否启用批量发送（默认：false）
562
+ - `batchInterval`: 批量发送间隔时间，单位毫秒（默认：5000）
563
+ - `batchMaxSize`: 批量发送最大数量，达到该数量会立即发送（默认：10）
564
+
565
+ #### 工作原理
566
+
567
+ 1. 启用批量发送后，所有埋点数据会先加入队列
568
+ 2. 当队列达到 `batchMaxSize` 时，立即批量发送
569
+ 3. 或者每隔 `batchInterval` 毫秒自动发送一次
570
+ 4. 批量发送失败时，数据会自动重新加入队列，避免数据丢失
571
+
572
+ #### 使用示例
573
+
574
+ ```jsx
575
+ WebTracking.init({
576
+ appKey: "218844",
577
+ serverUrl: "https://xxx/push",
578
+ // 启用批量发送
579
+ batchSend: true,
580
+ batchInterval: 5000, // 每5秒发送一次
581
+ batchMaxSize: 10, // 或达到10条数据时立即发送
582
+ });
583
+ ```
584
+
585
+ ### 5.3 数据采样
586
+
587
+ 当数据量过大时，可以使用数据采样功能来控制上报的数据量，节省服务器资源。
588
+
589
+ #### 配置参数
590
+
591
+ - `sampleRate`: 数据采样率，0-1 之间的数字（默认：1）
592
+ - `1`: 100% 采样，所有数据都上报
593
+ - `0.8`: 80% 采样，随机上报 80% 的数据
594
+ - `0.5`: 50% 采样，随机上报 50% 的数据
595
+ - `0`: 0% 采样，不上报任何数据
596
+
597
+ #### 使用示例
598
+
599
+ ```jsx
600
+ WebTracking.init({
601
+ appKey: "218844",
602
+ serverUrl: "https://xxx/push",
603
+ // 设置采样率为 80%
604
+ sampleRate: 0.8,
605
+ });
606
+ ```
607
+
608
+ ### 5.4 敏感数据过滤
609
+
610
+ SDK 会自动过滤敏感字段，保护用户隐私。默认会过滤以下字段：
611
+
612
+ - `password`
613
+ - `token`
614
+ - `secret`
615
+ - `key`
616
+
617
+ 被过滤的字段值会显示为 `***`。
618
+
619
+ #### 自定义敏感字段
620
+
621
+ 如果需要自定义敏感字段列表，可以在代码中扩展 `filterSensitiveData` 方法。
622
+
623
+ ---
624
+
625
+ ## 六、版本更新日志
626
+
627
+ ### v1.2.0 (最新)
628
+
629
+ - ✨ 新增设备 ID 管理功能（基于浏览器指纹技术）
630
+ - ✨ 新增批量发送功能，支持批量上报埋点数据
631
+ - ✨ 新增数据采样功能，支持按比例采样上报
632
+ - ✨ 新增敏感数据自动过滤功能
633
+ - 🔧 优化类型系统，提升类型安全性
634
+ - 🔧 优化错误处理机制，批量发送失败时自动重试
635
+ - 📝 完善文档和代码注释
636
+
637
+ ### v1.1.0
638
+
639
+ - 基础功能实现
640
+ - 全埋点支持
641
+ - 自定义埋点支持