# 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
```

## 🚀 快速开始

### 基础用法

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

### 自动上报

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

### 静态方法

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

## 📋 API 文档

### UtmTracker 构造函数

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

### 实例方法

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

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

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

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

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

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

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

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

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

### 静态方法

#### `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'
});
```

## 📊 返回数据结构

### 基础参数结构

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

### 浏览器类型支持

| 浏览器 | 识别标识 |
|--------|----------|
| 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 项目

```vue
<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 项目

#### 安装依赖
```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>(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` 错误**

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

```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);
}
```

### 普通 JavaScript

```html
<!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. **环境无关性**
   - 不依赖域名、路径等环境相关特征
   - 专注于设备本身的稳定特征

### 测试验证

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

## 🛠 高级配置

### 自定义请求头

```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'
  }
});
```

### 添加额外参数

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

### 自定义回调处理

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

## 🔧 构建和部署

### 开发环境

```bash
# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test
```

### 生产环境

```bash
# 构建生产版本
npm run build

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

### Webpack 配置

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

## 🐛 常见问题

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

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

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

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

### Q: 上报失败如何处理？

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

### Q: 如何禁用指纹功能？

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

### Q: 支持哪些浏览器？

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


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