React Native SDK 接入

React Native SDK 基于原生 iOS / Android SDK 封装，通过 @flashcatcloud/mobile-react-native 提供 RUM 能力。初始化后，SDK 会把应用中的视图、用户操作、网络请求、错误和崩溃事件上报到 Flashduty RUM，并使用 source: "react-native" 标识数据来源。

当前 SDK 版本为 0.1.x，支持 iOS 和 Android 平台（不支持 React Native Web）。SDK 提供两类 API 入口：DatadogProvider / DatadogProviderConfiguration（推荐，基于 React 组件的声明式初始化）和 DdSdkReactNative / DdSdkReactNativeConfiguration / DdRum（命令式 API，仍可用）。暂不支持 Session Replay；Logs 仅 Android 端生效，iOS 端为空操作。

前提条件

接入前，请先完成以下准备：

在 Flashduty 控制台创建一个类型为 React Native 的 RUM 应用，并获取 Application ID 和 Client Token
确认应用可以访问 https://browser.flashcat.cloud/api/v2/rum
React Native >= 0.63.4 < 1.0（新架构已在 0.76 上验证）；iOS 部署目标 ≥ 12.0，Android minSdkVersion ≥ 21
构建机可以访问 Maven Central 与 CocoaPods trunk：SDK 的原生依赖 cloud.flashcat:dd-sdk-android-*（Android）和 Flashcat* pods（iOS）会在构建时自动解析
在应用入口（index.js / App.tsx）尽早完成 SDK 初始化

安装 SDK

安装核心包，并按你使用的导航库安装对应的视图采集包。原生模块通过 autolinking 自动接入，iOS 端还需要执行 pod install。

npm install @flashcatcloud/mobile-react-native

# 视图采集：按导航库二选一
npm install @flashcatcloud/mobile-react-navigation          # react-navigation
npm install @flashcatcloud/mobile-react-native-navigation   # react-native-navigation (Wix)

# iOS
cd ios && pod install

请使用 0.1.1 或更高版本。0.1.0 的 Android source map 上传脚本会在缺少 FLASHCAT_API_KEY 时让 release 构建直接失败；0.1.1 起上传改为非阻塞，缺少 key 只打印警告并跳过上传。详见高级配置中的 Source map 上传。

配置 Metro（Debug ID）

用 withDatadogMetroConfig 包装 Metro 配置，让 release 构建产出的 bundle 与其 sourcemap 都带上 Debug ID——服务端据此把线上堆栈精确匹配到对应那一份 sourcemap。

metro.config.js

const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
const {withDatadogMetroConfig} = require('@flashcatcloud/mobile-react-native/metro');

module.exports = withDatadogMetroConfig(
  mergeConfig(getDefaultConfig(__dirname), {}),
);

Debug ID 建议配置，缺失时会退化匹配。 不配置 Metro 也能还原堆栈：构建日志会出现「No debugId found in packager sourcemap」，服务端退化为按 service + 版本匹配 sourcemap。但同一个版本先后上传过多份 sourcemap 时，退化匹配可能挑错那一份（例如同名 bundle 的多次数值变动），Debug ID 可精确锁定到唯一上传。

初始化 SDK

在应用入口尽早初始化，且只初始化一次。推荐使用 DatadogProvider 组件包裹应用根节点——它在初始化原生 SDK 之前先安装 JS 层插桩（XHR 代理），能捕获启动阶段的网络请求；命令式 DdSdkReactNative.initialize() 仍可用，但会丢失启动窗口内的资源采集。构造函数的三个布尔参数依次控制自动采集用户操作、网络请求和 JS 错误。

App.tsx

import {
  DatadogProvider,
  DatadogProviderConfiguration,
  TrackingConsent,
} from '@flashcatcloud/mobile-react-native';

const config = new DatadogProviderConfiguration(
  '<CLIENT_TOKEN>',
  'production',
  '<APPLICATION_ID>',
  true, // 自动采集用户操作（tap）
  true, // 自动采集 XHR / fetch 网络请求
  true, // 自动采集 JS 错误
  TrackingConsent.GRANTED,
);
config.site = 'CN';
config.serviceName = 'com.example.shopping'; // 建议设置：让 Android 与 iOS 归入同一个服务
config.nativeCrashReportEnabled = true; // 采集原生 Android / iOS 崩溃
config.sessionSamplingRate = 100;
config.firstPartyHosts = ['<YOUR_API_HOST>']; // 匹配的域名会注入链路追踪头

export default function App() {
  return (
    <DatadogProvider configuration={config}>
      {/* your app */}
    </DatadogProvider>
  );
}

建议显式设置 serviceName。 不设置时，Android 端默认取 applicationId，iOS 端默认取 bundle identifier。两个平台标识不同时，同一个应用会在控制台被拆成两个 service，错误列表、筛选和 source map 匹配也会分开。

请不要在客户端代码中使用服务端密钥。clientToken 只用于客户端 RUM 数据上报，applicationId 用于归属 RUM 应用数据。

私有化部署时，通过 customEndpoints 把各类数据指向你自己的上报地址：

config.customEndpoints = {
  rum: 'https://your-ingest.example.com/api/v2/rum',
  logs: 'https://your-ingest.example.com/api/v2/logs',
};

采集页面视图

SDK 不会自动识别路由，需要按你使用的导航库接入视图采集。

react-navigation
react-native-navigation (Wix)
手动管理

在导航容器就绪后开启采集，每次路由切换都会记录为一个 RUM 视图。

import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
import { DdRumReactNavigationTracking } from '@flashcatcloud/mobile-react-navigation';

function App() {
  const navigationRef = useNavigationContainerRef();
  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => {
        DdRumReactNavigationTracking.startTrackingViews(navigationRef.current);
      }}
    >
      {/* 你的页面 */}
    </NavigationContainer>
  );
}

同一时间只能跟踪一个 NavigationContainer；切换容器前需要传入原容器引用来停止采集：

DdRumReactNavigationTracking.stopTrackingViews(navigationRef.current);

startTrackingViews 的第二个参数可以重命名视图，返回 null 可忽略不需要采集的路由。如需使用此能力，请用以下调用替换上例 onReady 中的调用：

DdRumReactNavigationTracking.startTrackingViews(
  navigationRef.current,
  (route, trackedName) =>
    route.name === 'InternalDebug' ? null : `mobile/${trackedName}`,
);

谓词返回 null 只会跳过新视图，不会结束前一个 RUM 视图。被忽略页面上产生的后续事件可能仍归属于前一个视图；需要明确视图边界时，请改用手动视图管理。

在应用启动时调用一次即可：

import { DdRumReactNativeNavigationTracking } from '@flashcatcloud/mobile-react-native-navigation';

DdRumReactNativeNavigationTracking.startTracking(
  (_event, trackedName) =>
    trackedName === 'InternalDebug' ? null : `mobile/${trackedName}`,
);

不再需要自动采集时，调用 DdRumReactNativeNavigationTracking.stopTracking() 解除监听。

没有使用上述导航库时，可以手动开始和结束视图：

import { DdRum } from '@flashcatcloud/mobile-react-native';

DdRum.startView('checkout', 'Checkout');
// ...
DdRum.stopView('checkout');

采集用户操作

初始化时 trackInteractions 为 true，SDK 会自动把带 onPress 的组件点击记录为 action。默认使用组件的 accessibilityLabel 作为操作名；也可以通过 dd-action-name 属性指定：

<TouchableOpacity dd-action-name="Checkout" onPress={handleCheckout}>
  <Text>去结算</Text>
</TouchableOpacity>

你也可以手动记录一次操作：

import { DdRum, RumActionType } from '@flashcatcloud/mobile-react-native';

DdRum.addAction(RumActionType.TAP, 'Checkout');

采集网络请求

初始化时 trackResources 为 true，SDK 会拦截 JS 层的 XMLHttpRequest 与 fetch，把每次请求记录为 RUM resource（URL、方法、状态码、耗时）。

SDK 只能看到 经过 JavaScript 发出的请求。<Image> 等由原生网络栈加载的资源不会被采集，所有采集到的请求也一律记为 xhr 类型。因此控制台对 React Native 应用不展示「静态资源」相关面板，这是采集边界，不是数据缺失。详见数据收集。

如需把前端请求与后端链路关联，请配置 firstPartyHosts，SDK 会对命中的域名注入追踪头。详见高级配置。

关联用户信息

登录后设置当前用户，SDK 会把用户字段写入后续 RUM 事件的 usr 对象。请务必传入 id：iOS 端会忽略没有 id 的调用。

DdSdkReactNative.setUserInfo({
  id: 'user-1001',
  name: 'Alice',
  email: 'alice@example.com',
});

上报错误

初始化时 trackErrors 为 true，SDK 会自动采集未处理的 JS 异常；nativeCrashReportEnabled 为 true 时还会采集原生 Android / iOS 崩溃。你也可以手动上报捕获到的异常：

import { DdRum, ErrorSource } from '@flashcatcloud/mobile-react-native';

try {
  // ... 业务逻辑 ...
} catch (error) {
  DdRum.addError('Payment failed', ErrorSource.SOURCE, (error as Error).stack ?? '');
}

release 包的 JS 堆栈是压缩过的，需要上传 source map 才能还原到源码文件与行号。Android 可在 Gradle 构建中自动上传，iOS 通过 FlashCat CLI 上传；每次发布都会生成新的 bundle，需要重新上传对应的 source map。原生崩溃是另一套：需要上传 iOS 的 dSYM 与（开启混淆时）Android 的 mapping 文件。两者详见高级配置。

验证接入

完成接入后，可以按以下方式验证：

在初始化时临时设置 config.verbosity = SdkVerbosity.DEBUG，通过 Metro / Xcode / logcat 日志查看 SDK 上报行为
运行应用并触发页面切换、点击、网络请求或手动错误
在 Flashduty RUM 应用中筛选 source:react-native，确认出现 view、action、resource 或 error 事件
在控制台确认 Android 与 iOS 的数据都落在同一个 service 下

下一步

高级配置

配置采样率、隐私同意、事件过滤、追踪和 source map 上传。

兼容性

了解支持的平台、React Native 版本、伴生包和当前限制。

数据收集

查看 SDK 自动和手动采集的事件类型、性能指标与采集边界。

快速开始

分析看板

SDK 接入

性能监控

异常追踪

查看器

会话重放

最佳实践

其他

前提条件

安装 SDK

配置 Metro（Debug ID）

初始化 SDK

采集页面视图

采集用户操作

采集网络请求

关联用户信息

上报错误

验证接入

下一步

高级配置

兼容性

数据收集

​前提条件

​安装 SDK

​配置 Metro（Debug ID）

​初始化 SDK

​采集页面视图

​采集用户操作

​采集网络请求

​关联用户信息

​上报错误

​验证接入

​下一步

高级配置

兼容性

数据收集

前提条件

安装 SDK

配置 Metro（Debug ID）

初始化 SDK

采集页面视图

采集用户操作

采集网络请求

关联用户信息

上报错误

验证接入

下一步