dt-setup-flutter

用途

该技能用于把 Dynatrace Flutter 插件集成进一个已有的 Flutter 项目，覆盖从依赖安装、配置文件获取、SDK 启动引导、导航追踪、HTTP 埋点到集成后验证的完整流程。它按顺序引导操作，并在每个决策点与用户交互，强调先读取实际项目文件再提出修改，不假设项目当前状态。

前置条件

已安装 Flutter SDK，且 flutter 在 PATH 中可用。
存在一个 Flutter 项目，项目根目录有 pubspec.yaml。
有一个可访问 Experience Vitals 的 Dynatrace 环境，用于获取 applicationId 和 beaconUrl，或下载 dynatrace.config.yaml。
可访问 Experience Vitals → Mobile 控制台，用于配置应用设置（Data Privacy、Enablement and Cost Control）。
dart CLI 可用（随 Flutter SDK 提供，用于运行插件配置脚本）。

主要能力与使用方式

第 1 步：检查是否已有 dynatrace.config.yaml

先检查项目根目录是否存在 dynatrace.config.yaml。

文件存在：读取并展示 applicationId 和 beaconUrl，确认与目标环境一致。若正确，执行 userOptIn 检查并跳到第 3 步。
文件不存在：进入第 2 步。

userOptIn 检查：检查文件中的 userOptIn（Android）和 DTXUserOptIn（iOS）。两个平台都存在时按原值处理；若为 true 则标记第 7a 步，若为 false 则跳过第 7a 步。任一平台缺失时，询问用户是否启用了 User Opt-In 模式（不确定可查看 Experience Vitals → Mobile → [Your App] → Settings → Data Privacy），补全缺失值，若最终值为 true 则标记第 7a 步。

第 2 步：获取 dynatrace.config.yaml（仅当第 1 步未找到文件）

询问用户选择方式：

方式 A — 从控制台下载（推荐）：打开 Dynatrace 环境，进入 Experience Vitals → New Frontend → Mobile，输入应用名并选择 Flutter 平台；在 Select capability and settings 界面配置监控功能（崩溃报告、用户操作监控等），用户操作监控之后可通过 Experience Vitals → [App] → Settings → Enablement and Cost Control 修改；下载 dynatrace.config.yaml 并放到项目根目录（与 pubspec.yaml 同级）。文件就位后执行第 1 步的 userOptIn 检查，必要时标记第 7a 步。
方式 B — 手动提供凭据：阅读 references/config-yaml.md 获取完整模板和条件块，在创建任何文件前收集所有必需值，然后执行 userOptIn 检查，必要时标记第 7a 步。

第 3 步：添加依赖

先读取 pubspec.yaml。

未包含：运行 flutter pub add dynatrace_flutter_plugin。
已在 dependencies 下：无需改动，进入第 4 步。
在 dev_dependencies 下：从 dev_dependencies 移除，再运行 flutter pub add dynatrace_flutter_plugin。该插件在运行时必需，包括 release 构建。

第 4 步：拉取依赖

若第 3 步执行了 flutter pub add，依赖已拉取，跳过此步；否则运行 flutter pub get，确认成功后再继续。

第 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()，但若应用因其他启动前初始化需要它，可保留。不要 await Dynatrace().start() 本身；await 仅用于必须在调用 start() 前完成的其他应用初始化。

第 7 步：添加导航追踪

在根 MaterialApp 或 CupertinoApp 的 navigatorObservers 中加入 DynatraceNavigationObserver()：

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

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

第 7a 步：隐私选项调用（仅当 userOptIn: true）

若第 1 或第 2 步中 userOptIn 未设为 true，跳过此步。阅读 references/user-opt-in.md 获取 DataCollectionLevel、crashReportingOptedIn 和放置位置的完整指导，向用户提出其中定义的问题，然后把调用应用到相关文件。

第 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 — 已添加同意调用 / opt-out（SDK 默认））、导航追踪（已添加 DynatraceNavigationObserver）、HTTP 埋点（已应用 / 暂不适用）。

第 10 步：验证

阅读 references/verification.md 并向用户展示验证清单。若 5 分钟后仍无数据，按该文件中的故障排除步骤处理。

参考文件

references/config-yaml.md — 完整的 dynatrace.config.yaml 模板，含 Grail 和 userOptIn 条件块。
references/user-opt-in.md — applyUserPrivacyOptions 指导、DataCollectionLevel 选项、放置位置选项。
references/verification.md — 集成后验证清单与故障排除。

外部参考

pub.dev 上的 dynatrace_flutter_plugin — 包变更日志、API 文档和最新版本。
Dynatrace Flutter 安装文档 — 初始设置文档。

适用场景与限制

适用于已有 Flutter 项目需要接入 Dynatrace 监控的场景，尤其是需要按标准流程完成依赖、配置、启动引导、导航追踪和 HTTP 埋点的开发者。限制方面：需要可访问 Experience Vitals 的 Dynatrace 环境；部分步骤依赖用户提供凭据或控制台操作；HTTP 埋点对 dart:io HttpClient 没有可直接替换的包装器，只能手动计时；具体收费、价格、平台支持范围等资料未提供。