> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native SDK 数据收集

> 了解 React Native RUM SDK 采集的事件类型、性能指标、采集边界与上报行为

本文说明 React Native SDK 采集哪些数据、哪些数据**不在采集范围内**，以及如何控制采集范围。所有事件都写入 `source: "react-native"`。

## 事件类型

| 事件 | 触发方式 | 说明 |
| - | - | - |
| view | 导航采集包自动记录，或 `DdRum.startView` / `stopView` | 一次页面停留，记录停留时长、内部的 action / resource / error 数量，以及该视图期间的性能指标 |
| action | `trackInteractions` 自动采集 `onPress` 点击，或 `DdRum.addAction` | 用户交互（tap / scroll / swipe / custom），可关联 frustration 信号 |
| resource | `trackResources` 拦截 JS 的 `XMLHttpRequest` / `fetch`，或 `DdRum.startResource` / `stopResource` | 一次网络请求，记录 URL、方法、状态码、耗时 |
| error | 自动（未处理 JS 异常 / 原生崩溃）或 `DdRum.addError` | 错误与崩溃，含类型、消息、堆栈 |
| long task | 原生主线程默认开启（`nativeLongTaskThresholdMs`）；JS 线程需设置 `longTaskThresholdMs` | 超过阈值的线程阻塞 |

## 自动采集的上下文

每个事件会自动附带以下上下文（由原生层采集）：

* **应用信息**：`service`、`version`、`env`，以及 `application.id`
* **设备信息**：设备型号、操作系统与版本、屏幕尺寸
* **会话信息**：`session.id`，按 `sessionSamplingRate` 采样
* **连接信息**：网络类型（如可用）
* **用户信息**：通过 `DdSdkReactNative.setUserInfo` 设置的 `usr.id` / `usr.name` / `usr.email`
* **全局属性**：通过 `DdSdkReactNative.setAttributes` 设置的自定义字段

## 网络请求的采集边界

SDK 的资源采集只有一个入口：JavaScript 层的 `XMLHttpRequest` 代理（React Native 中 `fetch` 也基于它实现）。

| 请求来源 | 是否采集 | 记录类型 |
| - | - | - |
| 业务代码中的 `fetch` / `XMLHttpRequest` / axios 等 | 采集 | `xhr` |
| 用 `fetch` 下载图片等二进制内容 | 采集 | `xhr`（不按 Content-Type 区分） |
| `<Image source={{ uri }}>` 等由原生网络栈加载的资源 | **不采集** | — |
| 原生模块 / 第三方原生 SDK 自己发出的请求 | **不采集** | — |

<Note>
  因此 React Native 应用的资源数据里只有接口请求，没有图片、字体、脚本等静态资源。控制台对 React Native 应用**不展示静态资源面板**，这是按采集边界设计的，不代表数据丢失。
</Note>

## 性能数据

控制台会为 React Native 应用展示「性能」页。原生性能指标由封装的 Android / iOS SDK 采集，JS 线程帧率由 React Native SDK 额外采集：

| 指标 | Android | iOS | 说明 |
| - | - | - | - |
| 启动耗时 | 暂无 | 冷启动 / 热启动 | React Native Android 桥接层尚未补发启动事件，控制台对应卡片显示「暂无数据」 |
| 刷新率 | 支持 | 支持 | 原生 UI 线程的渲染帧率 |
| **JS 线程帧率** | 支持 | 支持 | React Native 特有，反映业务 JS 代码是否卡顿；控制台「性能」页展示 |
| CPU | 支持 | 支持 | 视图期间的 CPU 占用 |
| 内存 | 支持 | 支持 | 视图期间的内存使用 |
| 慢帧 / 冻结帧 | 支持 | 支持 | 视图期间的慢帧与冻结帧数量 |
| ANR | 支持 | — | 应用无响应；非致命 ANR 是否默认采集取决于 Android 版本，可用 `trackNonFatalAnrs` 覆盖 |
| App Hang | — | 支持 | 主线程卡顿；需设置 `appHangThreshold`，默认关闭 |

原生指标的采集频率由 `vitalsUpdateFrequency` 控制，默认 `VitalsUpdateFrequency.AVERAGE`；设为 `NEVER` 可关闭。

## Logs

`DdLogs.debug` / `info` / `warn` / `error` 会发送日志事件，不属于 RUM 事件。当前 **仅 Android 端会实际发送**，iOS 端为空操作。

## 手动埋点

除了自动采集，您可以手动记录事件与属性。

```typescript theme={null}
import { DdRum, DdSdkReactNative, ErrorSource, RumActionType } from '@flashcatcloud/mobile-react-native';

// 手动管理视图
DdRum.startView('checkout', 'Checkout');
DdRum.stopView('checkout');

// 手动记录操作
DdRum.addAction(RumActionType.TAP, 'pay_button');

// 手动记录网络请求
DdRum.startResource('req-1', 'GET', 'https://api.example.com/orders');
DdRum.stopResource('req-1', 200, 'xhr');

// 手动上报错误
const error = new Error('payment failed');
DdRum.addError(error.message, ErrorSource.SOURCE, error.stack ?? '');

// 附加全局属性（写入后续所有事件）
DdSdkReactNative.setAttributes({ tenant: 'acme' });

// 给当前视图追加自定义计时
DdRum.addTiming('first_order_rendered');
```

### 视图加载、会话与 Feature Flag

下列 API 用于补充视图加载状态、控制会话边界，以及把功能开关取值关联到当前 RUM 会话：

```typescript theme={null}
// 记录当前视图从 startView 到此刻的加载耗时；true 表示覆盖已有值
DdRum.addViewLoadingTime(false);

// 获取当前会话 ID；SDK 尚未初始化或会话不可用时返回 undefined
const sessionId = await DdRum.getCurrentSessionId();

// 关联当前会话中实际使用的 Feature Flag 取值
DdRum.addFeatureFlagEvaluation('checkout_redesign', 'variant-a');

// 结束当前会话；下一个 RUM 事件会进入新会话
await DdRum.stopSession();
```

## 采样与控制

| 配置 | 默认值 | 说明 |
| - | - | - |
| `sessionSamplingRate` | 100 | 会话采样率（百分比）；未命中的会话不产生 RUM 数据 |
| `resourceTracingSamplingRate` | 20 | resource 上分布式追踪的采样率 |
| `telemetrySampleRate` | 20 | SDK 自身遥测采样率 |
| `trackInteractions` / `trackResources` / `trackErrors` | 构造函数参数，默认 false | 是否自动采集操作 / 网络请求 / JS 错误 |
| `nativeCrashReportEnabled` | false | 是否采集原生崩溃 |
| `trackFrustrations` | true | 是否从用户操作生成 frustration 信号 |
| `trackBackgroundEvents` | false | 是否采集没有活跃视图时的事件 |
| `vitalsUpdateFrequency` | `AVERAGE` | 原生性能指标采集频率；`NEVER` 关闭 |
| `nativeLongTaskThresholdMs` | 200 | 原生主线程 long task 阈值；`0` / `false` 关闭 |
| `longTaskThresholdMs` | 0（关闭） | JS 线程 long task 阈值 |
| `trackNonFatalAnrs` | 平台默认 | 是否采集非致命 ANR |
| `appHangThreshold` | undefined | iOS App Hang 阈值（秒）；不设置表示关闭 |

## 数据脱敏

通过事件映射器可以在事件上报前修改或丢弃数据，用于脱敏或过滤噪声。详见 <a href="/zh/rum/sdk/react-native/advanced-config">高级配置</a>。

```typescript theme={null}
config.errorEventMapper = (event) => {
  // 返回 null 丢弃事件，或修改后返回
  if (event.message.includes('token=')) {
    return null;
  }
  return event;
};
```

## 上报行为

* SDK 在原生层做批量缓存，按 `uploadFrequency`、`batchSize` 与 `batchProcessingLevel` 分批上报
* 网络不可用时事件会持久化到本地，恢复后重试
* 上报地址默认为 `https://browser.flashcat.cloud/api/v2/rum`；私有化部署可通过 `customEndpoints.rum` 配置完整的 RUM intake URL（必须包含 `/api/v2/rum`，并保留部署的路径前缀）


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.