Install Android apps with Gradle and Android Studio

Owner, Admins, or Add-on Managers

If you use Gradle or Android Studio, follow these instructions to install New Relic Mobile for the first time. If you have previously installed the Android agent SDK for New Relic Mobile, follow the steps before upgrading to the latest version with Gradle and Android Studio.

Install your Android app

As part of the installation process, New Relic Mobile automatically generates an application token. This is a 40-character hexadecimal string for authenticating each mobile app you monitor in New Relic Mobile.

Owner, Admins, or Add-on Managers

If you have an existing New Relic account, follow this procedure to install and configure your Android application. If you do not have a New Relic account, get New Relic Mobile.

  1. Go to rpm.newrelic.com/mobile.
  2. If applicable: From the Mobile apps index, select Add a new app. screen mobile app add.png

  3. From the Get started page, select Android as the platform for mobile monitoring.
  4. Type a meaningful name for your mobile app, and select Continue.

Continue with the steps to configure New Relic Mobile with Gradle and Android Studio.

OR:

  • To complete the configuration process for a new mobile app later: Go to rpm.newrelic.com/mobile, then select See instructions next to your mobile app name.
  • To upgrade an existing Android installation: Go to rpm.newrelic.com/mobile > (select an app) > Settings > Installation.

Configure with Gradle and Android Studio

Owner, Admins, or Add-on Managers

These procedures to configure your Android app with Gradle and Android Studio also appear on the Get started page in New Relic Mobile.

  1. Merge the New Relic Mobile code in the Gradle & Android Studio tab to your build.gradle file.

    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"
      }
    }
    
    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 {
      compile 'com.newrelic.agent.android:android-agent:AGENT_VERSION'
    }
  2. ProGuard or DexGuard: In your project’s root directory (projectname/app), add a newrelic.properties file with the following line:

    com.newrelic.application_token=GENERATED_TOKEN
  3. Follow the additional, required configuration steps for using ProGuard or DexGuard with New Relic.
  4. 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" />
  5. To start the New Relic Mobile agent: In your Default Activity (as defined in your Manifest), import the NewRelic class:

    import com.newrelic.agent.android.NewRelic;

    New Relic does not support starting the Mobile agent in other classes, as that can cause unexpected or unstable behavior.

  6. To initialize New Relic Mobile: In the onCreate() method, add this call:

    NewRelic.withApplicationToken("GENERATED_TOKEN").start(this.getApplication());
  7. Optional: Change the logging level.
  8. To build and run your application: Clean your project, then run your app in an emulator or device to generate traffic.
  9. Wait a few minutes, then view data for your Android app from the New Relic Mobile Overview page: Go to rpm.newrelic.com/mobile > (select an app).

If you have problems with your Android installation, or if you do not see data in the New Relic Mobile UI for your Android app, follow the troubleshooting procedures.

Update your Android installation

Owner, Admins, or Add-on Managers

To keep your Android agent up to date, follow the procedures to upgrade the Android agent SDK for New Relic Mobile. To install the latest Android version for your mobile app: Go to rpm.newrelic.com/mobile > (select an app) > Settings > Installation.

Android 4.x: Multidex support

New Relic Mobile for Android versions prior to 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. In order 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 and then manages access to the additional DEX files and the code they contain.

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 any class required during startup is not provided in the primary DEX file, then your app crashes with the error java.lang.NoClassDefFoundError.

Owner, Admins, or Add-on Managers

If you see the java.lang.NoClassDefFoundError error, then you must manually specify these additional classes as required 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.

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

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

For more information, see the Android Developers documentation on declaring classes required in the primary DEX file.

For more help

Recommendations for learning more: