# Track Business SDK Documentation

> 面向当前公开交付平台的 SDK 接入文档。投递行为以对应版本说明和接收端配置为准。

## 文档目录

### 开始使用

- [快速接入](/integration/): 选择所用平台，完成安装、初始化、事件记录和接收验证。
- [AI 辅助接入](/integration/guides/ai-client-integration): 选择平台、SDK 版本和任务类型，下载对应 Skill，或复制任务文本供 AI 开发工具使用。
- [接入协作](/integration/guides/access-collaboration): 按以下步骤确认事件定义、完成 SDK 集成并验收接收结果。各平台安装步骤见快速接入。
- [平台与兼容性](/integration/reference/platform-compatibility): 选择 SDK 前，先核对目标系统、构建方式和所用包版本。安装步骤见各平台接入指南；功能范围见客户端能力总览。
- [主题索引](/integration/guides/): 首次接入请从快速接入开始，其他文档可按以下主题查找。

### 客户端 SDK

  - [快速接入](/integration/web/): AI 辅助接入 Web
  - [基础 API](/integration/web/api): const sdk = TrackBusinessSDK.create({ endpoint, projectKey });
  - [自动采集](/integration/web/autocapture): 按需启用页面浏览、文档活动状态和点击采集。点击采集只处理指定选择器范围内的元素；SDK 不读取表单输入值或 DOM 正文。
  - [插件](/integration/web/plugins): Web 插件需显式启用，可通过 `autocapture` 配置或 `plugins` 注册。按需要选择插件，避免在同一目标上重复记录点击或页面事件。
  - [隐私与安全](/integration/web/privacy-security): Web SDK 的数据处理范围和接入责任如下。隐私告知、授权方式及数据处理要求由接入方确定。Android 和 iOS 应用商店申报分别见 Google Play 数据安全和 App Store 隐私。
  - [React 与 Vue](/integration/web/frameworks/vue): `@track-business/sdk-react` 和 `@track-business/sdk-vue` 为 `@track-business/sdk-web` 提供框架适配。它们只负责框架 Context、Router、指令/Hoo
  - [快速接入](/integration/android/): AI 辅助接入 Android
  - [基础 API](/integration/android/api): val sdk = TrackBusinessSDK.createAsync(applicationContext, endpoint, projectKey)
  - [自动点击采集](/integration/android/autotrack): AutoTrack 是可选的实验能力。启用构建插件并安装运行时后，符合条件的传统 View 点击可生成 `$app_click`，无需为每个已覆盖的目标手动调用点击 API。采集仍受 SDK 授权与策略控制；它不代表覆盖所有控件或业务操作。
  - [Google Play 数据安全](/integration/android/google-play-data-safety): <span id="google-play-合规申报"></span>
  - [快速接入](/integration/ios/): AI 辅助接入 iOS
  - [基础 API](/integration/ios/api): let sdk = try TrackBusinessSDK.create(endpoint: endpoint, projectKey: projectKey)
  - [App Store 隐私](/integration/ios/app-store-privacy): 本文介绍 App Store 隐私清单和 Required Reason API 的核对方式。Android 申报见 Google Play 数据安全。
  - [React Native SDK](/integration/react-native/): AI 辅助接入 React Native
  - [Flutter SDK](/integration/flutter/): AI 辅助接入 Flutter
  - [身份与生命周期](/integration/guides/identity): SDK 在记录事件时保存当时的用户和会话信息。用户随后登录或退出，不会改变已记录事件的归属。
  - [授权与隐私](/integration/guides/consent): 按业务要求设置初始授权状态，并明确允许采集的事件和属性。SDK 提供技术控制；授权告知、同意记录及应用隐私申报由接入方负责。
  - [离线队列与可靠投递](/integration/guides/delivery): SDK 会暂存尚未确认的事件，在网络恢复或下次调度时重试。`track()` 返回仅表示调用已被处理，不代表事件已写入持久存储或被接收端接受。
  - [应用生命周期](/integration/guides/app-lifecycle): 页面隐藏或应用退后台时，SDK 会尝试发送待发事件。后台执行时间由浏览器或操作系统决定，不能保证立即送达；未确认事件会留在可用的本地队列中。
  - [位置快照](/integration/guides/location-snapshot): Web、iOS 和 Android 支持由宿主应用显式提供、仅用于单个事件的位置快照。SDK 不读取设备位置、不申请定位权限，也不会缓存坐标或自动为其他事件附加位置。
  - [设备标识扩展](/integration/guides/device-identity): 需要在事件中附带企业自有设备或风险信号时，可配置 Provider。它是可选能力，Web 和 Android 的标准创建入口支持注入；iOS 标准创建入口目前不支持。基础事件采集不依赖 Provider。
  - [原生 UI 集成](/integration/guides/native-ui-frameworks): 以下代码示意如何在已安装原生 SDK 与可选 UI 模块的宿主中绑定按钮和页面事件。按钮的 `action`、`targetTag` 应使用稳定业务标识；页面生命周期绑定按需使用。完整依赖和实例注入见下文。
  - [App 与 H5 集成](/integration/guides/hybrid): App 通过 WebView 加载 H5 页面时，可将 H5 事件交给原生 SDK 上传。接入方可选择独立的 H5 身份，或在可信页面关联 App 身份。

### 服务端 SDK

- [概览](/integration/server/): 服务端 SDK 用于记录业务后端确认的事件，例如订单状态变化、后台任务和第三方回调。当前公开接入文档和下载包提供 Java 与 Go SDK；各语言独立发版，版本以服务端下载页为准。
  - [快速接入](/integration/server/java/): AI 辅助接入 Java
  - [上报方式](/integration/server/java/delivery): 先在服务端 SDK 概览按事件风险选定路径，再使用本页的构造。安装、首条事件和 Spring 停机在Java 集成；`track` 与画像签名在Java 基础 API。
  - [基础 API](/integration/server/java/api): 以下示例使用已初始化的 `client`。安装见Java 集成，发送方式见上报方式，事件定义见服务端事件与用户操作。
  - [快速接入](/integration/server/go/): AI 辅助接入 Go
  - [上报方式](/integration/server/go/delivery): 先在服务端 SDK 概览按事件风险选定路径，再使用本页的构造。安装、首条事件和 Gin 备注在Go 集成；`Track` 与画像签名在Go 基础 API。
  - [基础 API](/integration/server/go/api): 以下示例使用已初始化的 `analytics`。安装见Go 集成，发送方式见上报方式，事件定义见服务端事件与用户操作。
  - [事件与用户操作](/integration/server/api): <span id="服务端操作语义"></span>
  - [身份与租户上下文](/integration/server/guides/identity-and-tenancy): 用户流程可能横跨 Web、移动应用和服务端。本文介绍登录时的匿名身份关联、服务端事件的客户端 Session 归属和 B2B 租户上下文。SDK 不负责用户认证，身份合并能力需由实际部署的数据平台提供。
  - [日志接入与交接](/integration/server/operations/logging): `LoggingConsumer` 将 Collector 网络请求替换为本地 JSON Lines 写入，由独立 LogAgent 负责后续交付。该方式依赖磁盘、Agent、清理和 ACK 运维协议，吞吐、延迟与故障恢复需在目标文件系统和

### 事件与属性参考

- [事件与属性字典](/integration/reference/events-and-properties): <PropertyDictionaryBrowser />
- [预置属性总表](/integration/reference/preset-properties): <PresetPropertyCatalog />

### 验证与排障

- [数据校验](/integration/guides/data-verification): 完成初始化后发送一条测试事件，并在接收端核对事件名称、属性和身份。`track()` 返回或队列为空，不代表接收端已确认。
- [常见问题](/integration/guides/troubleshooting): 先看 `getHealthSnapshot()` 的初始化、队列和最近错误状态，再按现象排查。需要核对事件是否真正送达时，按数据校验操作。

### 进阶集成与参考

  - [客户端能力总览](/integration/guides/client-plugins): <span id="客户端插件与能力接入"></span>
  - [自定义插件](/integration/web/plugins/custom): 通过 `TrackBusinessSDK.create({ plugins })` 注册插件。`start` 启动采集，`stop` 释放资源，`enrich` 为当前事件补充属性。插件生成的数据仍受授权、隐私规则和项目事件定义约束。
  - [B2B 多租户](/integration/guides/b2b-multitenant): 本文区分两种用途不同的上下文：客户端 `groupId` 用于记录用户当前所属的分析组织；服务端 `tenantId` 可用于表达由宿主认证状态确定的租户上下文。客户端传入的业务属性不能充当服务端鉴权或数据隔离依据。
  - [行业场景示例](/integration/guides/analytics-scenarios): 以下电商、B2B 和内容场景展示事件命名、属性与触发时机的设计方法。示例是可映射的业务模板，不是 SDK 全局预置属性或后端固定合同；接入方需根据业务事件定义、隐私要求和权威数据来源确定最终事件。
  - [事件接收协议](/integration/reference/server-ingestion): 本页供部署事件接收服务的团队核对请求、响应与重试规则。SDK 接入方只需配置 `endpoint` 和 `projectKey`；接收验证见数据校验。
  - [环境与项目凭据](/integration/guides/security): 创建 SDK 时，使用项目接入信息中对应环境的 `endpoint` 和 `projectKey`。测试与生产环境应分别配置。
  - [接入方责任](/integration/guides/tenant-responsibilities): 接入前确认项目配置、SDK 包和数据处理责任。安装及示例见快速接入，功能差异见平台与兼容性。
  - [版本与升级](/integration/guides/upgrade): 客户端和服务端 SDK 各自维护版本。客户端版本组合（Suite）记录配套的 Web、Android、iOS、React Native 和 Flutter 包；事件协议另有版本号。安装时以SDK 下载页所选版本及其包内说明为准。
  - [迁移指南](/integration/guides/migration): 本文帮助使用其他埋点 SDK 的团队规划迁移。接入前请核对身份、事件、Consent 和上传语义，再确定事件名及属性的映射关系。

## 完整公开上下文

- [llms-full.txt](/llms-full.txt): 按公开导航顺序拼接的 Markdown 技术文档。内容仍须以对应版本的 SDK、契约和能力矩阵为准。