Download PDF
Download page Instrument an iOS Application.
Instrument an iOS Application
Follow these steps to get your EUM App Key and instrument your iOS apps.
Get Your Application Key
After you completed the Getting Started Wizard, you were given an EUM App Key. You will need this key when you modify the source code. In some cases, multiple mobile applications can share the same key.
If you have completed the Getting Started Wizard, but don't have your EUM App Key, see Get Your Application Key.
Initialize the Agent
Edit your app's AppDelegate.m
file to initialize the Mobile Agent as soon as the app launches. This registers your application and only needs to be done once in your code.
In the
AppDelegate.m
file, add thisimport
statement:#import <ADEumInstrumentation/ADEumInstrumentation.h>
OBJ-CIn the method
didFinishLaunchingWithOptions
, create anADEumAgentConfiguration
object with the EUM App Key that you received when completing the Getting Started Wizard to initialize the iOS Agent:// Example EUM App Key: "AAA-AAB-AUM" ADEumAgentConfiguration *config = [[ADEumAgentConfiguration alloc] initWithAppKey:<#EUM_APP_KEY#>];
OBJ-CYour code should look something like the following:
#import <ADEumInstrumentation/ADEumInstrumentation.h> #import "AppDelegate.h" // ... -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // Example EUM App Key: "AAA-AAB-AUM" ADEumAgentConfiguration *config = [[ADEumAgentConfiguration alloc] initWithAppKey:<#EUM_APP_KEY#>]; // other tasks return YES; }
OBJ-CConfigure the iOS Agent to report metrics and screenshots to the SaaS EUM Server in your region and initialize the agent by passing the
ADEumAgentConfiguration
object to the methodi
nitWithConfiguration
. If you are using an on-premises EUM Server, see Configure the iOS Agent for On-Prem Deployments (Optional).#import <ADEumInstrumentation/ADEumInstrumentation.h> #import "AppDelegate.h" // ... -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { ADEumAgentConfiguration *config = [[ADEumAgentConfiguration alloc] initWithAppKey:<#EUM_APP_KEY#>]; //The default SaaS EUM Server and Screenshot Service are in the Americas, // so you can omit the following settings if you are in the Americas. config.collectorURL = "https://<your_region>.eum-appdynamics.com"; config.screenshotURL = "https://<you_region>-image.eum-appdynamics.com/"; [ADEumInstrumentation initWithConfiguration: config]; // other tasks return YES; }
OBJ-C(Optional) If your application is using another tool to report crashes, the iOS Agent may warn you with the following message:
Agent has detected a third party crash reporting tool. You may wish to disable AppDynamics Crash Reporting by setting the crashReportingEnabled configuration flag to NO
OBJ-CYou are recommended to use only one crash reporting tool for better results. See Disable Crash Reporting for instructions on how to disable the iOS Agent's crash reporting.
Save the file.
The iOS Agent is compatible with applications created using the Swift programming language.
In your application's
AppDelegate
class, add thisimport
statement:import ADEumInstrumentation
SWIFTIn the
AppDelegate
classdidFinishLaunchingWithOptions
, create anADEumAgentConfiguration
object with the EUM App Key that you received when completing the Getting Started Wizard to initialize the iOS Agent:#import <ADEumInstrumentation/ADEumInstrumentation.h> #import "AppDelegate.h" // ... func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { let config = ADEumAgentConfiguration(appKey: <#EUM_APP_KEY#>) }
SWIFTConfigure the iOS Agent to report metrics and screenshots to the SaaS EUM Server in your region, and initialize the agent by passing the
initWith()
method that takes theADEumAgentConfiguration
object as a parameter.If you are using an on-premises EUM Server, see Configure the iOS Agent for On-Prem Deployments (Optional).
#import <ADEumInstrumentation/ADEumInstrumentation.h> #import "AppDelegate.h" // ... func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { let config = ADEumAgentConfiguration(appKey: <#EUM_APP_KEY#>) config.collectorURL = "https://<your_region>.eum-appdynamics.com" config.screenshotURL = "https://<your_region>-image.eum-appdynamics.com" ADEumInstrumentation.initWith(config) // other tasks return true } // ...
SWIFT(Optional) If your application is using another tool to report crashes, the iOS Agent will warn you with the following message:
Agent has detected a third party crash reporting tool. You may wish to disable AppDynamics Crash Reporting by setting the crashReportingEnabled configuration flag to NO
SWIFTWe recommend you use only one crash reporting tool for better results. See Disable Crash Reporting for instructions on how to disable the iOS Agent's crash reporting.
Save the file.
Apps written for watchOS 1 contain a WatchKit extension that runs on the user's iPhone, but watchOS 2 also supports a new architecture, where the WatchKit extension runs on the Apple Watch itself. AppDynamics supports the watchOS 1 architecture, but not the new watchOS 2 architecture. Note that apps using the watchOS 1 architecture can run on both watchOS 1 and 2, so if your application is designed for watchOS 1, you can use AppDynamics on both versions of watchOS.
Because watchOS 1 apps are functionally launched in response to an interaction with the Watch UI, the SDK initialization code should be called at the point of that interaction in the iPhone app, which is usually not at the extension's AppDelegate.m
call. The syntax remains the same.
Generate a dSYM File
To enable the agent to provide human-readable information in the crash snapshots that are produced if the application crashes, compile with the DWARF
with dSYM
file option to generate a debug symbols (dSYM) file for the application. For more details about why you would want to do this, see Get Human-Readable Crash Snapshots.
- In Xcode, select your project in the Project Navigator.
- In the target list, select the target that builds your application.
- Select the Build Settings tab.
- In the Build Options section, make sure that the Debug Information Format is set to
DWARF with dSYM File
. Rebuild the Xcode project.
Monitor Crashes with the dSYM File
This step is optional but highly recommended if you plan to monitor crashes. AppDynamics needs the dSYM file for the application to produce human-readable stack traces for crash snapshots.
For instructions, see Upload the dSYM File.
Customize the Instrumentation (Optional)
The ADEumInstrumentation
class has additional methods to allow you to extend the kinds of data you can collect and aggregate using AppDynamics. There are five basic kinds of extensions that you can create:
- Custom timers: any arbitrary sequence of events within your code timed, even spanning multiple methods
- Custom metrics: any integer-based data you wish to collect
- User data: any string key/value pair you think might be useful
- Information points: how often a single method is invoked, and how long it takes to run
- Breadcrumbs: context for a crash
See Customize the iOS Instrumentation.
Configure the iOS Agent for On-Premises Deployments (Optional)
By default, the agent is configured to send its beacons to the EUM Cloud, which is an instance of the EUM Server running on AWS. If you wish to instrument your app in an environment that is using an on-premises version of the EUM Server, you need to modify the URL to which the agent sends its beacons. You do this using the ADEumAgentConfiguration
object to set the Collector URL and the Screenshot Service URL to your on-premises EUM Server URL.
The iOS Agent knows which path to use to make calls to different services (Collector/Screenshot Service). For example, if the EUM Server URL is https://myEUMServerURL.com:7001
, the iOS Agent will know to use https://myEUMServerURL.com:7001/eumcollector
to make requests to the EUM Collector. By specifying the Collector URL, you will not be able to use the SaaS deployment of the EUM Cloud for the Screenshot Service.
To get the EUM Server URL:
- Open the Administration Console.
- From the left navigation bar, click Controller Settings.
- In the search field, enter eum.beacon.host or eum.beacon.https.host if you're using HTTPS.
- Copy the value for the configuration. This is your EUM Server URL.
The code examples below show how to set the Collector URL and Screenshot Service URL using Objective-C and Swift.
ADEumAgentConfiguration *adeumAgentConfig = [[ADEumAgentConfiguration alloc] initWithAppKey:<#EUM_APP_KEY#>];
// Set the Collector URL and Screenshot Service URL to the EUM Server URL.
adeumAgentConfig.collectorURL = <#COLLECTOR_URL:PORT#>;
adeumAgentConfig.screenshotURL = adeumAgentConfig.collectorURL;
[ADEumInstrumentation initWithConfiguration:adeumAgentConfig];
let configuration = ADEumAgentConfiguration(appKey: <#EUM_APP_KEY#>)
// Set the Collector URL and Screenshot Service URL to the EUM Server URL.
config.collectorURL = <#COLLECTOR_URL:PORT#>
config.screenshotURL = config.collectorURL
ADEumInstrumentation.initWith(configuration)
Enable HTTP to Send Beacons to On-Premises EUM Servers
If you use an on-premises EUM Server and you wish to use HTTP to dispatch your beacons to the EUM Server, starting with iOS 9 you need to set a flag in your app's info.plist
file to allow it to use the unsecured connection. By default, HTTPS is enforced in all iOS 9 applications by App Transport Security (ATS), and the iOS Agent complies with ATS when used with the EUM Cloud.