Trace
@tripo3d/trace· 商业化埋点与广告归因 SDK，基于@tripo3d/fingerprint提供稳定 device id。
特性
🎯
渠道自动归因
进入落地页时检测 utm_source 是否命中 CDN 远程白名单，命中即上报 landing 事件
🆔
稳定 device id
基于 FingerprintJS 的 visitor id，跨会话稳定；暴露给业务侧用于所有后续请求追踪
🚫
零 Cookie 持久化
完全用 localStorage 存储，不污染请求头，避免 cookie 体积膨胀
⏱️
窗口去重
同一 landing URL 在 1 分钟滚动窗口内只上报一次
🌐
SSR 安全
服务端 import 与调用都不会爆错，所有副作用只在浏览器侧执行
🔁
幂等接入
landing() 可在 SPA 路由变化时重复调用，已有去重兜底
安装
请先完成 GitHub Packages 认证配置。
bash
pnpm add @tripo3d/trace快速开始
ts
import { TripoTrace } from '@tripo3d/trace';
const trace = new TripoTrace({
baseUrl: 'https://api-cn-test.tripo3d.com',
configUrl: 'https://cdn.example.com/trace/whitelist.json',
});
await trace.init();
trace.landing();
trace.deviceId // 32 位十六进制字符串
trace.headers // { 'x-tripo-device-id': '...' }适用场景
| 场景 | 推荐用法 |
|---|---|
| 付费投放归因 | 投放链接带 utm_source=xxx 进入站点 → SDK 自动发 landing 事件（白名单从 CDN 拉取，运营可动态调整） |
| 跨会话访客追踪 | 业务请求拦截器附加 x-tripo-device-id 头 |
| 商业化转化漏斗 | 配合服务端 Conversion API 与 click_id 做端到端归因 |
| 反爬 / 风控 | 不推荐 —— 归因 device id 易被脚本伪造，请用专业方案 |
下一步
- 快速上手 —
init()+landing()完整 API、Nuxt plugin 模板 - 高级用法 — CDN 配置文件维护、自定义 fetch、错误处理、SPA 路由
- API Reference — 完整 API 文档（自动生成）
- Playground — 模拟
?utm_source=xxx，实时查看请求与 device id