bd-instrumentation

bitdrift 埋点

介绍如何将 bitdrift Capture SDK 集成到移动应用中。SDK 会在设备本地记录所有内容；bitdrift 控制平面会动态决定上传哪些内容。

此技能如何使用文档

在每个步骤中，使用 bd-docs 从 docs.bitdrift.io 获取最新的 API 详情。平台参考文件会指出需要查阅哪些内容，bd-docs 负责发现和获取相关文档。

工作流概览

检测平台 → 检查是否已安装 SDK → 阅读平台参考文件 → 如果是全新安装：添加依赖项并调用 Logger.start() → 添加用户需要的埋点类别。

第 1 步 — 检测平台

根据用户的项目识别目标平台：

信号	平台
build.gradle、build.gradle.kts、.kt、.java、AndroidManifest.xml	Android
.xcodeproj、.xcworkspace、Package.swift、Podfile、.swift、.m/.h	iOS
包含 react-native 的 package.json、metro.config.js、App.tsx/App.js	React Native

如果项目包含多个平台的文件（例如，同一个 monorepo 中同时包含 Android 和 React Native），请询问用户要为哪个目标平台添加埋点。

第 2 步 — 确定 SDK 状态

搜索项目，检查是否已安装 bitdrift Capture SDK：

平台	找到以下内容即表示 SDK 已存在…
Android	build.gradle/build.gradle.kts 中的 io.bitdrift:capture，或源代码中的 import io.bitdrift.capture
iOS	Package.swift 中的 capture-ios 或 Podfile 中的 BitdriftCapture，或源代码中的 import Capture
React Native	package.json 中的 @bitdrift/react-native，或源代码中的 import { init } from '@bitdrift/react-native'

第 3 步 — 阅读平台参考文件并继续

阅读平台参考文件，然后按照相应路径操作：

平台	参考文件
Android（Kotlin/Java）	此技能目录中的 references/android.md
iOS（Swift/Objective-C）	此技能目录中的 references/ios.md
React Native	此技能目录中的 references/react-native.md

每个参考文件都包含两个部分：

• 全新安装 — 添加 SDK 依赖项并调用 Logger.start()。如果 SDK 尚未安装，请按此部分操作。SDK 运行后，继续查看下方的埋点类别。
• 埋点类别 — 可独立添加的增强功能（日志转发、网络监控、屏幕视图、TTI、字段、跨度等）。各项彼此独立，可直接跳转到用户需要的部分。无论用户刚完成全新安装，还是已经配置好 SDK，这些内容都适用。

验证清单（所有平台）

用户要求验证集成时，请检查所有项目，并为每项检查给出 PASS/FAIL/WARNING，同时提供失败项对应的具体代码修复方案。

#	检查项
1	SDK 依赖项已添加且为最新版本
2	在应用生命周期早期初始化 Logger
3	已配置会话策略
4	网络监控已启用
5	每个屏幕均已启用屏幕跟踪
6	已跟踪 TTI
7	崩溃报告工具已关联会话 URL
8	登录后通过 setEntityID / setEntityId 设置实体 ID（仅限 iOS/Android；可启用 bd entity 定向）
8a	登录后通过 addField 设置用户身份字段
9	已配置 dSYM/ProGuard 映射文件上传（如适用）