> ## 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.setUser` 设置的 `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       | 说明                                                           |
| ----------- | ------- | --------- | ------------------------------------------------------------ |
| 启动耗时        | 暂无      | 冷启动 / 热启动 | 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');

// 手动上报错误
DdRum.addError('payment failed', ErrorSource.SOURCE, stack);

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

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

## 采样与控制

| 配置                                                     | 默认值             | 说明                                  |
| ------------------------------------------------------ | --------------- | ----------------------------------- |
| `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`，并保留部署的路径前缀）