@tripo3d/trace / TripoTrace

Class: TripoTrace

Defined in: trace/src/trace.ts:53

商业化埋点 / 广告归因 SDK。

用法：

const trace = new TripoTrace({
  baseUrl:   'https://api-cn-test.tripo3d.com',
  configUrl: 'https://cdn.example.com/trace/whitelist.json',
});
await trace.init();    // 初始化 device id
trace.landing();       // 触发归因上报（fire-and-forget）
trace.deviceId         // string
trace.headers          // { 'x-tripo-device-id': string }

重要：必须在「业务任何 URL 操作（清理 query、SPA 路由跳转等）之前」调用 landing()。 构造时会立即缓存 window.location.href 作为 entry URL，landing() 用的是这个缓存值 而不是当次 window.location.href，避免业务方误清掉 UTM 参数后丢上报。

Constructors

Constructor

new TripoTrace(params): TripoTrace;

Defined in: trace/src/trace.ts:61

构造时校验必填、解析并缓存 entry URL，不发起任何 IO

Parameters

Parameter	Type
params	TripoTraceParams

Returns

TripoTrace

Accessors

deviceId

Get Signature

get deviceId(): string;

Defined in: trace/src/trace.ts:69

当前 device id；尚未 init 完成 / SSR 下为空字符串

Returns

string

---

headers

Get Signature

get headers(): Record<string, string>;

Defined in: trace/src/trace.ts:74

业务请求拦截器使用的 trace headers；无 device id 时为空对象

Returns

Record<string, string>

Methods

init()

init(): Promise<void>;

Defined in: trace/src/trace.ts:82

初始化 device id；SSR 下 no-op。 业务必须 await，完成后 deviceId / headers 即可用。

Returns

Promise<void>

---

landing()

landing(): Promise<void>;

Defined in: trace/src/trace.ts:93

落地页归因上报：fire-and-forget，不阻塞业务。 业务负责时序：必须在 init() 完成后调用，且应在任何 URL 改写之前调用。

• SSR / URL 非法 / 无 utm_source / 未命中白名单 / killSwitch / 当日已报 → 静默跳过
• CDN 配置拉取失败 / 上报请求失败 → 内部已通过 onError 回调通知

Returns

Promise<void>