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 to the Mobile app monitoring section and select Set up mobile monitoring.
- Enter a name for your application and select Create mobile app. The application 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.To set up Dynatrace as a dynamic XCFramework, add the
Dynatrace
pod to yourPodfile
. Ensure that you uncomment theuse_frameworks!
line.# 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 yourPodfile
. Ensure that you uncomment theuse_frameworks!
line.# 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 yourPodfile
. Ensure that you uncomment theuse_frameworks!
line.# 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 yourPodfile
. Ensure that you comment out theuse_frameworks!
line.# 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 OneAgentDynatraceSessionReplay
to add both OneAgent and the Session Replay on crashes moduleDo 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.
- 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 yourCartfile
. - Run
carthage update --use-xcframeworks
.
If you use the deprecated traditionalDynatrace.framework
framework, runcarthage update
. - Add
Dynatrace.xcframework
andDynatraceSessionReplay.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 toEmbed & Sign
. - Perform some additional steps depending on the framework you use.
- 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.
- 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 application that you want to configure.
- Select More (…) > Edit in the upper-right corner of the tile with your application name.
- From the application settings, select Instrumentation wizard.
Known limitations
- We don't recommend using several monitoring tools simultaneously with crash reporting functionality enabled. This might cause compatibility issues, reporting of wrong or invalid information, and loss of monitoring and crash data. Nevertheless, if you decide to do so, verify via manual testing that these tools are compatible.
- To use both Dynatrace and Firebase, do one of the following.
- Completely deactivate Firebase Performance Monitoring.
- Disable automatic web request instrumentation in OneAgent for iOS.
Follow only one of the approaches above; don't perform both actions.
- 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 customUIBarButton
items added to the navigation bar by a storyboard (such asinfo
) that use segues to transition to other views.