Track Business SDK

主题外观

最新
文档版本
最新文档✓2026.11.0
AI 文档索引 ↗

Web 插件 ​

Web 插件需显式启用，可通过 autocapture 配置或 plugins 注册。按需要选择插件，避免在同一目标上重复记录点击或页面事件。

使用前 ​

  1. 自动采集插件默认关闭，启用后仍受授权和采集策略约束。
  2. 内置插件不采集表单输入值；路径、标题和自定义属性仍需审查。
  3. 插件异常会被隔离，但自定义插件仍需控制同步计算量，避免阻塞页面。

Web SDK 的 pagePrivacy 对显式传入和后续 registerPlugin() 注册的插件使用同一实例策略。 页面标题默认省略；路径和来源页默认保留，可分别清洗或关闭。归因插件的首次/最近落地页和来源页存储副本也受控制。 完整配置、路由模板与旧缓存边界见页面地址与隐私。

预设插件组合 ​

可以按页面、点击、渠道和稳定性需求选择预设组合：

页面与稳定性组合 ​

createWebBetaPluginPack 组合页面、生命周期、归因和可靠性插件。各插件仍遵守自身的 Consent、Policy 和 Tracking Plan 门控；它不会自动启用 DOM 点击采集或录屏。接入前应按下方插件清单确认所需能力和数据范围：

typescript
import { TrackBusinessSDK } from '@track-business/sdk-web';
import { createWebBetaPluginPack } from '@track-business/sdk-web/plugins/presets';

const sdk = TrackBusinessSDK.create({
  endpoint: 'https://collector.example.com/v1/events/batch',
  projectKey: 'web-public-project-key',
  plugins: createWebBetaPluginPack({
    growth: { attribution: { mode: 'first_touch' } },
  }),
});

页面与点击采集 ​

需要采集单页应用的页面浏览、文档活动状态和受控点击时使用：

typescript
import { createWebAutocapturePluginPack } from '@track-business/sdk-web/plugins/presets';

const plugins = createWebAutocapturePluginPack({
  page: true,
  lifecycle: true,
  domClick: { selectorAllowlist: ['[data-track-id]'] }, // 必须指定选择器白名单
});

这只注册插件，不会自动提升 Consent。页面与生命周期、DOM 点击插件默认要求 STANDARD；默认 Consent 为 GRANTED + MINIMAL，需在宿主/CMP 确认授权后调用 grantConsent('STANDARD')。选择器必须由接入方控制范围，SDK 不会拒绝 '*' 这类宽选择器。

按场景组合 ​

typescript
import {
  createWebContentPluginPack,
  createWebGrowthPluginPack,
  createWebLifecyclePluginPack,
  createWebReliabilityPluginPack,
} from '@track-business/sdk-web/plugins/presets';

const plugins = [
  // 增长投放场景：包含 utm 渠道归因与落地页上下文
  ...createWebGrowthPluginPack({
    attribution: { mode: 'first_touch' },
  }),
  // 内容/电商场景：显式目标曝光与业务交互
  ...createWebContentPluginPack({
    exposure: {
      targets: [{ selector: '[data-track-exposure]', exposureId: 'home_hero' }],
    },
    interaction: {
      targets: [{ selector: '[data-track-action]', action: 'nav_click' }],
    },
  }),
  // 稳定性场景：包含 JS 异常、Web Vitals 与性能摘要
  ...createWebReliabilityPluginPack(),
  // 文档活动状态与页面停留片段；不定义 Session 开始/结束
  ...createWebLifecyclePluginPack(),
];

插件与事件 ​

下表列出插件产生的事件及采集范围：

插件名称 (Manifest)工厂函数入口触发标准事件采集语义与安全约束
web-spa-pagecreateWebSpaPagePlugin$pageview记录单页路由切换；页面地址按 pagePrivacy 配置处理
web-page-leavecreateWebPageLeavePlugin$page_leave页面隐藏/卸载时发出，记录页面停留片段
web-staycreateWebStayPlugin$web_stay页面处于可见且活跃状态的实际有效时长
web-page-loadcreateWebPageLoadPlugin$page_loadNavigation Timing API 性能指标摘要
web-scrollcreateWebScrollPlugin$scroll页面滚动深度有界阈值（25%、50%、75%、100%）
web-dom-clickcreateWebDomClickPlugin$element_click受控点击：只处理命中 selectorAllowlist 的元素，不读文本；选择器范围由接入方审查
web-rage-clickcreateWebRageClickPlugin$web_rage_click短时间内连续点击异常检测（默认关闭）
web-exposurecreateWebExposurePlugin$sdk_exposure基于 IntersectionObserver 监听指定视口曝光目标
web-interactioncreateWebInteractionPlugin$sdk_interaction显式声明的业务语义交互动作
web-attributioncreateWebAttributionPlugin$sdk_attribution白名单 Campaign 参数识别与跨会话存储
web-lifecyclecreateWebLifecyclePlugin$sdk_lifecycle文档活动状态；字段为 $lifecycle_state 与 $lifecycle_scope，不定义 Analytics Session 边界
web-vitalscreateWebVitalsPlugin$sdk_web_vital核心体验指标：LCP、INP、CLS 采集
web-performancecreateWebPerformancePlugin$sdk_performancePaint、首屏渲染与静态资源聚合耗时
web-exceptioncreateWebExceptionPlugin$sdk_exception捕获未处理异常；有限清洗常见邮箱、Bearer、凭据键名和 URL，不保证覆盖所有敏感内容
web-network-performancecreateWebNetworkPerformancePlugin$sdk_network_performanceResource Timing 网络请求耗时统计
web-network-enrichmentcreateWebNetworkEnrichmentPlugin— (Context 扩展)注入 context.network.online；有效连接类型、RTT 与下行速率仅在显式启用后读取，且受浏览器支持限制

常用插件配置 ​

元素曝光 (web-exposure) ​

曝光插件使用浏览器的 IntersectionObserver 监听显式配置的目标，最多读取前 50 个配置项。每个选择器每轮最多检查前 1,024 个匹配元素，同时观察最多 64 个。DOM 变化会合并处理，动态元素可能稍后开始计时。长列表和虚拟滚动可在业务确认元素曝光时显式记录。

html
<div id="hero-banner" data-track-exposure></div>
typescript
import { createWebExposurePlugin } from '@track-business/sdk-web/plugins';

createWebExposurePlugin({
  targets: [{ selector: '#hero-banner', exposureId: 'home_hero_banner' }],
  minVisibleMs: 500, // 元素持续可见至少 500 毫秒才计入有效曝光
  threshold: 0.5, // 视口内可见面积比例必须 >= 50%
});

交互语义 (web-interaction) ​

用于捕获关键业务控件动作。仅接受显式配置的语义目标，不会读取控件文本或表单输入：

typescript
import { createWebInteractionPlugin } from '@track-business/sdk-web/plugins';

createWebInteractionPlugin({
  targets: [
    {
      selector: '[data-action="checkout_pay"]',
      action: 'checkout_submit',
      elementType: 'primary_button',
      screenName: 'CheckoutPage',
    },
  ],
});

渠道来源 (web-attribution) ​

页面离开 (web-page-leave) ​

页面隐藏、切换路由或离开文档时生成 $page_leave。关闭标签时浏览器可能中止后续工作，事件能否送达仍取决于 Outbox 与浏览器生命周期，不构成送达保证：

typescript
import { createWebPageLeavePlugin } from '@track-business/sdk-web/plugins';

createWebPageLeavePlugin({
  // 默认记录页面可见期间的停留片段，无需配置时长开关。
});

表单、下载与可见性 ​

针对特定业务场景，SDK 还提供 3 个细分元数据插件；它们不会读取输入值、文件正文或 DOM 文本，但会生成少量事件元数据。宿主应审查选择器、ID 和页面 URL：

插件名称触发事件采集数据范围采集边界
web-form$web_form_submit当前页面 URL、表单标签及可选的表单 ID 哈希；仅监听命中选择器的 submit不读取表单控件值或表单文本
web-download$web_download当前页面 URL、链接标签及可选的下载文件名哈希；只处理含 download 属性且命中选择器的链接不读取文件正文、磁盘数据或下载扩展名
web-visibility$web_visibility目标标签、当前页面 URL、可见比例；每个元素每次插件运行最多一次不读取 DOM 文本；默认可见比例 50%，不设持续时间门槛

按场景选择插件 ​

根据业务需要选择插件：

业务场景推荐配置插件组合预期产生核心事件
内容资讯 / 社区web-spa-page + web-stay + web-scroll$pageview、$web_stay、$scroll
电商与商品交易web-spa-page + web-exposure + web-interaction$pageview、$sdk_exposure、$sdk_interaction
获客投放落地页web-spa-page + web-attribution + web-page-leave$pageview、$sdk_attribution、$page_leave
后台管理系统web-spa-page + web-exception + web-vitals$pageview、$sdk_exception、$sdk_web_vital

体积与 Tree-shaking 说明 ​

Web 包提供 ESM 导出并标记 sideEffects: false，支持使用方构建工具进行 Tree-shaking。实际移除效果取决于导入入口、构建器配置和宿主打包结果；请用生产构建产物分析确认体积，不保证未调用的每个工厂及其依赖都必然完全剔除。

Web Vitals 统计口径 ​

$sdk_web_vital 的 $report_version 为 2.0。同一 $metric_id 的新观测会增加 $revision；统计时按项目和指标 ID 取最高修订，不要把累计的 $value 相加。$unit 对 CLS 为 dimensionless，对 FCP、LCP、INP 为 ms；$value_clamped 标记截断值，不宜按精确测量参与分布统计。

$document_id 关联文档，$observation_id 关联一次观测；$navigation_type 描述导航类型，$algorithm_version 标识指标算法。$measurement_scope 区分完整文档、往返缓存恢复和局部采集。授权晚于页面启动或采集重启时，样本标为 collection-segment，不应并入完整文档分布。浏览器不支持相应观测能力时，指标会缺失，不能按零值统计。