> ## 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 版本、伴生包和当前限制

本文说明 React Native SDK 的支持范围和当前限制，帮助你在接入前判断工程是否满足要求。

## 支持范围

| 项目           | 支持情况                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------- |
| SDK 版本       | `@flashcatcloud/mobile-react-native` 0.1.x（建议 ≥ 0.1.1）                                                        |
| 目标平台         | **iOS 和 Android**（不支持 React Native Web / macOS / Windows）                                                     |
| React Native | `>= 0.63.4 < 1.0`；新架构（Fabric / TurboModules）已在 0.76 上验证                                                       |
| iOS          | 部署目标 ≥ 12.0                                                                                                   |
| Android      | `minSdkVersion` ≥ 21                                                                                          |
| 原生依赖         | Android `cloud.flashcat:dd-sdk-android-*` 0.5.x（Maven Central）；iOS `Flashcat*` pods `~> 0.5`（CocoaPods trunk） |
| RUM 数据源      | 事件固定写入 `source: "react-native"`                                                                               |
| 实现方式         | 基于原生 iOS / Android SDK 封装的 React Native 原生模块                                                                  |
| 数据上报         | `POST /api/v2/rum`                                                                                            |

## 包和能力

| 包                            | npm 名                                           | 说明                                                                                    |
| ---------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- |
| RUM / Core / Crash           | `@flashcatcloud/mobile-react-native`            | 初始化、配置、RUM（view / action / resource / error / session）、原生崩溃采集、Android source map 上传脚本 |
| react-navigation 视图采集        | `@flashcatcloud/mobile-react-navigation`        | 把 `NavigationContainer` 的路由切换记录为视图                                                    |
| react-native-navigation 视图采集 | `@flashcatcloud/mobile-react-native-navigation` | 把 Wix `react-native-navigation`（`^7.5.0`）的页面切换记录为视图                                   |
| WebView 追踪                   | `@flashcatcloud/mobile-react-native-webview`    | 关联 `react-native-webview`（`>= 11.0.0`）内的 Browser RUM 数据                               |
| Source map 上传                | `@flashcatcloud/flashcat-cli`                   | `sourcemaps upload-react-native` 命令（≥ 0.4.0）                                          |

<Note>
  JavaScript 类名以 `Dd*` 开头（`DdSdkReactNative`、`DdSdkReactNativeConfiguration`、`DdRum`、`DdLogs`）。公有云请保持默认的 `site = 'CN'`；私有化部署请配置完整的 `customEndpoints`。
</Note>

## 支持的自动采集

| 能力          | 支持情况        | 说明                                                                               |
| ----------- | ----------- | -------------------------------------------------------------------------------- |
| 自动 view     | 支持（需伴生包）    | react-navigation 或 react-native-navigation 对应的采集包；其他导航方案用 `DdRum.startView` 手动管理 |
| 自动 action   | 支持          | `trackInteractions: true`，采集带 `onPress` 组件的点击                                    |
| 自动 resource | 支持（仅 JS 请求） | `trackResources: true`，拦截 `XMLHttpRequest` / `fetch`；一律记为 `xhr` 类型               |
| 未处理 JS 异常   | 支持          | `trackErrors: true`                                                              |
| 原生崩溃        | 支持          | 需 `nativeCrashReportEnabled: true`                                               |
| 分布式追踪       | 支持          | 对 `firstPartyHosts` 命中的域名注入 W3C `traceparent` 与 Datadog 追踪头                      |
| 原生移动端性能指标   | 支持          | CPU、内存、刷新率、慢帧 / 冻结帧；iOS 另有启动耗时（冷 / 热启动）                                          |
| JS 线程帧率     | 支持          | React Native 特有指标，控制台「性能」页展示                                                     |
| 卡顿检测        | 支持          | Android 支持 ANR；iOS 设置 `appHangThreshold` 后支持 App Hang                            |
| Long task   | 支持          | 原生主线程默认开启（200 ms）；JS 线程默认关闭，通过 `longTaskThresholdMs` 开启                          |
| WebView 追踪  | 支持（需伴生包）    | `@flashcatcloud/mobile-react-native-webview`                                     |

## 当前限制

| 限制             | 说明                                                                                     |
| -------------- | -------------------------------------------------------------------------------------- |
| Session Replay | 不支持                                                                                    |
| Logs           | `DdLogs` 仅 Android 端会发送日志；iOS 端为空操作，不发送任何数据                                            |
| 静态资源           | 只采集经 JavaScript 发出的请求；`<Image>` 等原生网络栈加载的图片、字体等**不会被采集**，控制台对 React Native 应用不展示静态资源面板 |
| resource 类型    | 所有采集到的请求一律记为 `xhr`，不按响应 Content-Type 区分                                                |
| Android 启动耗时   | Android 端暂无启动耗时（app launch）指标；iOS 端上报冷 / 热启动耗时                                         |
| 平台范围           | 仅 iOS / Android；React Native Web 不支持                                                   |
| 最低版本           | 建议 `0.1.1` 或更高；`0.1.0` 在缺少 `FLASHCAT_API_KEY` 时 Android release 构建会失败                  |

## 符号解析兼容性

React Native 的错误堆栈可能同时包含 JS 帧与原生帧，两者的还原方式不同：

| 栈帧类型                | 所需上传文件                      | 上传方式                                                         |
| ------------------- | --------------------------- | ------------------------------------------------------------ |
| JavaScript（Android） | release bundle 的 source map | `flashcat-sourcemaps.gradle` 随构建自动上传                         |
| JavaScript（iOS）     | release bundle 的 source map | `flashcat-cli sourcemaps upload-react-native --platform ios` |
| iOS Native          | dSYM                        | `flashcat-cli dsyms upload`；**总是需要**                         |
| Android Native（JVM） | mapping 文件                  | Flashcat Android Gradle 插件；**仅在开启混淆时需要**                     |
| Android Native（NDK） | NDK 符号文件                    | 同上，含原生代码时需要                                                  |

<Tip>
  JS source map 按 **service + 版本号 + bundle 文件名** 匹配，不依赖 Metro 的 debug ID 插件。请保持 SDK 的 `serviceName` / 版本号与上传参数一致，并把上传纳入每一次发布构建。

  原生崩溃还需要先把 `nativeCrashReportEnabled` 设为 `true`（默认关闭）。两类符号文件的完整说明见 <a href="/zh/rum/sdk/react-native/advanced-config">高级配置</a>。
</Tip>