# @bitdrift/react-native 中文文档

规范地址：https://npmcn.com/package/%40bitdrift/react-native/

版本：0\.15\.0
npm 元数据更新时间：2026-10-22T18:44:56.474Z
中文译文更新时间：2026-11-08T04:13:34.962Z
软件包许可：SEE LICENSE IN LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bitdrift/react-native
原文对照：https://npmcn.com/package/%40bitdrift/react-native/?lang=original
项目主页：https://github.com/bitdriftlabs/capture-es#readme
源码仓库：https://github.com/bitdriftlabs/capture-es

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：246 kB，90 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：expo \>=47\.0\.0，react \*，react-native \*
- 首次发布：2024-04-01T18:30:17.135Z
- 最新版本发布：2026-10-22T18:44:55.911Z
- 近 30 天下载量：59911（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：82（近 12 个月 47 个）

## 中文简介

react 原生的比特干ft集成

## 安装

```sh
npm install @bitdrift/react-native
```

也可以使用：`pnpm add @bitdrift/react-native`、`yarn add @bitdrift/react-native`、`bun add @bitdrift/react-native`

## README

# @ bitdrift/ react- native (英语)

react 原生的比特干ft集成

## 安装

```sh
npm install @bitdrift/react-native
```

## 使用量

### 博览

如果您正在使用 Expo 来构建您的 React 本地应用程序, 并且不想使用被弹出的工作流程, 您可以使用 `@bitdrift/react-native` 要初始化的软件包 在不同日志级别获取库和日志信息 。 请注意,这比理想的要晚于初始化了库,但仍应提供使用Capture的大部分好处.

```js
import {
  init,
  trace,
  debug,
  info,
  warn,
  error,
  isTracingActive,
  setEntityId,
  clearEntityId,
  startSpan,
  SpanResult,
  SessionStrategy,
} from '@bitdrift/react-native';

init('<api key>', SessionStrategy.Activity, {
  startResult: (result) => {
    console.log('Capture start result', result);
  },
  crashReporting: {
    enableNativeFatalIssues: true, // Enable native crash reporting (crashes, ANRs, etc.)
    UNSTABLE_enableJsErrors: true, // Enable JavaScript error reporting (fatal and non-fatal)
    UNSTABLE_onBeforeReportSend: (report) => {
      // Add your custom handling for report metadata.
      // Available fields: report.reportType, report.sessionId, report.details, report.reason, report.fields
    },
  },
});

info('Hello, World!');
setEntityId('user-123');
console.log('Tracing active?', isTracingActive());
clearEntityId();

const span = startSpan('loading_profile', 'info', { source: 'tap' });
// ... perform the work ...
span?.end(SpanResult.SUCCESS, { cached: false });
```

对于所有博览会的用法,请确保添加 `@bitdrift/react-native` 页:1 `plugins` 字段中 `app.json` 文档。 这有助于确保正确设置本地模块.

```json
{
  "expo": {
    "plugins": [
      "@bitdrift/react-native"
    ]
  }
}
```

仅限Android的WebView仪器注释 :

-   `UNSTABLE_webViewInstrumentation` 目前只影响Android应用构建.
-   在这个软件包中,自动设置只通过Expo配置插件/生成Android Gradle设置提供.
-   非Expo Android 应用程序仍然可以通过应用 Gradle 插件和配置 `bitdrift` 仪表挡.
-   它不影响iOS构建.
-   它不会自动配置非 Expo / 香草 React 原生Android 项目 .

#### 博览去

由于装入本地模块 `@bitdrift/react-native` 在 Expo Go 中不支持软件包.

### 反应原生/ 退出的博览会

使用每个平台找到的指令初始化 Capture 库 [这里](https://docs.bitdrift.io/sdk/quickstart#configuration)。 。 。 .

对于iOS,在 `didFinishLaunchingWithOptions` 在你身边 `AppDelegate.m` 文档.

```objective-c
-
(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

  [CAPLogger startWithAPIKey:@"<api key>" sessionStrategy: CAPSessionStrategy.fixed]];

  ...
```

对于Android,在 `onCreate` 在你身边 `MainApplication.kt` 文档.

```kotlin
  override fun onCreate() {
    super.onCreate()
    Capture.Logger.start(
      apiKey = "<api key>",
      sessionStrategy = SessionStrategy.Fixed()
    )
    ...
  }
```

要从您的 React Introduct app 添加自定义日志消息, 请从 导入日志级别函数 `@bitdrift/react-native` 软件包,并用它们记录所需日志级别的信息.

### 西班牙语

使用相匹配的起始和结束事件来测量操作 . `startSpan` 返回时 `null` 直到捕获被初始化。 结束每个起始间隔一次; 重复 `end` 电话被忽略.

```ts
import { startSpan, SpanResult } from '@bitdrift/react-native';

const parent = startSpan('load_profile', 'info', { profileId: '123' });
const child = startSpan('fetch_profile', 'debug', undefined, undefined, parent?.id);

// ... perform the request ...
child?.end(SpanResult.SUCCESS, { cacheHit: false });
parent?.end(SpanResult.SUCCESS);
```

`startTimeMs` 财务报告和审定财务报表 `endTimeMs` 是以毫秒计的可选 Unix 时间戳。 如果使用其中之一, 提供两者,这样Capture就可以计算和正确定位跨度.

## 配置选项

### 崩溃报告

这个 `crashReporting` 选项允许您配置崩溃和错误报告行为 :

```js
init('<api key>', SessionStrategy.Activity, {
  crashReporting: {
    enableNativeFatalIssues: true, // Enable native crash reporting (crashes, ANRs, etc.)
    UNSTABLE_enableJsErrors: true, // Enable JavaScript error reporting (fatal and non-fatal)
    UNSTABLE_onBeforeReportSend: (report) => {
      // Add your custom handling for report metadata.
      // Available fields: report.reportType, report.sessionId, report.details, report.reason, report.fields
    },
  }
});
```

-   `enableNativeFatalIssues`: 当 `true`,可以报告本地致命问题,包括坠机、ANRs(应用不回应)和其他重大错误。 默认为 `true`。 。 。 .
-   `UNSTABLE_enableJsErrors`: 当 `true`,允许通过 React Native 的全球错误处理器来报告 JavaScript 错误(无论是致命的还是非致命的). 抓取无处理的有堆积痕迹的例外. 这个特征是实验性的,在未来的释放中可能会有变化. 默认为 `false`。 。 。 .
-   `UNSTABLE_onBeforeReportSend`:在发送问题报告前打电话。 接收 `{ reportType, reason, details, sessionId, fields }`。 。 。 .

### 上一个运行信息

使用 `getPreviousRunInfo()` 检查上一个应用程序运行是否以致命终止而结束.

```ts
import {
  getPreviousRunInfo,
  init,
  SessionStrategy,
  type PreviousRunInfo,
} from '@bitdrift/react-native';

init('<api key>', SessionStrategy.Activity);

const previousRunInfo: PreviousRunInfo = getPreviousRunInfo();

if (previousRunInfo?.hasFatallyTerminated) {
  console.log('Previous run terminated fatally', previousRunInfo.terminationReason);
}
```

`PreviousRunInfo` 形状 :

```ts
type PreviousRunInfo = {
  hasFatallyTerminated: boolean;
  terminationReason?: string;
} | null;
```

-   此 API 是同步的 .
-   以后再打给你 `init(...)`。 。 。 .
-   Android:在API 30+(Android 11+)上可用;返回 `null` 在旧版本.
-   iOS 模拟器: 返回 `null` ; 使用物理设备进行验证.
-   `terminationReason` 目前在Android上有人居住. iOS 目前提供 `hasFatallyTerminated`。 。 。 .

### SDK 状态

使用 `getSdkStatus()` 以检查 SDK 当前初始化状态和最近的后端活动.

```ts
import { getSdkStatus, init, SessionStrategy, type SdkStatus } from '@bitdrift/react-native';

init('<api key>', SessionStrategy.Activity);

const sdkStatus: SdkStatus = getSdkStatus();
console.log(sdkStatus.initializationState);
```

`SdkStatus` 形状 :

```ts
type SdkStatus = {
  initializationState: 'notStarted' | 'loaded' | 'running' | 'disabled';
  lastHandshakeTimeMs?: number;
  lastConfigDeliveryTimeMs?: number;
};
```

-   此 API 是同步的 .
-   它可以叫在之前或之后 `init(...)`。 。 。 .
-   当捕获尚未开始时, `initializationState` 实值 `notStarted`。 。 。 .

### 启动结果调回

使用 `startResult` 以观察本地 SDK 启动是否成功.

```ts
import { init, SessionStrategy } from '@bitdrift/react-native';

init('<api key>', SessionStrategy.Activity, {
  startResult: (result) => {
    if (result.success) {
      console.log('Capture started successfully');
    } else {
      console.log('Capture failed to start', result.error);
    }
  },
});
```

`StartResult` 形状 :

```ts
type StartResult = {
  success: boolean;
  error?: string;
};
```

-   每一次最多引用一次回调 `init(...)` 电话.
-   这种回调是实验性的,可能会改变.

```js
import { trace, debug, info, warn, error } from '@bitdrift/react-native';

// Log at the desired log level using the different log level functions.

trace('Hello, World!');

debug('Hello, World!');

info('Hello, World!');

warn('Hello, World!');

error('Hello, World!');

// Optionally pass an Error object to automatically capture error details
try {
  // some code that might throw
} catch (err) {
  error('Failed to process request', err);
  // Or with additional fields
  error('Failed to process request', err, { userId: '123' });
}

```

### 特性旗跟踪

跟踪特性旗曝光以了解用户看到哪些变种:

```js
import { setFeatureFlagExposure } from '@bitdrift/react-native';

// Track string variant
setFeatureFlagExposure('dark_mode', 'enabled');
setFeatureFlagExposure('new_ui', 'variant_b');

// Track boolean variant
setFeatureFlagExposure('experimental_feature', true);
setFeatureFlagExposure('beta_mode', false);
```

### 实体识别

设置后端关联的实体标识符与设备标识符。 该值被散列储存,准确值从未被坚持.

```js
import { clearEntityId, setEntityId } from '@bitdrift/react-native';

setEntityId('user-123');
setEntityId('account-456');
clearEntityId();
```

### 追踪状态

使用 `isTracingActive()` 以同步检查痕量传播是否正在激活.

```ts
import { init, isTracingActive, SessionStrategy } from '@bitdrift/react-native';

init('<api key>', SessionStrategy.Activity);

const tracingActive = isTracingActive();
console.log('Tracing active?', tracingActive);
```

-   它回来了 `false` 当追踪未激活或SDK未运行时.

### 网络整合

网络请求的自动捕捉可视平台和正在使用的网络库的不同方式实现.

#### iOS系统

通过联署材料初始化时通过 `enableNetworkInstrumentation: true` 作为选择 `init`数字 :

```javascript
import { init, SessionStrategy } from '@bitdrift/react-native';

init('<api key>', sessionStrategy: SessionStrategy.Activity, {
  enableNetworkInstrumentation: true
});
```

如果初始化是通过本地的API进行,则尚未支持通过目标-C API实现此功能,如果对这一功能感兴趣,请联系.

#### 机器人

要启用自动在Android上的 OkHttp 仪器,请添加 `io.bitdrift.capture-plugin` 应用程序中的插件 `build.gradle` 文件 :

```gradle
plugins {
    id 'io.bitdrift.capture-plugin' version '<version>'
}
```

要找到要使用的版本,请使用React Introduct计划中正在使用的Caption SDK的同版本. 检查 `build.gradle` 文档中 `node_modules/@bitdrift/react-native/android` 正在使用的 Caption SDK 版本的目录 .

对于手动 Gradle 设置, 启用插件仪表 :

```gradle
bitdrift {
    instrumentation {
        automaticOkHttpInstrumentation = true
        // Optional. Defaults to PROXY when omitted.
        // okHttpInstrumentationType = OVERWRITE
    }
}
```

除此之外,插件寄存器还需要添加到 `pluginManagement` 块 `settings.gradle` 文件 :

```gradle
pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
        maven {
            url 'https://dl.bitdrift.io/sdk/android-maven'
            content {
                includeGroupByRegex "io\\.bitdrift.*"
            }
        }
    }
}
```

当使用 Expo 生成项目时,可以通过设置 `networkInstrumentation` 选项到 `true` 输入 `app.json` 文件 :

```json
{
  "expo": {
    "plugins": [
        [
          '@bitdrift/react-native',
          {
            networkInstrumentation: true,
          },
        ],
    ]
  }
}
```

当使用 Expo 插件时 `networkInstrumentation: true`,则Android Gradle插件和 `bitdrift { instrumentation { ... } }` 块自动生成.

### 网络视频集成

WebView 仪器从 `react-native-webview` 网页视图如页面浏览,网络请求,导航事件,Web Vitals,长任务,控制台日志,用户互动和出错等. 打电话 `init(...)` 在任何 WebView 安装之前.

#### iOS系统

通过通过启用每个 WebVew 的自动仪器 `UNSTABLE_enableWebViewInstrumentation: true` 改为 `init`数字 :

```ts
import { init, SessionStrategy } from '@bitdrift/react-native';

init('<api key>', SessionStrategy.Activity, {
  UNSTABLE_enableWebViewInstrumentation: true,
});
```

#### 机器人

`UNSTABLE_webViewInstrumentation` 用于Android应用程序构建.

对于由Expo生成的Android应用程序,启用构建时的WebView字节码仪表:

```json
{
  "expo": {
    "plugins": [
      [
        "@bitdrift/react-native",
        {
          "UNSTABLE_webViewInstrumentation": true
        }
      ]
    ]
  }
}
```

注释:

-   `UNSTABLE_webViewInstrumentation` 只影响Android应用构建. 在iOS上,使用 `UNSTABLE_enableWebViewInstrumentation` 内 `init`。 。 。 .
-   它不会自动被应用到"梵地拉 React Independent Android"外的"博览会"配置插件流出.
-   对于非Expo Android 应用程序,应用 Gradle 插件和 `bitdrift { instrumentation { automaticWebViewInstrumentation = true } }` 手动.

Android 插件模式可以配置 `okHttpInstrumentationType`数字 :

```json
{
  "expo": {
    "plugins": [
      [
        "@bitdrift/react-native",
        {
          "networkInstrumentation": true,
          "okHttpInstrumentationType": "OVERWRITE"
        }
      ]
    ]
  }
}
```

`okHttpInstrumentationType` 只有Android,对iOS没有影响.

-   `PROXY` (默认):保留现有 `EventListener.Factory` okHttp客户端的行为.
-   `OVERWRITE`:替换收听器厂并可以避免某些应用设置中的网络跨度重复.

如果您最近升级并开始看到Android上的重复,请设定 `okHttpInstrumentationType` 改为 `OVERWRITE`。 。 。 .

## 常见问题

### @bitdrift/react-native 是什么？

react 原生的比特干ft集成

### 如何安装 @bitdrift/react-native？

在项目目录运行 npm install @bitdrift/react-native，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\*）、react-native（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bitdrift/react-native 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bitdrift/react-native 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bitdrift/react-native 可以商用吗？

@bitdrift/react-native 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @bitdrift/react-native 的下载量有多少？

根据 npm 官方下载统计，@bitdrift/react-native 在 2026/10/08 – 2026/11/06 这 30 天内被下载 59,911 次，日均约 1,997 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bitdrift/react-native 还在维护吗？

最新版本 0\.15\.0 发布于 2026/10/23（16 天前）；至今共发布 82 个版本，其中过去 12 个月发布了 47 个；首次发布于 2024/04/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。