/dt-setup-ios

name: dt-setup-ios
description: 'Set up the Dynatrace iOS SDK (OneAgent) in an iOS project using Swift Package Manager. Automates adding the SPM dependency, creating a Dynatrace.plist configuration file, adding the import statement, adding privacy opt-in code, and building the project. Use this skill when the user wants to integrate, install, add, or set up Dynatrace monitoring in their iOS app. Keywords: Dynatrace, iOS, SDK, OneAgent, setup, install, integrate, SPM, Swift Package Manager, Info.plist, DTXApplicationID, DTXBeaconURL, mobile monitoring, RUM.'
license: Apache-2.0
compatibility: Requires macOS, Xcode 16+, and the Xcode MCP server
argument-hint: Paste your dynatrace-ios-setup-config block, or provide DTXApplicationID and DTXBeaconURL
metadata:
  author: dynatrace
  version: '1.0'

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](https://docs.dynatrace.com/docs/observe/digital-experience/new-rum-experience/mobile-frontends/ios/id-01-initial-setup).

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:

```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](./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](#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](./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 1. **File > Add Package Dependencies...** 1. Enter URL: `https://github.com/Dynatrace/swift-mobile-sdk.git` 1. **Up to Next Major Version** from `8.0.0` 1. Add the chosen library to the app target 1. Click **Add Package**

After the script succeeds (or the user conf