AppDynamics Application Intelligence Platform

3.8.x Documentation

PDFs

Videos

Release Notes

Downloading the Android SDK

You must download the SDK separately for each application that you instrument.

To get the mobile APM SDK for Android

  1. Go to the mobile instrumentation screen for the application that you will instrument. See Instrument a Mobile Application.
  2. Click the Download Android SDK link.
  3. 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

  1. Copy ADEumAgent.jar to the libs subdirectory in your project.
  2. 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:

  1. Create a file in your project's root directory named custom_rules.xml.
  2. Copy and paste the following text into custom_rules.xml.
<project>
    <target name="-post-compile">
        <taskdef name="injector"
                 classname="com.appdynamics.android.ant.EUMAgentInjectorTask"
                 classpath="ADEUMInjector.jar"/>
        <injector classfilespath="${out.classes.absolute.dir}"
                  outputlocation="${out.absolute.dir}/instrumented-jars/"
                  instrumentationjarlocation="${jar.libs.absolute.dir}/ADEUMAgent.jar"
                  jarfilesrefid="project.all.jars.path"
                  androidjarlocation="${project.target.android.jar}"/>
    </target>
</project>

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:

<target name="-post-compile">
    <taskdef name="injector"
             classname="com.appdynamics.android.ant.EUMAgentInjectorTask"
             classpath="ADEUMInjector.jar"/>
    <injector classfilespath="${out.classes.absolute.dir}"
              outputlocation="${out.absolute.dir}/instrumented-jars/"
              instrumentationjarlocation="${jar.libs.absolute.dir}/ADEUMAgent.jar"
              jarfilesrefid="project.all.jars.path"
              androidjarlocation="${project.target.android.jar}"/>
</target>

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:

<taskdef name="injector"
             classname="com.appdynamics.android.ant.EUMAgentInjectorTask"
             classpath="ADEUMInjector.jar"/>
    <injector classfilespath="${out.classes.absolute.dir}"
              outputlocation="${out.absolute.dir}/instrumented-jars/"
              instrumentationjarlocation="${jar.libs.absolute.dir}/ADEUMAgent.jar"
              jarfilesrefid="project.all.jars.path"
              androidjarlocation="${project.target.android.jar}"/>

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:

<taskdef name="injector"
	classname="com.appdynamics.android.ant.EUMAgentInjectorTask"
	classpath="ADEUMInjector.jar"/>
<injector classfilespath="${out.classes.absolute.dir}"
	outputlocation="${out.absolute.dir}/instrumented-jars/"
	instrumentationjarlocation="${jar.libs.absolute.dir}/ADEUMAgent.jar"
	jarfilesrefid="project.all.jars.path"
	androidjarlocation="${project.target.android.jar}"/>

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

  1. Copy the adeum-maven-repo directory to your project directory. This is the directory that contains pom.xml.
  2. Add the following code to your pom.xml file:
<repositories>
    <repository>
        <id>adeum</id>
        <name>AppDynamics Repo</name>
        <url>file://${project.basedir}/adeum-maven-repo</url>
    </repository>
</repositories>

To add the maven runtime dependency

Add the following code to the <dependencies> section of your pom.xml:

<dependency>
     <groupId>com.appdynamics</groupId>
     <artifactId>appdynamics-runtime</artifactId>
     <version>1.0</version>
 </dependency>

To add the maven plugin

Add the following code to the <plugins> section of your pom.xml:

<plugin>
    <groupId>com.appdynamics</groupId>
    <artifactId>appdynamics-maven-plugin</artifactId>
    <version>1.0</version>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>adinject</goal>
            </goals>
        </execution>
    </executions>
</plugin>

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:

  1. Edit or create the "buildscript" section and:

    1. Add "adeum-maven-repo" as a repository

    2. Add the appropriate version of the AppDynamics plugin as a "classpath" dependency. See the table to determine the correct version.

      Gradle versionAndroid Tools plugin versionAppDynamics plugin versionAppDynamics version
      1.90.7.0, 0.7.1,0.7.3,0.8.3,0.9.2These Android Tools versions do not support this version of Gradle 
      1.80.6.3com.appdynamics:appdynamics-gradle-plugin:1.03.8.0 and later
      1.100.7.3,0.8.3, 0.9.2com.appdynamics:appdynamics-gradle-plugin:2.03.8.3 and later
       0.10.xNot supported yet 
  2. In the main section:
    1. Add the "adeum" plugin immediately after the "android" plugin.
    2. Add "adeum-maven-repo" as a dependency.

    3. 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:

buildscript {
    repositories {
        maven {
            url uri('adeum-maven-repo')
        }
    }
    dependencies {
        classpath 'com.appdynamics:appdynamics-gradle-plugin:1.0'
    }
}
 
apply plugin: 'android'
apply plugin: 'adeum'
 
repositories {
    maven {
        url uri('adeum-maven-repo')
    }
}
 
dependencies {
    compile 'com.appdynamics:appdynamics-runtime:1.0'
} 

Integrating ProGuard

If you use ProGuard to verify or optimize your code, add the following lines to your proguard.cfg:

-keep class com.appdynamics.eumagent.runtime.DontObfuscate
-keep @com.appdynamics.eumagent.runtime.DontObfuscate class * { *; }

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:

import com.appdynamics.eumagent.runtime.Instrumentation;

 In your primary Activity's onCreate() method, add the following line:

Instrumentation.start("$CURRENT_APP_KEY", getApplicationContext());

Save the file.

Your code should look something like this.

import com.appdynamics.eumagent.runtime.Instrumentation;
...

@Override
public void onCreate(Bundle savedInstanceState)
{
    ...
    Instrumentation.start("<your app key here>", getApplicationContext());
}

Adding the Required Permissions

Open your application's AndroidManifest.xml file and verify that it has these permissions:

<uses-permission android:name="android.permission.INTERNET"></uses-permission>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>

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

  1.  Access the instrumentation window.
  2. Click the Upload ProGuard mapping file for Android crashes button.
  3. 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.
  4. 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.
  5. Click Select ProGuard mapping file.
    The uploader expects a file with .txt extension. The file is named mapping.txt.
  6. In the file browser locate and select the mapping file and click Open.
  7. 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

  1. In the upper right section of the Controller UI, click Settings -> License.
  2. Note the account name at the top of the Account panel. This will be your username for authentication.
  3. Note the license key at the top of the End User Monitoring panel. This will be your password for authentication.
  4. URL-encode the account name and the license key.
  5. 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.
  6. Add an authentication header to each request, setting its value to "Basic <authentication string>"

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:

https://api.eum-appdynamics.com/eumaggregator/crash-reports/proguardMappingFile/<androidPackageName>/<versionString>

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.

curl -v --upload-file mapping.txt --user Example+account:Example-License-Key-4e8ec2ae6cfe https://api.eum-appdynamics.com/eumaggregator/crash-reports/proguardMappingFile/com.example.networklogger/1

Example Mapping File Output

The successful output of the example request looks like this:

* About to connect() to api.eum-appdynamics.com port 443 (#0)
*   Trying ::1...
* connected
* Connected to api.eum-appdynamics.com  (::1) port 443 (#0)
* Server auth using Basic with user 'Example+account'
> PUT /eumaggregator/crash-reports/proguardMappingFile/com.example.networklogger/1 HTTP/1.1
> Authorization: Basic SW50ZXJuYWwrdGVzdCthY2NvdW50OlRlc3RBY2N0LTFlMzktNDVkMy05MzAzLTRlOGVjMmFlNmNmZQ==
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8y zlib/1.2.5
> Host: app.eum-appdynamics.com
> Accept: */*
> Content-Length: 4
> Expect: 100-continue
>
< HTTP/1.1 100 Continue
* We are completely uploaded and fine
< HTTP/1.1 200 OK
< Content-Length: 0
< Server: Jetty(8.1.4.v20120524)
<
* Connection #0 to host app.eum-appdynamics.com left intact
* Closing connection #0