Install the Android agent

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 as a community plugin. The Gradle plugin DSL simplifies 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:

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

     Copier

     Make sure to replace AGENT_VERSION with your agent version number. We strongly recommend you use the latest version.

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

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

     Copier

     For detailed information on applying plugins within Gradle, refer to the Gradle documentation.

  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.

  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:

     buildscript {
       repositories {
         mavenCentral()
       }
     
       // not required if plugin classpath in resolutionStrategy{} below
       dependencies {
         classpath "com.newrelic.agent.android:agent-gradle-plugin:AGENT_VERSION"
       }
     }

     Copier

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

     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
       }
     }

     Copier

     Make sure to replace AGENT_VERSION with your agent version number. We strongly recommend you use the latest version.

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

     plugins {
       id("newrelic")
     }

     Copier

  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.

In your AndroidManifest.xml file, add the following permissions:

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

Start the agent in the onCreate() method of your Application class, so the agent is running before Android creates any Activity, no matter which Activity your app opens on.

If your app already has an Application subclass, add the import statement and the start() call below to it. If your app doesn't have one, create it:

import android.app.Application;
import com.newrelic.agent.android.NewRelic;

public class MyApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    NewRelic.withApplicationToken("GENERATED_TOKEN").start(this);
  }
}

Make sure to replace GENERATED_TOKEN with your app token (you generate it when you create your app in New Relic).

If you created a new Application class, register it in your AndroidManifest.xml by adding the android:name attribute to the <application> element:

<application
    android:name=".MyApplication"
    ... >

Without this step, Android doesn't create your class, and the agent doesn't start.

Use either the fully qualified class name or a name that starts with a dot (for example, .MyApplication), which Android resolves relative to your app's package.

(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:

   com.newrelic.application_token=GENERATED_TOKEN

   Copier

   Important

   New Relic automatically adds the proguard rules for agent version 7.6.8 and later.

3. Follow the steps described on Configure ProGuard or DexGuard for Android apps.

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.

View your app's data on New Relic by going to one.newrelic.com > All capabilities > Mobile > (select an app).