utm-params-extractor-test

一个功能强大的 UTM 参数提取和浏览器指纹生成库，支持自动上报、跨环境指纹一致性、多种使用方式。

✨ 主要特性

- 🔍 UTM 参数自动提取 - 支持 utm_source、utm_medium、utm_campaign、utm_term、utm_content
- 🌐 浏览器信息识别 - 自动识别浏览器类型、操作系统、设备类型
- 🎯 唯一指纹生成 - 基于设备特征生成稳定的浏览器指纹
- 📊 自动上报功能 - 支持自动/手动数据上报到后端
- 🔄 跨环境一致性 - 同一设备在不同项目环境下生成相同指纹
- 📱 多端支持 - 支持 PC、移动端、各种浏览器环境
- 🛠 灵活配置 - 支持多种使用方式和自定义配置
- 📦 多模块支持 - 支持 ES6、CommonJS、UMD 等多种模块规范

📦 安装

``bash

安装主包

npm install utm-params-extractor-test

安装依赖（FingerprintJS）

npm install @fingerprintjs/fingerprintjs
`

🚀 快速开始

$3

`javascript
import UtmTracker from 'utm-params-extractor-test';

// 创建实例
const tracker = new UtmTracker({
reportUrl: 'https://your-api.com/collect',
autoSend: false
});

// 获取参数
const params = tracker.getParams();
console.log('UTM参数:', params);

// 手动上报
tracker.send();
`

$3

`javascript
// 实例化时自动上报
new UtmTracker({
reportUrl: 'https://your-api.com/collect',
autoSend: true
});
`

$3

`javascript
// 快速获取参数
const params = await UtmTracker.get({
reportUrl: 'https://your-api.com/collect',
autoSend: true
});
`

📋 API 文档

$3

`javascript
new UtmTracker(config)
`

#### 配置参数 (config)

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| reportUrl | string | ✅ | '' | 数据上报的接口地址 |
| autoSend | boolean | ❌ | true | 是否在实例化时自动上报 |
| method | string | ❌ | 'POST' | 请求方法，支持 'POST' 或 'GET' |
| headers | object | ❌ | { 'Content-Type': 'application/json' } | 请求头设置 |
| extra | object | ❌ | {} | 额外的自定义参数 |
| onParams | function | ❌ | null | 获取参数后的回调函数 |
| onSend | function | ❌ | null | 发送成功后的回调函数 |
| onError | function | ❌ | null | 发送失败后的回调函数 |

$3

#### getParams() - 同步获取参数

`javascript
const params = tracker.getParams();
`

返回当前页面的 UTM 参数和浏览器信息（不包含指纹）。

#### getParamsAsync() - 异步获取参数（含指纹）

`javascript
const params = await tracker.getParamsAsync();
`

返回包含浏览器指纹的完整参数对象。

#### send(data) - 发送数据

`javascript
// 发送默认参数
tracker.send();

// 发送自定义数据
tracker.send(customData);
`

$3

#### UtmTracker.get(config) - 快速获取参数

`javascript
const params = await UtmTracker.get({
reportUrl: 'https://your-api.com/collect',
autoSend: true
});
`

#### UtmTracker.send(data, config) - 快速发送数据

`javascript
await UtmTracker.send(customData, {
reportUrl: 'https://your-api.com/collect'
});
`

📊 返回数据结构

$3

`javascript
{
// UTM 参数
utmSource: "google", // UTM 来源
utmMedium: "cpc", // UTM 媒介
utmCampaign: "summer_sale", // UTM 活动
utmTerm: "shoes", // UTM 关键词
utmContent: "ad1", // UTM 内容

// 页面信息
referrer: "https://www.google.com/", // 来源页面
url: "https://yoursite.com/?utm_source=google", // 当前页面
domain: "yoursite.com", // 当前域名
timestamp: "2024-01-01T12:00:00.000Z", // 时间戳

// 设备信息
isMobile: true, // 是否移动端
browser: "Chrome", // 浏览器类型
browserVersion: "120.0.0.0", // 浏览器版本号
userAgent: "Mozilla/5.0...", // 用户代理
osType: "Android", // 操作系统类型
osVersion: "13", // 操作系统版本

// 指纹信息
fingerprint: "stable_fp_1a2b3c4d5e" // 浏览器唯一指纹
}
`

$3

| 浏览器 | 识别标识 |
|--------|----------|
| Chrome | Chrome |
| Safari | Safari |
| Firefox | Firefox |
| Edge | Edge |
| IE | IE |
| 微信 | WeChat |
| QQ浏览器 | QQBrowser |
| UC浏览器 | UCBrowser |
| 华为浏览器 | HuaweiBrowser |
| Telegram | Telegram |

$3

| 系统 | 识别标识 | 版本获取 |
|------|----------|----------|
| iOS | iOS | ✅ |
| Android | Android | ✅ |
| HarmonyOS | HarmonyOS | ✅ |
| 其他 | Unknown | ❌ |

🔧 使用示例

$3

`vue



`

$3

#### 安装依赖
`bash
npm install utm-params-extractor-test @fingerprintjs/fingerprintjs
`

#### 使用示例
`jsx
import { useEffect, useState } from 'react';
import 'utm-params-extractor-test'; // 引入后会挂载到 window 上

function App() {
const [tracker, setTracker] = useState(null);

useEffect(() => {
// 实例化追踪器，并保存实例到状态
// @ts-ignore
const trackerInstance = new window.UtmTracker({
reportUrl: '发送地址',
autoSend: false
});
// @ts-ignore
setTracker(trackerInstance); // 存入实例，而非类本身
console.log('初始化完成:', trackerInstance);
}, []);

const onClickSend = () => {
if (tracker) {
// @ts-ignore
tracker.send(); // 调用实例方法
} else {
console.warn('UtmTracker 尚未初始化');
}
};

return (

发送

);
}

export default App;
`

#### 常见问题解决

问题1：UtmTracker is not defined 或 is not a constructor 错误

如果遇到这些错误，请尝试以下解决方案：

`jsx
// 方案1：标准导入（推荐）
import UtmTracker from 'utm-params-extractor-test';

// 方案2：如果标准导入失败，使用 require
const UtmTracker = require('utm-params-extractor-test');

// 方案3：如果使用 CDN 或全局引入
const UtmTracker = window.UtmTracker;

// 方案4：动态导入
import('utm-params-extractor-test').then(module => {
const UtmTracker = module.default || module;
// 使用 UtmTracker
});

// 方案5：检查导入的模块
console.log('UtmTracker:', UtmTracker);
console.log('typeof UtmTracker:', typeof UtmTracker);
`

问题2：FingerprintJS 依赖问题

确保安装了 FingerprintJS 依赖：
`bash
npm install @fingerprintjs/fingerprintjs
`

问题3：ESLint 配置

如果 ESLint 报错，可以在 .eslintrc.js 中添加：
`javascript
module.exports = {
globals: {
UtmTracker: 'readonly'
}
};
`

问题4：调试导入问题

如果遇到导入问题，可以添加以下调试代码：

`jsx
// 在组件顶部添加调试代码
console.log('=== 调试信息 ===');
console.log('window.UtmTracker:', window.UtmTracker);
console.log('typeof window.UtmTracker:', typeof window.UtmTracker);

// 尝试不同的导入方式
try {
const module = require('utm-params-extractor-test');
console.log('require result:', module);
console.log('module.default:', module.default);
} catch (e) {
console.log('require failed:', e);
}

try {
import('utm-params-extractor-test').then(module => {
console.log('dynamic import result:', module);
console.log('module.default:', module.default);
});
} catch (e) {
console.log('dynamic import failed:', e);
}
`

$3

`html

UTM 参数追踪

发送数据

`

🎯 浏览器指纹说明

$3

本库使用两种指纹生成方式：

1. FingerprintJS 方式（默认）
- 使用 FingerprintJS 库生成
- 基于多种浏览器特征
- 更准确和稳定

2. 自定义稳定指纹
- 基于设备固定特征
- 确保跨环境一致性
- 包含屏幕信息、用户代理、时区等

$3

指纹生成基于以下稳定特征：
- 屏幕分辨率、颜色深度
- 用户代理字符串（前50字符）
- 时区信息
- 语言设置
- 平台信息
- CPU核心数
- 设备内存
- Canvas指纹
- WebGL渲染器信息

$3

- 指纹生成后存储在 localStorage 中
- 键名：fingerprint_id
- 后续请求优先使用已存储的指纹
- 清除 localStorage 后重新生成

🔄 跨环境一致性

$3

在不同项目环境下，同一设备可能生成不同的指纹ID，影响用户追踪的准确性。

$3

本库通过以下方式确保跨环境一致性：

1. 使用稳定的设备特征
- 避免使用可能变化的特征
- 对长字符串进行截取，减少细微差异

2. 统一的指纹算法
- 相同的哈希算法
- 相同的特征组合方式

3. 环境无关性
- 不依赖域名、路径等环境相关特征
- 专注于设备本身的稳定特征

$3

`javascript
// 在项目A中
const trackerA = new UtmTracker({ reportUrl: 'http://localhost:3000/api' });
const paramsA = await trackerA.getParamsAsync();
console.log('项目A指纹:', paramsA.fingerprint);

// 在项目B中（同一设备）
const trackerB = new UtmTracker({ reportUrl: 'http://localhost:3001/api' });
const paramsB = await trackerB.getParamsAsync();
console.log('项目B指纹:', paramsB.fingerprint);

// 两个指纹应该相同
console.log('指纹一致:', paramsA.fingerprint === paramsB.fingerprint);
`

🛠 高级配置

$3

`javascript
const tracker = new UtmTracker({
reportUrl: 'https://your-api.com/collect',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your-token',
'X-Custom-Header': 'custom-value'
}
});
`

$3

`javascript
const tracker = new UtmTracker({
reportUrl: 'https://your-api.com/collect',
extra: {
userId: '12345',
sessionId: 'abc123',
customField: 'customValue'
}
});
`

$3

`javascript
const tracker = new UtmTracker({
reportUrl: 'https://your-api.com/collect',
onParams: (params) => {
// 参数获取后的处理
console.log('获取到参数:', params);

// 可以修改参数
params.customField = 'modified';

// 可以存储到其他地方
localStorage.setItem('utm_params', JSON.stringify(params));
},
onSend: (response, params) => {
// 发送成功的处理
console.log('发送成功:', response);

// 可以触发其他操作
if (response.success) {
showSuccessMessage('数据上报成功');
}
},
onError: (error, params) => {
// 发送失败的处理
console.error('发送失败:', error);

// 可以重试或显示错误信息
showErrorMessage('数据上报失败，请重试');
}
});
`

🔧 构建和部署

$3

`bash

安装依赖

npm install

构建项目

npm run build

运行测试

npm test
`

$3

`bash

构建生产版本

npm run build

构建后的文件在 dist/ 目录

- main.js: 主文件

- main.js.map: 源码映射文件

`

$3

`javascript
// webpack.config.js
module.exports = {
entry: './src/index.js',
output: {
filename: 'main.js',
path: path.resolve(__dirname, 'dist'),
library: {
name: 'UtmTracker',
type: 'umd',
},
globalObject: 'this',
},
// ... 其他配置
};
`

🐛 常见问题

$3

A: 确保使用相同版本的库，并检查是否有环境特定的配置影响了指纹生成。

$3

A: 可以修改源码中的 generateStableFingerprint() 函数，或通过配置参数调整 FingerprintJS 的设置。

$3

A: 使用 onError` 回调函数处理错误，可以实现重试机制或错误提示。

$3

A: 目前不支持完全禁用指纹功能，但可以通过配置调整指纹生成方式。

$3

A: 支持所有现代浏览器，包括 Chrome、Firefox、Safari、Edge 等，以及移动端浏览器。


注意： 使用本库时请遵守相关法律法规和隐私政策，确保用户数据的安全和隐私保护。