bd-instrumentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

bitdrift Instrumentation

bitdrift 插桩集成

Guides integration of the bitdrift Capture SDK into mobile apps. The SDK logs everything locally on-device; the bitdrift control plane dynamically decides what to upload.

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

How this skill uses docs

本技能如何使用文档

Use $bd-docs to fetch live API details from docs.bitdrift.io at each step. The platform reference files indicate what to look up — $bd-docs handles the mechanics of discovery and fetching.

使用$bd-docs在每一步从docs.bitdrift.io获取实时API详情。平台参考文件指明需要查找的内容——$bd-docs负责处理发现和获取的具体机制。

Workflow summary

工作流程概述

Detect platform → Check if SDK is installed → Read platform reference → If new install: add dependency +

Logger.start()

→ Add instrumentation categories the user needs.

检测平台 → 检查SDK是否已安装 → 读取平台参考文档 → 若为全新安装：添加依赖 + 调用

Logger.start()

→ 添加用户所需的插桩分类。

Step 1 — Detect platform

步骤1 — 检测平台

Identify the target platform from the user's project:

Signal	Platform
`build.gradle` , `build.gradle.kts` , `.kt` , `.java` , `AndroidManifest.xml`	Android
`.xcodeproj` , `.xcworkspace` , `Package.swift` , `Podfile` , `.swift` , `.m` / `.h`	iOS
`package.json` with `react-native` , `metro.config.js` , `App.tsx` / `App.js`	React Native

If the project contains files for multiple platforms (e.g., both Android and React Native in a monorepo), ask the user which target to instrument.

从用户项目中识别目标平台：

标识文件	平台
`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

如果项目包含多平台文件（例如单体仓库中同时存在Android和React Native文件），请询问用户要为哪个目标平台进行插桩。

Step 2 — Determine SDK status

步骤2 — 确定SDK状态

Check whether the bitdrift Capture SDK is already installed by searching the project for:

Platform SDK already present if you find…

Android

Platform	SDK already present if you find…
Android	`io.bitdrift:capture` in `build.gradle` / `build.gradle.kts` , or `import io.bitdrift.capture` in source
iOS	`capture-ios` in `Package.swift` or `BitdriftCapture` in `Podfile` , or `import Capture` in source
React Native	`@bitdrift/react-native` in `package.json` , or `import { init } from '@bitdrift/react-native'` in source

io.bitdrift:capture

build.gradle

build.gradle.kts

, or

import io.bitdrift.capture

in source

iOS

capture-ios

Package.swift

BitdriftCapture

Podfile

, or

import Capture

in source

React Native

@bitdrift/react-native

package.json

, or

import { init } from '@bitdrift/react-native'

in source

通过在项目中搜索以下内容，检查bitdrift Capture SDK是否已安装：

平台若找到以下内容则表示SDK已存在

Android

平台	若找到以下内容则表示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'`

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'

Step 3 — Read the platform reference and proceed

步骤3 — 读取平台参考文档并继续

Read the platform reference file, then follow the appropriate path:

Platform	Reference file
Android (Kotlin/Java)	`references/android.md` in this skill directory
iOS (Swift/Objective-C)	`references/ios.md` in this skill directory
React Native	`references/react-native.md` in this skill directory

Each reference file has two sections:

New installation — Add the SDK dependency and call
```
Logger.start()
```
. Follow this when the SDK is not yet present. Once the SDK is running, proceed to the instrumentation categories below.
Instrumentation categories — Standalone enhancements (log forwarding, network monitoring, screen views, TTI, fields, spans, etc.). Each is independent — jump directly to whichever one the user needs. These apply whether the user just finished a new install or already had the SDK set up.

读取平台参考文件，然后遵循相应流程：

平台	参考文件
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的用户。

Validation checklist (all platforms)

验证清单（全平台）

When asked to validate an integration, check all items and produce a report with PASS/FAIL/WARNING per check, plus concrete code fixes for failures.

#	Check
1	SDK dependency present and up to date
2	Logger initialized early in app lifecycle
3	Session strategy configured
4	Network monitoring active
5	Screen tracking on every screen
6	TTI tracked
7	Crash reporter linked with session URL
8	Entity ID set after login via `setEntityID` / `setEntityId` (iOS/Android only; enables `bd entity` targeting)
8a	User identity fields set after login via `addField`
9	dSYM/ProGuard mapping upload configured (if applicable)

当需要验证集成情况时，检查所有项目并生成一份报告，包含每项检查的通过/失败/警告状态，以及针对失败项的具体代码修复方案。

序号	检查项
1	SDK依赖已存在且为最新版本
2	Logger在应用生命周期早期完成初始化
3	会话策略已配置
4	网络监控已激活
5	所有屏幕均已开启屏幕追踪
6	TTI已被追踪
7	崩溃报告工具已与会话URL关联
8	登录后通过 `setEntityID` / `setEntityId` 设置实体ID（仅iOS/Android；支持 `bd entity` 目标定位）
8a	登录后通过 `addField` 设置用户身份字段
9	已配置dSYM/ProGuard映射文件上传（如适用）