dt-obs-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
```
文件
拥有Dynatrace环境，且可访问Experience Vitals（用于获取
```
applicationId
```
和
```
beaconUrl
```
，或下载
```
dynatrace.config.yaml
```
）
可通过控制台访问Experience Vitals → Mobile来配置应用设置（数据隐私、功能启用与成本控制）
可使用
```
dart
```
CLI（随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 → 新前端 → 移动
输入应用名称，并选择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 instrumentation（如适用）

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

的使用。如果存在其中任意一项，进行instrumentation：

包	Instrumentation方式
`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 instrumentation：[已配置 / 暂不适用]

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

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

dt-obs-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 instrumentation（如适用）

Step 9 — Post-setup summary

步骤9——设置后总结

Step 10 — Verification

步骤10——验证

Reference Files

参考文件

External References

外部参考

dt-obs-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 instrumentation（如适用）

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`
时执行）