|
|
@@ -179,3 +179,75 @@ new UtmTracker({
|
|
|
|
|
|
如需更多帮助或定制返回内容，请联系作者。
|
|
|
|
|
|
+## 配置项说明（config 参数）
|
|
|
+
|
|
|
+| 配置项 | 类型 | 说明 | 是否必填 | 默认值 |
|
|
|
+|-------------|----------|--------------------------------------------------------------|----------|-----------------------------|
|
|
|
+| reportUrl | string | 上报数据的接口地址 | 是 | '' |
|
|
|
+| autoSend | boolean | 是否在实例化时自动上报一次 | 否 | true |
|
|
|
+| method | string | 请求方式，支持 'POST' 或 'GET' | 否 | 'POST' |
|
|
|
+| headers | object | 请求头设置 | 否 | { 'Content-Type': 'application/json' } |
|
|
|
+| extra | object | 额外自定义参数，会合并进最终上报数据 | 否 | {} |
|
|
|
+| onParams | function | 获取参数后回调，参数为 params | 否 | null |
|
|
|
+| onSend | function | 发送成功回调，参数为 (response, params) | 否 | null |
|
|
|
+| onError | function | 发送失败回调，参数为 (error, params) | 否 | null |
|
|
|
+
|
|
|
+### 示例
|
|
|
+
|
|
|
+```js
|
|
|
+import UtmTracker from 'utm-params-extractor-test';
|
|
|
+
|
|
|
+const tracker = new UtmTracker({
|
|
|
+ reportUrl: 'https://your-server.com/collect',
|
|
|
+ autoSend: false,
|
|
|
+ method: 'POST',
|
|
|
+ headers: { 'Content-Type': 'application/json' },
|
|
|
+ extra: { foo: 'bar' },
|
|
|
+ onParams: params => console.log(params),
|
|
|
+ onSend: (res, params) => console.log('sent', res, params),
|
|
|
+ onError: (err, params) => console.error('error', err, params)
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+## 浏览器指纹（fingerprintId）说明
|
|
|
+
|
|
|
+- `fingerprintId` 字段会自动添加到所有 UTM 参数和上报数据中。
|
|
|
+- 该字段用于唯一标识当前浏览器环境，便于后端做用户去重、分析等。
|
|
|
+- 指纹生成后会存储在本地 localStorage（key: fingerprint_id），后续请求会优先复用，确保唯一性和高效性。
|
|
|
+- **本包已自动集成 [FingerprintJS](https://github.com/fingerprintjs/fingerprintjs)，无需单独安装或引入，无论 npm 还是浏览器全局都能直接用指纹功能。**
|
|
|
+
|
|
|
+### 示例
|
|
|
+
|
|
|
+```js
|
|
|
+const tracker = new UtmTracker({ ... });
|
|
|
+const params = await tracker.getParamsAsync();
|
|
|
+console.log(params.fingerprintId); // 浏览器唯一指纹
|
|
|
+```
|
|
|
+
|
|
|
+## FingerprintJS 依赖说明
|
|
|
+
|
|
|
+本库自动适配两种场景：
|
|
|
+
|
|
|
+### 1. npm/打包工具用户
|
|
|
+- 请在你的项目中安装依赖：
|
|
|
+ ```bash
|
|
|
+ npm install @fingerprintjs/fingerprintjs
|
|
|
+ ```
|
|
|
+- 本库会自动 require 该依赖，无需手动引入。
|
|
|
+- 推荐在 package.json 中声明 peerDependencies：
|
|
|
+ ```json
|
|
|
+ "peerDependencies": {
|
|
|
+ "@fingerprintjs/fingerprintjs": ">=4.0.0"
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+### 2. 浏览器全局用户
|
|
|
+- 请在你的 HTML 中**先**引入 FingerprintJS，再引入本库：
|
|
|
+ ```html
|
|
|
+ <script src="https://openfpcdn.io/fingerprintjs/v4"></script>
|
|
|
+ <script src="dist/your-utm-bundle.js"></script>
|
|
|
+ ```
|
|
|
+- 本库会自动检测 window.FingerprintJS。
|
|
|
+
|
|
|
+如未正确引入依赖，指纹功能将无法使用，fingerprintId 字段会为空字符串。
|
|
|
+
|
jcq