On this page:
Watch the video:
Use this method to have CocoaPods manage your dependencies.
1. Access the instrumentation window
- Open the application in which you are interested. This can be an instrumented server-side application with which your mobile app interacts or a "container" application that holds your mobile application's information in the Controller UI.
- On the left navigation bar, click Configuration.
- Select Instrumentation > End User Monitoring.
- Click the Mobile Apps tab.
2. Record Your Application Key
Record the application key generated for this application, displayed in step.
You will need this key when you modify the source code.
3. Set Up Your Podfile
Add this line to your Podfile:
In your project directory, run this command:
4. Initialize the Agent - Objective C
Edit your app's AppDelegate 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 your application's AppDelegate.m file, add this import:
In AppDelegate, add a call to initialize the SDK using
didFinishLaunchingWithOptions.Use the SDK
initWithKeypassing in your application key, recorded in step 2, as a parameter by adding this line of code:
Your code should look something like this:
- Save the file.
4A. Initialize the Agent - SWIFT
The iOS Agent is compatible with applications created using the Swift programming language.
- Create a bridging header, as described in this Apple document, to expose the Agent's Objective C code to your Swift code.
To your bridging header, add this code:
didFinishLaunchingWithOptions, initialize the SDK like this:
using the application key from step 2, for example, EUM-AAB-AUM.
Save the file.
4B. Initialize the Agent - Apple Watch Extensions
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.
5. Enable 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 create a debug symbols file for the application. For more details about why you would want to do this see Get Human-Readable Crash Snapshots.
To enable dSYM
- 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 Debugging Information Format is set to "DWARF with dSYM File".
The AppDynamics iOS SDK does not currently include bitcode. While bitcode will be coming in a future release, if you are using Xcode 7, you will need to set ENABLE_BITCODE to NO in order to build your application. See this StackOverflow article for more information.
6. Upload 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 details about why you should do this, see Get Human-Readable Crash Snapshots.
If you update the application, you need to provide the new dSYM file for the new application version. The dSYM file contains an UUID that links it to a specific Xcode build, so AppDynamics can unambiguously match the correct dSYM file with an incoming crash report with no additional information.
- set up your environment to upload the file automatically each time you build
- upload the file manually
Upload the dSYM File to AppDynamics Automatically with Each Build
Automating the upload of your dSYM file reduces the number of manual steps required with each build, and ensures that all builds have appropriate dSYM files available for AppDynamics to use.
- In Xcode, select your project from the Project Navigator.
- Click on the Application Target
- Select the Build Phase tab in the Settings editor
- Click the + icon in the upper left corner of the main panel
- Select New Run Script Phase from the dropdown box.
In the script box, add the following lines:
There are also some optional parameters you can set if desired. To set them, add the following line(s) after the second
The last statement should be used to set the URL for an on-prem version of the EUM Server.
Upload the dSYM File to AppDynamics Manually
- Get the dSYM file from Xcode
- Upload the dSYM file to AppDynamics using the UI
Upload the dSYM File to AppDynamics Using the API
Get the dSYM file from Xcode
- In Xcode, run the Xcode build: Product > Build.
- View the log navigator: View > Navigators > Show Report Navigator.
- Click the log entry for the most recent build.
- Near the end of the log, find and mouse over the log entry named "Generate <Your_App_Name>.app.dSYM".
- Click the button on the right side of the entry you found in step #4 to expand it.
The end of the displayed command is the path to the dSYM file.
- Navigate to this dSYM file in the Finder.
- Right click on the dSYM file and choose Compress.
- Upload to AppDynamics the .zip file that Finder generates.
Upload the dSYM file to AppDynamics using the UI
- In the instrumentation window in the controller UI, click the Upload dSym package file for iOS crashes button.
- In the Xcode dSym package upload window click Select zipped dSym file.
The uploader expects a file with a .zip extension.
- In the file browser locate the zipped dSYM file for the application that you are instrumenting and click Open.
- Click Upload.
Upload the dSYM File to AppDynamics Using the REST API
The API uses HTTP basic authentication to send a PUT request to AppDynamics. The username is your AppDynamics account name and the password is your EUM license key.
Set up your HTTP basic authentication credentials
- In the upper right section of the Controller UI, click Settings -> License.
- Scroll down to the End User Experience Management panel.
- Note the Account Name at the top of the panel. This is your username for authentication.
- Note the License Key just below the Account Name. This is your password for authentication.
- URL-encode the account name and the license key.
- Generate an authentication string of the form: "<URL-encoded EUM account name>:<URL-encoded EUM license key>" and base64 encode it. You will use this string the following step.
- Add an authentication header to each request, setting its value to "Basic <authentication string>"
Send the dSYM file
Send the dSym as a zip archive in the body of a PUT request to the following URI:
The content type of the body must be application/zip if the file is a zip file or application/gzip if it is a gzip file. Only these formats are accepted.
Sample Request and Response Using the REST API
This is a sample request and response using the REST API.
The following example uses
curl to send a dSym file named UISampleApp.app.dSYM.zip. The account name is "Example account " and the license key/password is Example-License-Key-4e8ec2ae6cfe. The plus signs replace spaces in the account name when the account name is URL-encoded.
The successful output of the sample request looks like this:
7. Customize Your Instrumentation (Optional)
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
- custom metrics
- user data
- information points
In addition, if you are using an environment with an on-premise EUM Server, you need to update your code to indicate the URL to which your agent should send its beacons. You can also set up the agent to use a custom HTTP library.
For more information, see Use the APIs of the iOS SDK to Customize Your Instrumentation.
There are currently no documented cases of conflicts with other third-party libraries/tools that might also be used in your application. However any tool that does crash reports is likely to be incompatible with the AddDynamics iOS SDK.
Upgrade the iOS Mobile Agent
In your project directory, run this command:
App Transport Security (ATS), iOS 9, and On-Premise EUM Servers
If you use an on-premise EUM Server and you wish to use HTTP to dispatch your beacons to the 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. For more detailed information, see this Apple Technote.