utm-params-extractor

utm-params-extractor-test

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

✨ 主要特性

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

📦 安装

# 安装主包
npm install utm-params-extractor-test

# 安装依赖（FingerprintJS）
npm install @fingerprintjs/fingerprintjs

🚀 快速开始

基础用法

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();

自动上报

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

静态方法

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

📋 API 文档

UtmTracker 构造函数

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	发送失败后的回调函数

实例方法

getParams() - 同步获取参数

const params = tracker.getParams();

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

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

const params = await tracker.getParamsAsync();

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

send(data) - 发送数据

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

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

静态方法

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

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

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

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

📊 返回数据结构

基础参数结构

{
  // 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"  // 浏览器唯一指纹
}

浏览器类型支持

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

操作系统支持

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

🔧 使用示例

Vue.js 项目

<template>
  <div>
    <h1>UTM 参数追踪</h1>
    <button @click="sendData">发送数据</button>
    <pre>{{ utmParams }}</pre>
  </div>
</template>

<script>
import UtmTracker from 'utm-params-extractor-test';

export default {
  data() {
    return {
      tracker: null,
      utmParams: null
    };
  },
  async mounted() {
    this.tracker = new UtmTracker({
      reportUrl: 'https://your-api.com/collect',
      autoSend: false,
      onSend: (response, params) => {
        console.log('数据发送成功:', response);
      },
      onError: (error, params) => {
        console.error('数据发送失败:', error);
      }
    });
    
    // 获取包含指纹的完整参数
    try {
      this.utmParams = await this.tracker.getParamsAsync();
      console.log('参数获取成功:', this.utmParams);
    } catch (error) {
      console.error('参数获取失败:', error);
      // 如果异步获取失败，使用同步方法
      this.utmParams = this.tracker.getParams();
    }
  },
  methods: {
    async sendData() {
      if (this.tracker) {
        await this.tracker.send();
      }
    }
  }
};
</script>

React 项目

安装依赖

npm install utm-params-extractor-test @fingerprintjs/fingerprintjs

使用示例

import { useEffect, useState } from 'react';
import 'utm-params-extractor-test'; // 引入后会挂载到 window 上

function App() {
  const [tracker, setTracker] = useState<null>(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 (
    <div>
      <button onClick={onClickSend}>发送</button>
    </div>
  );
}

export default App;

常见问题解决

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

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

// 方案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 依赖：

npm install @fingerprintjs/fingerprintjs

问题3：ESLint 配置

如果 ESLint 报错，可以在 .eslintrc.js 中添加：

module.exports = {
  globals: {
    UtmTracker: 'readonly'
  }
};

问题4：调试导入问题

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

// 在组件顶部添加调试代码
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);
}

普通 JavaScript

<!DOCTYPE html>
<html>
<head>
    <title>UTM 参数追踪</title>
</head>
<body>
    <h1>UTM 参数追踪</h1>
    <button onclick="sendData()">发送数据</button>
    <pre id="params"></pre>

    <script src="https://openfpcdn.io/fingerprintjs/v4"></script>
    <script src="dist/main.js"></script>
    <script>
        let tracker = null;

        // 页面加载完成后初始化
        document.addEventListener('DOMContentLoaded', async function() {
            tracker = new window.UtmTracker({
                reportUrl: 'https://your-api.com/collect',
                autoSend: false,
                onSend: function(response, params) {
                    console.log('数据发送成功:', response);
                    alert('数据发送成功！');
                },
                onError: function(error, params) {
                    console.error('数据发送失败:', error);
                    alert('数据发送失败！');
                }
            });

            // 获取包含指纹的完整参数
            try {
                const params = await tracker.getParamsAsync();
                document.getElementById('params').textContent = 
                    JSON.stringify(params, null, 2);
                console.log('参数获取成功:', params);
            } catch (error) {
                console.error('参数获取失败:', error);
                // 如果异步获取失败，使用同步方法
                const syncParams = tracker.getParams();
                document.getElementById('params').textContent = 
                    JSON.stringify(syncParams, null, 2);
            }
        });

        async function sendData() {
            if (tracker) {
                await tracker.send();
            }
        }
    </script>
</body>
</html>

🎯 浏览器指纹说明

指纹生成原理

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

1. FingerprintJS 方式（默认）

   • 使用 FingerprintJS 库生成
   • 基于多种浏览器特征
   • 更准确和稳定

2. 自定义稳定指纹

   • 基于设备固定特征
   • 确保跨环境一致性
   • 包含屏幕信息、用户代理、时区等

指纹特征

指纹生成基于以下稳定特征：

• 屏幕分辨率、颜色深度
• 用户代理字符串（前50字符）
• 时区信息
• 语言设置
• 平台信息
• CPU核心数
• 设备内存
• Canvas指纹
• WebGL渲染器信息

指纹存储

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

🔄 跨环境一致性

问题背景

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

解决方案

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

1. 使用稳定的设备特征

   • 避免使用可能变化的特征
   • 对长字符串进行截取，减少细微差异

2. 统一的指纹算法

   • 相同的哈希算法
   • 相同的特征组合方式

3. 环境无关性

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

测试验证

// 在项目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);

🛠 高级配置

自定义请求头

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

添加额外参数

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

自定义回调处理

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('数据上报失败，请重试');
  }
});

🔧 构建和部署

开发环境

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

生产环境

# 构建生产版本
npm run build

# 构建后的文件在 dist/ 目录
# - main.js: 主文件
# - main.js.map: 源码映射文件

Webpack 配置

// 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',
  },
  // ... 其他配置
};

🐛 常见问题

Q: 指纹ID在不同环境下不一致怎么办？

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

Q: 如何自定义指纹生成算法？

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

Q: 上报失败如何处理？

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

Q: 如何禁用指纹功能？

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

Q: 支持哪些浏览器？

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

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