dt-setup-ios

Dynatrace iOS SDK 设置

此技能可在用户的 iOS 项目中设置 Dynatrace iOS SDK（OneAgent），从零开始直至发送第一个事件。此流程遵循 Dynatrace 文档中的官方设置步骤。

何时使用此技能

• 用户想要在其 iOS 应用中添加 Dynatrace 监控
• 用户要求集成、安装或设置 Dynatrace iOS SDK
• 用户想要使用 Dynatrace 为其 iOS 应用添加监控
• 用户粘贴了从 Experience Vitals 向导复制的设置提示词

预填充值

从 Experience Vitals 向导调用时，用户的消息中会包含一个带有预填配置值的代码围栏区块，标记为 dynatrace-ios-setup-config。示例：

```dynatrace-ios-setup-config
DTXApplicationID: ABC-123
DTXBeaconURL: https://example.dynatrace.com/mbeacon
Product: DynatraceSessionReplay
DTXUserOptIn: true
```

存在这些值时：

• 跳过第 2 步（收集应用标识密钥）——使用提供的 DTXApplicationID 和 DTXBeaconURL。
• 跳过第 3 步中的产品问题——使用提供的 Product 值 （Dynatrace 或 DynatraceSessionReplay）。
• 使用 DTXUserOptIn 判断是否在第 5 步中添加隐私选择加入代码。如果为 true，添加选择加入代码。如果为 false，跳过第 5 步。

其他所有步骤（先决条件、SPM 依赖项、创建 plist、导入、构建、验证）照常进行。

操作步骤

1. 检查先决条件

继续之前，主动验证每项先决条件。如果任何检查失败，请告知用户并停止。

a) Xcode MCP 服务可用 这是硬性要求。此技能使用 Xcode MCP 服务与 Xcode 项目交互（添加 SPM 依赖项、构建等）。验证能否使用 Xcode MCP 工具（例如 mcp_xcode_XcodeListWindows）。如果无法使用，请告知用户先安装并启用 Xcode MCP 服务，然后再继续。

b) iOS 部署目标 >= 12.0 Xcode MCP 服务无法访问 .pbxproj 文件（它是项目元数据，而非导航器文件）。请改用终端中的 grep：

grep 'IPHONEOS_DEPLOYMENT_TARGET' <path/to/project.pbxproj>

检查所有部署目标值是否均 >= 12.0。如果有任何值低于 12.0，请告知用户更新这些值。

c) Xcode 版本 >= 16.0 在终端中运行 xcodebuild -version 进行验证。如果版本低于 16.0，请告知用户更新 Xcode。

d) Ruby + xcodeproj gem 第 3 步中的 scripts/add_spm_dependency.rb 需要这些。请检查：

ruby -e 'require "xcodeproj"; puts Xcodeproj::VERSION'

如果检查失败，运行 gem install xcodeproj 并重试。

2. 收集应用标识密钥

如果用户的消息中包含 dynatrace-ios-setup-config 区块（参见 预填充值），从中提取 DTXApplicationID 和 DTXBeaconURL，然后跳至第 3 步。

否则，请向用户询问这两个必需值：

• DTXApplicationID — 应用的唯一标识符
• DTXBeaconURL — 信标端点 URL（例如，https://{environment}.dynatrace.com/mbeacon）

如果用户已在消息中提供这些值，请跳过询问。

如果用户没有这些值，或者不知道如何获取，请引导他们参阅官方设置文档：https://docs.dynatrace.com/docs/observe/digital-experience/new-rum-experience/mobile-frontends/ios/id-01-initial-setup

3. 将 OneAgent 添加到项目中（SPM 依赖）

通过 Swift Package Manager 添加 Dynatrace Swift Mobile SDK。

如果用户的消息中包含 dynatrace-ios-setup-config 代码块，并且其中有 Product 值，请直接使用该值。否则，询问用户想要哪种产品：

• Dynatrace — 用于自动检测移动应用的 OneAgent
• DynatraceSessionReplay — OneAgent + Session Replay 模块（崩溃时回放）

SPM 软件包 URL： https://github.com/Dynatrace/swift-mobile-sdk.git

运行随附的 Ruby 脚本 scripts/add_spm_dependency.rb。该脚本使用 xcodeproj gem 正确添加软件包引用、产品依赖项和 frameworks 构建文件条目，不会对 .pbxproj 进行字符串操作。

ruby ./scripts/add_spm_dependency.rb \
  <ProjectPath> \
  https://github.com/Dynatrace/swift-mobile-sdk.git \
  8.0.0 \
  <Product> \
  [TargetName]

• ProjectPath — 例如 ./MyApp.xcodeproj
• <Product> — Dynatrace 或 DynatraceSessionReplay（根据步骤 3 的选择）
• TargetName — 可选；默认为项目中的第一个应用目标

该脚本具有幂等性——运行两次不会产生任何变化。成功时会输出 OK: project saved。

如果脚本因任何原因失败（项目布局特殊、无法使用 Ruby），请改为引导用户通过 Xcode 手动操作：

1. 在 Xcode 中打开项目
2. File > Add Package Dependencies...
3. 输入 URL：https://github.com/Dynatrace/swift-mobile-sdk.git
4. 选择 Up to Next Major Version，版本为 8.0.0
5. 将所选库添加到应用目标
6. 点击 Add Package

脚本成功运行后（或用户确认已手动添加），继续执行步骤 4。

4. 创建 Dynatrace.plist 配置

使用 mcp_xcode_XcodeWrite 在应用的主源代码目录中创建新的 Dynatrace.plist 文件。这可确保该文件自动注册到 Xcode 项目中。

内容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>DTXApplicationID</key>
    <string>{USER_PROVIDED_APP_ID}</string>
    <key>DTXBeaconURL</key>
    <string>{USER_PROVIDED_BEACON_URL}</string>
    <key>DTXUserOptIn</key>
    {USER_OPT_IN_VALUE}
    <key>DTXStartupLoadBalancing</key>
    <true/>
    <key>DTXStartupWithGrailEnabled</key>
    <true/>
</dict>
</plist>

将 {USER_PROVIDED_APP_ID} 和 {USER_PROVIDED_BEACON_URL} 替换为步骤 2 中的实际值。 根据配置代码块中的 DTXUserOptIn 值，将 {USER_OPT_IN_VALUE} 替换为 <true/> 或 <false/>。如果未提供配置代码块，则默认为 <true/>。

• DTXUserOptIn — 为 true 时，Agent 启动后会关闭数据收集，必须通过隐私 API 明确选择加入（在步骤 5 中配置）。为 false 时，数据收集会立即开始，无需用户选择加入，并跳过步骤 5。
• DTXStartupLoadBalancing — 启动时启用集群节点间的负载均衡。
• DTXStartupWithGrailEnabled — 在收到集群配置前，于首次应用启动时在最新 Dynatrace 上启用 RUM。集群配置缓存后，此标志会被永久覆盖。

5. 添加用户选择加入隐私配置

使用 mcp_xcode_XcodeRead 读取应用的入口点文件，然后使用 mcp_xcode_XcodeUpdate 添加隐私配置代码，并附上 TODO 注释，提醒用户将代码移至适当位置（例如隐私设置屏幕）：

对于 SwiftUI 应用（@main App 结构体文件）： 在 App 结构体的 init() 方法中添加以下内容（如果不存在，则创建该方法）：

init() {
    // TODO: Move this privacy configuration to your app's privacy settings screen.
    // These settings are provided here for a quick start with capturing monitoring data.
    // In production, this should be driven by user consent (e.g., a privacy settings screen).
    let privacyConfig = Dynatrace.userPrivacyOptions()
    privacyConfig.dataCollectionLevel = .userBehavior
    privacyConfig.crashReportingOptedIn = true
    Dynatrace.applyUserPrivacyOptions(privacyConfig) { (successful) in
        // callback after privacy changed
    }
}

对于 UIKit 应用（AppDelegate）： 在 application(_:didFinishLaunchingWithOptions:) 中添加相同代码。

6. 添加 Dynatrace 导入语句

使用 mcp_xcode_XcodeUpdate 在应用入口点文件中添加 import Dynatrace。

对于 SwiftUI 应用： 添加到包含 @main App 结构体的文件中。

对于 UIKit 应用： 添加到 AppDelegate.swift 中。

7. 构建并运行

使用 Xcode MCP 服务构建项目：

• 使用 mcp_xcode_BuildProject 构建项目
• 如果构建成功，向用户报告成功
• 如果构建失败，显示构建错误并帮助用户解决

8. 验证安装

运行随附的验证脚本 scripts/verify-setup.sh。该脚本会依次检查构建输出、plist 值、模拟器启动和 Agent 启动，并使用 set -e，遇到错误时会立即失败并返回不同的退出码。

调用方式：

./scripts/verify-setup.sh <ProjectPath> <SchemeName> \
  <ExpectedAppID> <ExpectedBeaconURL> [ExpectedOptIn]

参数（从 Xcode 项目以及第 2/4 步中使用的值获取）：

• ProjectPath — 例如 ./MyApp.xcodeproj
• SchemeName — 运行 xcodebuild -list -project <ProjectPath> 查看可用的 scheme，然后选择正确的 App scheme（而不是测试或无关的 scheme）
• ExpectedAppID — 写入 Dynatrace.plist 的 DTXApplicationID 值
• ExpectedBeaconURL — 写入 Dynatrace.plist 的 DTXBeaconURL 值
• ExpectedOptIn — 可选；true 或 false。传入第 4 步使用的 DTXUserOptIn 值即可验证。省略此参数则跳过验证。

退出码：

Code	含义	操作
0	所有检查均通过；plist 值正确；已检测到 Agent 启动日志	报告成功
2	构建输出缺少 framework、缺少 plist，或 plist 值与预期不符	检查 SPM 链接、plist 目标成员资格或值是否错误 — stderr 会指出具体问题
3	模拟器启动、安装或运行失败	检查 stderr；如果 App bundle 已过期，请重新运行第 7 步
4	启动后未找到 Dynatrace Core 日志	确认入口点中包含 import Dynatrace；建议手动启动，并检查 Dynatrace 环境
5	log show 本身运行失败	模拟器状态问题；重启模拟器后重试

脚本会打印 === Phase N: ... === 标题，方便根据 stdout 排查部分失败。

验证后的指导

保持模拟器运行，并让 App 保持打开状态，以便用户与其交互并生成事件，这些事件会显示在其 Dynatrace 环境中。不要关闭模拟器。

验证成功后，告知用户：

• 模拟器正在运行 App — 要验证数据是否到达其 Dynatrace 环境，请执行以下操作：
  1. 与 App 交互：点击按钮、切换屏幕，以生成用户操作和事件
  2. 将 App 置于后台（按模拟器中的 Home 按钮），然后再将其切回前台 — 这会立即将会话数据刷新到 Dynatrace 集群
  3. 几分钟内，生成的事件就会显示在其 Dynatrace 环境中
• 查看数据：Experience Vitals > Overview > Mobile > 选择 frontend
• 也可以使用 DQL 在 Grail 中直接查询数据
• 如需了解高级配置选项，请参阅：https://docs.dynatrace.com/docs/observe/digital-experience/new-rum-experience/mobile-frontends/ios/id-03-configuration

重要说明

• 此 skill 仅涵盖 SPM 集成。不支持 CocoaPods 和手动集成 framework。
• 除非用户明确提出要求，否则不要添加额外的 DTX 配置键 — 默认设置已针对良好的初次体验进行了优化。
• 此设置的公开文档位于：https://docs.dynatrace.com/docs/observe/digital-experience/new-rum-experience/mobile-frontends/ios/id-01-initial-setup