dt-setup-flutter

Dynatrace Flutter Plugin の統合スキル

前提条件

• Flutter SDK がインストールされ、flutter が PATH から利用できること
• プロジェクトのルートに pubspec.yaml がある既存の Flutter プロジェクト
• Experience Vitals にアクセスできる Dynatrace 環境（applicationId と beaconUrl の取得、または dynatrace.config.yaml のダウンロードに使用）
• Experience Vitals → Mobile にアクセスできるコンソール（アプリの設定（Data Privacy、Enablement and Cost Control）を構成するため）
• dart CLI を利用できること（Flutter SDK に付属。プラグインの構成スクリプトの実行に使用）

以下の手順を順番に進め、判断が必要な箇所ではその都度ユーザーに確認してください。変更を提案する前に実際のプロジェクトファイルを読み、現在の状態を決めつけないでください。

Step 1 — 既存の dynatrace.config.yaml を確認する

ユーザーに何かを尋ねる前に、プロジェクトのルートに dynatrace.config.yaml があるか確認します。

• ファイルがある場合： ファイルを読み込み、applicationId と beaconUrl を表示して、対象環境の値と一致していることを確認します。一致している場合は、以下の userOptIn チェックを実行して Step 3 に進みます。
• ファイルがない場合： Step 2 に進みます。

userOptIn チェック：

ファイル内の userOptIn（Android）と DTXUserOptIn（iOS）を確認します。

• 両方のプラットフォームに設定されている場合： 値はそのまま信頼します。true の場合は Step 7a の対象として記録します。false の場合は Step 7a をスキップします。
• いずれかのプラットフォームで設定されていない場合： ユーザーに次のように尋ねます。「User Opt-In モードは有効ですか、無効ですか？」（不明な場合：Experience Vitals → Mobile → [Your App] → Settings → Data Privacy。）不足している値を該当するプラットフォームに追加し、最終的な値が true の場合は Step 7a の対象として記録します。

Step 2 — dynatrace.config.yaml を取得する（Step 1 でファイルが見つからなかった場合のみ）

どちらの方法を希望するか、ユーザーに尋ねます。

Option A — コンソールからダウンロード（推奨）：

1. Dynatrace 環境を開きます
2. 次に移動します：Experience Vitals → New Frontend → Mobile
3. アプリ名を入力し、プラットフォームとして Flutter を選択します
4. Select capability and settings 画面で、監視機能（クラッシュレポート、ユーザーアクションの監視など）を設定します。ユーザーアクションの監視は、後から Experience Vitals → [App] → Settings → Enablement and Cost Control で変更できます。
5. dynatrace.config.yaml をダウンロードし、プロジェクトのルート（pubspec.yaml と同じ階層）に配置します

ファイルを配置したら、Step 1 の userOptIn チェックを適用し、必要に応じて Step 7a の対象として記録します。

Option B — 認証情報を手動で入力： 完全なテンプレートと条件付きブロックについては、references/config-yaml.md を読みます。ファイルを作成する前に、必要な値をすべてユーザーから収集し、その後 userOptIn チェックを適用して、必要に応じて Step 7a の対象として記録します。

Step 3 — 依存関係を追加する

まず pubspec.yaml を読みます。

• 存在しない場合： 次を実行します。

  flutter pub add dynatrace_flutter_plugin
  

• すでに dependencies にある場合： 変更せず Step 4 に進みます。
• dev_dependencies にある場合： dev_dependencies から削除してから、flutter pub add dynatrace_flutter_plugin を実行します。このプラグインは、リリースビルドを含め、実行時に必要です。

Step 4 — 依存関係を取得する

Step 3 で flutter pub add を実行した場合は、依存関係をすでに取得しているため、この手順をスキップします。

それ以外の場合は、次を実行します。

flutter pub get

続行する前に、成功したことを確認します。

Step 5 — Dynatrace 構成スクリプトを実行する

dart run dynatrace_flutter_plugin

このスクリプトは dynatrace.config.yaml を読み込み、Android Gradle と ios/Runner/Info.plist を自動的に構成します。ネイティブファイルを手動で編集する必要はありません。

よくある間違いとして、次を指摘して修正します。

• flutter pub run dynatrace_flutter_plugin — 誤りです。dart run dynatrace_flutter_plugin を使用します
• build.gradle / build.gradle.kts または Info.plist の手動編集 — 不要です

ステップ 6 — main.dart で SDK を初期化する

lib/main.dart を読み込みます。runApp(...) を Dynatrace().start(...) に置き換えます。

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';
import 'package:flutter/material.dart';

void main() {
  Dynatrace().start(const MyApp());
}

• Dynatrace().start() は内部で runApp を呼び出すため、個別の runApp 呼び出しは削除してください
• Dynatrace では start() の前に WidgetsFlutterBinding.ensureInitialized() を呼び出す必要はありません。ただし、プラグインやプラットフォームの設定など、アプリでほかの初期化処理が必要な場合は残してください
• Dynatrace().start() 自体に await を付けないでください。start() の呼び出し前に完了させる必要がある、ほかのアプリ初期化処理にのみ await を使用してください

ステップ 7 — ナビゲーションのトラッキングを追加する

ルートの MaterialApp または CupertinoApp の navigatorObservers に DynatraceNavigationObserver() を追加します。

MaterialApp(
  navigatorObservers: [DynatraceNavigationObserver()],
  ...
)

CupertinoApp(
  navigatorObservers: [DynatraceNavigationObserver()],
  ...
)

ステップ 7a — プライバシーオプションの呼び出し（userOptIn: true の場合のみ）

ステップ 1 または 2 で userOptIn を true に設定していない場合は、このステップをスキップしてください。

DataCollectionLevel、crashReportingOptedIn、配置オプションの詳細については、references/user-opt-in.md をお読みください。そこに定義されている質問をユーザーに確認してから、該当するファイルに呼び出しを適用します。

ステップ 8 — HTTP の計測（該当する場合）

pubspec.yaml で http パッケージへの依存関係を確認します。さらに、コードベース全体から import 'dart:io' と HttpClient の使用箇所を検索します。いずれかが見つかった場合は、計測を適用します。

パッケージ	計測
http	Dynatrace().createHttpClient() — インスタンスの生成箇所にある http.Client() を置き換えます
dart:io HttpClient	Dynatrace().createWebRequestTiming(...) による手動の計測 — そのまま置き換えられるラッパーはありません

createHttpClient() には省略可能な client: パラメーターがあり、既存のクライアントインスタンスをラップできます。プロジェクト内の http.Client() の生成箇所をすべて見つけ、Dynatrace().createHttpClient() に置き換えてください。

いずれも見つからない場合は、ネットワーク呼び出しを追加する際の対応事項として記録してください。

ステップ 9 — セットアップ後の概要

有効になっている項目をユーザーに確認します。

デフォルトで有効（userOptIn が false または未指定の場合）：

• ✅ クラッシュレポート
• ✅ ユーザーアクションのトラッキング
• ✅ ネットワークモニタリング
• ✅ ライフサイクルのモニタリング
• ✅ 自動起動

userOptIn: true の場合、クラッシュレポートを含むすべてのデータ収集は、applyUserPrivacyOptions(...) の呼び出しを条件として有効になります。

このセットアップで設定した項目：

• プライバシーモード：[userOptIn: true — 同意の呼び出しを追加済み／オプトアウト（SDK のデフォルト）]
• ナビゲーショントラッキング：[DynatraceNavigationObserver を追加済み]
• HTTP の計測：[適用済み／現時点では該当なし]

ステップ 10 — 検証

references/verification.md を読み込み、検証チェックリストをユーザーに提示します。5 分経ってもデータが表示されない場合は、そのファイルのトラブルシューティング手順に沿って確認します。

参照ファイル

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

外部リファレンス

• pub.dev の dynatrace_flutter_plugin — パッケージの変更履歴、API ドキュメント、最新バージョン
• Dynatrace Flutter インストールガイド — 初期セットアップのドキュメント