utm-params-extractor

utm-params-extractor-test

使用示例

1. 安装包

npm install utm-params-extractor-test

2. 在项目中使用

// 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 中直接使用

<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 中修改：

  output: {
   // ...
   library: {
     name: 'UtmTracker', // 你想要的全局变量名
     type: 'umd',
   },
   globalObject: 'this',
  }
  

  这样 HTML 里就可以直接用 window.UtmTracker.get()。

使用示例

自动上报

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

手动上报

const tracker = new UtmTracker({ reportUrl: 'https://your-server.com/collect' });
const params = tracker.getParams();
tracker.send(params);

静态用法

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

示例返回

{
  "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。

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

示例

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，无需单独安装或引入，无论 npm 还是浏览器全局都能直接用指纹功能。

示例

const tracker = new UtmTracker({ ... });
const params = await tracker.getParamsAsync();
console.log(params.fingerprintId); // 浏览器唯一指纹

FingerprintJS 依赖说明

本库自动适配两种场景：

1. npm/打包工具用户

• 请在你的项目中安装依赖：

  npm install @fingerprintjs/fingerprintjs
  

• 本库会自动 require 该依赖，无需手动引入。

• 推荐在 package.json 中声明 peerDependencies：

  "peerDependencies": {
  "@fingerprintjs/fingerprintjs": ">=4.0.0"
  }
  

2. 浏览器全局用户

• 请在你的 HTML 中先引入 FingerprintJS，再引入本库：

  <script src="https://openfpcdn.io/fingerprintjs/v4"></script>
  <script src="dist/your-utm-bundle.js"></script>
  

• 本库会自动检测 window.FingerprintJS。

如未正确引入依赖，指纹功能将无法使用，fingerprintId 字段会为空字符串。