dt-setup-flutter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dynatrace Flutter Plugin Integration Skill

Dynatrace Flutter Plugin集成技能

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.

已安装Flutter SDK，且
```
flutter
```
命令可在
```
PATH
```
中访问
已有一个Flutter项目，项目根目录下存在
```
pubspec.yaml
```
文件
拥有可访问Experience Vitals的Dynatrace环境（用于获取
```
applicationId
```
和
```
beaconUrl
```
，或下载
```
dynatrace.config.yaml
```
）
具备Experience Vitals → Mobile的控制台访问权限，用于配置应用设置（数据隐私、功能启用与成本控制）
可使用
```
dart
```
命令行工具（随Flutter SDK一同安装；用于运行插件配置脚本）

请按顺序完成以下步骤，在每个决策点与用户交互。在建议修改前，请先读取实际项目文件——不要假设当前状态。

Step 1 — Check for existing

dynatrace.config.yaml

步骤1 — 检查是否存在

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
```
.

在询问用户任何问题之前，先检查项目根目录下是否存在

dynatrace.config.yaml

。

文件已存在： 读取该文件，展示
```
applicationId
```
和
```
beaconUrl
```
，并确认它们与目标环境匹配。如果正确，执行下方的
```
userOptIn
```
检查，然后跳过步骤3。
文件不存在： 继续执行步骤2。

userOptIn
检查：

检查文件中是否存在Android的

userOptIn

和iOS的

DTXUserOptIn

配置。

两个平台均已配置： 保留现有值。如果值为
```
true
```
，标记步骤7a；如果值为
```
false
```
，跳过步骤7a。
任一平台未配置： 询问用户："您是否启用了用户选择加入模式？"（若不确定：请前往Experience Vitals → Mobile → [您的应用] → 设置 → 数据隐私。）为相关平台添加缺失的值，若最终值为
```
true
```
则标记步骤7a。

Step 2 — Obtain

dynatrace.config.yaml

(only if Step 1 found no file)

步骤2 — 获取

dynatrace.config.yaml

（仅当步骤1未找到文件时执行）

Ask the user which approach they prefer:

Option A — Download from console (recommended):

Open their Dynatrace environment
Navigate to: Experience Vitals → New Frontend → Mobile
Enter app name and choose Flutter as the platform
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.
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.

询问用户偏好的方式：

选项A — 从控制台下载（推荐）：

打开您的Dynatrace环境
导航至：Experience Vitals → New Frontend → Mobile
输入应用名称，选择Flutter作为平台
在选择功能与设置页面，配置监控功能（崩溃报告、用户行为监控等）。用户行为监控可后续通过Experience Vitals → [应用] → 设置 → 功能启用与成本控制修改。
下载
```
dynatrace.config.yaml
```
并放置在项目根目录（与
```
pubspec.yaml
```
同级）

文件就位后，执行步骤1中的

userOptIn

检查，必要时标记步骤7a。

选项B — 手动提供凭证： 阅读

references/config-yaml.md

获取完整模板和条件块。在创建任何文件前，先向用户收集所有必填值，然后执行

userOptIn

检查，必要时标记步骤7a。

Step 3 — Add the dependency

步骤3 — 添加依赖

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.

先读取

pubspec.yaml

文件。

依赖未存在： 执行命令：

bash

flutter pub add dynatrace_flutter_plugin

已在
dependencies
下：无需修改——继续执行步骤4。
在
dev_dependencies
下：将其从
```
dev_dependencies
```
中移除，然后执行
```
flutter pub add dynatrace_flutter_plugin
```
。该插件为运行时所需，包括发布版本构建。

Step 4 — Fetch dependencies

步骤4 — 获取依赖

If Step 3 ran

flutter pub add

, dependencies are already fetched — skip this step.

Otherwise run:

bash

flutter pub get

Confirm success before continuing.

如果步骤3执行了

flutter pub add

，则依赖已自动获取——跳过此步骤。

否则执行：

bash

flutter pub get

确认执行成功后再继续。

Step 5 — Run the Dynatrace configuration script

步骤5 — 运行Dynatrace配置脚本

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

bash

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
```
— 无需操作

Step 6 — Bootstrap the SDK in

main.dart

步骤6 — 在

main.dart

中初始化SDK

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()
```

读取

lib/main.dart

文件。将

runApp(...)

替换为

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()
```
内部会调用
```
runApp
```
— 移除单独的
```
runApp
```
调用
Dynatrace不要求在
```
start()
```
前调用
```
WidgetsFlutterBinding.ensureInitialized()
```
，但如果您的应用因其他初始化需求（如插件或平台设置）需要该调用，请保留
不要
```
await
```
```
Dynatrace().start()
```
本身；仅对必须在调用
```
start()
```
前完成的其他应用初始化操作使用
```
await
```

Step 7 — Add navigation tracking

步骤7 — 添加导航跟踪

In the root

MaterialApp

CupertinoApp

, add

DynatraceNavigationObserver()

navigatorObservers

dart

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

dart

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

在根

MaterialApp

或

CupertinoApp

中，将

DynatraceNavigationObserver()

添加到

navigatorObservers

：

dart

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

dart

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

Step 7a — Privacy options call (only if

userOptIn: true

)

步骤7a — 隐私选项调用（仅当

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.

如果步骤1或步骤2中
userOptIn
未设置为
true
，请跳过此步骤。

阅读

references/user-opt-in.md

获取关于

DataCollectionLevel

、

crashReportingOptedIn

和代码放置位置的完整指南。询问用户该文档中定义的问题，然后在相关文件中添加调用代码。

Step 8 — HTTP instrumentation (if applicable)

步骤8 — HTTP埋点（如适用）

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.

检查

pubspec.yaml

中是否存在

http

包依赖。另外，搜索代码库中是否有

import 'dart:io'

和

HttpClient

的使用。如果存在其中任一情况，执行埋点操作：

包	埋点方式
`http`	使用 `Dynatrace().createHttpClient()` — 在构造位置替换 `http.Client()`
`dart:io HttpClient`	通过 `Dynatrace().createWebRequestTiming(...)` 手动计时 — 无现成的封装可用

createHttpClient()

接受可选的

client:

参数，用于封装现有客户端实例。找到项目中所有

http.Client()

的构造位置，替换为

Dynatrace().createHttpClient()

。

如果均不存在，请记录下来，以便后续添加网络调用时使用。

Step 9 — Post-setup summary

步骤9 — 安装后总结

Confirm to the user what is active:

Enabled by default (when

userOptIn

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]

向用户确认已启用的功能：

默认启用（当

userOptIn

为

false

或未配置时）：

✅ 崩溃报告
✅ 用户行为跟踪
✅ 网络监控
✅ 生命周期监控
✅ 自动启动

当
userOptIn: true
时，所有数据收集（包括崩溃报告）均受
applyUserPrivacyOptions(...)
调用控制。

本次安装已配置：

隐私模式：[userOptIn: true — 已添加授权调用 / 选择退出（SDK默认值）]
导航跟踪：[已添加DynatraceNavigationObserver]
HTTP埋点：[已配置 / 暂不适用]

Step 10 — Verification

步骤10 — 验证

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.

阅读

references/verification.md

并向用户展示验证清单。如果5分钟后仍无数据显示，请按照该文档中的故障排除步骤操作。

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

```
references/config-yaml.md
```
— 完整的
```
dynatrace.config.yaml
```
模板，包含Grail和userOptIn条件块

references/user-opt-in.md

—

applyUserPrivacyOptions

指南、

DataCollectionLevel

选项、代码放置位置选项

```
references/verification.md
```
— 安装后验证清单及故障排除

External References

外部参考

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

dynatrace_flutter_plugin on pub.dev — 包更新日志、API文档及最新版本
Dynatrace Flutter安装文档 — 初始安装文档

dt-setup-flutter

Original

Translation

Dynatrace Flutter Plugin Integration Skill

Dynatrace Flutter Plugin集成技能

Prerequisites

前置条件

Step 1 — Check for existing
`dynatrace.config.yaml`

步骤1 — 检查是否存在
`dynatrace.config.yaml`

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

步骤2 — 获取
`dynatrace.config.yaml`
（仅当步骤1未找到文件时执行）

Step 3 — Add the dependency

步骤3 — 添加依赖

Step 4 — Fetch dependencies

步骤4 — 获取依赖

Step 5 — Run the Dynatrace configuration script

步骤5 — 运行Dynatrace配置脚本

Step 6 — Bootstrap the SDK in
`main.dart`

步骤6 — 在
`main.dart`
中初始化SDK

Step 7 — Add navigation tracking

步骤7 — 添加导航跟踪

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

步骤7a — 隐私选项调用（仅当
`userOptIn: true`
时执行）

Step 8 — HTTP instrumentation (if applicable)

步骤8 — HTTP埋点（如适用）

Step 9 — Post-setup summary

步骤9 — 安装后总结

Step 10 — Verification

步骤10 — 验证

Reference Files

参考文件

External References

外部参考

dt-setup-flutter

Original

Translation

Dynatrace Flutter Plugin Integration Skill

Dynatrace Flutter Plugin集成技能

Prerequisites

前置条件

Step 1 — Check for existing dynatrace.config.yaml

步骤1 — 检查是否存在dynatrace.config.yaml

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

步骤2 — 获取dynatrace.config.yaml（仅当步骤1未找到文件时执行）

Step 3 — Add the dependency

步骤3 — 添加依赖

Step 4 — Fetch dependencies

步骤4 — 获取依赖

Step 5 — Run the Dynatrace configuration script

步骤5 — 运行Dynatrace配置脚本

Step 6 — Bootstrap the SDK in main.dart

步骤6 — 在main.dart中初始化SDK

Step 7 — Add navigation tracking

步骤7 — 添加导航跟踪

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

步骤7a — 隐私选项调用（仅当userOptIn: true时执行）

Step 8 — HTTP instrumentation (if applicable)

步骤8 — HTTP埋点（如适用）

Step 9 — Post-setup summary

步骤9 — 安装后总结

Step 10 — Verification

步骤10 — 验证

Reference Files

参考文件

External References

外部参考

Step 1 — Check for existing
`dynatrace.config.yaml`

步骤1 — 检查是否存在
`dynatrace.config.yaml`

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

步骤2 — 获取
`dynatrace.config.yaml`
（仅当步骤1未找到文件时执行）

Step 6 — Bootstrap the SDK in
`main.dart`

步骤6 — 在
`main.dart`
中初始化SDK

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

步骤7a — 隐私选项调用（仅当
`userOptIn: true`
时执行）