Set up OneAgent for your iOS apps

iOS tvOS

To monitor your mobile app with Dynatrace, you need to create an application in the Dynatrace web UI and set up OneAgent for your mobile app.

After that, you might also want to instrument your app's SwiftUI controls, fine-tune the auto-instrumentation features via configuration keys, or capture additional details via manual instrumentation.

Create an app in Dynatrace

To create a mobile application in the Dynatrace web UI

In the Dynatrace menu, go to Deploy Dynatrace.
Scroll down, and select Set up mobile monitoring.
Enter a name for your app, and select Create mobile app.
The app settings page opens.

Set up OneAgent

Use CocoaPods, Swift Package Manager, or Carthage to set up Real User Monitoring for your app. You can also follow the manual approach, though it's better to use one of the automated approaches.

You can set up OneAgent as a dynamic XCFramework, static XCFramework (available for OneAgent for iOS version 8.237+), traditional framework, or static library.

You can't combine the static Dynatrace XCFramework and the dynamic Session Replay XCFramework. For Session Replay, both XCFrameworks have to be dynamic.

If you use the static XCFramework, the traditional framework, or the static library to instrument your iOS app, you'll need to perform some additional steps.

Set up OneAgent with CocoaPods

Add Dynatrace OneAgent as a dependency within the CocoaPods Podfile specification. You can do this by setting up OneAgent as a dynamic XCFramework, static XCFramework, traditional framework, or static library.

Dynamic XCFrameworkStatic XCFrameworkTraditional frameworkStatic library

To set up Dynatrace as a dynamic XCFramework, add the Dynatrace pod to your Podfile. Ensure that you uncomment the use_frameworks! line.

python
# Uncomment this line to define a global platform for your project
  # platform :ios, '9.0'
  target 'DemoApp' do
    # Uncomment this line if you're using Swift or want to use dynamic frameworks
    use_frameworks!
    # Pods for DemoApp
    pod 'Dynatrace', '~> 8.237'
  end

To set up Dynatrace as a static XCFramework, add the Dynatrace/xcframeworkStatic pod to your Podfile. Ensure that you uncomment the use_frameworks! line.

python
# Uncomment this line to define a global platform for your project
  # platform :ios, '9.0'
  target 'DemoApp' do
    # Uncomment this line if you're using Swift or want to use dynamic frameworks
    use_frameworks!
    # Pods for DemoApp
    pod 'Dynatrace/xcframeworkStatic', '~> 8.237'
  end

To set up Dynatrace as a traditional framework, add the Dynatrace/framework pod to your Podfile. Ensure that you uncomment the use_frameworks! line.

python
# Uncomment this line to define a global platform for your project
  # platform :ios, '9.0'
  target 'DemoApp' do
    # Uncomment this line if you're using Swift or want to use dynamic frameworks
    use_frameworks!
    # Pods for DemoApp
    pod 'Dynatrace/framework', '~> 8.237'
  end

To set up Dynatrace as a static library, add the Dynatrace/lib pod to your Podfile. Ensure that you comment out the use_frameworks! line.

python
# Uncomment this line to define a global platform for your project
  # platform :ios, '9.0'
  target 'DemoApp' do
    # Uncomment this line if you're using Swift or want to use dynamic frameworks
    # use_frameworks!
    # Pods for DemoApp
    pod 'Dynatrace/lib', '~> 8.237'
  end

The traditional framework and the static library were deprecated as they don't support ARM64 Simulator architecture. This architecture is required to build apps on Mac computers with Apple silicon.

Add your app's identification keys to the Info.plist file. Check the instrumentation wizard in the Dynatrace web UI for the exact values.
Trigger your project build once before using OneAgent SDK or any import declarations in Xcode.

CocoaPods automatically adds OneAgent to your iOS project during the build process.

For more information on Podfiles, see Podfile Syntax Reference.

Set up OneAgent with Swift Package Manager

In Xcode, select File > Swift Packages > Add Package Dependency.
Add https://github.com/Dynatrace/swift-mobile-sdk.git as the package repository URL.
Select only one package product:
- Dynatrace to add only OneAgent
- DynatraceSessionReplay to add both OneAgent and the Session Replay on crashes module
  Do not select DynatraceSessionReplay for tvOS as Session Replay is not available for this operating system.
- Dynatrace-Static to add only OneAgent as a static XCFramework
Perform additional steps depending on the framework you use.
Static XCFramework: Add a linker flag
1. In Xcode, go to the Build Settings tab of your application target.
2. Expand Linking.
3. Add the -ObjC linker flag to Other Linker Flags.
Static XCFramework: Make Dynatrace available to Swift code
You can skip this step if your application doesn't have Swift code or doesn't need access to the Dynatrace framework.
We assume that you already created the Objective-C bridging header file for your Swift code in Xcode.
1. Make sure you set the bridging header file in your application target build settings.
2. Add the following import line to the bridging header file:
```
objectivec
#import <DynatraceStatic/Dynatrace.h>
```
Static library: Add a linker flag
1. In Xcode, go to the Build Settings tab of your application target.
2. Expand Linking.
3. Add the -ObjC linker flag to Other Linker Flags.
Static library: Make Dynatrace available to Swift code
You can skip this step if your application doesn't have Swift code or doesn't need access to the Dynatrace library.
We assume that you already created the Objective-C bridging header file for your Swift code in Xcode.
1. Make sure you set the bridging header file in your application target build settings.
2. Add the following import line to the bridging header file:
```
objectivec
#import Dynatrace.h
```
Add your app's identification keys to the Info.plist file. Check the instrumentation wizard in the Dynatrace web UI for the exact values.
Trigger your project build once before using OneAgent SDK or any import declarations in Xcode.

To update the package version rule, double-click the product entry in the Swift Packages tab within the Xcode project settings. To change the product selection, remove the package and add it again.

To update the package, select File > Swift Packages > Update to Latest Package Versions in Xcode.

Note that you can't edit Swift packages in Xcode 14.

Set up OneAgent with Carthage

Add binary "https://mobileagent.downloads.dynatrace.com/ios/carthage/dynatrace.json" ~> 8.237 to your Cartfile.
Run carthage update --use-xcframeworks.
If you use the deprecated traditional Dynatrace.framework framework, run carthage update.
Add Dynatrace.xcframework and DynatraceSessionReplay.xcframework from the Carthage/Build folder to the Frameworks, Libraries and Embedded Content section located within the General tab of your application target, and set it to Embed & Sign.
Perform some additional steps depending on the framework you use.
Static XCFramework: Add a linker flag
1. In Xcode, go to the Build Settings tab of your application target.
2. Expand Linking.
3. Add the -ObjC linker flag to Other Linker Flags.
Static XCFramework: Add a linked library
1. In Xcode, go to the General tab of your application target.
2. Expand Frameworks, Libraries, and Embedded Content.
3. Add the libc++.tbd library.
You might need to add this library twice. In our internal tests, the library was linked to the project tree only after we added the library a second time.
Static XCFramework: Make Dynatrace available to Swift code
You can skip this step if your application doesn't have Swift code or doesn't need access to the Dynatrace framework.
We assume that you already created the Objective-C bridging header file for your Swift code in Xcode.
1. Make sure you set the bridging header file in your application target build settings.
2. Add the following import line to the bridging header file:
```
objectivec
#import <DynatraceStatic/Dynatrace.h>
```
Traditional framework: Remove iOS Simulator architecture of the release binary
1. In Xcode, add a Run Script phase as the last Build Phase of your application target.
2. Add the following script:
```
sh
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
    FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
    FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
    EXTRACTED_ARCHS=()

    for ARCH in $ARCHS
    do
        lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
        EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
    done

    lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
    rm "${EXTRACTED_ARCHS[@]}"
    rm "$FRAMEWORK_EXECUTABLE_PATH"
    mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
done
```
3. Select Run script: For install builds only.
This removes the iOS Simulator architecture from your release binary used for AppStore Connect upload.
Static library: Add a linker flag
1. In Xcode, go to the Build Settings tab of your application target.
2. Expand Linking.
3. Add the -ObjC linker flag to Other Linker Flags.
Static library: Make Dynatrace available to Swift code
You can skip this step if your application doesn't have Swift code or doesn't need access to the Dynatrace library.
We assume that you already created the Objective-C bridging header file for your Swift code in Xcode.
1. Make sure you set the bridging header file in your application target build settings.
2. Add the following import line to the bridging header file:
```
objectivec
#import Dynatrace.h
```
Add your app's identification keys to the Info.plist file. Check the instrumentation wizard in the Dynatrace web UI for the exact values.
Trigger your project build once before using OneAgent SDK or any import declarations in Xcode.

Set up OneAgent manually

Access the mobile instrumentation wizard.
Select iOS, and then go to the Developer tab.
Follow the provided instructions.
Perform some additional steps depending on the framework you use.
Static XCFramework: Add a linker flag
1. In Xcode, go to the Build Settings tab of your application target.
2. Expand Linking.
3. Add the -ObjC linker flag to Other Linker Flags.
Static XCFramework: Add a linked library
1. In Xcode, go to the General tab of your application target.
2. Expand Frameworks, Libraries, and Embedded Content.
3. Add the libc++.tbd library.
You might need to add this library twice. In our internal tests, the library was linked to the project tree only after we added the library a second time.
Static XCFramework: Make Dynatrace available to Swift code
You can skip this step if your application doesn't have Swift code or doesn't need access to the Dynatrace framework.
We assume that you already created the Objective-C bridging header file for your Swift code in Xcode.
1. Make sure you set the bridging header file in your application target build settings.
2. Add the following import line to the bridging header file:
```
objectivec
#import <DynatraceStatic/Dynatrace.h>
```
Traditional framework: Remove iOS Simulator architecture of the release binary
1. In Xcode, add a Run Script phase as the last Build Phase of your application target.
2. Add the following script:
```
sh
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
    FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
    FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
    EXTRACTED_ARCHS=()

    for ARCH in $ARCHS
    do
        lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
        EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
    done

    lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
    rm "${EXTRACTED_ARCHS[@]}"
    rm "$FRAMEWORK_EXECUTABLE_PATH"
    mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
done
```
3. Select Run script: For install builds only.
This removes the iOS Simulator architecture from your release binary used for AppStore Connect upload.
Static library: Add a linker flag
1. In Xcode, go to the Build Settings tab of your application target.
2. Expand Linking.
3. Add the -ObjC linker flag to Other Linker Flags.
Static library: Make Dynatrace available to Swift code
You can skip this step if your application doesn't have Swift code or doesn't need access to the Dynatrace library.
We assume that you already created the Objective-C bridging header file for your Swift code in Xcode.
1. Make sure you set the bridging header file in your application target build settings.
2. Add the following import line to the bridging header file:
```
objectivec
#import Dynatrace.h
```
Trigger your project build once before using OneAgent SDK or any import declarations in Xcode.

Access mobile instrumentation wizard

The mobile instrumentation wizard in the Dynatrace web UI provides you with get-started instructions on instrumenting your iOS apps. To follow more detailed instructions, go to the Set up OneAgent section on this page.

The wizard also contains code snippets with your app's identification keys that you'll need to add to the Info.plist file.

In the Dynatrace menu, go to Mobile.
Select the mobile app that you want to configure.
Select More (…) > Edit in the upper-right corner of the tile with your app name.

From the app settings, go to Instrumentation wizard.

Limitations

An auto-instrumented application can't carry out functions such as Dynatrace.shutdown() or Dynatrace .flushEvents(). You can manually insert these methods and other user-defined actions and events before performing auto-instrumentation.
The following controls can't be used to create autogenerated actions:
- Gestures
- Certain UIBarButton items, including custom UIBarButton items added to the navigation bar by a storyboard (such as info) that use segues to transition to other views.