dt-obs-react-native

Dynatrace React Native 插件集成技能

前置条件

• 已安装 Node.js 16.0+ 和 npm，且可通过 PATH 访问
• 已有 React Native 项目（v0.68+）或 Expo 项目（v45+），项目根目录包含 package.json
• 存在 android/ 和 ios/ 平台文件夹（Expo 托管工作流需先运行 npx expo prebuild）
• 拥有可访问 Experience Vitals 的 Dynatrace 环境（用于获取 applicationId 和 beaconUrl，或下载 dynatrace.config.js）
• 可访问 Experience Vitals → Mobile 控制台，以配置应用设置（Data Privacy、Enablement 和 Cost Control）
• 用于 iOS 构建的 macOS 和 CocoaPods

请按顺序完成以下步骤，并在每个决策点与用户确认。提出更改建议前，先读取实际项目文件；不要臆测当前状态。

步骤 1 — 检查是否已有 dynatrace.config.js

在询问用户任何问题之前，检查项目根目录是否存在 dynatrace.config.js。

• **文件存在：**读取文件，显示 applicationId 和 beaconUrl，并确认它们与目标环境一致。如果正确，运行下方的 userOptIn 检查，然后跳至步骤 3（配置已存在，无需执行步骤 2）。
• **文件不存在：**继续步骤 2。

userOptIn 检查：

检查文件中的 userOptIn（Android 配置块）和 DTXUserOptIn（iOS 配置块）。

• **两个平台都存在：**按原值处理。如果为 true，标记步骤 9；如果为 false，跳过步骤 9。
• 任一平台缺失：询问用户：“是否启用了 User Opt-In 模式？”（如不确定，请前往：Experience Vitals → Mobile → [Your App] → Settings → Data Privacy。）将缺失的值添加到相关平台，然后在最终值为 true 时标记步骤 9。

步骤 2 — 获取 dynatrace.config.js（仅当步骤 1 中未找到文件时）

询问用户希望采用哪种方式：

选项 A — 从控制台下载（推荐）：

1. 打开其 Dynatrace 环境
2. 前往：Experience Vitals → New Frontend → Mobile
3. 输入应用名称，并选择 React Native 作为平台
4. 在 Select capability and settings 屏幕中，配置监控功能（崩溃报告、用户操作监控等）
5. 下载 dynatrace.config.js，并将其放在项目根目录（与 package.json 同级）

文件就位后，执行步骤 1 中的 userOptIn 检查，并在需要时标记步骤 9。

选项 B — 手动提供凭据： 阅读 references/config-js.md，了解完整模板和条件配置块。创建任何文件前，先向用户收集所有必需值，然后执行 userOptIn 检查，并在需要时标记步骤 9。

步骤 3 — 安装插件

先读取 package.json。

• **未安装：**运行：

  npm install @dynatrace/react-native-plugin
  

• **已列在 dependencies 中：**无需更改。
• **列在 devDependencies 中：**将其移除并运行 npm install @dynatrace/react-native-plugin。插件是运行时必需项，包括发布构建。

注意：npm install 会按字母顺序排列 package.json 中的 dependencies 对象。此步骤后现有条目的顺序可能发生变化，这是 npm 的预期行为，并非错误。

步骤 4 — 安装 iOS Pods（仅限 macOS）

如果使用 macOS 且目标平台为 iOS，请运行：

cd ios && pod install && cd ..

确认成功后再继续。必须安装 CocoaPods（如缺失，请运行 gem install cocoapods）。

步骤 5 — 在 babel.config.js 中注册 Babel 插件

读取 babel.config.js。将 BabelPluginDynatrace 添加到 plugins 数组中，如果存在 react-native-reanimated/plugin，则将其放在该插件之前（reanimated 必须始终位于最后）：

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    // ... existing plugins ...
    '@dynatrace/react-native-plugin/instrumentation/BabelPluginDynatrace',
    // react-native-reanimated/plugin goes here if present — must stay last
  ],
};

• 如果 plugins 数组中已包含 '@dynatrace/react-native-plugin/instrumentation/BabelPluginDynatrace'：跳过此步骤。
• 如果 dynatrace.config.js 中设置了 useLegacyJscodeshift: true：Babel 插件已在内部应用，跳过此步骤。
• 如果项目已在 metro.config.js 中配置 babelTransformerPath: '@dynatrace/react-native-plugin/lib/dynatrace-transformer'：这是旧版 Metro 转换器方案，自动插桩已处理；跳过此步骤和步骤 6。

需要标记并纠正的常见错误：

• 将插件放在 presets 中，而不是 plugins 中
• 将 BabelPluginDynatrace 放在 react-native-reanimated/plugin 之后——reanimated 必须始终是绝对最后一个插件

步骤 6 — 在 babel.config.js 中注册 JSX runtime

读取 babel.config.js，确定项目使用哪个 preset——这决定了如何注册 JSX runtime。

Expo（babel-preset-expo）

如果 presets 中出现 babel-preset-expo，请在 preset 本身上设置 jsxImportSource。不要单独添加 @babel/plugin-transform-react-jsx 插件——Expo 的 preset 已负责 JSX 转换，叠加第二个 JSX 插件会破坏插桩。

module.exports = function (api) {
  api.cache(true);
  return {
    presets: [
      ['babel-preset-expo', {
        jsxRuntime: 'automatic',
        jsxImportSource: '@dynatrace/react-native-plugin',
      }],
    ],
    plugins: [
      '@dynatrace/react-native-plugin/instrumentation/BabelPluginDynatrace',
      'react-native-reanimated/plugin',  // stays last
    ],
  };
};

• 如果 babel-preset-expo 已有 jsxImportSource: '@dynatrace/react-native-plugin'：无需更改。
• 如果已设置其他 jsxImportSource：将其替换为 '@dynatrace/react-native-plugin'。
• 移除现有的任何 @babel/plugin-transform-react-jsx 插件条目——它不得与 babel-preset-expo 上的 preset 级 jsxImportSource 同时存在。

Bare React Native（@react-native/babel-preset 或 metro-react-native-babel-preset）

对于 metro 0.72.0+（React Native 0.71+），在 plugins 数组中将带有 Dynatrace importSource 的 @babel/plugin-transform-react-jsx 添加到 BabelPluginDynatrace 之前：

module.exports = {
  presets: [
    ['module:@react-native/babel-preset', { unstable_transformProfile: 'hermes-stable' }],
  ],
  plugins: [
    ['@babel/plugin-transform-react-jsx', {
      runtime: 'automatic',
      importSource: '@dynatrace/react-native-plugin',
    }],
    '@dynatrace/react-native-plugin/instrumentation/BabelPluginDynatrace',
    'react-native-reanimated/plugin',  // stays last
  ],
};

所需的插件顺序为：

1. @babel/plugin-transform-react-jsx（JSX runtime — 第一个）
2. BabelPluginDynatrace（自动插桩 — 位于 reanimated 之前）
3. react-native-reanimated/plugin（必须绝对位于最后）

• 如果项目已有带有 importSource: '@dynatrace/react-native-plugin' 的 @babel/plugin-transform-react-jsx：无需更改。
• 如果已设置其他 importSource：将其替换为 '@dynatrace/react-native-plugin'。

更改 Babel 后，请在下次构建时重置 Metro 缓存：

npx react-native start --reset-cache

步骤 7 — 运行 npx instrumentDynatrace

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。

步骤 7a — 手动启动 SDK（仅在 autoStart: false 时）

如果 dynatrace.config.js 中的 autoStart 为 true 或未设置，请跳过此步骤——SDK 会自动启动。

检查 dynatrace.config.js 中的 react 块，确认是否设置了 autoStart: false。如果设置了，SDK 不会自行启动，并且在显式调用 Dynatrace.start() 之前不会收集任何数据。

在应用入口文件的顶层添加启动调用（例如 App.tsx 或 index.js）。依赖 SDK 就绪状态的逻辑应放在 await 之后：

import { Dynatrace, ConfigurationBuilder } from '@dynatrace/react-native-plugin';

await Dynatrace.start(
  new ConfigurationBuilder('<BEACON_URL>', '<APPLICATION_ID>').buildConfiguration()
);
// SDK is initialized — place any SDK-dependent logic here

将 <BEACON_URL> 和 <APPLICATION_ID> 替换为 dynatrace.config.js 中的完全相同的值——它们必须匹配，否则 SDK 会将数据报告到错误的环境。

**重要：**即使 autoStart: false，dynatrace.config.js 中仍必须包含 beaconUrl 和 applicationId（npx instrumentDynatrace 会用它们配置原生文件）。运行时传递给 ConfigurationBuilder 的值会生效——使用手动启动时，配置文件中的值会被忽略。

**权衡：**手动启动会导致 SDK 错过原生应用启动事件，以及在调用 start() 之前发生的所有交互。除非运行时注入凭据是硬性要求，否则请使用 autoStart: true（默认值）。

步骤 8 — 启用导航跟踪

检查 dynatrace.config.js 中的 react.navigation 块，并检查 package.json 中是否包含 @react-navigation/native。

如果存在 @react-navigation/native，且未将 navigation.enabled 设为 true，请添加：

module.exports = {
  react: {
    navigation: {
      enabled: true,  // requires @react-navigation/native v5–v7
    },
    // ...
  },
  // ...
};

然后重新运行 npx instrumentDynatrace。

**此设置的作用：**启用后，插件会接入 React Navigation 的 NavigationContainer，并自动检测路由变化。每个导航事件都会作为视图变化报告给 Dynatrace，当前路由会以 URL 风格的路径表示（例如 /Home、/Home/Details）。这会在 Dynatrace 用户会话中填充屏幕时间线，并将所有事件关联到当前活动屏幕。插件自带的配置模板默认启用此设置。

如果未安装 @react-navigation/native：请告知用户，自动视图跟踪需要 @react-navigation/native。用户也可以改用 Dynatrace.startView("ScreenName") 手动跟踪视图。

步骤 9 — 隐私选项调用（仅在 userOptIn: true 时）

如果步骤 1 或步骤 2 中未将 userOptIn 设为 true，请跳过此步骤。

阅读 references/user-opt-in.md，了解 DataCollectionLevel、crashReportingOptedIn 和调用位置选项的完整指南。向用户询问其中定义的问题，然后在相关文件中添加调用。

步骤 10 — 设置后摘要

向用户确认当前启用的功能：

默认启用（userOptIn 为 false 或未设置时）：

• ✅ 崩溃报告
• ✅ 用户操作跟踪（Touchables、Buttons、Pressable、Switch）
• ✅ 网络监控
• ✅ 错误处理器
• ✅ 自动启动

当 userOptIn: true 时，所有数据收集（包括崩溃报告）都必须通过调用 applyUserPrivacyOptions(...) 才会启用。

本次设置中配置的内容：

• 隐私模式：[userOptIn: true — 已添加同意调用 / 选择退出（SDK 默认值）]
• 导航跟踪：[react.navigation.enabled: true / 通过 Dynatrace.startView() 手动跟踪]

步骤 11 — 验证

阅读 references/verification.md，并向用户展示验证清单。如果 5 分钟后仍未显示任何数据，请按照该文件中的故障排除步骤进行排查。

参考文件

• references/config-js.md — 完整的 dynatrace.config.js 模板，包含 Grail 和 userOptIn 条件块
• references/user-opt-in.md — applyUserPrivacyOptions 指南、DataCollectionLevel 选项和调用位置选项
• references/verification.md — 设置后验证清单和故障排除

外部参考资料

• npm 上的 @dynatrace/react-native-plugin — 软件包更新日志、API 文档和最新版本
• Dynatrace React Native 安装文档 — 官方设置指南