Back to Details

dt-obs-ios

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dynatrace iOS SDK Setup

Dynatrace iOS SDK 设置

This skill sets up the Dynatrace iOS SDK (OneAgent) in the user's iOS project — from zero to first event. It follows the official setup flow from the Dynatrace documentation.
此技能可在用户的iOS项目中完成Dynatrace iOS SDK（OneAgent）的设置——从零基础到生成首个监控事件。流程遵循Dynatrace 官方文档中的官方设置步骤。

When to use this skill

何时使用此技能

  • The user wants to add Dynatrace monitoring to their iOS app
  • The user asks to integrate, install, or set up the Dynatrace iOS SDK
  • The user wants to instrument their iOS app with Dynatrace
  • The user pastes a setup prompt copied from the Experience Vitals wizard
  • 用户希望为其iOS应用添加Dynatrace监控
  • 用户要求集成、安装或设置Dynatrace iOS SDK
  • 用户希望为其iOS应用接入Dynatrace埋点
  • 用户粘贴了从Experience Vitals向导复制的设置提示

Pre-filled values

预填充值

When invoked from the Experience Vitals wizard, the user's message will contain pre-filled configuration values in a fenced block labeled 
dynatrace-ios-setup-config
. Example:
text
```dynatrace-ios-setup-config
DTXApplicationID: ABC-123
DTXBeaconURL: https://example.dynatrace.com/mbeacon
Product: DynatraceSessionReplay
DTXUserOptIn: true
```
When these values are present:
  • Skip step 2 (Collect application identification keys) — use the provided 
    DTXApplicationID
    and 
    DTXBeaconURL
    .
  • Skip the product question in step 3 — use the provided 
    Product
    value (
    Dynatrace
    or 
    DynatraceSessionReplay
    ).
  • Use 
    DTXUserOptIn
     to determine whether to add the privacy opt-in code in step 5. If 
    true
    , add the opt-in code. If 
    false
    , skip step 5.
All other steps (prerequisites, SPM dependency, plist creation, import, build, verify) proceed as normal.
当从Experience Vitals向导调用此技能时，用户的消息中会包含一个标记为
dynatrace-ios-setup-config
的代码块，其中包含预填充的配置值。示例：
text
```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文件创建、导入语句添加、构建、验证）均正常执行。

Procedure

操作步骤

1. Check prerequisites

1. 检查前置条件

Actively verify each prerequisite before proceeding. If any check fails, inform the user and stop.
a) Xcode MCP server is available This is a hard requirement. The skill uses the Xcode MCP server to interact with the Xcode project (adding SPM dependencies, building, etc.). Verify that Xcode MCP tools are accessible (e.g., 
mcp_xcode_XcodeListWindows
). If not available, tell the user to install and enable the Xcode MCP server before proceeding.
b) iOS deployment target >= 12.0 The 
.pbxproj
file is not accessible through the Xcode MCP server (it's project metadata, not a navigator file). Use 
grep
in the terminal instead:
bash
grep 'IPHONEOS_DEPLOYMENT_TARGET' <path/to/project.pbxproj>
Check that all deployment target values are >= 12.0. If any are below 12.0, tell the user to update them.
c) Xcode version >= 16.0 Run 
xcodebuild -version
in the terminal to verify. If below 16.0, tell the user to update Xcode.
d) Ruby + 
xcodeproj
gem Needed by scripts/add_spm_dependency.rb in step 3. Check:
bash
ruby -e 'require "xcodeproj"; puts Xcodeproj::VERSION'
If it fails, run 
gem install xcodeproj
and retry.
在继续操作前主动验证每个前置条件。如果任何检查失败，告知用户并停止操作。
a) Xcode MCP服务器可用 这是硬性要求。此技能使用Xcode MCP服务器与Xcode项目交互（添加SPM依赖项、构建等）。验证Xcode MCP工具是否可访问（例如
mcp_xcode_XcodeListWindows
）。如果不可用，告知用户先安装并启用Xcode MCP服务器，然后再继续。
b) iOS部署目标 >= 12.0 Xcode MCP服务器无法访问
.pbxproj
文件（它是项目元数据，而非导航器文件）。改用终端中的
grep
命令：
bash
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脚本需要此环境。检查：
bash
ruby -e 'require "xcodeproj"; puts Xcodeproj::VERSION'
如果检查失败，运行
gem install xcodeproj
并重试。

2. Collect application identification keys

2. 收集应用标识密钥

If the user's message contains a 
dynatrace-ios-setup-config
block (see Pre-filled values), extract 
DTXApplicationID
and 
DTXBeaconURL
from there and skip to step 3.
Otherwise, ask the user for the two required values:
  • DTXApplicationID — the application's unique identifier
  • DTXBeaconURL — the beacon endpoint URL (e.g., 
    https://{environment}.dynatrace.com/mbeacon
    )
If the user already provided these values in their message, skip asking.
If the user doesn't have these values or doesn't know how to get them, refer them to the official setup documentation: https://docs.dynatrace.com/docs/observe/digital-experience/new-rum-experience/mobile-frontends/ios/id-01-initial-setup
如果用户的消息中包含
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. Add OneAgent to the project (SPM dependency)

3. 向项目添加OneAgent（SPM依赖项）

Add the Dynatrace Swift Mobile SDK via Swift Package Manager.
If the user's message contains a 
dynatrace-ios-setup-config
block with a 
Product
value, use that directly. Otherwise, ask the user which product they want:
  • Dynatrace — OneAgent for automatic mobile app instrumentation
  • DynatraceSessionReplay — OneAgent + Session Replay module (replay on crash)
SPM package URL: 
https://github.com/Dynatrace/swift-mobile-sdk.git
Run the bundled Ruby script scripts/add_spm_dependency.rb. It uses the 
xcodeproj
gem to add the package reference, product dependency, and frameworks build-file entry correctly — no string manipulation of 
.pbxproj
.
bash
ruby ./scripts/add_spm_dependency.rb \
  <ProjectPath> \
  https://github.com/Dynatrace/swift-mobile-sdk.git \
  8.0.0 \
  <Product> \
  [TargetName]
  • ProjectPath
    — e.g. 
    ./MyApp.xcodeproj
  • <Product>
    — 
    Dynatrace
    or 
    DynatraceSessionReplay
    (from step 3 choice)
  • TargetName
    — optional; defaults to the first application target in the project
The script is idempotent — running it twice is a no-op. Prints 
OK: project saved
on success.
If the script fails for any reason (unusual project layout, Ruby unavailable), fall back to guiding the user through Xcode manually:
  1. Open the project in Xcode
  2. File > Add Package Dependencies...
  3. Enter URL: 
    https://github.com/Dynatrace/swift-mobile-sdk.git
  4. Up to Next Major Version from 
    8.0.0
  5. Add the chosen library to the app target
  6. Click Add Package
After the script succeeds (or the user confirms manual addition), proceed to step 4.
通过Swift Package Manager添加Dynatrace Swift Mobile SDK。
如果用户的消息中包含带有
Product
值的
dynatrace-ios-setup-config
代码块，直接使用该值。否则，询问用户想要的产品类型：
  • Dynatrace —— 用于自动移动应用埋点的OneAgent
  • DynatraceSessionReplay —— OneAgent + 会话重放模块（崩溃时重放会话）
SPM包URL: 
https://github.com/Dynatrace/swift-mobile-sdk.git
运行捆绑的Ruby脚本scripts/add_spm_dependency.rb。它使用
xcodeproj
gem正确添加包引用、产品依赖项和框架构建文件条目——无需手动修改
.pbxproj
字符串。
bash
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. 文件 > 添加包依赖...
  3. 输入URL: 
    https://github.com/Dynatrace/swift-mobile-sdk.git
  4. 选择
    8.0.0
    之后的最新大版本
  5. 将所选库添加到应用目标
  6. 点击添加包
脚本成功运行（或用户确认手动添加完成）后，继续步骤4。

4. Create Dynatrace.plist configuration

4. 创建Dynatrace.plist配置文件

Use 
mcp_xcode_XcodeWrite
to create a new 
Dynatrace.plist
file in the app's main source directory. This ensures the file is automatically registered in the Xcode project.
Content:
text
<?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>
Replace 
{USER_PROVIDED_APP_ID}
and 
{USER_PROVIDED_BEACON_URL}
with the actual values from step 2. Replace 
{USER_OPT_IN_VALUE}
with 
<true/>
or 
<false/>
based on the 
DTXUserOptIn
value from the config block. If no config block is provided, default to 
<true/>
.
  • DTXUserOptIn
    — when 
    true
    , starts the agent with data collection OFF, requiring explicit opt-in via the privacy API (configured in step 5). When 
    false
    , data collection starts immediately without requiring opt-in, and step 5 is skipped.
  • DTXStartupLoadBalancing
    — enables load balancing across cluster nodes on startup.
  • DTXStartupWithGrailEnabled
    — enables RUM on the latest Dynatrace on the first app start before the cluster configuration is received. Once the cluster config is cached, this flag is permanently overridden.
使用
mcp_xcode_XcodeWrite
在应用的主源码目录中创建新的
Dynatrace.plist
文件。这可确保文件自动注册到Xcode项目中。
文件内容：
text
<?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中获取的实际值。将
{USER_OPT_IN_VALUE}
替换为
<true/>
或
<false/>
，具体取决于配置块中的
DTXUserOptIn
值。如果没有配置块，默认使用
<true/>
。
  • DTXUserOptIn
    —— 当为
    true
    时，代理启动时数据收集处于关闭状态，需要通过隐私API明确授权（在步骤5中配置）。当为
    false
    时，数据收集立即启动，无需授权，且跳过步骤5。
  • DTXStartupLoadBalancing
    —— 启用启动时跨集群节点的负载均衡。
  • DTXStartupWithGrailEnabled
    —— 在收到集群配置之前，首次启动应用时启用最新Dynatrace版本的RUM功能。一旦集群配置被缓存，此标志将被永久覆盖。

5. Add user opt-in privacy configuration

5. 添加用户隐私授权配置

Use 
mcp_xcode_XcodeRead
to read the app's entry point file, then use 
mcp_xcode_XcodeUpdate
to add the privacy configuration code with a TODO comment so the user knows to move it to the appropriate place (e.g., a privacy settings screen):
For SwiftUI apps (
@main
App struct file): Add the following inside the 
App
struct's 
init()
method (create one if it doesn't exist):
text
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
    }
}
For UIKit apps (AppDelegate): Add the same code inside 
application(_:didFinishLaunchingWithOptions:)
.
使用
mcp_xcode_XcodeRead
读取应用的入口文件，然后使用
mcp_xcode_XcodeUpdate
添加隐私配置代码，并附带TODO注释，以便用户知道需要将其移至合适的位置（例如隐私设置界面）：
对于SwiftUI应用（包含
@main
App结构体的文件）： 在
App
结构体的
init()
方法中添加以下代码（如果不存在则创建该方法）：
text
init() {
    // TODO: 将此隐私配置移至应用的隐私设置界面。
    // 此处提供的设置用于快速启动监控数据采集。
    // 在生产环境中，应根据用户同意情况（例如隐私设置界面）进行控制。
    let privacyConfig = Dynatrace.userPrivacyOptions()
    privacyConfig.dataCollectionLevel = .userBehavior
    privacyConfig.crashReportingOptedIn = true
    Dynatrace.applyUserPrivacyOptions(privacyConfig) { (successful) in
        // 隐私设置更改后的回调
    }
}
对于UIKit应用（AppDelegate）： 在
application(_:didFinishLaunchingWithOptions:)
方法中添加相同代码。

6. Add the Dynatrace import

6. 添加Dynatrace导入语句

Use 
mcp_xcode_XcodeUpdate
to add 
import Dynatrace
to the app's entry point file.
For SwiftUI apps: Add to the file containing the 
@main
App struct.
For UIKit apps: Add to 
AppDelegate.swift
.
使用
mcp_xcode_XcodeUpdate
在应用的入口文件中添加
import Dynatrace
。
对于SwiftUI应用： 添加到包含
@main
App结构体的文件中。
对于UIKit应用： 添加到
AppDelegate.swift
中。

7. Build and run

7. 构建并运行

Use the Xcode MCP server to build the project:
  • Build the project using 
    mcp_xcode_BuildProject
  • If the build succeeds, report success to the user
  • If the build fails, show the build errors and help the user resolve them
使用Xcode MCP服务器构建项目：
  • 使用
    mcp_xcode_BuildProject
    构建项目
  • 如果构建成功，向用户报告成功
  • 如果构建失败，显示构建错误并帮助用户解决

8. Verify installation

8. 验证安装

Run the bundled verification script scripts/verify-setup.sh. It asserts build output, plist values, simulator launch, and agent startup — all serially with 
set -e
, hard-failing with distinct exit codes.
Invocation:
bash
./scripts/verify-setup.sh <ProjectPath> <SchemeName> \
  <ExpectedAppID> <ExpectedBeaconURL> [ExpectedOptIn]
Arguments (discover from the Xcode project and the values used in step 2/4):
  • ProjectPath
    — e.g. 
    ./MyApp.xcodeproj
  • SchemeName
    — run 
    xcodebuild -list -project <ProjectPath>
    to see available schemes, then pick the correct app scheme (not test or irrelevant schemes)
  • ExpectedAppID
    — the 
    DTXApplicationID
    value written to 
    Dynatrace.plist
  • ExpectedBeaconURL
    — the 
    DTXBeaconURL
    value written to 
    Dynatrace.plist
  • ExpectedOptIn
    — optional; 
    true
    or 
    false
    . Pass the 
    DTXUserOptIn
    value used in step 4 to assert it. Omit to skip.
Exit codes:
CodeMeaningAction
0
All checks passed; plist values correct; agent startup log seenReport success
2
Build output missing framework, missing plist, or plist values don't match expectedSPM link / plist target membership / wrong values — stderr says which
3
Simulator boot / install / launch failedInspect stderr; re-run step 7 if app bundle is stale
4
Dynatrace Core
log not found after launch		Verify 
import Dynatrace
is in entry point; suggest manual launch and checking the Dynatrace environment
5
log show
itself failed		Simulator state issue; retry after restarting the simulator
The script prints 
=== Phase N: ... ===
headers so partial failures are debuggable from stdout.
运行捆绑的验证脚本scripts/verify-setup.sh。它会依次检查构建输出、plist值、模拟器启动和代理启动——所有步骤通过
set -e
强制执行，失败时返回不同的退出码。
调用方式：
bash
./scripts/verify-setup.sh <ProjectPath> <SchemeName> \
  <ExpectedAppID> <ExpectedBeaconURL> [ExpectedOptIn]
参数（从Xcode项目和步骤2/4中使用的值获取）：
  • ProjectPath
    —— 例如 
    ./MyApp.xcodeproj
  • SchemeName
    —— 运行
    xcodebuild -list -project <ProjectPath>
    查看可用scheme，然后选择正确的应用scheme（不是测试或无关scheme）
  • ExpectedAppID
    —— 写入
    Dynatrace.plist
    的
    DTXApplicationID
    值
  • ExpectedBeaconURL
    —— 写入
    Dynatrace.plist
    的
    DTXBeaconURL
    值
  • ExpectedOptIn
    —— 可选；
    true
    或
    false
    。传入步骤4中使用的
    DTXUserOptIn
    值进行验证。省略则跳过此检查。
退出码：
代码含义操作建议
0
所有检查通过；plist值正确；已检测到代理启动日志报告成功
2
构建输出缺少框架、缺少plist或plist值与预期不符检查SPM链接 / plist目标成员资格 / 值是否正确——stderr会提示具体问题
3
模拟器启动/安装/运行失败查看stderr；如果应用包已过期，重新执行步骤7
4
启动后未找到
Dynatrace Core
日志		验证入口文件中是否添加了
import Dynatrace
；建议手动启动应用并检查Dynatrace环境
5
log show
命令本身执行失败		模拟器状态异常；重启模拟器后重试
脚本会输出
=== Phase N: ... ===
标题，以便从stdout中调试部分失败的情况。

Post-verification guidance

验证后指引

Leave the simulator running with the app open so the user can interact with it and generate events that will appear in their Dynatrace environment. Do NOT shut down the simulator.
After successful verification, inform the user:
  • The simulator is running with the app — to verify data reaches their Dynatrace environment, they should:
    1. Interact with the app: tap buttons, navigate between screens to generate user actions and events
    2. Send the app to the background (press the Home button in the simulator) and bring it back to the foreground — this triggers an immediate session flush to the Dynatrace cluster
    3. Within a few minutes, the generated events will appear in their Dynatrace environment
  • To view data: Experience Vitals > Overview > Mobile > select frontend
  • Data can also be queried directly in Grail using DQL
  • For advanced configuration options, see: https://docs.dynatrace.com/docs/observe/digital-experience/new-rum-experience/mobile-frontends/ios/id-03-configuration
保持模拟器运行并打开应用，以便用户与应用交互并生成将显示在其Dynatrace环境中的事件。不要关闭模拟器。
验证成功后，告知用户：
  • 模拟器正在运行应用——要验证数据是否到达Dynatrace环境，他们需要：
    1. 与应用交互：点击按钮、在屏幕间导航以生成用户操作和事件
    2. 将应用切换到后台（在模拟器中按Home键），再切换回前台——这会触发会话立即上报到Dynatrace集群
    3. 几分钟内，生成的事件将显示在其Dynatrace环境中
  • 查看数据：Experience Vitals > 概览 > 移动 > 选择前端
  • 也可以使用DQL在Grail中直接查询数据
  • 如需高级配置选项，请查看：https://docs.dynatrace.com/docs/observe/digital-experience/new-rum-experience/mobile-frontends/ios/id-03-configuration

Important notes

重要说明