在 Flutter 项目中集成 Dynatrace…

当需要给现有 Flutter 应用接入 Dynatrace Flutter 插件做移动端可观测性时，按顺序完成依赖安装、配置生成、SDK 启动、导航追踪与验证。

适用场景

解决思路

1. 先检查项目根目录是否已存在 dynatrace.config.yaml：若存在，读取并展示 applicationId 与 beaconUrl，确认与目标环境一致；若一致则执行 userOptIn 检查并跳到 Step 3；若不存在则进入 Step 2。
2. 执行 userOptIn 检查：查看文件中 Android 的 userOptIn 与 iOS 的 DTXUserOptIn。若两个平台都已存在，直接信任其值（为 true 则标记 Step 7a，为 false 则跳过 Step 7a）；若任一平台缺失，询问用户“是否启用了 User Opt-In 模式？”（不确定时查看 Experience Vitals → Mobile → [Your App] → Settings → Data Privacy），补全缺失值，若最终为 true 则标记 Step 7a。
3. 若 Step 1 未找到配置文件，询问用户选择获取方式。Option 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 同级），然后执行 userOptIn 检查并按需标记 Step 7a。
4. Option B：读取 references/config-yaml.md 获取完整模板与条件块，在创建任何文件前先向用户收集所有必需值，然后执行 userOptIn 检查并按需标记 Step 7a。
5. 添加依赖：先读取 pubspec.yaml。若未出现该依赖，运行 flutter pub add dynatrace_flutter_plugin；若已在 dependencies 下则无需改动，进入 Step 4；若在 dev_dependencies 下，先移除再运行 flutter pub add dynatrace_flutter_plugin（该插件在运行时包括 release 构建都需要）。
6. 拉取依赖：若 Step 3 已运行 flutter pub add 则跳过；否则运行 flutter pub get，确认成功后再继续。
7. 运行 Dynatrace 配置脚本：dart run dynatrace_flutter_plugin。它会读取 dynatrace.config.yaml 并自动配置 Android Gradle 与 ios/Runner/Info.plist，无需手动改原生文件。常见错误需纠正：不要用 flutter pub run dynatrace_flutter_plugin（应使用 dart run）；不要手动编辑 build.gradle / build.gradle.kts 或 Info.plist。
8. 在 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() 前完成的其他初始化。
9. 添加导航追踪：在根 MaterialApp 或 CupertinoApp 的 navigatorObservers 中加入 DynatraceNavigationObserver()，例如 MaterialApp(navigatorObservers: [DynatraceNavigationObserver()], ...) 或 CupertinoApp(navigatorObservers: [DynatraceNavigationObserver()], ...)。
10. Step 7a（仅当 userOptIn 为 true 时）：若 Step 1 或 Step 2 中 userOptIn 未设为 true 则跳过。读取 references/user-opt-in.md 获取 DataCollectionLevel、crashReportingOptedIn 与放置位置的完整指引，按其中定义的问题询问用户，再将调用应用到相关文件。
11. HTTP 埋点（如适用）：检查 pubspec.yaml 是否有 http 包依赖，并搜索代码库中的 import 'dart:io' 与 HttpClient 用法。若存在则埋点：http 包用 Dynatrace().createHttpClient() 替换构造处的 http.Client()（createHttpClient() 可接受可选 client: 参数包装已有客户端实例，需找到项目中每一处 http.Client() 构造点并替换）；dart:io HttpClient 用 Dynatrace().createWebRequestTiming(...) 手动计时（没有可直接替换的包装器）。若都不存在，记录下来以便后续添加网络调用时处理。
12. 输出安装后总结：向用户确认已启用的能力。默认启用（userOptIn 为 false 或缺失时）：崩溃上报、用户行为追踪、网络监控、生命周期监控、自动启动；当 userOptIn: true 时，所有数据采集（包括崩溃上报）都取决于 applyUserPrivacyOptions(...) 调用。同时列出本次配置项：隐私模式（userOptIn: true 已加同意调用 / opt-out 即 SDK 默认）、导航追踪（已添加 DynatraceNavigationObserver）、HTTP 埋点（已应用 / 暂不适用）。
13. 验证：读取 references/verification.md 并向用户展示验证清单；若 5 分钟后仍无数据，按该文件中的排查步骤逐项处理。

适用边界 · 注意事项

• 不要用于查询 Flutter RUM 数据（应使用 dt-obs-frontends）。
• 不要用于非 Flutter 的移动端接入。
• 不要用于 Dynatrace 服务端配置。