Web 自定义插件

通过 TrackBusinessSDK.create({ plugins }) 注册插件。start 启动采集，stop 释放资源，enrich 为当前事件补充属性。插件生成的数据仍受授权、隐私规则和项目事件定义约束。

事件属性增强

以下示例为指定事件增加固定业务分类。不要把用户输入、凭据或完整 URL 放入属性。

typescript

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

const sdk = TrackBusinessSDK.create({
  endpoint: 'https://collector.example.com/v1/events/batch',
  projectKey: 'web-public-project-key',
  initialConsent: { status: 'PENDING' },
  plugins: [
    {
      name: 'checkout-context',
      version: '1.0.0',
      role: 'enrichment',
      requiredConsent: 'STANDARD',
      start() {},
      enrich(event) {
        if (event.eventName !== 'checkout_completed') return null;
        return { properties: { business_area: 'checkout' } };
      },
    },
  ],
});
await sdk.ready();

授权后调用 await sdk.grantConsent('STANDARD') 并记录 checkout_completed，检查事件是否包含 properties.business_area。PENDING 时插件不运行。

enrich() 可返回 { context?, properties? }；返回 null 表示不增加字段。插件不能修改事件 ID、身份、Session 或时间戳。需要主动产生事件时，在 start(context) 中安装受控监听，通过 context.trackAuto(eventName, properties?, options?) 提交，并在插件声明中列出事件名。

插件生命周期

接口	用途	注意事项
`start(context)`	插件获准运行时启动；可同步或异步	可观察 `context.signal`，在取消时停止异步工作
`stop()`	Policy、授权或实例关闭等原因停止插件	清理监听器、定时器和其他宿主资源；重复启动时应能重新建立资源
`enrich(event)`	返回额外的 `context` / `properties`	返回 `null` 表示不修改；异常由插件运行时记录并隔离
`context.trackAuto(...)`	插件提交自动来源事件	仍受插件准入、Consent、Policy、采样、事件大小与 Tracking Plan 约束

故障隔离

enrichTimeoutMs 与 stopTimeoutMs 默认 1000ms，范围 1–5000ms。增强超时或补丁超过默认 16 KiB 上限时，SDK 保留原事件并记录诊断；迟到的增强结果不会回写。增强后的事件仍经过隐私和事件规则检查。

同步死循环不能由超时计时器中断。插件应限制同步工作量，并在取消信号出现时停止异步工作。

插件默认连续失败阈值为 3 次，恢复冷却时间为 30 秒。失败达到阈值后暂时跳过该插件，冷却结束后尝试恢复。可用 failureThreshold 和 recoveryCooldownMs 调整，范围分别为 1–20 次、1 秒–24 小时。

这项保护不替代插件自身的性能和隐私测试。启动超时默认 5 秒，可用 startTimeoutMs 配置；诊断只记录有限错误摘要，插件错误文本也应避免敏感信息。

接入检查

确认插件事件名、授权等级和字段范围。
确认 stop() 会移除监听器和定时器，重复启动不会重复注册。
在插件抛错或超时时检查手工 track() 仍可用，并查看诊断状态。
不在 enrich() 或事件监听回调中执行耗时的同步操作。

Web 自定义插件 ​

事件属性增强 ​

插件生命周期 ​

故障隔离 ​

接入检查 ​

Web 自定义插件

事件属性增强

插件生命周期

故障隔离

接入检查