---
title: Install the Android agent
source: https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle
---

To install the Android agent, we recommend you follow our guided install:

1.  Go to **[one.newrelic.com](https://one.newrelic.com) > Integrations & Agents > 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](https://one.newrelic.com/all-capabilities) > Mobile > (select your app)**.

## Manually install the Android agent [#manual-install]

The steps below are outlined in our guided install. Note that even if you manually install the agent, you'll still need to create a New Relic app and obtain the generated application token. This token is essential for the agent to send data to New Relic.

1.  Add the Android agent plugin to your project.
    Regarding the location of the plugin, you have two options:
    -   Recommended: Using the Gradle plugin DSL
        -   Starting with agent version 7.6.0, the Android agent plugin is available on the [Gradle Plugin Portal](https://plugins.gradle.org/) as a community plugin. The Gradle plugin DSL simpifies adding plugin dependencies to apps.
        -   This method involves adding the agent plugin dependency to your project's plugins DSL block.
    -   Legacy Plugin ID (`newrelic`)

        -   For older projects or specific use cases, you can use the legacy plugin ID.
        -   This method involves adding the agent as a dependency to your project's build script, specifying the MavenCentral repository.

        Follow the detailed steps below for your chosen installation method.

        **(Recommended) Apply the plugin using the plugins DSL block**

        The recommended approach for managing plugin dependencies in Gradle utilizes the plugins DSL block. This section details applying the fully qualified form of the plugin ID (`com.newrelic.agent.android`) within this structure.

        1.  Declare the New Relic plugin to the top-level `build.gradle(.kts)` file using the Gradle Plugin Portal plugin ID:

            ```groovy
            plugins {
              // for binary Gradle plugins that need to be resolved
              id("com.newrelic.agent.android") version "AGENT_VERSION" apply false
            }
            ```

            Make sure to replace `AGENT_VERSION` with your agent version number. We strongly recommend you use the [latest version](https://docs.newrelic.com/docs/release-notes/mobile-release-notes/android-release-notes/).

        2.  Apply the plugin explicitly to the app-level build file (and any sub-modules intended for instrumentation) using the following syntax:

            ```groovy
            plugins {
              id("com.newrelic.agent.android")
            }
            ```

            For detailed information on applying plugins within Gradle, refer to the [Gradle documentation](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block).

        ** Apply the plugin using the buildscript{} block**

        The Android agent plugin is available on MavenCentral and uses the legacy plugin ID `newrelic` for compatibility with older projects. If you choose to leverage this legacy ID for an existing app, you'll need to explicitly configure the classpath to MavenCentral. This ensures Gradle can locate the plugin during your build process. For further details on various methods for resolving plugins, refer to the [Gradle documentation](https://docs.gradle.org/current/userguide/plugins.html#sec:binary_plugin_locations).

        To prefer MavenCentral over the Gradle Plugin Portal, you need to make the following changes to Gradle files:

        1.  Add this snippet to your top-level build.gradle(.kts) file:

            ```groovy
            buildscript {
              repositories {
                mavenCentral()
              }

              // not required if plugin classpath in resolutionStrategy{} below
              dependencies {
                classpath "com.newrelic.agent.android:agent-gradle-plugin:AGENT_VERSION"
              }
            }
            ```

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

            ```groovy
            pluginManagement {
              repositories {
                mavenCentral()  // adds repo for NewRelic artifacts
              }
              resolutionStrategy {
                eachPlugin {
                  // not required if using `classpath dependency` above
                  if (requested.id.id.startsWith("newrelic") || requested.id.id.startsWith("com.newrelic.agent.android")) {
                    useModule("com.newrelic.agent.android:agent-gradle-plugin:${AGENT_VERSION}")
                  }
                }
              }
              plugins {
                id("newrelic") apply false
              }
            }
            ```

            Make sure to replace `AGENT_VERSION` with your agent version number. We strongly recommend you use the [latest version](https://docs.newrelic.com/docs/release-notes/mobile-release-notes/android-release-notes/).

        3.  Apply the plugin to the app-level build file, as well as any other sub-module to be instrumented:

            ```groovy
            plugins {
              id("newrelic")
            }
            ```

        > #### ⚠️ IMPORTANT
        >
        > New Relic automatically adds the following permissions to allow the agent to make HTTP requests to deliver captured data for agent versions 7.6.8 and higher.
2.  In your `AndroidManifest.xml` file, add the following permissions:
    ```xml
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    ```
3.  In your main `Activity` class within the `onCreate` method, add this import statement:
    ```java
    import com.newrelic.agent.android.NewRelic;
    ```
    Note: You must add this import statement to the `Activity` class. We don’t support starting the agent in other classes.
4.  In the `onCreate` method, add the following line, making sure to replace `GENERATED_TOKEN` with your actual app token (created during the guided install):
    ```java
    NewRelic.withApplicationToken("GENERATED_TOKEN").start(this.getApplicationContext());
    ```
5.  (Optional) Additional configurations for Proguard/Dexguard
    If you use ProGuard or Dexguard for code shrinking, follow these steps:
    1.  Create a `newrelic.properties` file in your app-level directory (ex: `/projectname/app/newrelic.properties`).
    2.  In this new file, add the following line, replacing `GENERATED_TOKEN ` with your actual token:

        ```java
        com.newrelic.application_token=GENERATED_TOKEN 
        ```

        > #### ⚠️ IMPORTANT
        >
        > New Relic automatically adds the proguard rules for agent version 7.6.8 and later.
    3.  Follow the steps decribed on [Configure ProGuard or DexGuard for Android apps](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-android/install-configure/configure-proguard-or-dexguard-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 app's data on New Relic by going to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app)**.

## 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](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-android/install-configure/configure-new-relic-gradle-plugin).
-   [Upgrade the Android agent SDK](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-android/install-configure/upgrading-new-relic-mobiles-android-sdk) to keep your Android agent up to date.
-   Having problems with your Android installation? Follow the [troubleshooting procedures](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-android/troubleshoot/no-data-appears-android).

## Android 4.x: Multidex support [#4x-multidex]

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](https://developer.android.com/studio/build/multidex.html). Then you can use the [multidex support library](https://developer.android.com/tools/support-library/features.html#multidex), which becomes part of the primary DEX file of your app. The library manages access to the additional DEX files and their containing code.

**Troubleshoot the java.lang.NoClassDefFoundError error**

When building each DEX file for a multidex app, the build tools perform complex decision making to determine which classes are needed in the primary DEX file so that your app can start successfully. If, during start up, the required classes aren't available in the primary DEX file, your app will crash with the error `java.lang.NoClassDefFoundError`.

If you see the `java.lang.NoClassDefFoundError` error, then you must [manually specify these additional classes as required](https://developer.android.com/studio/build/multidex.html#keep) in the primary DEX file:

1.  Create a `proguard.multidex.config` file within the `/app` folder of your project. Update `mypackage` to reflect your package name.

    ```profile
    ####################
    # keep class names #
    ####################

    #Keep New Relic in the main dex
    -keep class com.newrelic.** { *; }
    -keep class com.mypackage.activities.** { *; }
    ```

2.  Merge the following code into the app-level `build.gradle` file:

    ```groovy
    android {
      defaultConfig{
        …
        multiDexKeepProguard file("proguard.multidex.config")
      }
    }
    ```

    For more information, see the [Android Developers documentation](https://developer.android.com/studio/build/multidex.html#keep) on declaring classes required in the primary DEX file.