行为埋点

行为埋点（点击 / 曝光 / 页面浏览 / 停留 / 自定义事件）由 TrackingPlugin 提供，需要 opt-in 显式装配，并受 tracking Consent 管控。可在 Playground · 行为埋点在线体验声明式与命令式两种接法。

import { TripoLens, TrackingPlugin } from '@tripo3d/lens';

const trace = new TripoLens({
  app: 'shop',
  configUrl: '...',
  endpoint: '...',
  plugins: [
    new TrackingPlugin({ autoTrack: true }), // 开启自动采集
  ],
});
await trace.init();

不装 TrackingPlugin 时，下面的命令式 API（track/expo/click/pageview）调用都是安全的 no-op（取不到能力，不报错）。

装配方式

TrackingPlugin 构造参数是 { autoTrack?: boolean | AutoTrackOptions }：

// 只留命令式 API，不自动采集
new TrackingPlugin();

// 自动采集，全用默认
new TrackingPlugin({ autoTrack: true });

// 自动采集，细调
new TrackingPlugin({
  autoTrack: {
    exposeThreshold: 0.5,
    observeMutations: true,
    root: '#app',
    hashChange: false,
    queryChange: false,
  }
});

`AutoTrackOptions`

字段	类型	默认	说明
`exposeThreshold`	`number`	`0.5`	曝光阈值：元素进入视口的可见比例达到此值算曝光
`observeMutations`	`boolean`	`true`	是否观察动态新增的曝光元素（用 MutationObserver）
`root`	`string`	`document.body`	MutationObserver 观察根选择器，收窄可降开销
`hashChange`	`boolean`	`false`	hash 变化是否计一次 PV / 停留
`queryChange`	`boolean`	`false`	query 变化是否计一次 PV / 停留

autoTrack 开启后自动采集：声明式点击/曝光、Auto PageView（首屏 + SPA 路由进入）、停留标记（hide/show/leave）。

无 DOM 环境自动降级

在小程序 / RN / SSR 等没有 DOM 的环境，声明式采集与曝光自动禁用，只保留命令式 API——不会报错。

声明式埋点（推荐）

给元素加 data-trace* 属性，autoTrack 会自动委托采集，无需手写事件监听：

html

<!-- 点击 home.banner.buy（坐标由祖先链 data-trace 逐段拼接 + 叶子 data-trace-key） -->
<section data-trace="home">
  <div data-trace="banner">
    <button
      data-trace-key="buy"
      data-trace-type="click"
      data-trace-params='{"sku":"A1"}'
    >
      购买
    </button>
  </div>
</section>

属性	作用
`data-trace`	扁平坐标或祖先段（由外到内逐段拼接）
`data-trace-key`	叶子末段，与祖先 `data-trace` 组合成完整坐标
`data-trace-type`	触发事件，空白/逗号分隔多事件（`"click expose"`）；缺省 `click`
`data-trace-params`	上报参数（JSON 字符串）；别名 `data-trace-data`
`data-trace-expose-policy`	元素级曝光去重策略，覆盖坐标级配置；取值见曝光去重策略，非法值静默忽略

纯 HTML / 原生 JS（动态属性）

无框架、服务端模板、静态站点等纯 HTML 场景：坐标固定时直接写属性（如上例）；需要动态时用原生 JS 更新属性即可——采集器在触发那一刻才读属性，所以更新后无需任何通知。

html

<button
  id="buy"
  data-trace-key="home.banner.buy"
  data-trace-type="click expose"
>
  购买
</button>

<script>
  const el = document.getElementById('buy');

  // 动态参数：属性只能存字符串，对象必须自己 JSON.stringify
  el.setAttribute('data-trace-params', JSON.stringify({ sku: 'A1' }));

  // 也可用 dataset（注意驼峰映射：data-trace-params ↔ dataset.traceParams）
  el.dataset.traceParams = JSON.stringify({ sku: 'A1' });

  // 事件 token 想避免硬编码，可从 SDK 引入 TraceEvent 常量：
  // import { TraceEvent } from '@tripo3d/lens'
  // el.dataset.traceType = [TraceEvent.Click, TraceEvent.Expose].join(' ');
</script>

要点：

参数唯一需序列化：data-trace-params 是对象时必须 JSON.stringify；坐标（data-trace / data-trace-key）与事件（data-trace-type）是字符串，直接写即可。
触发时才读：更新属性后无需通知 SDK——下次点击读到的就是最新值（全局事件委托，天然覆盖后续变更）；曝光的参数（data-trace-params）同样触发时活读，但坐标与策略在元素登记时快照（见曝光去重策略边界说明）。
动态新增元素：autoTrack 默认开 observeMutations，动态插入 DOM 的、带 data-trace / data-trace-key 的元素会被自动登记曝光；收窄观察范围或关闭见 AutoTrackOptions。

不要把对象直接塞给属性

el.setAttribute('data-trace-params', { sku }) 或 el.dataset.traceParams = { sku } 都会写成字符串 "[object Object]"（DOM 属性只能存字符串），采集端 JSON.parse 失败、参数丢失。必须 JSON.stringify 后再赋值。

框架适配器

Vue / React 项目推荐用对应适配器的声明式语法，无需手写 data-trace*——适配器底层只把声明式绑定映射成上面的 data-trace* 属性，采集逻辑完全复用本页的 autoTrack，坐标拼接、tripo 前缀、曝光去重等规则与手写一致。各适配器的安装与完整用法见独立接入页：

适配器	声明式 API	接入文档
`@tripo3d/lens/vue`	`v-trace` 指令	Vue 接入
`@tripo3d/lens/react`	`useTraceProps` + `<Trace>`	React 接入

Nuxt 项目

@tripo3d/lens/nuxt 是 Nuxt Module，SSR、性能、错误与行为埋点默认全部开启；行为埋点走的同样是本页的 autoTrack，可显式配 tracking: false 关闭。它的定位与完整选项见性能收集与 Nuxt 接入。

曝光去重策略

自动曝光默认按 once-per-session 去重（同一坐标一个会话只报一次）。可选策略：

策略	`ExposePolicy` 枚举	行为
`always`	`ExposePolicy.Always`	每次进入视口都报
`once-per-element`	`ExposePolicy.OncePerElement`	同一 DOM 元素只报一次
`once-per-session`	`ExposePolicy.OncePerSession`	默认，同一坐标整会话只报一次
`throttle`	`ExposePolicy.Throttle`	同坐标节流窗口内至多一次（默认窗口 5000 ms）

在 TS / 框架绑定场景，策略值可从 SDK 引入 ExposePolicy 枚举（import { ExposePolicy } from '@tripo3d/lens'，vue / react 子路径同步 re-export），避免手拼字符串字面量；纯 HTML 属性场景仍直接写字符串 token。

策略有两个配置入口，解析优先级：元素属性 data-trace-expose-policy > setExposurePolicy（overrides > default）> 内置 once-per-session。

元素级：在元素上写 data-trace-expose-policy，策略跟随声明走。典型场景是列表——v-for 渲染的多个列表项共享同一坐标，默认 once-per-session 只会报第一条；声明 once-per-element 后每条各报一次：
html
```
<div
  v-for="msg in list"
  data-trace-key="message_content"
  data-trace-type="click expose"
  data-trace-expose-policy="once-per-element"
  :data-trace-params="JSON.stringify({ title: msg.title })"
/>
```
坐标级：setExposurePolicy 按坐标模式批量指定，适合集中治理（用法见下文进阶）。

四处边界

throttle 节流窗口当前固定 5000 ms，不可配置。
命令式 trackImpression 只支持 once-per-element（once: true，默认）与 always（once: false）；要 once-per-session / throttle 请走 setExposurePolicy。
data-trace-expose-policy 值非法（拼写错误等）时静默回落坐标级配置，不报错；建议 Vue / React 用适配器的 exposePolicy 字段获得 TS 类型约束。
曝光的坐标与策略在元素登记时解析并快照（首扫或 MutationObserver 发现元素时）：登记后再改 data-trace-expose-policy、或再调 setExposurePolicy，对已登记元素不生效——策略须在元素渲染前就位。触发时仍活读的只有 data-trace-params。

命令式埋点

不依赖 DOM 属性，直接调 TripoLens 上的方法。坐标须为合法 TracePath（点分坐标）：

trace.track('checkout.submit', { amount: 99 }); // 自定义事件
trace.click('home.banner.buy', { sku: 'A1' });  // 命令式点击
trace.expo('home.banner', { pos: 'top' });      // 命令式曝光
trace.pageview({ from: 'push' });               // 手动 PageView（页面身份由 SDK 注入）

方法	签名	说明
`track`	`(event: string, properties?) => void`	自定义事件，`event` 为 TracePath 坐标
`click`	`(path: string, properties?) => void`	命令式点击
`expo`	`(path: string, properties?) => void`	命令式曝光
`pageview`	`(properties?) => void`	手动 PageView，仅带 properties；`page_url`/`referrer` 由 SDK 注入

坐标不在 payload 里

事件坐标统一承载在信封 event_format，不随 properties 重复下发；properties 只装你的业务私参。

进阶：命令式曝光与运行时曝光策略

以下两个方法与其余命令式 API 一样直接在 trace 门面上调用，无需保留 TrackingPlugin 实例；须在 await trace.init() 之后调用（能力未就绪时 no-op）：

const trace = new TripoLens({
  app: 'shop', configUrl: '...', endpoint: '...',
  plugins: [new TrackingPlugin({ autoTrack: true })],
});
await trace.init();

`trackImpression(selector, opts)`：给现有元素登记曝光

对调用时已存在、命中选择器的元素登记曝光上报（动态新增的元素需再调一次，或改用声明式 data-trace* 自动跟新增）：

trace.trackImpression('.product-card', {
  eventName: 'list.product.card',                              // 曝光坐标（须合法 TracePath）
  once: true,                                                  // true=每元素一次（默认）；false=每次进视口都报
  threshold: 0.5,                                              // 可见比例阈值（默认 0.5）
  getProps: (el) => ({ id: (el as HTMLElement).dataset.id }), // 按元素生成上报参数
});

字段	类型	默认	说明
`eventName`	`string`	必填	曝光坐标，非法 TracePath 丢弃
`once`	`boolean`	`true`	`true` → once-per-element；`false` → always
`threshold`	`number`	`0.5`	进视口可见比例阈值
`getProps`	`(el: Element) => object`	—	按元素生成上报参数

`setExposurePolicy(policy)`：运行时改曝光去重策略

运行时设置曝光策略。远程配置不含曝光策略字段，此 API 是曝光策略的唯一配置来源；建议在元素登记前调用：

import { ExposePolicy } from '@tripo3d/lens';

trace.setExposurePolicy({
  // 全局默认：同一坐标整会话只报一次
  default: ExposePolicy.OncePerSession,
  overrides: {
    // always：每次进视口都报（轮播、需反复曝光的位）
    'home.banner.*': ExposePolicy.Always,
    // once-per-element：同一 DOM 元素只报一次（同坐标多实例各报一次）
    'list.product.*': ExposePolicy.OncePerElement,
    // throttle：同坐标节流窗口（固定 5000 ms）内至多一次
    'feed.card.*': ExposePolicy.Throttle,
  },
});

策略取值见曝光去重策略；解析优先级：元素属性 data-trace-expose-policy > overrides（坐标模式匹配）> default > 内置 once-per-session。overrides 内部多条同时命中时按具体度取胜者：精确键 > 最长通配前缀（如 a.b.* 胜过 a.*），与书写顺序无关。

坐标模式的匹配边界

overrides 的坐标模式只支持精确匹配与后缀 .*（如 list.product.*），不支持中段通配（app.*.card 无效）。中段是变量的坐标（如按路由变化的 studio.<route>.message_content）无法用模式命中，请改用元素级 data-trace-expose-policy。

产出的事件类型

事件	触发
`click`	声明式点击 / `click()`
`expo`	曝光 / `expo()`
`pageview`	首屏 + SPA 路由进入 / `pageview()`
`hide` / `show` / `leave`	停留标记（前端只报时间点，时长由后端按时间线还原）
`track`	`track()` 自定义事件

API 说明

命令式行为埋点 API 经 trace 门面暴露（受 tracking Consent 管控，未装 / 未授权时 no-op）。

`trace.track(event, properties?)`

含义与作用：上报自定义事件，event 为事件坐标。
类型：(event: string, properties?: Record<string, unknown>) => void。
注意：event 须为合法 TracePath（. 分隔 2–8 段），非法时丢弃并在控制台 warn（含具体原因）、同时经 onError 上报；受远程 track 门控（userId 白名单 / trackGray 登录用户比例）影响。

`trace.click(path, properties?)` / `trace.expo(path, properties?)`

含义与作用：命令式点击 / 曝光上报。
类型：(path: string, properties?: Record<string, unknown>) => void。
注意：path 须为合法 TracePath，非法丢弃且不发脏事件，并在控制台 warn 说明具体原因（段数越界 / 段超长 / 含非法字符）。

`trace.pageview(properties?)`

含义与作用：手动 PageView；autoTrack 关也可用。
类型：(properties?: Record<string, unknown>) => void。
注意：只可附带 properties，page_url / referrer 由 SDK 注入，不要自填。

`trace.trackImpression(selector, opts)`

含义与作用：给现有元素登记曝光上报。
类型：(selector: string, opts: { eventName: string; once?: boolean; threshold?: number; getProps?: (el: Element) => Record<string, unknown> }) => void。
注意：只观察调用时已存在的元素；无 DOM 环境 no-op；须在 init() 完成后调用。详见命令式曝光。

`trace.setExposurePolicy(policy)`

含义与作用：运行时设置曝光去重策略（远程配置不含曝光策略字段，此 API 是唯一配置来源）。
类型：(policy: { default?: ExposePolicyType; overrides?: Record<string, ExposePolicyType> }) => void。
注意：ExposePolicyType ∈ 'always' | 'once-per-element' | 'once-per-session' | 'throttle'（可用 ExposePolicy 枚举取值，免手拼）；须在 init() 完成后、元素登记前调用。

`new TrackingPlugin(opts?)`

含义与作用：构造行为埋点插件（opt-in，经构造参数 plugins 装配）。
类型：new TrackingPlugin(opts?: { autoTrack?: boolean | AutoTrackOptions })。
注意：autoTrack 传 true / 对象才开启声明式采集 + Auto PageView + 停留标记；不传只留命令式 API。字段见装配方式。

上手

采集能力

工具

行为埋点

装配方式

`AutoTrackOptions`

声明式埋点（推荐）

纯 HTML / 原生 JS（动态属性）

框架适配器

曝光去重策略

命令式埋点

进阶：命令式曝光与运行时曝光策略

`trackImpression(selector, opts)`：给现有元素登记曝光

`setExposurePolicy(policy)`：运行时改曝光去重策略

产出的事件类型

API 说明

`trace.track(event, properties?)`

`trace.click(path, properties?)` / `trace.expo(path, properties?)`

`trace.pageview(properties?)`

`trace.trackImpression(selector, opts)`

`trace.setExposurePolicy(policy)`

`new TrackingPlugin(opts?)`

下一步

行为埋点 ​

装配方式 ​

AutoTrackOptions ​

声明式埋点（推荐） ​

纯 HTML / 原生 JS（动态属性） ​

框架适配器 ​

曝光去重策略 ​

命令式埋点 ​

进阶：命令式曝光与运行时曝光策略 ​

trackImpression(selector, opts)：给现有元素登记曝光 ​

setExposurePolicy(policy)：运行时改曝光去重策略 ​

产出的事件类型 ​

API 说明 ​

trace.track(event, properties?) ​

trace.click(path, properties?) / trace.expo(path, properties?) ​

trace.pageview(properties?) ​

trace.trackImpression(selector, opts) ​

trace.setExposurePolicy(policy) ​

new TrackingPlugin(opts?) ​

下一步 ​

行为埋点

装配方式

`AutoTrackOptions`

声明式埋点（推荐）

纯 HTML / 原生 JS（动态属性）

框架适配器

曝光去重策略

命令式埋点

进阶：命令式曝光与运行时曝光策略

`trackImpression(selector, opts)`：给现有元素登记曝光

`setExposurePolicy(policy)`：运行时改曝光去重策略

产出的事件类型

API 说明

`trace.track(event, properties?)`

`trace.click(path, properties?)` / `trace.expo(path, properties?)`

`trace.pageview(properties?)`

`trace.trackImpression(selector, opts)`

`trace.setExposurePolicy(policy)`

`new TrackingPlugin(opts?)`

下一步