Downloading the Android SDK
You must download the SDK separately for each application that you instrument.
To get the mobile APM SDK for Android
- Go to the mobile instrumentation screen for the application that you will instrument. See .
- Click the Download Android SDK link.
From the download site download the Android SDK.
Recording the Application Key
Record the application key generated for this application. You will need this key when you modify the source code.
Setting Up Your Environment
Follow the instructions for your Android environment:
If you use Eclipse ADT to produce your builds, first build the application with ant and then follow the instructions for the Android Ant installation.
Setup for Ant
If your build system is ant you must:
To add the AppDynamics Android agent files
- Copy ADEumAgent.jar to the libs subdirectory in your project.
- Copy ADEumInjector.jar to your project's root directory.
To add the post-compile hook
Do one of the following:
If there is no custom_rules.xml file in your project:
- Create a file in your project's root directory named custom_rules.xml.
- Copy and paste the following text into custom_rules.xml.
If there is an existing custom_rules.xml file in your project but it does not contain a "-post-compile" <target> element:
Add the following text to the end of the existing <project> element in the custom_rules.xml file:
If there is an existing custom_rules.xml file in your project and it already contains a "-post-compile" <target> element:
Add the following text to the end of the existing "-post-compile" <target> element in the custom_rules.xml file:
If you are using Eclipse + Ant
Do not include
android.jar in the list of jar files provided as "
jarfilesrefid" to your injector task.
For example if your
build.xml looks something like this:
Make sure that
android.jar is not included in the list of files specified by the refid "
project.all.jars.path". Otherwise the injector will fail to instrument your build properly.
Setup for Maven
If your build system is maven you must:
These instructions assume you are building your application using the android-maven-plugin with Maven 3.1.1+.
To add the AppDynamics Android agent repository to your project
- Copy the adeum-maven-repo directory to your project directory. This is the directory that contains pom.xml.
- Add the following code to your pom.xml file:
To add the maven runtime dependency
Add the following code to the <dependencies> section of your pom.xml:
To add the maven plugin
Add the following code to the <plugins> section of your pom.xml:
Setup for Gradle
If your build system is gradle:
To add the AppDynamics Android agent repository to your project
Copy the adeum-maven-repo directory to your project directory. This is the same directory that contains build.gradle.
To modify your build.gradle file
Make the following changes to build.gradle:
Edit or create the "buildscript" section and:
Add "adeum-maven-repo" as a repository
Add the appropriate version of the AppDynamics plugin as a "classpath" dependency. See the table to determine the correct version.
Gradle version Android Tools plugin version AppDynamics plugin version AppDynamics version 1.9 0.7.0, 0.7.1,0.7.3,0.8.3,0.9.2 These Android Tools versions do not support this version of Gradle 1.8 0.6.3 com.appdynamics:appdynamics-gradle-plugin:1.0 3.8.0 and later 1.10 0.7.3,0.8.3, 0.9.2 com.appdynamics:appdynamics-gradle-plugin:2.0 3.8.3 and later 0.10.x Not supported yet
- In the main section:
- Add the "adeum" plugin immediately after the "android" plugin.
Add "adeum-maven-repo" as a dependency.
- Add the appropriate version of the AppDynamics plugin as a compile-time dependency.
After you have added all the AppDynamics Android Agent requirements, your build.gradle file will have information similar to this:
If you use ProGuard to verify or optimize your code, add the following lines to your proguard.cfg:
If you use Proguard to obfuscate your code, note the name and location of the mapping file that ProGuard produced, because AppDynamics will need this file to create human-readable crash snapshots. See Uploading the ProGuard Mapping File. Every time the application is changed and recompiled the ProGuard mapping file changes also, so you need to upload the new mapping file to AppDynamics every time you modify the app.
Modifying the Application Source Code
Modify the source code to initialize the mobile agent as soon as the app launches. A good place to do this is the onCreate() method of your application's primary Activity.
To modify the source code
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 line:
Save the file.
Your code should look something like this.
Adding 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.
Rebuilding the Application
Rebuild your application.
Uploading the ProGuard Mapping File
If you did not obfuscate your application source code, 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. The mapping file is named "mapping.txt".
For details about why you should do this, see Get Human-Readable Crash Snapshots
If you update the application, you need to upload the new mapping file for the new application version.
To associate the mapping file with the correction 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 AndroidManifest.xml file
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.
To upload the ProGuard in the UI
- Click 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 or enter a new package name for the mobile application.
If the application is already registered with the Controller, you can select its package 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 versionCode property in the AndroidManifest.xml of 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 mapping.txt.
- In the file browser locate and select the mapping file and click Open.
- Click Upload.
Uploading 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 account name and the password is your EUM license key.
To set up your HTTP basic authentication credentials
To 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: name of the Android package for which this mapping file was generated
- versionString: string representation of the versionCode property in the AndroidManifest.xml of 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.
Example Mapping File Upload Request
The following example uses curl to send a mapping file file named mapping.txt. 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.
Example Mapping File Output
The successful output of the example request looks like this: