• Remove any existing @babel/plugin-transform-react-jsx plugin entry — it must not coexist with the preset-level jsxImportSource on babel-preset-expo.

Bare React Native (@react-native/babel-preset or metro-react-native-babel-preset)

For metro 0.72.0+ (React Native 0.71+), add @babel/plugin-transform-react-jsx with the Dynatrace importSource before BabelPluginDynatrace in the plugins array:

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
  ],
};

The required plugin order is:

1. @babel/plugin-transform-react-jsx (JSX runtime — first)
2. BabelPluginDynatrace (auto-instrumentation — before reanimated)
3. react-native-reanimated/plugin (must be absolutely last)

• If the project already has @babel/plugin-transform-react-jsx with importSource: '@dynatrace/react-native-plugin': no change needed.
• If a different importSource is set: replace it with '@dynatrace/react-native-plugin'.

After any Babel change, reset Metro cache on next build:

npx react-native start --reset-cache

Step 7 — Run npx instrumentDynatrace

npx instrumentDynatrace

This reads dynatrace.config.js and automatically configures Android build.gradle and iOS Info.plist. Must be re-run whenever dynatrace.config.js changes.

Common mistakes to flag and correct:

• Skipping this step after changing dynatrace.config.js
• Using react-native instrument-dynatrace — same effect but deprecated for RN 0.70+
• Manual edits to build.gradle or Info.plist — not needed, the script handles it

If android/ and ios/ folders exist but automatic plist discovery fails, pass explicit paths:

npx instrumentDynatrace plist=ios/YourApp/Info.plist

Expo only: If android/ and ios/ folders do not yet exist, run npx expo prebuild first, then re-run npx instrumentDynatrace.

Step 7a — Manual SDK startup (only if autoStart: false)

Skip this step if autoStart is true or absent in dynatrace.config.js — the SDK starts automatically.

Check dynatrace.config.js for autoStart: false in the react block. If present, the SDK will not start on its own and no data will be collected until Dynatrace.start() is called explicitly.

Native auto start must be disabled in the same file, and the native blocks must not carry applicationId / beaconUrl (on iOS, npx instrumentDynatrace fails if DTXApplicationID or DTXBeaconURL are present while DTXAutoStart is false):

• Android: replace the autoStart { ... } block with autoStart.enabled false and keep every other setting the app needs (userOptIn, sessionReplay.enabled true, agentBehavior.*) — the Gradle plugin still applies them at build time.
• iOS: the plugin's guidance is that DTXAutoStart = false is the only property for a manual startup; other iOS keys are not guaranteed to be used. Pass anything else (for example opt-in mode) at runtime through ConfigurationBuilder.

module.exports = {
  react: {
    autoStart: false,
    // ...
  },
  android: {
    config: `
      dynatrace {
        configurations {
          defaultConfig {
            autoStart.enabled false
            agentBehavior.startupLoadBalancing true
            agentBehavior.startupWithGrailEnabled true
            // keep userOptIn / sessionReplay.enabled here if they were set
          }
        }
      }
    `,
  },
  ios: {
    config: `
      <key>DTXAutoStart</key>
      <false/>
    `,
  },
};

Re-run npx instrumentDynatrace after changing these blocks.

Add the startup call at the top level of the app entry file (for example App.tsx or index.js). Any logic that depends on the SDK being ready goes after the 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

Replace <BEACON_URL> and <APPLICATION_ID> with the values for the target app (from the console's dynatrace.config.js download or the user's credentials).

Important: With manual startup, beaconUrl and applicationId come only from the ConfigurationBuilder call. If native auto start is not disabled as shown above, the runtime values are discarded and the config-file values are used. Other react options in dynatrace.config.js (for example lifecycle) remain the baseline for manual startup.

Opt-in mode with manual startup: ConfigurationBuilder has its own userOptIn setting that is passed to the native agent on start and defaults to false. If User Opt-In mode is on (Step 1, or switched on for Session Replay in Step 9), add .withUserOptIn(true) before .buildConfiguration() so the runtime value matches the config, and still make the applyUserPrivacyOptions(...) call in Step 10.

Tradeoff: Manual startup causes the SDK to miss the native application start event and any interactions that happen before start() is called. Use autoStart: true (the default) unless runtime credential injection is a hard requirement.

Step 8 — Enable navigation tracking

Check dynatrace.config.js for the react.navigation block and check package.json for @react-navigation/native.

If @react-navigation/native is present and navigation.enabled is not set to true, add it:

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

Then re-run npx instrumentDynatrace.

What this does: When enabled, the plugin hooks into React Navigation's NavigationContainer and detects route changes automatically. Each navigation event is reported to Dynatrace as a view change, with the current route represented as a URL-style path (e.g., /Home, /Home/Details). This populates the screen timeline in Dynatrace user sessions and associates all events with the currently active screen. This setting is enabled by default in the plugin's own config template.

If @react-navigation/native is not present: inform the user that automatic view tracking requires @react-navigation/native. They can use Dynatrace.startView("ScreenName") for manual view tracking instead.

Step 9 — Session Replay (optional)

Ask the user: "Do you want to enable Session Replay?" If they already said so, or @dynatrace/react-native-session-replay is already in package.json, treat it as yes. On no, continue to Step 10.

Read references/session-replay.md for the Grail flags, plugin version check, package install, Android config flag, SessionReplay.configure(...) call, masking, and console capability. Remember the answer — Step 10 needs it.

Session Replay requires userOptIn: true: the Android Gradle plugin fails the build if sessionReplay.enabled true is set without it. If the user chose Session Replay while userOptIn is false, references/session-replay.md (section 4) covers switching it on with the user's consent — Step 10 then becomes required.

Step 10 — Privacy options call (only if userOptIn: true)

Skip this step if userOptIn was not true after Steps 1, 2 and 9.

Read references/user-opt-in.md for the full guidance on DataCollectionLevel, crashReportingOptedIn, Session Replay consent, and placement options. Ask the user the questions defined there, then apply the call to the relevant file.

Step 11 — Post-setup summary

Confirm to the user what is active:

Enabled by default (when userOptIn is false or absent):

• ✅ Crash reporting
• ✅ User action tracking (Touchables, Buttons, Pressable, Switch)
• ✅ Network monitoring
• ✅ Error handler
• ✅ Auto-start

When userOptIn: true, all data collection — including crash reporting — is gated on the applyUserPrivacyOptions(...) call.

Configured during this setup:

• Privacy mode: [userOptIn: true — consent call added / opt-out (SDK default)]
• Navigation tracking: [react.navigation.enabled: true / manual via Dynatrace.startView()]
• Session Replay: [package added, SessionReplay.configure(...) added, Android sessionReplay.enabled true set, console capability confirmed, masking level chosen, screenRecordOptedIn set if opt-in / not enabled]

Step 12 — Verification

Read references/verification.md and show the user the verification checklist. If no data appears after 5 minutes, work through the troubleshooting steps in that file.

Reference Files

• references/config-js.md — Full dynatrace.config.js template with userOptIn, Session Replay and manual-startup conditional blocks
• references/user-opt-in.md — applyUserPrivacyOptions guidance, DataCollectionLevel options, Session Replay consent, placement options
• references/session-replay.md — Session Replay setup: Grail flags, plugin version, package, Android flag, configure, masking, console capability
• references/verification.md — Post-setup verification checklist and troubleshooting

External References

• @dynatrace/react-native-plugin on npm — package changelog, API docs, and latest version
• @dynatrace/react-native-session-replay on npm — Session Replay package, requirements, and changelog
• Dynatrace React Native Installation Docs — official setup guide