Dynatrace iOS SDK Setup

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.

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

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.

Procedure

1. Check prerequisites

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.

2. Collect application identification keys

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

3. Add OneAgent to the project (SPM dependency)

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

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:

Open the project in Xcode
File > Add Package Dependencies...

Enter URL:

https://github.com/Dynatrace/swift-mobile-sdk.git

Up to Next Major Version from
```
8.0.0
```
Add the chosen library to the app target
Click Add Package

After the script succeeds (or the user confirms manual addition), proceed to step 4.

4. Create Dynatrace.plist configuration

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/>

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

5. Add user opt-in privacy configuration

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:)

6. Add the Dynatrace import

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

7. Build and run

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

8. Verify installation

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:

Code	Meaning	Action
`0`	All checks passed; plist values correct; agent startup log seen	Report success
`2`	Build output missing framework, missing plist, or plist values don't match expected	SPM link / plist target membership / wrong values — stderr says which
`3`	Simulator boot / install / launch failed	Inspect 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.

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

Important notes

This skill covers SPM integration only. CocoaPods and manual framework integration are not supported.
Do NOT add extra DTX configuration keys unless the user explicitly asks for them — the defaults are optimized for a good first experience.
The public documentation for this setup is at: https://docs.dynatrace.com/docs/observe/digital-experience/new-rum-experience/mobile-frontends/ios/id-01-initial-setup

dt-obs-ios

NPX Install

Tags

SKILL.md Content

Dynatrace iOS SDK Setup

When to use this skill

Pre-filled values

Procedure

1. Check prerequisites

2. Collect application identification keys

3. Add OneAgent to the project (SPM dependency)

4. Create Dynatrace.plist configuration

5. Add user opt-in privacy configuration

6. Add the Dynatrace import

7. Build and run

8. Verify installation

Post-verification guidance

Important notes