Web 自动采集

按需启用页面浏览、文档活动状态和点击采集。点击采集只处理指定选择器范围内的元素；SDK 不读取表单输入值或 DOM 正文。

开启采集

import { TrackBusinessSDK } from '@track-business/sdk-web';

const sdk = TrackBusinessSDK.create({
  projectKey: 'web-public-project-key',
  endpoint: 'https://collector.example.com/v1/events/batch',
  initialConsent: { status: 'PENDING' },
  autocapture: {
    page: true,
    lifecycle: true,
    domClick: {
      selectorAllowlist: ['[data-track-id]'],
      maxEventsPerMinute: 60,
    },
  },
});

await sdk.ready();
// 业务取得相应授权后调用。
await sdk.grantConsent('STANDARD');

自动采集默认关闭。页面、生命周期和 DOM 点击插件默认要求 STANDARD 授权；未获授权时不运行。点击选择器必须非空，范围由接入方指定。maxEventsPerMinute 默认 120、最大 120；还可用 maxPathDepth 限制结构路径深度，默认和最大值均为 8。完整插件清单见 Web 插件。

标记采集范围

使用不含用户数据的固定业务标识：

<button data-track-id="checkout-submit" type="button">提交订单</button>

不要把手机号、邮箱、订单号或 Token 写入 data-track-id。以下标记可排除区域内的自动点击采集：

<section data-tb-no-capture="true">
  <button data-track-id="private-action">敏感操作</button>
</section>

也可使用 tb-no-capture 类名或 data-track-ignore="true"。密码输入框、原生表单控件和 contenteditable 区域的点击默认排除。SDK 使用文档捕获阶段监听；普通动态挂载元素可匹配，封闭 Shadow DOM 内部事件可能不可见。

同一控件若已在业务代码中手工记录点击，可排除自动点击，避免重复。需要业务语义动作时，给语义插件与 DOM 点击插件分配不相交的选择器。点击与业务成功是不同事实，可以分别记录。

页面地址与隐私

URL 的查询和片段会被移除，路径仍可能含用户编号。启用页面采集前，可用 pagePrivacy 将动态路径改为路由模板：

pagePrivacy: {
  collectTitle: false,
  collectReferrer: false,
  sanitizePath: (path) => path.replace(/^\/users\/[^/]+/, '/users/:userId'),
}

collectTitle 默认关闭。需要标题时显式开启，并用 sanitizeTitle 清理动态内容。sanitizePath 只接收路径；返回 null 或抛错时，SDK 省略路径。清洗仅作用于新事件，不改写已入队数据。页面地址和来源信息的完整设置见 Web 隐私与安全。

会记录什么

白名单点击产生 $element_click。其中 $element_selector 是元素结构路径的非加密哈希，可用于分组，但不能作为匿名化依据；$track_id 来自 data-track-id。可选的 $aria_label 只有显式开启 captureAriaLabel 才采集。字段表见 事件与属性字典。

表单、下载、可见性和连续点击需分别注册可选插件：

插件	记录内容
createWebFormPlugin	命中白名单的表单提交；不读取输入值
createWebDownloadPlugin	命中白名单的下载链接点击；文件名仅生成摘要，不记录扩展名
createWebVisibilityPlugin	指定元素进入视口的观测
createWebRageClickPlugin	指定范围内的连续点击观测

这些事件表示浏览器中的观察结果，不证明表单提交成功、文件下载完成或用户关注了元素。配置示例见 Web 插件。

验证

1. 授予 STANDARD 后点击一个命中白名单的元素，确认只出现预期事件；再点击排除区域，确认没有自动点击事件。
2. 检查事件中的 URL、$track_id 和可选属性，确认不含用户输入或动态敏感信息。
3. 在浏览器离线后恢复网络，检查重试及接收端确认。getHealthSnapshot().webStorage.outbox 可查看当前队列存储类型；SDK 不保证所有环境均使用 IndexedDB。

若没有事件，先检查授权等级、选择器和排除标记；上传结果按 数据校验 核对。