在 React Native/Expo 项目中集成…

当需要为 React Native 或 Expo 应用接入 Dynatrace RUM 移动端监控（崩溃上报、用户行为、网络监控、导航追踪）时，按顺序完成依赖、Babel、原生配置与验证。

适用场景

解决思路

1. 先检查项目根目录是否已存在 dynatrace.config.js：若存在则读取并展示 applicationId 与 beaconUrl，确认与目标环境一致；若一致则做 userOptIn 检查并跳到 Step 3；若不存在则进入 Step 2。
2. userOptIn 检查：查看 Android 块的 userOptIn 与 iOS 块的 DTXUserOptIn。两者都存在则直接信任其值（为 true 则标记 Step 9，为 false 则跳过 Step 9）；任一缺失则询问用户是否启用了 User Opt-In 模式（可提示在 Experience Vitals → Mobile → [Your App] → Settings → Data Privacy 查看），补全缺失值，若最终为 true 则标记 Step 9。
3. 若没有 dynatrace.config.js，让用户选择获取方式。Option A（推荐）：在 Dynatrace 环境中进入 Experience Vitals → New Frontend → Mobile，输入应用名并选择 React Native 平台，在 Select capability and settings 页面配置监控功能（崩溃上报、用户行为监控等），下载 dynatrace.config.js 放到项目根目录（与 package.json 同级），然后执行 userOptIn 检查并按需标记 Step 9。
4. Option B：读取 references/config-js.md 获取完整模板与条件块，先向用户收集全部所需值再创建文件，然后执行 userOptIn 检查并按需标记 Step 9。
5. 安装插件：先读 package.json。若未包含则运行 npm install @dynatrace/react-native-plugin；若已在 dependencies 中则无需改动；若在 devDependencies 中则移除并运行 npm install @dynatrace/react-native-plugin（该插件在运行时包括 release 构建都需要）。注意 npm install 会按字母排序 dependencies，条目重排属正常现象。
6. iOS 平台（仅 macOS）：运行 cd ios && pod install && cd ..，确认成功后再继续；若缺少 CocoaPods 则先 gem install cocoapods。
7. 在 babel.config.js 中注册 Babel 插件：读取该文件，把 BabelPluginDynatrace 追加到 plugins 数组，且放在 react-native-reanimated/plugin 之前（reanimated 必须始终最后）。写法为 '@dynatrace/react-native-plugin/instrumentation/BabelPluginDynatrace'。若已包含该插件则跳过；若 dynatrace.config.js 中设置了 useLegacyJscodeshift: true 则跳过（Babel 插件已在内部应用）；若 metro.config.js 已配置 babelTransformerPath: '@dynatrace/react-native-plugin/lib/dynatrace-transformer'（旧版 Metro transformer 方案）则跳过本步与 Step 6。常见错误需纠正：把插件放进 presets 而非 plugins；把 BabelPluginDynatrace 放在 react-native-reanimated/plugin 之后。
8. 在 babel.config.js 中注册 JSX runtime，先判断项目使用的 preset。Expo（babel-preset-expo）：在 preset 本身设置 jsxImportSource，不要额外添加 @babel/plugin-transform-react-jsx（Expo preset 已拥有 JSX 转换，叠加第二个 JSX 插件会破坏插桩）。配置为 presets: [['babel-preset-expo', { jsxRuntime: 'automatic', jsxImportSource: '@dynatrace/react-native-plugin' }]]，plugins 中依次为 BabelPluginDynatrace 和最后的 react-native-reanimated/plugin。若已设置该 jsxImportSource 则无需改动；若设置了其他 jsxImportSource 则替换为 '@dynatrace/react-native-plugin'；并移除已有的 @babel/plugin-transform-react-jsx 条目。
9. 裸 React Native（@react-native/babel-preset 或 metro-react-native-babel-preset）：对 metro 0.72.0+（React Native 0.71+），在 plugins 数组中于 BabelPluginDynatrace 之前添加 @babel/plugin-transform-react-jsx 并设置 Dynatrace 的 importSource，即 ['@babel/plugin-transform-react-jsx', { runtime: 'automatic', importSource: '@dynatrace/react-native-plugin' }]。插件顺序必须为：1) @babel/plugin-transform-react-jsx（JSX runtime，最先）；2) BabelPluginDynatrace（自动插桩，在 reanimated 之前）；3) react-native-reanimated/plugin（必须绝对最后）。若已存在带该 importSource 的 @babel/plugin-transform-react-jsx 则无需改动；若 importSource 不同则替换为 '@dynatrace/react-native-plugin'。任何 Babel 改动后，下次构建需重置 Metro 缓存：npx react-native start --reset-cache。
10. 运行 npx instrumentDynatrace：它会读取 dynatrace.config.js 并自动配置 Android build.gradle 与 iOS Info.plist。每当 dynatrace.config.js 变化都必须重新运行。常见错误需纠正：改了 dynatrace.config.js 后跳过此步；使用已弃用的 react-native instrument-dynatrace（RN 0.70+ 已弃用）；手动编辑 build.gradle 或 Info.plist（脚本已处理，无需手动）。若 android/ 与 ios/ 存在但自动发现 plist 失败，显式传路径：npx instrumentDynatrace plist=ios/YourApp/Info.plist。Expo 专属：若 android/ 与 ios/ 尚不存在，先运行 npx expo prebuild，再重新运行 npx instrumentDynatrace。
11. 仅当 dynatrace.config.js 的 react 块中 autoStart: false 时执行手动启动（autoStart 为 true 或缺失则跳过，SDK 会自动启动）。在应用入口文件（如 App.tsx 或 index.js）顶层调用：import { Dynatrace, ConfigurationBuilder } from '@dynatrace/react-native-plugin'; await Dynatrace.start(new ConfigurationBuilder('<BEACON_URL>', '<APPLICATION_ID>').buildConfiguration()); 依赖 SDK 就绪的逻辑放在 await 之后。替换的 <BEACON_URL> 与 <APPLICATION_ID> 必须与 dynatrace.config.js 中完全一致，否则会上报到错误环境。注意：即使 autoStart: false，beaconUrl 与 applicationId 仍必须存在于 dynatrace.config.js（供 npx instrumentDynatrace 配置原生文件），运行时以 ConfigurationBuilder 传入的值为准。权衡：手动启动会错过原生应用启动事件及 start() 之前发生的交互，除非必须运行时注入凭据，否则用默认的 autoStart: true。
12. 启用导航追踪：检查 dynatrace.config.js 的 react.navigation 块与 package.json 中的 @react-navigation/native。若存在 @react-navigation/native 且 navigation.enabled 未设为 true，则在 react.navigation 中设置 enabled: true（需要 @react-navigation/native v5–v7），然后重新运行 npx instrumentDynatrace。启用后插件会挂接 React Navigation 的 NavigationContainer 自动检测路由变化，每次导航作为视图切换上报，当前路由以 URL 风格路径表示（如 /Home、/Home/Details），从而填充 Dynatrace 用户会话的屏幕时间线并把事件关联到当前活动屏幕；该设置默认在插件配置模板中启用。若不存在 @react-navigation/native，告知用户自动视图追踪需要它，可改用 Dynatrace.startView("ScreenName") 手动追踪。
13. 仅当 userOptIn 为 true 时执行隐私选项调用（Steps 1 或 2 中未设为 true 则跳过）。读取 references/user-opt-in.md 获取关于 DataCollectionLevel、crashReportingOptedIn 与放置位置的完整指引，按其中定义的问题询问用户，再把调用应用到相应文件。
14. 输出安装后总结：确认默认启用项（当 userOptIn 为 false 或缺失时）——崩溃上报、用户行为追踪（Touchables、Buttons、Pressable、Switch）、网络监控、错误处理器、自动启动；并说明当 userOptIn: true 时所有数据收集（含崩溃上报）都取决于 applyUserPrivacyOptions(...) 调用。列出本次配置项：隐私模式（userOptIn: true 已加同意调用 / opt-out 即 SDK 默认）、导航追踪（react.navigation.enabled: true / 通过 Dynatrace.startView() 手动）。
15. 验证：读取 references/verification.md 并向用户展示验证清单；若 5 分钟后仍无数据，按该文件中的排障步骤逐项排查。

适用边界 · 注意事项

• 不要用于查询 React Native RUM 数据（应使用 dt-obs-frontends）。
• 不要用于非 React Native 的移动端接入。
• 不要用于 Dynatrace 服务端配置。