dt-obs-flutter

Dynatrace Flutter 插件集成技能

前置条件

• 已安装 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 — 从控制台下载（推荐）：

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 位于同一层级）

文件就位后，执行步骤 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。该插件是运行时必需的，包括发布版本。

步骤 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()；但如果应用需要它来进行其他启动前初始化（例如插件或平台设置），请保留
• 不要对 Dynatrace().start() 本身使用 await；只有在调用 start() 前必须完成的其他应用初始化才使用 await

第 7 步 — 添加导航跟踪

在根 MaterialApp 或 CupertinoApp 中，将 DynatraceNavigationObserver() 添加到 navigatorObservers：

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 — 已添加同意调用 / 选择退出（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 — 设置后验证清单和故障排查

外部参考

• dynatrace_flutter_plugin on pub.dev — 软件包更新日志、API 文档和最新版本
• Dynatrace Flutter 安装文档 — 初始设置文档