### utm-params-extractor-test

#### 使用示例

##### 1. 安装包

```bash
npm install utm-params-extractor-test
```

##### 2. 在项目中使用

```javascript
// ES6 模块
import UtmTracker from 'utm-params-extractor-test';

// 方法1：使用静态方法直接获取
const utmParams = UtmTracker.get();
console.log('UTM参数:', utmParams);

// 方法2：实例化后获取（适合扩展）
const tracker = new UtmTracker();
const params = tracker.getParams();

// 自行处理数据（例如发送到后端）
fetch('https://your-api.com/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(params)
})
.then(response => response.json())
.then(data => console.log('发送成功:', data))
.catch(error => console.error('发送失败:', error));
```

##### 3. 在 HTML 中直接使用

```html
<script src="dist/main.js"></script>
<script>
  // 你的库会挂载在 window.UtmTracker
  var utmParams = window.UtmTracker.get();
  console.log('UTM参数:', utmParams);
</script>
```

 **注意：**
 - HTML 直接引用时，npm 包名（如 utm-params-extractor-test）与全局变量名无关。
 - 全局变量名由 webpack.config.js 的 `library.name` 决定，默认是 `UtmTracker`。
 - 如需自定义全局变量名，请在 webpack.config.js 中修改：
   ```js
   output: {
     // ...
     library: {
       name: 'UtmTracker', // 你想要的全局变量名
       type: 'umd',
     },
     globalObject: 'this',
   }
   ```
   这样 HTML 里就可以直接用 `window.UtmTracker.get()`。

## 使用示例

### 自动上报
```js
new UtmTracker({
  reportUrl: 'https://your-server.com/collect',
  autoSend: true,
  method: 'POST', // 或 'GET'
  extra: { custom: 'value' }
});
```

### 手动上报
```js
const tracker = new UtmTracker({ reportUrl: 'https://your-server.com/collect' });
const params = tracker.getParams();
tracker.send(params);
```

### 静态用法
```js
UtmTracker.get({
  reportUrl: 'https://your-server.com/collect',
  autoSend: true
});
```

### 返回参数说明

`UtmTracker.get()` 或 `tracker.getParams()` 返回对象结构如下：

| 字段         | 类型    | 说明                                                                 |
| ------------ | ------- | -------------------------------------------------------------------- |
| utm_source   | string  | UTM 来源渠道参数（如广告平台、搜索引擎等）                           |
| utm_medium   | string  | UTM 媒介参数（如 cpc、email、banner 等）                              |
| utm_campaign | string  | UTM 活动名称参数                                                     |
| utm_term     | string  | UTM 关键词参数                                                       |
| utm_content  | string  | UTM 内容参数（用于区分广告内容）                                     |
| referrer     | string  | 上一个页面的 URL                                                     |
| browser      | object  | 浏览器和设备信息对象（见下表）                                       |
| timestamp    | string  | 获取参数的时间戳（ISO 格式）                                         |
| url          | string  | 当前页面完整 URL                                                     |

#### browser 字段结构

| 字段       | 类型    | 说明                                                         |
| ---------- | ------- | ------------------------------------------------------------ |
| isMobile   | boolean | 是否为移动端设备                                              |
| browser    | string  | 浏览器类型（如 Chrome、Safari、Edge、WeChat、HuaweiBrowser 等）|
| userAgent  | string  | 浏览器的 User-Agent 字符串                                    |
| osType     | string  | 操作系统类型（iOS、Android、HarmonyOS、Unknown）              |
| osVersion  | string  | 操作系统版本号（如 16.6、13.0、3.0.0、Unknown）              |

##### browser.browser 可能的值
- Chrome
- Safari
- Edge
- Firefox
- IE
- WeChat
- QQBrowser
- UCBrowser
- HuaweiBrowser
- Telegram
- 其他

##### browser.osType 可能的值
- iOS
- Android
- HarmonyOS
- Unknown

##### 示例返回

```json
{
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "summer_sale",
  "utm_term": "shoes",
  "utm_content": "ad1",
  "referrer": "https://www.example.com/",
  "browser": {
    "isMobile": true,
    "browser": "Chrome",
    "userAgent": "Mozilla/5.0 (Linux; Android 13; ...)",
    "osType": "Android",
    "osVersion": "13"
  },
  "timestamp": "2024-07-01T12:00:00.000Z",
  "url": "https://your-site.com/?utm_source=google&utm_medium=cpc"
}
```

## 跳转倒计时弹窗使用示例

当后端返回 { downloadUrl, type } 时，自动弹出3秒倒计时弹窗，倒计时结束后自动跳转到 downloadUrl。

```js
new UtmTracker({
  reportUrl: 'https://your-server.com/collect',
  autoSend: true,
  // 只需后端返回 { downloadUrl: '...', type: 'video'|'audio'|'image' }，无需额外配置
});
```

// 后端返回示例：
// {
//   downloadUrl: 'https://your-server.com/file.mp4',
//   type: 'video'
// }

// 前端会自动弹出“即将跳转，3秒...”的弹窗，3秒后自动跳转到 downloadUrl。

---

如需更多帮助或定制返回内容，请联系作者。

## 配置项说明（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 字段会为空字符串。