On this page: Watch the video:
On this page:
Watch the video:
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 > Instrumentation > End User Monitoring.
- Click the Mobile Apps tab.
2. Record the 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 Environment
Follow the instructions based on your build environment.
Setup for Gradle
If you are using Gradle, you need to modify both your
Modify your top-level build.gradle
Make the following changes to your top-level
Edit or create the "buildscript" section and add the AppDynamics plugin as a dependency as follows:
To stay on a particular version of the agent, replace "4.+" with the desired version number.
Modify your module-level build.gradle
Apply the "adeum" plugin immediately after the "com.android.application" plugin.
- Add "com.appdynamics:appdynamics-runtime:4.+" as a compile-time dependency.
- Step 8 below. Optional: to automate uploading Proguard mapping files so that they are updated every time you build, add the Proguard snippet. You can use this instead of the manual options discussed in
After you have added all the AppDynamics Android Agent requirements, your module-level
build.gradle resembles this:
Optional: Enable/Disable Instrumentation with Build Types
In certain cases you might want to be able to select whether or not a particular build is instrumented, for example, if you are tracking down an issue in your code. You can modify your module-level "build types" section to support two options, one of which is instrumented and the other not. You need to add information to two sections of the module-level
android "build-types" section and the
adeum section, if you already have one.
If you use this option, you need to do a bit more work when you set up instrumentation in your code. See Optional: Modify the source if you are using Build Types
Setup for Maven
If you are using Maven you must:
These instructions assume you are building your application using the android-maven-plugin with Maven 3.1.1+.
Add the Maven runtime dependency
Add the following code to the <dependencies> section:
Add the Maven plugin
Add the following code to the <plugins> section:
4. Integrate ProGuard, if Necessary
If you use ProGuard to verify or optimize your code, add the following lines to your ProGuard configuration file, by default
Depending on your environment, this file may renamed by your build.
If you use Proguard to obfuscate your code, note the name and location of the mapping file that ProGuard produces, because AppDynamics needs this file to create human-readable stack traces for crash snapshots. For details about why you should do this, see Get Human-Readable Crash Snapshots. For more information on the process, see Upload the ProGuard Mapping File.
Every time the application is changed and recompiled the ProGuard mapping file changes, so you need to upload the new mapping file to AppDynamics every time you modify your app, either manually or as a part of your build process.
5. Modify the Source
In the source file that defines your application's primary Activity, add the following import:
In your primary Activity's onCreate() method, add the following lines, passing in the App Key from step 2 above:
Save the file.
Your code should look something like this.
Optional: Point to an on-prem EUM Server
If you are using an on-prem EUM Server instead of the EUM Cloud, you need to tell the Agent where to send its beacons. To do that, you need to create an Agent Configuration object and pass it into the
Instrumentation.start call. The AgentConfiguration object allows you to customize the configuration of the Agent in various ways. To set a URL for an on-prem Server, use the
withCollectorUrl method. You also need to pass in the App Key, as in the simpler process above.
In your primary Activity's onCreate() method, use this form of the Instrumentation.start call:
The full JavaDocs that describe the available options using this method are available here.
Optional: Modify the source if you are using Build Types (Gradle only)
If you are using Gradle and have used the "build types" option in your
build.gradle file to enable/disable instrumentation, you will need to do a little additional work. Instead of the above, in your primary Activity's onCreate() method, add the following lines:
Save the file.
Your code should then look something like this.
6. Add the Required Permissions
Open your application's
AndroidManifest.xml file and verify that it has these permissions:
If both of these permissions are not present, add them.
7. Rebuild the Application
Rebuild your application. If you are using Gradle, add the -i flag (
In the console, you should see something like this:
Verify your instrumentation - Gradle
If you didn't use the
-i flag, check to make sure there is a line in your console output that contains "
inject". If you don't see this information printed in your console, either your project is incorrectly configured or the injector failed to run completely. There is a very detailed log of this process at
Verify your instrumentation - Maven
If you don't see this information printed in your console, either your project is incorrectly configured or the injector failed to run completely. There is a very detailed log of this process at
8. Upload the ProGuard Mapping File
If you did not obfuscate your application source code, you can skip this step. If you have set up automatic uploading of this file using your
build.gradle file, you can skip this step.
This step is optional but highly recommended if you obfuscated your code and plan to monitor crashes. AppDynamics needs the mapping file for the application to produce human-readable stack traces for crash snapshots. By default, the mapping file is named
mapping.txt, unless you have renamed it in your build.
If you update your application, you need to upload the new version of the mapping file.
To associate the mapping file with the correct version of the application, you need to provide:
- the package name of the Android package for the application
- the version code for that application from the
You can either upload the mapping file using the instrumentation screen in the Controller UI or use a special REST API. Perform the upload separately for each ProGuard mapping file that you are providing.
Upload the ProGuard Mapping File using the UI
- lick the Upload ProGuard mapping file for Android crashes button.
- In the ProGuard mapping file upload window, either
- select an existing package from the dropdown list
- enter a new package name for the mobile application.
- select an existing package from the dropdown list
If the application is already registered with the controller, you can select its package which is listed in the dropdown list.
If the application is not yet registered, enter the package name in the New Package field.
- Enter the version code (a number) for the package. This is the
versionCodeproperty in the
AndroidManifest.xmlof the application for which this mapping file was generated.
- Click Select ProGuard mapping file.
The uploader expects a file with .txt extension. The file is named
- In the file browser locate and select the mapping file and click Open.
- Click Upload.
Upload the ProGuard Mapping File using the API
The API uses HTTP basic authentication to send a PUT request to AppDynamics. The username is your AppDynamics EUM 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 the gear icon > License.
- Scroll down to the End User Monitoring 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 mapping file
Send the ProGuard mapping file as as a text file in the body of the PUT request to the following URI:
These parameters are required:
androidPackagename: the name of the Android package for which this mapping file was generated
versionString: the string representation of the "versionCod"e property in the
AndroidManifest.xmlof the application for which this mapping file was generated
The request body contains the mapping file. The content type of the body is either text/plan or gzip if the body was ended with gzip.
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 mapping file. 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 package name for the Android application is "com.example.networklogger". The mapping file corresponds to the version with versionCode 1.
The successful output of the example request looks like this:
9. Customize Your Instrumentation (Optional)
Instrumentation class has additional methods to allow you to extend the kinds of application data you can collect and aggregate using Mobile RUM. There are five basic kinds of extensions that you can create:
- custom timers
- custom metrics
- information points
- user data
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.
For more information, see Use the APIs of the Android SDK to Customize Your Instrumentation.
Upgrade the Android Mobile Agent
As new features are added to the agent, you will need to rebuild to upgrade the Android SDK.