Install the Android agent

To install the Android agent, you need to use our guided install. Setting up the Android agent requires an application token that authenticates each mobile app you want to monitor. The app token is only available by going through the guided install.

Install the Android agent with guided install

1. Go to one.newrelic.com > Add data > Mobile > Android.
2. Follow the guided install steps to set up your Android agent.
3. Wait a few minutes, then view your data by going to one.newrelic.com > All capabilities > Mobile > (select your app).

Manually install the Android agent

These procedures appear in our guided install. Keep in mind that even if you're updating your build files through the docs, you still need to add your app to New Relic and grab your generated app token from the guided install. You cannot capture data about your Android apps otherwise.

1. Add the following code to your build.gradle files found in the Gradle & Android Studio tab. You need to update the top-level build snippet and each sub-module that you want to instrument.

   Project level `build.gradle` file:

   In this example, <AGENT_VERSION> represents your agent version number. See the agent release notes, and use the latest version.

   buildscript {
     repositories {
       mavenCentral()
     }
   
     dependencies {
       classpath "com.newrelic.agent.android:agent-gradle-plugin:<AGENT_VERSION>"
     }
   }

   Copy

   App level `build.gradle` file:

   In this example, <AGENT_VERSION> represents your agent version number. See the agent release notes, and use the latest version.

   repositories {
     mavenCentral()
   }
   
   apply plugin: 'android'
   apply plugin: 'newrelic'
   
   dependencies {
     implementation 'com.newrelic.agent.android:android-agent:<AGENT_VERSION>'
   }

   Copy

2. Set app permissions. Ensure that your Android app requests INTERNET and ACCESS_NETWORK_STATE permissions by adding these lines to your AndroidManifest.xml file:

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

   Copy

3. Start the Android agent. In your default Activity found in your manifest, import the NewRelic class:

   import com.newrelic.agent.android.NewRelic;

   Copy

   We don't support starting the mobile monitoring agent in other classes, as that can cause unexpected or unstable behavior.

4. After you've imported the NewRelic class, you need to add an additional snippet to the onCreate() method, which includes your app token, which is generated in the guided install. The snippet looks like this:

   NewRelic.withApplicationToken("<GENERATED_TOKEN>").start(this.getApplicationContext());

   Copy

5. If you're using minification (for example, like with ProGuard or Dexguard), you need to add newrelic.properties file to your app-level directory (projectname/app). This step only applies to ProGuard and DexGuard users.

   com.newrelic.application_token=<GENERATED_TOKEN>

   Copy

   To finish set up for minification, follow the steps in configure ProGuard or DexGuard for Android apps.

6. Clean your project, then run your app in an emulator or device to generate traffic. Wait a few minutes as your agent captures that data.

7. View your data for your Android app. Go to one.newrelic.com > All capabilities > Mobile > (select an app).

Configure the Android agent for Gradle Plugin Portal

Because the Android agent isn't yet available as a community plugin, you need to provide the classpath through MavenCentral so the agent can instrument your Android app. If you've configured your app to look for plugins through Gradle Plugin Portal, you need to repeat this step in the settings.gradle(.kts) file.

1. Add this snippet to your settings.gradle(.kts) file through pluginManagement {} block:

   pluginManagement {
     repositories {
       mavenCentral()  // adds repo for NewRelic artifacts
     }
     resolutionStrategy {
       eachPlugin {
         if (requested.id.id.startsWith("newrelic")) {
           useModule("com.newrelic.agent.android:agent-gradle-plugin:${AGENT_VERSION}")
         }
       }
     }
   
     // optional: define as a community plugin here or in root level build file
   
     // for core Gradle plugins or plugins already available to the build script
     plugins {
       id("newrelic") version "${<AGENT_VERSION>}"
     }
   }

   Copy

2. Declare the New Relic plugin:

   plugins {
     // for binary Gradle plugins that need to be resolved
     id("newrelic") version "<AGENT_VERSION>" apply false
   }

   Copy

3. Apply the plugin to the app-level build files:

   plugins {
       id("com.android.application")
       id("org.jetbrains.kotlin.android")
       id("newrelic")
   }

   Copy

In the above snippets, <AGENT_VERSION> represents your agent version number. We strongly recommend you use the latest agent for set up.

Android 4.x: Multidex support

Mobile monitoring for Android versions older than Android 5.0 (API level 21) use the Dalvik runtime to execute app code. By default, Dalvik limits apps to a single classes.dex bytecode file per APK. To get around this limitation, you must enable multidex support. Then you can use the multidex support library, which becomes part of the primary DEX file of your app. The library manages access to the additional DEX files and their containing code.

What's next?

Congratulations! You've successfully installed the Android agent. You have a few options for next steps:

• Configure agent behavior during Gradle builds with the New Relic Gradle plugin.
• Upgrade the Android agent SDK to keep your Android agent up to date.
• Having problems with your Android installation? Follow the troubleshooting procedures.