构造参数
new TripoLens(params) 接受一个 TripoLensParams 对象。app、configUrl、endpoint 三个必填，其余可选。
const trace = new TripoLens({
app: 'shop', // 必填
configUrl: 'https://cdn.example.com/wl.json', // 必填
endpoint: 'https://api.example.com/v2/trace/events',
deviceIdOverride: undefined,
fetch: $fetch as unknown as typeof fetch,
onError: (err, ctx) => report(err, ctx.phase),
onReported: (type, payload) => {},
beforeEmit: (event) => event,
debug: false,
plugins: [new TrackingPlugin({ autoTrack: true })],
});速查表
| 字段 | 类型 / 默认 | 说明 |
|---|---|---|
app | string（必填） | 事件前缀，全插件共用；归一为合法坐标段 |
configUrl | string（必填） | CDN 远程配置 JSON 的完整 URL |
endpoint | string（必填） | 完整上报地址（含路径）；SDK 无内置默认 |
deviceIdOverride | string / undefined | 显式 device id，跳过指纹计算 |
fetch | typeof fetch / globalThis.fetch | 自定义 fetch；Nuxt 传 $fetch |
onError | (err, ctx) => void / 静默 | 错误回调；ctx.phase 标识阶段 |
onReported | (type, payload) => void | 上报观测钩子 |
beforeEmit | BeforeEmitHook / 无 | L4 业务最后处理钩子，可改写或丢弃事件 |
debug | boolean / 跟随运行期 flag | Debug 桥三态开关（仅本地/测试）：true 强开、false 硬关（拒绝运行期 flag）、缺省跟随运行期 flag |
plugins | TracePlugin[] / [] | 追加装配的 opt-in 插件（非替换） |
逐项详解
app（必填）
事件统一信封 event_format 的前缀，全插件共用。例如错误事件的坐标尾段是 <app>.Error、性能是 <app>.Perf、行为生命周期是 <app>.Track。
会被归一为合法坐标段：trim + 转小写，字符集限 [a-z0-9_-]，长度 1–32；非法或为空时回落为 'tripo'。注意归一只做 trim + 小写，不会剔除非法字符：传 'Shop App' 归一后为 'shop app'，含非法字符（空格），整体回落 'tripo'——请直接传规范值如 'shop' / 'studio'。
configUrl（必填）
CDN 上远程配置 JSON 的完整 URL。init() 会拉取它来判定渠道白名单、采样率、错误分级、熔断等。拉取失败会 fail-open 降级，不阻塞 init。配置 schema 见 远程配置。
endpoint（必填）
完整的上报地址（含路径，SDK 不再自行拼接路径段），形如：
https://your-gateway.example.com/v2/trace/events必传，无内置默认
SDK 已移除内置默认上报地址（不再导出 DEFAULT_GATEWAY_ENDPOINT）。endpoint 缺失或为空时 new TripoLens() 直接抛错——这是刻意为之，避免把流量误发到非预期环境。请按部署环境显式传入对应网关地址。
deviceIdOverride
业务自管 device id 时显式传入，SDK 跳过默认解析、直接用这个值（并写入 cookie + localStorage 缓存）。不传则走默认解析链：cookie → localStorage 缓存 → FingerprintJS 现算。
合法字符集：可打印 ASCII（不含空格与控制字符）、1-128 位——带 . / : / @ 的业务 id 均合法。不满足的值会被忽略并在控制台 warn 一次，然后回落默认解析链：读写两侧用同一白名单，防止含换行等控制字符的值进入 X-DeviceId 请求头（会让 fetch 构造 Headers 抛 TypeError），也避免「首次会话写得进、后续会话读不回」的身份漂移。
fetch
自定义 fetch 实现，同时用于拉取 CDN 配置与上报请求。缺省用 globalThis.fetch。Nuxt 项目推荐传 $fetch（统一拦截器、与框架的请求体系一致）。
onError
统一错误回调，默认静默。SDK 内部任何阶段出错都经它通知，第二个参数 ctx.phase 标识出错阶段，便于定位：
ctx.phase | 含义 |
|---|---|
config | 拉取 CDN 远程配置阶段 |
init | 加载 device id 阶段 |
identity | device↔user 身份绑定上报阶段 |
report | landing 归因上报请求阶段 |
track | 行为埋点（命令式 / 声明式 / 曝光 / 停留 / pageview）阶段 |
error | 错误监控（采集 / 控量 / 分级 / 上报）阶段 |
destroy | teardown 插件 / 释放资源阶段 |
onError: (err, ctx) => {
// 接到你自己的监控里，按 phase 归类
reportToSentry(err, { tags: { lensPhase: ctx.phase } });
}onReported
上报观测钩子：事件经 L4 进入 L5 后触发一次，按 type 判别 payload。触发时机随事件优先级：
- P0（
landing/identity）：送达成功后触发、失败不触发。 - P1 / P2（行为 / 错误 / 性能）：入队即触发。
- 被 Pipeline 丢弃（采样 / Schema / beforeEmit 返回 null）的事件不触发。
onReported: (type, payload) => {
if (type === 'landing') analytics.mark('attribution_sent');
}beforeEmit
L4 Pipeline 的业务最后处理钩子，在事件序列化前调用。你可以改写事件、或返回 null 直接丢弃该事件。是业务侧能介入采集管线的唯一钩子。
beforeEmit: (event) => {
if (event.type === 'pageview' && isInternalUser()) return null; // 丢弃内部用户 PV
return event;
}debug
开启 SDK 内置 Debug 桥（仅本地 / 测试用）：动态加载 WindowBridgeTap（默认不进主包初始 bundle），向 DevTools 的「管线」Tab 广播 Pipeline / 队列的内部观测，可看到被采样 / Schema / killSwitch 在 SDK 内部丢弃的事件——这些事件从不上网络，外部观测扩展看不到。
除了构造参数，还可不改代码、用运行期 flag 临时开启（便于在任意页面打开）：
localStorage['__tripo_lens_debug'] = '1'; // 或
window.__TRIPO_LENS_DEBUG__ = true;三态语义：true 强开；显式 false 硬关（本实例拒绝上述运行期 flag——跑分 / 静默实例用，Debug 桥每条事件广播约 7 条 postMessage 结构化克隆，高吞吐下会洪泛消息队列）；缺省（不传）跟随运行期 flag。联调用法见 用 playground + DevTools 联调管线。
plugins
追加装配的插件列表。AttributionPlugin（归因）与 IdentityPlugin（身份）始终默认装配，这里是追加而非替换。行为 / 错误 / 性能为 opt-in，在此显式 new：
plugins: [
new TrackingPlugin({ autoTrack: true }),
new ErrorPlugin({ captureApi: true, captureWhiteScreen: true }),
new PerformancePlugin({ webVitals: true }),
]