Extract UTM parameters from URL and browser information
npm install utm-params-extractor-testbash
安装主包
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
UTM 参数追踪
{{ utmParams }}
`
$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 参数追踪
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` 回调函数处理错误,可以实现重试机制或错误提示。