dt-obs-flutter

name	dt-obs-flutter
license	Apache-2.0
description	Integrate the Dynatrace Flutter Plugin into a Flutter project — dependency setup, config, SDK bootstrap, navigation tracking, and verification. Trigger: "add Dynatrace to Flutter", "Flutter plugin setup", "instrument Flutter app", "integrate Dynatrace Flutter", "mobile observability Flutter", "dynatrace_flutter_plugin". Do NOT use for: querying Flutter RUM data (use dt-obs-frontends), non-Flutter mobile setups, or Dynatrace server-side configuration.

Dynatrace Flutter Plugin Integration Skill

Prerequisites

• Flutter SDK installed and flutter available on PATH
• An existing Flutter project with a pubspec.yaml at the project root
• A Dynatrace environment with access to Experience Vitals (to obtain applicationId and beaconUrl, or to download dynatrace.config.yaml)
• Console access to Experience Vitals → Mobile to configure app settings (Data Privacy, Enablement and Cost Control)
• dart CLI available (comes with Flutter SDK; used to run the plugin configuration script)

Work through the steps below in order, interacting with the user at each decision point. Read actual project files before suggesting changes — do not assume the current state.

Step 1 — Check for existing dynatrace.config.yaml

Before asking the user anything, check whether dynatrace.config.yaml exists at the project root.

• File exists: Read it, show the applicationId and beaconUrl, and confirm they match the target environment. If correct, run the userOptIn check below and skip to Step 3.
• File does not exist: Proceed to Step 2.

userOptIn check:

Inspect the file for userOptIn (Android) and DTXUserOptIn (iOS).

• Present on both platforms: Trust the value as-is. If true, flag Step 7a. If false, skip Step 7a.
• Absent from either platform: Ask the user: "Do you have User Opt-In mode enabled or disabled?" (If unsure: Experience Vitals → Mobile → [Your App] → Settings → Data Privacy.) Add the missing value to the relevant platform(s), then flag Step 7a if the final value is true.

Step 2 — Obtain dynatrace.config.yaml (only if Step 1 found no file)

Ask the user which approach they prefer:

Option A — Download from console (recommended):

1. Open their Dynatrace environment
2. Navigate to: Experience Vitals → New Frontend → Mobile
3. Enter app name and choose Flutter as the platform
4. On the Select capability and settings screen, configure monitoring features (Crash reporting, user action monitoring, etc.). User action monitoring can be changed later via Experience Vitals → [App] → Settings → Enablement and Cost Control.
5. Download dynatrace.config.yaml and place it at the project root (same level as pubspec.yaml)

Once the file is in place, apply the userOptIn check from Step 1 and flag Step 7a if needed.

Option B — Provide credentials manually: Read references/config-yaml.md for the full template and conditional blocks. Collect all required values from the user before creating any files, then apply the userOptIn check and flag Step 7a if needed.

Step 3 — Add the dependency

Read pubspec.yaml first.

• Not present: Run:

  flutter pub add dynatrace_flutter_plugin
  

• Already under dependencies: No change — proceed to Step 4.
• Under dev_dependencies: Remove it from dev_dependencies, then run flutter pub add dynatrace_flutter_plugin. The plugin is required at runtime, including in release builds.

Step 4 — Fetch dependencies

If Step 3 ran flutter pub add, dependencies are already fetched — skip this step.

Otherwise run:

flutter pub get

Confirm success before continuing.

Step 5 — Run the Dynatrace configuration script

dart run dynatrace_flutter_plugin

This reads dynatrace.config.yaml and automatically configures Android Gradle and ios/Runner/Info.plist. No manual native file edits are needed.

Common mistakes to flag and correct:

• flutter pub run dynatrace_flutter_plugin — wrong, use dart run dynatrace_flutter_plugin
• Manual edits to build.gradle / build.gradle.kts or Info.plist — not needed

Step 6 — Bootstrap the SDK in main.dart

Read lib/main.dart. Replace runApp(...) with Dynatrace().start(...):

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

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

• Dynatrace().start() calls runApp internally — remove any separate runApp call
• WidgetsFlutterBinding.ensureInitialized() is not required by Dynatrace before start(), but keep it if your app needs it for other pre-start initialization (for example, plugin or platform setup)
• Do not await Dynatrace().start() itself; only use await for other app initialization that must complete before calling start()

Step 7 — Add navigation tracking

In the root MaterialApp or CupertinoApp, add DynatraceNavigationObserver() to navigatorObservers:

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

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

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

Skip this step if userOptIn was not set to true during Steps 1 or 2.

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

Step 8 — HTTP instrumentation (if applicable)

Check pubspec.yaml for the http package dependency. Separately, search the codebase for import 'dart:io' and HttpClient usages. If either is present, apply instrumentation:

Package	Instrumentation
http	Dynatrace().createHttpClient() — replace http.Client() at the construction site
dart:io HttpClient	Manual timing via Dynatrace().createWebRequestTiming(...) — no drop-in wrapper exists

createHttpClient() accepts an optional client: parameter to wrap an existing client instance. Find every http.Client() construction site in the project and replace it with Dynatrace().createHttpClient().

If none are present, note it for when network calls are added.

Step 9 — Post-setup summary

Confirm to the user what is active:

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

• ✅ Crash reporting
• ✅ User action tracking
• ✅ Network monitoring
• ✅ Lifecycle monitoring
• ✅ 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: [DynatraceNavigationObserver added]
• HTTP instrumentation: [applied / not applicable yet]

Step 10 — 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-yaml.md — Full dynatrace.config.yaml template with Grail and userOptIn conditional blocks
• references/user-opt-in.md — applyUserPrivacyOptions guidance, DataCollectionLevel options, placement options
• references/verification.md — Post-setup verification checklist and troubleshooting

External References

• dynatrace_flutter_plugin on pub.dev — package changelog, API docs, and latest version
• Dynatrace Flutter Installation Docs — initial setup docs