Trace
@tripo3d/trace· 商业化埋点与广告归因 SDK，基于@tripo3d/fingerprint提供稳定 device id。
特性
🎯
渠道自动归因
进入落地页时检测付费广告 click_id（v0.1 支持百度 bd_vid），命中即上报 landing 事件
🆔
稳定 device id
基于 FingerprintJS 的 visitor id，跨会话稳定；暴露给业务侧用于所有后续请求追踪
🚫
零 Cookie 持久化
完全用 localStorage 存储，不污染请求头，避免 cookie 体积膨胀
📅
自然日去重
同一 landing URL 每个本地自然日只上报一次，0 点切换
🌐
SSR 安全
服务端 import 与调用都不会爆错，所有副作用只在浏览器侧执行
🔁
幂等接入
initLanding() 可在 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',
});
await trace.initLanding();
trace.deviceId // 32 位十六进制字符串
trace.headers // { 'x-tripo-device-id': '...' }适用场景
| 场景 | 推荐用法 |
|---|---|
| 百度搜索广告归因 | URL 带 bd_vid 进入站点 → SDK 自动发 landing 事件 |
| 跨会话访客追踪 | 业务请求拦截器附加 x-tripo-device-id 头 |
| 商业化转化漏斗 | 配合服务端 Conversion API 与 click_id 做端到端归因 |
| 反爬 / 风控 | 不推荐 —— 归因 device id 易被脚本伪造，请用专业方案 |
下一步
- 快速上手 —
initLanding()完整 API、Nuxt plugin 模板 - 高级用法 — 自定义渠道、自定义 fetch、错误处理、SPA 路由
- API Reference — 完整 API 文档（自动生成）
- Playground — 模拟
?bd_vid=xxx，实时查看请求与 device id