UtmTrack使用示例

UtmTrack 是一个用于落地页 UTM/推广参数持久化的库，支持 LocalStorage + Cookie 双写，first/last 归因，站内跳转不丢失。

安装与使用

落地页 UTM/推广参数持久化，LocalStorage + Cookie 双写，first/last 归因，站内跳转不丢失。

安装

npm install utm-track

快速开始 · NPM (ESM)

import UtmTrack from 'utm-track';

// 落地页：autoCapture: true 即用当前页 URL 自动捕获，无需再调 captureFromUrl()
UtmTrack.init({
  autoCapture: true,
  expire: 14 * 24 * 60 * 60 * 1000,
  strategy: 'first',
  storage: { key: 'utm_track_promo', cookie: true },
  onCapture: (params) => console.log('推广来源已记录', params),
});

const promo = UtmTrack.get();
if (promo) {
  console.log(promo.params, promo.savedAt, promo.expiresAt);
}

快速开始 · Script (UMD)

<script src="https://unpkg.com/utm-tradist/utm-track.umd.js"></script>
<script>
  UtmTrack.init({ autoCapture: true, keys: ['utm_source','utm_medium','ref'], expire: 604800000, storage: { key: 'utm_track_promo', cookie: true } });
  // 落地页到此即可；任意页: var data = UtmTrack.get();
</script>

API 速查

方法	说明
`init(options?)`	初始化配置，见下方参数表。
`captureFromUrl(urlOrSearch?)`	不传参即使用当前页 URL；传入则用该 URL/query 解析并写入。若当前存储已过期会先清除旧数据再写入。返回 `{ wrote, reason }`。
`get()`	读取已存推广数据，返回见下方「get() 返回值」。
`clear()`	强制清空存储（同时清 LocalStorage 与 Cookie），无参数。

init(options) 参数

参数	类型	默认	说明
`storage`	`{ key?, cookie? }`	key 默认 `'utm_track_promo'`，cookie 默认 `true`	存储配置：key 为 LocalStorage 的 key，cookie 为 false/true/对象（name、domain、path、sameSite）。
`keys`	`(string \| RegExp)[]`	常见 UTM + ref	要捕获的 URL 参数名：字符串精确匹配（大小写不敏感），正则可匹配 key。
`expire`	`number`	`604800000`（7 天）	有效期，单位毫秒；<=0 表示不过期。
`strategy`	`'first' \| 'last'`	`'first'`	first：有效期内不覆盖；last：每次带参访问都覆盖。
`captureAllQuery`	`boolean`	`false`	为 true 时：有任一 keys 匹配即存该 URL 全部 query；否则只存匹配项。
`onCapture`	`(params) => void`	—	本次写入成功后回调，用于上报/埋点。
`autoCapture`	`boolean`	`false`	为 true 时，init 完成后自动用当前页 URL 执行一次 captureFromUrl()，落地页只需 init 即可。

captureFromUrl 返回值

字段	类型	说明
`wrote`	`boolean`	本次是否写入存储。
`reason`	`string`	`'no_params'` 无匹配参数；`'written'` 已写入；`'skipped_first_touch'` 有效期内未覆盖（first 策略）。

get() 返回值

字段	类型	说明
`params`	`object`	捕获到的参数键值对。
`url`	`string`	捕获时的完整落地页 URL。
`savedAt`	`number`	写入时间戳（毫秒）。
`expiresAt`	`number`	过期时间戳（毫秒）；init 的 expire<=0 时为 `Infinity`（永不过期）。
过期或不存在时返回 `null`。

存储结构（LocalStorage / Cookie 双写同一 JSON）

{
  "params": { "utm_source": "google", "utm_medium": "cpc", ... },
  "url": "https://example.com/landing?utm_source=...",
  "savedAt": 1710672000000,
  "expiresAt": 1711276800000
}

url 为捕获时的完整落地 URL；Cookie 约 4KB 限制，超限则仅 LS 有效。

右侧为本库的可交互演示。完整 API、清空/自定义参数/仅用 LS 等见 README.md。

配置表单（修改后点击「应用配置」生效）

keys（要捕获的 URL 参数名，一行一个；支持正则，如 /utm_.+/ 或 /^ref$/i） storage.key（LocalStorage key） expire（有效期，单位毫秒；不填默认 7 天，<=0 表示不过期）归因策略 strategy

捕获全部 query（captureAllQuery）开启后，只要 URL 有任一 keys 匹配就存该 URL 的全部 query；否则只存匹配项。

storage.cookie（双写 Cookie）

写入时在控制台打印 onCapture(params)

当前已生效的配置

以下为上次点击「应用配置」后实际生效的 init 参数，可与上方表单对比确认。

加载中

当前状态

当前页面 URL

最近一次捕获结果（captureFromUrl 返回值：无匹配参数 / 已写入 / 有效期内未覆盖）

当前存储内容 get()（含 params、url、savedAt、expiresAt）

模拟与操作

模拟落地并捕获：用下方 URL 执行一次 captureFromUrl，可能写入存储（含 params、url 等）。
读取并刷新展示：不刷新页面，仅重新读取存储与当前 URL 并更新下方展示（不重新执行 init/捕获）。
直接刷新整页也会看到最新状态，但会重新执行 init 和 captureFromUrl。

模拟落地 URL（留空则用当前页 URL；或输入完整 URL / ?utm_source=xx）