渠道归因（landing）
投放落地页自动归因：用户带
utm_source进站时，自动上报一条landing事件，把投放渠道和落地 URL 记下来。
渠道归因由 AttributionPlugin 承载，它和身份一样是默认装配、不受 Consent 管控的基础采集能力——你不需要手动 new、也没有要调的开关。可在 Playground · 渠道归因 在线体验 entry URL 快照与窗口去重。
如何使用
不需要任何额外配置，正常构造并 init() 即可。归因在 init() 内自动触发，无需手动调用任何方法：
import { TripoLens } from '@tripo3d/lens';
const trace = new TripoLens({
app: 'shop',
configUrl: 'https://cdn.example.com/trace/whitelist.json',
endpoint: 'https://gateway.example.com/v2/trace/events',
});
await trace.init(); // 命中渠道白名单时，这一步内部自动上报 landing要让某个渠道被上报，把它的 utm_source 加进远程配置的白名单即可（运营改 CDN，不发版）。
验证是否生效
带上渠道参数访问页面（如 https://yoursite.com/?utm_source=baidu），打开浏览器 Network 面板，应能看到一条发往接口的请求；或在构造时挂 onReported 观察：
new TripoLens({
app: 'shop',
configUrl: '...',
endpoint: '...',
onReported: (type) => { if (type === 'landing') console.log('归因已上报'); },
});行为说明
归因没有对外方法，它的行为完全由「进站 URL + 远程配置」决定。一次 landing 只在同时满足以下条件时上报：
| 条件 | 说明 |
|---|---|
| 浏览器环境 | SSR 下整体 no-op |
| 已解析 device id | init() 完成后 |
入口 URL 带 utm_source | 取构造时快照的 entry URL，转小写匹配 |
| 命中白名单 | utm_source 在远程配置 utm.utmSource 内；白名单为空时 fail-open 放行全部 |
| 未熔断 | 远程配置 killSwitch 为 false |
| 窗口内未报过 | 同一落地 URL 在 1 分钟窗口内只上报一次 |
任一条件不满足即静默跳过，不报错。
landing 事件的信封 event_format 为 <app>.Landing。SDK 不把 utm_* 解析为独立字段：落地 URL（含原始 utm query）以 landing 落地快照进公参 context.page_url（入口快照另有 context.entry_url），来源进 context.referrer；utm_source 仅在 SDK 内部提取用于白名单判定，渠道解析归后端。
实现原理
new TripoLens() 快照 entry URL（location.href）
│
await init() → setup AttributionPlugin
│
├─ 取 entry URL 的 utm_source（trim + 小写）
├─ shouldReport：killSwitch? → 否；白名单空? → 放行；否则须命中白名单
├─ 窗口去重：isReportedRecently(href)? → 窗口内已报则跳过
└─ emit landing 事件（P0：入队即发 + 等送达回执）→ 标记已报（记录时间戳）归因是 P0 优先级事件：入队即发、并等待后端 2xx 送达回执才算成功（onReported('landing') 在送达后触发，失败不触发）。
API 说明
归因是默认装配、无对外方法的能力——没有命令式 API，也没有构造选项；行为完全由「进站 URL + 远程配置」决定。
new AttributionPlugin()
- 含义与作用：渠道归因插件，由
TripoLens默认装配，无需手动new。 - 类型：
new AttributionPlugin()（无构造参数）。 - 注意：无对外方法；
landing在init()内自动触发，是否上报见上方 行为说明。
观测上报：onReported
- 含义与作用：要感知
landing是否送达，用构造参数onReported（非归因专有）。 - 类型：
onReported?: (type, payload) => void。 - 注意：
landing为 P0，送达成功后才触发onReported('landing', ...)，失败不触发。
注意事项
必须在 URL 操作之前构造
entry URL 在 new TripoLens(...) 时就快照了。若先清理了 query（去掉 UTM）、做了 SPA 跳转再构造，渠道参数已丢、归因失败。务必进页面第一时间构造。详见 初始化 · entry URL 快照。
- 白名单为空 = fail-open：远程配置拿不到或白名单为空时，所有带
utm_source的访问都会上报（避免 CDN 故障丢投放数据）。要精确控制渠道，务必维护白名单。 - 窗口去重：同一落地 URL 在 1 分钟滚动窗口内只报一次；SPA 内短时间重复进入不会重复刷量，超过窗口后再次进入会重新上报。实现为单一 localStorage key
tripo:landing-dedupe，值是「URL 哈希 → 标记时间戳(ms)」映射，读时按窗口剪枝（now - ts >= 60s的条目顺手 GC）。 - 不受 Consent 管控：归因是基础采集能力，始终随
init()触发，不随tracking/errors/performance授权开关变化。