客户端能力总览

按业务需求选择能力，再按对应平台的步骤安装、授权并确认事件接收。

页面和点击采集的接入方式因界面技术而异：

场景	推荐方式	接入时需要做什么
Web 页面与指定元素	Web 自动采集	启用所需能力；点击目标配置选择器白名单
Android Compose、iOS SwiftUI	原生 UI 接入	为页面和需要记录的控件显式绑定
iOS UIKit	原生 UI 接入	为需要记录的控件显式绑定
Android 传统 View	自动点击采集（实验）	配对构建插件和运行时；支持部分 Java/Kotlin Lambda，须验证实际目标
支付完成等业务结果	手动 `track`	在业务结果确定时记录，不依赖 UI 点击推断

自动或绑定采集需要满足对应授权和策略；默认授权等级不代表已启用所有自动采集。一次行为选择一个点击采集来源，业务结果可以另行记录。

Android 传统 View 未启用插桩或目标已从插桩采集范围中排除时，可以在已有点击回调中显式记录，随后执行原有业务操作：

kotlin

checkoutButton.setOnClickListener {
    sdk.recordAppClick(action = "checkout_submit", targetTag = "button")
    submitOrder()
}

同一按钮不要同时通过插桩和 recordAppClick 记录点击。升级后部分 Java/Kotlin Lambda 可能新增自动采集；对于原来已显式记录的目标，应移除显式点击记录或通过 ignoredResourceNames 排除该目标，并验证只产生一次点击事件。点击只代表控件被激活；订单提交或支付是否成功应在业务结果确定后另行记录。接口参数见 Android API。

您要实现的功能	阅读入口
页面、点击、曝光等其他插件，或原生组件接入	组件选择与下方能力目录

IMPORTANT

请确认所用 SDK 包支持所需能力；原生增强器需要 event_enrichment。

1. 选择组件

平台	基础安装	可选组件与触发责任	释放方式
Web	同一 Web SDK；ESM 通过 `plugins` 子路径导入，推荐 Script 包含工厂	显式工厂/Pack 或 `autocapture`；受控 DOM 功能还需声明目标	SDK `destroy()`；自定义插件 `stop()` 清理自己的监听
iOS	Core SDK	SwiftUI/UIKit 显式 UI 绑定；异常/网络等由 Host 提交；Location 是独立模块	释放绑定句柄并 `close()`；视图绑定遵循所在模块生命周期
Android	Core SDK	Compose、Lifecycle 适配按需引入；传统 View AutoTrack 是构建插件与运行时组件配对的实验能力	释放安装句柄并 `close()`

各组件须与 SDK 配套安装。安装方式见 Web、Android、iOS 接入指南。

默认进程后台 flush、身份和 Session 处理是 SDK 的基础职责。停用生命周期事件插件，不等于关闭这些机制。不同平台的页面/曝光机制见 Compose、SwiftUI 与 UIKit。

2. 第一方能力目录

按下表查找能力和接入入口。自动采集默认关闭；启用后仍需满足用户授权、项目采集策略、事件计划和浏览器或系统支持条件。

平台	插件	采集机制	事件	授权/默认状态	触发条件	入口
android	`android-autotrack`	构建插桩 + 运行时绑定（实验）	`$app_click`	STANDARD / 默认关闭	配对引入 AGP 插件与运行时包，调用 install 并命中允许的传统 View listener	接入说明
android	`android-exception`	宿主提交信号	`$sdk_exception`	STANDARD / 默认关闭	Host 调用 recordNonFatalError；不安装全局 Crash Handler	接入说明
android	`android-exposure`	宿主/UI 绑定	`$sdk_exposure`	STANDARD / 默认关闭	安装对应 UI 曝光绑定并提供稳定目标；手工 recordExposure 另走手工语义	接入说明
android	`android-lifecycle`	自动观察（需显式注册）	`$sdk_lifecycle`	STANDARD / 默认关闭	标准工厂的 Activity 生命周期接入；需授权和插件策略允许	接入说明
android	`android-network-performance`	宿主提交信号	`$sdk_network_performance`	STANDARD / 默认关闭	Host 提供网络耗时/数量/字节汇总，不拦截全局请求	接入说明
android	`android-performance`	宿主提交信号	`$sdk_performance`	STANDARD / 默认关闭	Host 提供启动耗时等有界测量值	接入说明
ios	`ios-exception`	宿主提交信号	`$sdk_exception`	STANDARD / 默认关闭	Host 调用 recordNonFatalError；不安装全局 Crash Handler	接入说明
ios	`ios-exposure`	宿主/UI 绑定	`$sdk_exposure`	STANDARD / 默认关闭	安装对应 UI 曝光绑定并提供稳定目标；手工 recordExposure 另走手工语义	接入说明
ios	`ios-lifecycle`	宿主/UI 绑定	`$sdk_lifecycle`	STANDARD / 默认关闭	安装 UIKit 应用生命周期适配或转交 Host 生命周期信号	接入说明
ios	`ios-network-performance`	宿主提交信号	`$sdk_network_performance`	STANDARD / 默认关闭	Host 提供网络耗时/数量/字节汇总，不拦截全局请求	接入说明
ios	`ios-performance`	宿主提交信号	`$sdk_performance`	STANDARD / 默认关闭	Host 提供启动耗时等有界测量值	接入说明
web	`web-dom-click`	自动观察（需显式注册）	`$element_click`	STANDARD / 默认关闭	点击命中宿主声明的 selectorAllowlist；不读取文本	接入说明
web	`web-download`	自动观察（需显式注册）	`$web_download`	STANDARD / 默认关闭	白名单链接的下载动作元数据	接入说明
web	`web-exception`	自动观察（需显式注册）	`$sdk_exception`	STANDARD / 默认关闭	监听浏览器异常与未处理拒绝；仅有限清洗摘要	接入说明
web	`web-exposure`	自动观察（需显式注册）	`$sdk_exposure`	STANDARD / 默认关闭	显式 targets 达到可见面积与持续时长条件	接入说明
web	`web-form`	自动观察（需显式注册）	`$web_form_submit`	STANDARD / 默认关闭	白名单表单提交元数据，不读取输入值	接入说明
web	`web-interaction`	自动观察（需显式注册）	`$sdk_interaction`	STANDARD / 默认关闭	命中显式 targets 的业务语义交互	接入说明
web	`web-lifecycle`	自动观察（需显式注册）	`$sdk_lifecycle`	STANDARD / 默认关闭	文档可见性/活动状态变化，不定义 Session 边界	接入说明
web	`web-network-enrichment`	事件属性增强	只增强当前事件	STANDARD / 默认关闭	读取当前网络状态快照；可选连接质量受浏览器支持限制	接入说明
web	`web-network-performance`	自动观察（需显式注册）	`$sdk_network_performance`	STANDARD / 默认关闭	Resource Timing 网络资源汇总，不读取请求正文	接入说明
web	`web-page-leave`	自动观察（需显式注册）	`$page_leave`	STANDARD / 默认关闭	路由切换、页面隐藏或离开时记录停留片段	接入说明
web	`web-page-load`	自动观察（需显式注册）	`$page_load`	STANDARD / 默认关闭	读取 Navigation Timing 摘要	接入说明
web	`web-performance`	自动观察（需显式注册）	`$sdk_performance`	STANDARD / 默认关闭	浏览器 Performance API 的有界性能摘要	接入说明
web	`web-rage-click`	自动观察（需显式注册）	`$web_rage_click`	STANDARD / 默认关闭	显式受控目标内的短时连续点击	接入说明
web	`web-scroll`	自动观察（需显式注册）	`$scroll`	STANDARD / 默认关闭	滚动达到已配置深度阈值	接入说明
web	`web-spa-page`	自动观察（需显式注册）	`$pageview`	STANDARD / 默认关闭	初始化及路由导航；按实例 pageRouting 选择 history/hash	接入说明
web	`web-stay`	自动观察（需显式注册）	`$web_stay`	STANDARD / 默认关闭	页面可见且活跃时累计有效停留	接入说明
web	`web-visibility`	自动观察（需显式注册）	`$web_visibility`	STANDARD / 默认关闭	白名单目标的可见性变化	接入说明
web	`web-vitals`	自动观察（需显式注册）	`$sdk_web_vital`	STANDARD / 默认关闭	受支持的 PerformanceObserver 体验指标	接入说明

3. 选择接入路径

Web 自动采集

按 Web 插件指南选工厂或配方；配置不升级 Consent。DOM 点击/曝光须声明业务目标，表单功能不采集输入正文。

同名配置按 默认配方 → autoPage → autocapture → 显式 plugins 的顺序覆盖。框架负责页面采集时，设置 autoPage: 'manual'。动态注册的插件名称不能重复；替换前先注销旧插件。

原生内置处理器和 UI 绑定

原生通过 policy.pluginEnabled 允许插件运行，使用 allowlist 只启用所需插件，再按目录绑定 UI 或调用 Host API。默认 GRANTED + MINIMAL 不满足大部分自动采集要求；应在宿主确认授权后提升到 STANDARD。

原生 started 表示策略准入；Host 未提供信号时没有事件是正常状态。异常摘要不等于完整 Crash 监控；网络汇总不等于 SDK 已拦截 App 的所有请求。

各端采用同一准入概念，配置字段遵循各自 API，不能直接跨语言复制：

配置	Web	iOS / Android
插件总开关	`policy.pluginPolicy.enabled`	`policy.pluginEnabled`
插件白名单	`policy.pluginPolicy.allowlist`	`policy.pluginAllowlist`
自定义增强器	`plugins` 中的 enrichment 对象	iOS `enrichmentPlugins`；Android `eventEnrichers`

Android Java 可通过 Builder 设置 pluginEnabled(...) 和 pluginAllowlist(...)。

自定义业务属性增强

单个宿主的字段调整/过滤可继续使用 beforeSend。多模块复用使用命名增强器，按配置列表顺序执行；同名业务属性由后一个覆盖。增强器返回 null/nil 表示不修改，不能用来删除事件。三个平台都在最终隐私和事件计划检查前执行增强。

Web 在 plugins 中提供 role: 'enrichment'、start() 和 enrich()，详见 Web 自定义插件。

以下配方都先安装增强器并保持 PENDING，随后由宿主自己的授权流程决定是否启用。实例在项目作用域内复用，不要为每条事件创建实例。

查看各平台增强器配置示例

Web 注册

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' },
  policy: { pluginPolicy: { enabled: true, allowlist: ['checkout-context'] } },
  plugins: [
    {
      name: 'checkout-context',
      role: 'enrichment',
      requiredConsent: 'STANDARD',
      start() {},
      enrich(event) {
        return event.eventName === 'checkout_completed'
          ? { properties: { business_area: 'checkout' } }
          : null;
      },
    },
  ],
});
await sdk.ready();

Android Java 注册

Android Java/Kotlin 标准工厂使用 Map 和同步回调，无需接触内部 JsonObject：

java

EventEnricher business = EventEnricher.create("checkout-context", input ->
    "checkout_completed".equals(input.getEventName())
        ? EventEnrichmentPatch.properties(Collections.singletonMap("business_area", "checkout"))
        : null);
TrackBusinessConfig config = TrackBusinessConfig.builder()
    .initialConsent(com.trackbusiness.sdk.models.ConsentDecision.pending())
    .eventEnrichers(Collections.singletonList(business))
    .pluginEnabled(true)
    .pluginAllowlist(Collections.singleton("checkout-context"))
    .build();
TrackBusinessSDK sdk = TrackBusinessSDK.create(context, endpoint, projectKey, config);

Android Kotlin 注册

kotlin

import com.trackbusiness.sdk.EventEnricher
import com.trackbusiness.sdk.EventEnrichmentPatch
import com.trackbusiness.sdk.TrackBusinessConfig
import com.trackbusiness.sdk.TrackBusinessSDK
import com.trackbusiness.sdk.models.ConsentDecision
import com.trackbusiness.sdk.models.SDKPolicy

val business = EventEnricher.create("checkout-context") { input ->
    if (input.eventName == "checkout_completed")
        EventEnrichmentPatch.properties(mapOf("business_area" to "checkout"))
    else null
}
val config = TrackBusinessConfig(
    initialConsent = ConsentDecision.pending(),
    policy = SDKPolicy(pluginEnabled = true, pluginAllowlist = setOf("checkout-context")),
    eventEnrichers = listOf(business),
)
val sdk = TrackBusinessSDK.create(context, endpoint, projectKey, config)

iOS Swift 注册

iOS 标准 create 和 createWithRemotePolicy 都接受 enrichmentPlugins：

swift

struct CheckoutContext: EventEnrichmentPlugin {
    let name = "checkout-context"
    let requiredConsent = "STANDARD"
    func enrich(_ event: EventEnvelope) throws -> EventEnrichmentResult? {
        guard event.eventName == "checkout_completed" else { return nil }
        return EventEnrichmentResult(properties: ["business_area": .string("checkout")])
    }
}
let sdk = try TrackBusinessSDK.create(
    endpoint: endpoint, projectKey: projectKey,
    policy: SDKPolicy(pluginEnabled: true, pluginAllowlist: ["checkout-context"]),
    initialConsent: .pending,
    enrichmentPlugins: [CheckoutContext()]
)

离线二进制包使用 import TrackBusinessSDKKit；源码 Swift Package 使用 import TrackBusinessSDK。

宿主确认授权后，再触发事件

下面的代码只能放在宿主/CMP 已确认相应授权的分支中；它不是自动授权逻辑。只执行上面的注册示例时，PENDING 下没有事件是预期行为。

typescript

await sdk.grantConsent('STANDARD');
sdk.track('checkout_completed', {});

java

sdk.grantConsent("STANDARD", error -> {
    if (error == null) sdk.track("checkout_completed", Collections.emptyMap());
});

kotlin

sdk.grantConsent("STANDARD") { error ->
    if (error == null) sdk.track("checkout_completed")
}

swift

sdk.grantConsent(level: "STANDARD") { applied in
    if applied { sdk.track("checkout_completed", properties: [:]) }
}

事件应包含 properties.business_area = "checkout"。使用真实接收端核对该字段及整批 ACK；入队、Health 或一次 flush() 调用返回都不能单独证明后端收到。收尾分别使用 Web await sdk.destroy()、原生 sdk.close()；不要为刷新事件关闭项目级单例。

增强器只修改允许的业务属性，不能改写身份、Session、事件 ID 或投递字段。名称冲突时请调整插件名，手工事件仍可使用。

4. 故障与成本边界

Web enrichTimeoutMs / stopTimeoutMs 默认 1000ms，本地范围 1–5000ms；每插件最多保留一个未完成增强任务。超时后保留事件，后续事件绕过该任务，迟到结果丢弃。停止未完成时不会重叠启动；任务结束后可再次显式更新策略恢复。
任意 Promise 不能被 SDK 强制取消；插件仍应遵循 AbortSignal 并清理资源。同步死循环不能被同线程计时器中断。
原生增强器是同步短任务；不要执行网络请求、磁盘 I/O、等待主线程或重入 SDK。宿主异步预取业务数据，增强时读取有界缓存。
属性补丁默认预算 16384 bytes，可受现有插件预算配置约束；超限或异常时跳过本次增强，原事件继续走隐私和准入检查。它不是敏感数据脱敏的替代机制。
SDK 不提供任意第三方代码的进程级安全沙箱。插件只能来自受信、经审查的代码；名称与诊断不得放入身份值、Token 或原始业务数据。

5. 集成验证顺序

核对真实安装包、版本与可选依赖，使用标准 create。
检查配置、授权、Health 的阻断原因；绑定目标或提供 Host 信号。
触发一个确定动作，检查入队/过滤诊断和事件语义。一个指标作用域选择一个生产者，避免同一点击同时绑定两条路径。
flush 后核对本地队列与合法整批 ACK，再核对后端实际接收。Health、候选计数和 autoEvents 都不是 ACK。
在目标应用与接收环境中验证撤销授权、解绑、重启、异常与恢复。

旧配置迁移及组合优先级变化见迁移指南。

客户端能力总览 ​

1. 选择组件 ​

2. 第一方能力目录 ​

3. 选择接入路径 ​

Web 自动采集 ​

原生内置处理器和 UI 绑定 ​

自定义业务属性增强 ​

Web 注册 ​

Android Java 注册 ​

Android Kotlin 注册 ​

iOS Swift 注册 ​

宿主确认授权后，再触发事件 ​

4. 故障与成本边界 ​

5. 集成验证顺序 ​

客户端能力总览

1. 选择组件

2. 第一方能力目录

3. 选择接入路径

Web 自动采集

原生内置处理器和 UI 绑定

自定义业务属性增强

Web 注册

Android Java 注册

Android Kotlin 注册

iOS Swift 注册

宿主确认授权后，再触发事件

4. 故障与成本边界

5. 集成验证顺序