@fle-sdk/event-tracking-web 1.2.0-beta.1 → 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.
- package/README.md +340 -115
- package/lib/index.esm.js +1979 -16
- package/lib/index.esm.min.js +1 -0
- package/lib/index.js +1987 -16
- package/lib/index.min.js +1 -0
- package/lib/types/index.d.ts +132 -87
- package/lib/types/tools.d.ts +209 -113
- package/lib/types/type.d.ts +466 -243
- package/package.json +9 -6
- package/lib/index.ems.js +0 -16
- package/lib/index.ems.js.map +0 -1
- package/lib/index.esm.js.map +0 -1
- package/lib/index.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,16 +1,18 @@
|
|
|
1
1
|
> **构建用户数据体系，让用户行为数据发挥深远的价值。**
|
|
2
2
|
|
|
3
|
-
|
|
4
3
|
## 前言
|
|
5
|
-
|
|
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.
|
|
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.
|
|
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.
|
|
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,25 +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
|
-
| header | {[key: string]: any} | 自定义请求头 | 否 | - |
|
|
189
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 |
|
|
190
202
|
|
|
191
203
|
#### 例子
|
|
204
|
+
|
|
192
205
|
> 初始化 sdk 例子，建议在 src/App.js 中初始化，且需在**useLayoutEffect**中初始化。
|
|
193
206
|
|
|
194
207
|
```jsx
|
|
@@ -202,12 +215,19 @@ const App = () => {
|
|
|
202
215
|
appKey: "218844",
|
|
203
216
|
showLog: true,
|
|
204
217
|
autoTrack: true,
|
|
205
|
-
platform:
|
|
218
|
+
platform: "h5",
|
|
206
219
|
isTrackSinglePage: true,
|
|
207
|
-
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",
|
|
208
222
|
business: {
|
|
209
223
|
appId: "1000010",
|
|
210
|
-
}
|
|
224
|
+
},
|
|
225
|
+
// 数据采样率：0.8 表示 80% 的数据会被上报
|
|
226
|
+
sampleRate: 0.8,
|
|
227
|
+
// 启用批量发送：每 5 秒或达到 10 条数据时批量发送
|
|
228
|
+
batchSend: true,
|
|
229
|
+
batchInterval: 5000,
|
|
230
|
+
batchMaxSize: 10,
|
|
211
231
|
});
|
|
212
232
|
}, []);
|
|
213
233
|
|
|
@@ -218,22 +238,29 @@ export default App;
|
|
|
218
238
|
```
|
|
219
239
|
|
|
220
240
|
### Preset
|
|
221
|
-
|
|
241
|
+
|
|
242
|
+
> 除了不可配置 appKey、serverUrl，本质上和 init 差不多，这么做是为了更好的区分使用场景，不产生歧义。
|
|
222
243
|
|
|
223
244
|
#### 参数
|
|
224
|
-
|
|
225
|
-
|
|
|
226
|
-
|
|
|
227
|
-
|
|
|
228
|
-
|
|
|
229
|
-
|
|
|
230
|
-
|
|
|
231
|
-
|
|
232
|
-
|
|
|
233
|
-
|
|
|
234
|
-
|
|
|
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 |
|
|
235
261
|
|
|
236
262
|
#### 例子
|
|
263
|
+
|
|
237
264
|
```jsx
|
|
238
265
|
import React, { useLayoutEffect } from "react";
|
|
239
266
|
import WebTracking from "@fle-sdk/event-tracking-web";
|
|
@@ -245,22 +272,28 @@ const App = () => {
|
|
|
245
272
|
appKey: "xxxxxx", // 由接口生成，应用唯一标识
|
|
246
273
|
serverUrl: "https://www.serverHost.com/serverApi/push",
|
|
247
274
|
});
|
|
248
|
-
|
|
275
|
+
|
|
249
276
|
// 配置全局参数，初始化后预置属性用该方法。
|
|
250
277
|
// 注意：如果配置的全局属性初始化已配置，将覆盖
|
|
251
278
|
WebTracking.preset({
|
|
252
279
|
autoTrack: true,
|
|
253
280
|
showLog: true,
|
|
254
281
|
isTrackSinglePage: true,
|
|
255
|
-
|
|
256
|
-
|
|
282
|
+
sendTimeout: 10000,
|
|
283
|
+
// 启用批量发送
|
|
284
|
+
batchSend: true,
|
|
285
|
+
batchInterval: 5000,
|
|
286
|
+
batchMaxSize: 10,
|
|
287
|
+
// 设置采样率为 90%
|
|
288
|
+
sampleRate: 0.9,
|
|
289
|
+
});
|
|
257
290
|
}, []);
|
|
258
|
-
|
|
291
|
+
|
|
259
292
|
const pageHandle = () => {
|
|
260
|
-
|
|
293
|
+
WebTracking.preset({
|
|
261
294
|
autoTrack: false, // 关闭全埋点
|
|
262
|
-
})
|
|
263
|
-
}
|
|
295
|
+
});
|
|
296
|
+
};
|
|
264
297
|
|
|
265
298
|
return <div className="App" onClick={pageHandle}></div>;
|
|
266
299
|
};
|
|
@@ -269,24 +302,29 @@ export default App;
|
|
|
269
302
|
```
|
|
270
303
|
|
|
271
304
|
### Login
|
|
305
|
+
|
|
272
306
|
#### 参数
|
|
273
|
-
|
|
274
|
-
|
|
|
275
|
-
|
|
|
307
|
+
|
|
308
|
+
| 参数名 | type | 描述 | 是否必填 | 默认值 |
|
|
309
|
+
| ------ | -------------------- | -------- | -------- | ------ |
|
|
310
|
+
| params | {[key: string]: any} | 用户信息 | 是 | - |
|
|
276
311
|
|
|
277
312
|
#### 例子
|
|
313
|
+
|
|
278
314
|
```jsx
|
|
279
315
|
import React, { useEffect } from "react";
|
|
280
316
|
import WebTracking from "@fle-sdk/event-tracking-web";
|
|
281
317
|
import { LoginStore } from "store";
|
|
282
318
|
|
|
283
319
|
const Test = () => {
|
|
284
|
-
const getUserInfo = () => {
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
320
|
+
const getUserInfo = async () => {
|
|
321
|
+
const userInfo = await LoginStore.getUserInfo();
|
|
322
|
+
// 注意：方法名是 login，不是 Login
|
|
323
|
+
WebTracking.login(userInfo);
|
|
324
|
+
};
|
|
325
|
+
|
|
288
326
|
useEffect(() => {
|
|
289
|
-
getUserInfo()
|
|
327
|
+
getUserInfo();
|
|
290
328
|
}, []);
|
|
291
329
|
|
|
292
330
|
return <div className="Test"></div>;
|
|
@@ -295,19 +333,27 @@ const Test = () => {
|
|
|
295
333
|
export default Test;
|
|
296
334
|
```
|
|
297
335
|
|
|
336
|
+
### GetDeviceId
|
|
337
|
+
|
|
338
|
+
#### 描述
|
|
339
|
+
|
|
340
|
+
> 获取设备唯一标识。SDK 会基于浏览器指纹技术自动生成设备 ID，并存储在 Cookie 和 LocalStorage 中，确保同一设备在不同会话中保持相同的设备 ID。
|
|
341
|
+
|
|
342
|
+
#### 返回值
|
|
343
|
+
|
|
344
|
+
- `string` - 设备唯一标识字符串
|
|
298
345
|
|
|
299
|
-
### GetDistinctId
|
|
300
346
|
#### 例子
|
|
301
|
-
> 获取设备唯一标识，当用户没有登录时即用户唯一标识
|
|
302
347
|
|
|
303
348
|
```jsx
|
|
304
349
|
import React, { useEffect } from "react";
|
|
305
350
|
import WebTracking from "@fle-sdk/event-tracking-web";
|
|
306
|
-
import { LoginStore } from "store";
|
|
307
351
|
|
|
308
352
|
const Test = () => {
|
|
309
353
|
useEffect(() => {
|
|
310
|
-
|
|
354
|
+
// 获取设备ID
|
|
355
|
+
const deviceId = WebTracking.getDeviceId();
|
|
356
|
+
console.log("设备ID:", deviceId);
|
|
311
357
|
}, []);
|
|
312
358
|
|
|
313
359
|
return <div className="Test"></div>;
|
|
@@ -316,20 +362,82 @@ const Test = () => {
|
|
|
316
362
|
export default Test;
|
|
317
363
|
```
|
|
318
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
|
+
```
|
|
319
425
|
|
|
320
426
|
### Track
|
|
427
|
+
|
|
321
428
|
> 手动代码埋点上报
|
|
322
429
|
|
|
323
430
|
#### 上报参数
|
|
324
|
-
| **参数名** | **type** | **描述** | **是否必填** | **默认值** |
|
|
325
|
-
| --- | --- | --- | --- | --- |
|
|
326
|
-
| partkey | numberstring | 上报事件 Key（由前后端协商定义或由后端接口生成，该应用下需唯一且具有一定意义，例：goods_detail_pv） | 是 | - |
|
|
327
|
-
| desc | string | 上报事件描述 | 否 | 自定义上报事件 |
|
|
328
|
-
| business | {[key: string]: any} | 上报的业务参数 | 否 | - |
|
|
329
|
-
| header | {[key: string]: any} | 自定义请求头 | 否 | - |
|
|
330
431
|
|
|
432
|
+
| **参数名** | **type** | **描述** | **是否必填** | **默认值** |
|
|
433
|
+
| ---------- | -------------------- | --------------------------------------------------------------------------------------------------- | ------------ | -------------- |
|
|
434
|
+
| partkey | numberstring | 上报事件 Key（由前后端协商定义或由后端接口生成，该应用下需唯一且具有一定意义，例：goods_detail_pv） | 是 | - |
|
|
435
|
+
| desc | string | 上报事件描述 | 否 | 自定义上报事件 |
|
|
436
|
+
| business | {[key: string]: any} | 上报的业务参数 | 否 | - |
|
|
437
|
+
| header | {[key: string]: any} | 自定义请求头 | 否 | - |
|
|
331
438
|
|
|
332
439
|
#### 例子
|
|
440
|
+
|
|
333
441
|
```jsx
|
|
334
442
|
import React, { useEffect } from "react";
|
|
335
443
|
import WebTracking from "@fle-sdk/event-tracking-web";
|
|
@@ -338,10 +446,10 @@ const Index = () => {
|
|
|
338
446
|
const history = useHistory();
|
|
339
447
|
|
|
340
448
|
const tracking = () => {
|
|
341
|
-
|
|
449
|
+
WebTracking.track({ desc: "我是描述", partkey: "xxx" })
|
|
342
450
|
.then((res) => console.log(res || "上报成功！"))
|
|
343
451
|
.catch((err) => console.log(err || "上报失败！"));
|
|
344
|
-
}
|
|
452
|
+
};
|
|
345
453
|
|
|
346
454
|
// 手动上报商品详情浏览量示例
|
|
347
455
|
useEffect(() => {
|
|
@@ -366,51 +474,168 @@ export default Index;
|
|
|
366
474
|
```
|
|
367
475
|
|
|
368
476
|
## 四、完整参数明细
|
|
369
|
-
### 4.1 request参数明细
|
|
370
|
-
| **参数名** | **type** | **描述** | **示例值** |
|
|
371
|
-
| --- | --- | --- | --- |
|
|
372
|
-
| event | string | 有四种类型的值：
|
|
373
|
-
PageViewPageRetainedCustomTrackWebClick | - |
|
|
374
|
-
| desc | string | 埋点事件描述 | - |
|
|
375
|
-
| itemKey | string | 当前埋点事件Key | appkey.pagekey.partkey |
|
|
376
|
-
| requestTime | number | 发送请求事件 | - |
|
|
377
|
-
| privateParamMap | object | 私有参数 | [查看详情](#mWMBL) |
|
|
378
|
-
| deviceId | string | 设备ID | 9ce0159574b00867c7d2c5b200bd2f60 |
|
|
379
|
-
|
|
380
|
-
#### 4.2.1 privateParamMap参数明细
|
|
381
|
-
| **参数名** | **type** | **描述** | **示例值** |
|
|
382
|
-
| --- | --- | --- | --- |
|
|
383
|
-
| currentUrl | string | 当前URL | http://localhost:9999/main |
|
|
384
|
-
| targetUrl | string | 目标URL | http://localhost:9999/app/other |
|
|
385
|
-
| business | {[key: string]: any} | 手动埋点参数 | - |
|
|
386
|
-
| targetEle | TargetEleProps | 触发元素属性 | [查看详情](#YC74u) |
|
|
387
|
-
| pageWidth | number | 页面可视区宽度 | 1440 |
|
|
388
|
-
| pageHeight | number | 页面可视区高度 | 860 |
|
|
389
|
-
| screenWidth | number | 显示屏宽度 | 1440 |
|
|
390
|
-
| screenHeight | number | 显示屏高度 | 860 |
|
|
391
|
-
| pointerType | string | 手动触发的指针类型 | mouse、touch、pen |
|
|
392
|
-
| elementSelector | string | 触发元素链路 | #root > div:nth-of-type(1) > div:nth-of-type(1) > h1:nth-of-type(1) |
|
|
393
|
-
| userInfo | {[key: string]: any} | 用户信息 | {userName: "啊盛", userId: 1001} |
|
|
394
|
-
| urlParams | string | 路由参数 | - |
|
|
395
|
-
| systemsInfo | SystemsInfoTypes | 系统信息 | [查看详情](#VHfQH) |
|
|
396
|
-
| sdkVersion | string | 埋点SDk版本 | 1.0.0 |
|
|
397
|
-
| retainedDuration | number | 页面停留时长（毫秒） | 2000 |
|
|
398
|
-
|
|
399
|
-
#### 4.2.2 TargetEleProps参数明细
|
|
400
|
-
| **参数名** | **type** | **描述** | **示例值** |
|
|
401
|
-
| --- | --- | --- | --- |
|
|
402
|
-
| nodeName | string | dom节点名称 | BUTTON |
|
|
403
|
-
| id | string | id类名 | main_btn |
|
|
404
|
-
| className | string | class类名 | fx-primary-btn |
|
|
405
|
-
| position | [number, number] | 元素触发位置：[x, y] | [100, 200] |
|
|
406
|
-
|
|
407
|
-
#### 4.2.3 SystemsInfoTypes参数明细
|
|
408
|
-
| **参数名** | **type** | **描述** | **示例值** |
|
|
409
|
-
| --- | --- | --- | --- |
|
|
410
|
-
| language | string | 系统语言 | zh-CN |
|
|
411
|
-
| network | string | 网络类型 | - |
|
|
412
|
-
| 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 |
|
|
413
|
-
| client | string | 客户端（Mac/Android/iPhone/iPad/iPod/WeChat） | Mac, MacOS 10.15.7 |
|
|
414
|
-
| platform | string | 应用平台类型，如不传会自动获取
|
|
415
|
-
枚举：h5iPadpcother | h5 |
|
|
416
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
|
+
- 自定义埋点支持
|