dt-setup-react-native

Dynatrace React Native Plugin 統合スキル

前提条件

• PATH から利用できる Node.js 16.0+ と npm
• プロジェクトのルートに package.json がある既存の React Native プロジェクト（v0.68+）または Expo プロジェクト（v45+）
• android/ と ios/ のプラットフォームフォルダーが存在すること（Expo のマネージドワークフローでは、事前に npx expo prebuild が必要です）
• Experience Vitals にアクセスできる Dynatrace 環境（applicationId と beaconUrl の取得、または dynatrace.config.js のダウンロードに使用します）
• アプリ設定（データプライバシー、有効化、コスト管理）を構成するための Experience Vitals → Mobile へのコンソールアクセス
• iOS ビルド用の CocoaPods がインストールされた macOS

以下の手順を順に進め、各判断ポイントでユーザーとやり取りしてください。変更を提案する前に実際のプロジェクトファイルを読み取り、現在の状態を推測しないでください。

ステップ 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 の Pod をインストールする（macOS のみ）

macOS 上で iOS を対象とする場合は、次を実行します：

cd ios && pod install && cd ..

続行する前に、正常に完了したことを確認してください。CocoaPods がインストールされている必要があります（見つからない場合は gem install cocoapods を実行します）。

ステップ 5 — babel.config.js に Babel プラグインを登録する

babel.config.js を読み込みます。plugins 配列に BabelPluginDynatrace を追加します。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 をスキップします。

よくある間違いと修正点：

• プラグインを plugins ではなく presets に配置する
• BabelPluginDynatrace を react-native-reanimated/plugin の後に配置する — reanimated は必ず最後のプラグインにする必要があります

ステップ 6 — babel.config.js に JSX ランタイムを登録する

babel.config.js を読み込み、プロジェクトで使用しているプリセットを確認します。JSX ランタイムの登録方法は、使用するプリセットによって異なります。

Expo（babel-preset-expo）

presets に babel-preset-expo が含まれている場合は、jsxImportSource をプリセット自体に設定します。個別の @babel/plugin-transform-react-jsx プラグインは追加しないでください。Expo のプリセットが 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 のプリセットレベルの jsxImportSource と併用してはいけません。

Bare React Native（@react-native/babel-preset または metro-react-native-babel-preset）

metro 0.72.0+（React Native 0.71+）では、Dynatrace の importSource を指定して @babel/plugin-transform-react-jsx を追加し、plugins 配列で 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 ランタイム — 最初）
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 の場合でも、beaconUrl と applicationId は dynatrace.config.js に設定されている必要があります（ネイティブファイルの設定に 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 に設定されていない場合は、このステップをスキップしてください。

DataCollectionLevel、crashReportingOptedIn、および配置オプションの詳細なガイダンスについては、references/user-opt-in.md を読んでください。そこに定義されている質問をユーザーに尋ねたうえで、該当するファイルに呼び出しを適用してください。

ステップ 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 — Grail と userOptIn の条件付きブロックを含む、dynatrace.config.js の完全なテンプレート
• references/user-opt-in.md — applyUserPrivacyOptions のガイダンス、DataCollectionLevel のオプション、配置オプション
• references/verification.md — セットアップ後の検証チェックリストとトラブルシューティング

外部リファレンス

• npm の @dynatrace/react-native-plugin — パッケージの変更履歴、API ドキュメント、最新バージョン
• Dynatrace React Native インストールガイド — 公式セットアップガイド