dt-setup-flutter

---
name: dt-setup-flutter
license: Apache-2.0
description: >-
  Integrate the Dynatrace Flutter Plugin into a Flutter project — dependency setup, config,
  SDK bootstrap, navigation tracking, Session Replay, and verification.
  Trigger: "add Dynatrace to Flutter", "Flutter plugin setup", "instrument Flutter app",
  "integrate Dynatrace Flutter", "mobile observability Flutter", "dynatrace_flutter_plugin",
  "Flutter session replay", "dynatrace_flutter_plugin_replay".
  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 9. If `false`, skip Step 9.
- **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 9 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
1. Navigate to: Experience Vitals → New Frontend → Mobile
1. Enter app name and choose **Flutter** as the platform
1. On the **Select capability and settings** screen, configure monitoring features (Crash reporting, user action monitoring, Session Replay, etc.). These settings can be changed later via Experience Vitals → [App] → Settings → Enablement and Cost Control.
1. 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 9 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 9 if needed.

## Step 3 — Add the dependency

Read `pubspec.yaml` first.

- **Not present:** Run:
  ```bash
  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:

```bash
flutter pub get
```

Confirm success before continuing.

## Step 5 — Run the Dynatrace configuration script

```bash
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(...)`:

```dart
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`:

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

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

## Step 8 — Session Replay (optional)

Ask the user: **"Do you want to enable Session Replay?"** If they already said so, or `dynatrace_flutter_plugin_replay` is already in `pubspec.yaml`, treat it as yes. On no, continue to Step 9.

Read `references/session-replay.md` for the Grail check, replay package, and console capability. Remember the answer — Step 9 needs it.

## Step 9 — 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`, Session Replay consent, and placement options. Ask the user the questions defined there, then apply the call to the relevant file.

## Step 10 — 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 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
- ✅ 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]
- Session Replay: [package added, console capability confirmed, screenRecordOptedIn set if opt-in / not enabled]
- HTTP instrumentation: [applied / not applicable yet]

## 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-yaml.md` — Full `dynatrace.config.yaml` template with Grail and userOptIn conditional blocks
- `references/user-opt-in.md` — `applyUserPrivacyOptions` guidance, `DataCollectionLevel` options, Session Replay consent, placement options
- `references/session-replay.md` — Session Replay setup: Grail check, replay package, console capability
- `references/verification.md` — Post-setup verification checklist and troubleshooting

## External References

- [dynatrace_flutter_plugin on pub.dev](https://pub.dev/packages/dynatrace_flutter_plugin) — package changelog, API docs, and latest version
- [Dynatrace Flutter Installation Docs](https://docs.dynatrace.com/docs/observe/digital-experience/new-rum-experience/mobile-frontends/flutter/id-01-initial-setup) — initial setup docs