Dt Setup iOS

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:

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:

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:

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.

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.

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:

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

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

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