Change Dynatrace Android Gradle plugin configuration based on the project structure

The Dynatrace Android Gradle plugin scans all subprojects and configures the auto-instrumentation process for your application modules. Other modules are unaffected by the plugin, so you might need to adjust the instrumentation process in some cases, such as with Android library modules.

This page describes the behavior of the Dynatrace Android Gradle plugin and the additional configuration steps required for certain types of modules and architectures.

Projects with library modules

All Android/Java libraries as well as all third-party libraries are auto-instrumented by our plugin when they're part of your Android application project. No additional configuration is required, as the plugin has access to all Gradle dependencies of your Android application project.

If you want to enrich mobile user experience data generated by your Android library modules, add the OneAgent SDK manually as a Gradle dependency. Use the same version of the OneAgent SDK and the Dynatrace Android Gradle plugin, and specify the OneAgent SDK dependency via the Dynatrace Android Gradle plugin.

If you have a project with multiple modules and want to use the OneAgent SDK in each library module, use the following code snippet.

gradlecopydownload
subprojects {
    pluginManager.withPlugin("com.android.library") {
        dependencies {
            implementation com.dynatrace.tools.android.DynatracePlugin.agentDependency()
        }
    }
}

gradlecopydownload
subprojects {
    pluginManager.withPlugin("com.android.library") {
        dependencies {
            "implementation"(com.dynatrace.tools.android.DynatracePlugin.agentDependency())
        }
    }
}

You can also use other Gradle features to fine-tune this behavior. For example, the following Gradle snippet uses the module name to determine if the OneAgent SDK should be added to a specific Android library module.

gradlecopydownload
subprojects { project ->
    pluginManager.withPlugin("com.android.library") {
        if(project.name == 'firstLibrary' || project.name == 'secondLibrary') {
            dependencies {
                implementation com.dynatrace.tools.android.DynatracePlugin.agentDependency()
            }
        }
    }
}

gradlecopydownload
subprojects { project ->
    pluginManager.withPlugin("com.android.library") {
        if(project.name == "firstLibrary" || project.name == "secondLibrary") {
            dependencies {
                "implementation"(com.dynatrace.tools.android.DynatracePlugin.agentDependency())
            }
        }
    }
}

Projects with feature modules

For Play Feature Delivery, your application must consist of a base module and one or more feature modules. Feature modules can be delivered conditionally, downloaded on demand, or launched without being installed.

The base module applies the com.android.application plugin, while the feature modules apply the com.android.dynamic-feature plugin. When you build your application, the Dynatrace Android Gradle plugin auto-instruments both com.android.application and com.android.dynamic-feature plugins, and the same configuration is used for all modules.

When the automatic OneAgent startup is enabled, our plugin instruments the Application class of the base module. This ensures that OneAgent is always running, even when a feature is delivered instantly.

Instant delivery and OneAgent manual startup

With instant delivery, users can interact with your application's features without installing APK on their devices. However, their devices must download both the base module and the instant-enabled feature module. See Google Play Instant for more details.

If you've disabled the automatic OneAgent startup for your project with feature modules, start OneAgent manually within the base module, preferably in the Application class of the base module. This way, OneAgent is ready to be used when required, and you can avoid potential issues caused by delayed OneAgent startup in other classes or within a feature module.

Build variant instrumentation

If you've configured build variants via product flavors, use the same product flavor names and dimensions in each module.

When using the missingDimensionStrategy property of the Android Gradle plugin, ensure that each build variant in every module is linked to the correct variant-specific configuration by adjusting the variantFilter property. To view which configuration is used for each build variant, use the printVariantAffiliation task.

Projects with multiple application modules

Configuring the Dynatrace Android Gradle plugin for projects with multiple application modules is similar to configuring a project that has only a single application module.

Follow the steps below to instrument Android projects with multiple application modules.

1. Ensure that the Maven Central repository is declared.

   Dynatrace is hosted on Maven Central. In the Gradle settings file, verify that mavenCentral() is added to the repositories blocks under pluginManagement and dependencyResolutionManagement. Check the official Android documentation to see what the settings file should look like.

   Projects with previous Android template: Ensure that the Maven Central repository is declared.

   You might need to add mavenCentral() to all repositories blocks in the top-level build file.

2. Add our plugin to the build script classpath.

   In the top-level build file, add the buildscript block with the dependencies block inside and add the classpath of the Dynatrace Android Gradle plugin (com.dynatrace.tools.android:gradle-plugin).

   GroovyKotlin

   gradlecopydownload
   // add this entire block
   buildscript {
       dependencies {
           classpath 'com.dynatrace.tools.android:gradle-plugin:8.+'
       }
   }
   
   // this block already exists
   plugins {
       id 'com.android.application' version '8.1.0' apply false
       id 'com.android.library' version '8.1.0' apply false
   }

   gradlecopydownload
   // add this entire block
   buildscript {
       dependencies {
           classpath("com.dynatrace.tools.android:gradle-plugin:8.+")
       }
   }
   
   // this block already exists
   plugins {
       id("com.android.application") version "8.1.0" apply false
       id("com.android.library") version "8.1.0" apply false
   }

   Projects with previous Android template: Add our plugin to the build script classpath.

   In the top-level build file, find the dependencies block inside the buildscript block, and add the classpath of the Dynatrace Android Gradle plugin (com.dynatrace.tools.android:gradle-plugin) after the build script classpath of the Android Gradle plugin (com.android.tools.build:gradle).

   GroovyKotlin

   gradlecopydownload
   buildscript {
       repositories {
           google()
           mavenCentral() // hosts Dynatrace Android Gradle plugin
       }
       dependencies {
           // build script classpath of Android Gradle plugin
           classpath 'com.android.tools.build:gradle:<version>'
           // build script classpath of Dynatrace Android Gradle plugin; add this line to build.gradle file
           classpath 'com.dynatrace.tools.android:gradle-plugin:8.+'
       }
   }

   gradlecopydownload
   buildscript {
       repositories {
           google()
           mavenCentral() // hosts Dynatrace Android Gradle plugin
       }
       dependencies {
           // build script classpath of Android Gradle plugin
           classpath("com.android.tools.build:gradle:<version>")
           // build script classpath of Dynatrace Android Gradle plugin; add this line to build.gradle.kts file
           classpath("com.dynatrace.tools.android:gradle-plugin:8.+")
       }
   }

   Use version 8.+ so that Gradle can automatically update our plugin when a new minor version is available. When Dynatrace releases a new major version, manually upgrade to the new version—the new major version might contain breaking changes, so manual adjustments are usually required.

3. Apply our plugin and add its configuration snippet.

   Apply the Dynatrace Android Gradle plugin with the com.dynatrace.instrumentation.module plugin ID in the module-level build file of every application module.

   Then, add the code snippet from step 3 (Apply the Dynatrace plugin and add the plugin configuration) of the Android instrumentation wizard to have the correct applicationId and beaconUrl values.

   GroovyKotlin

   gradlecopydownload
   apply plugin: 'com.dynatrace.instrumentation.module'
   dynatrace {
       configurations {
           sampleConfig {
               autoStart {
                   applicationId '<YourApplicationID>'
                   beaconUrl '<ProvidedBeaconURL>'
               }
           }
       }
   }

   gradlecopydownload
   apply(plugin = "com.dynatrace.instrumentation.module")
   configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
       configurations {
           create("sampleConfig") {
               autoStart {
                   applicationId("<YourApplicationID>")
                   beaconUrl("<ProvidedBeaconURL>")
               }
           }
       }
   }

4. Customize the plugin configuration.

   The Gradle snippet that you've copied from the Android instrumentation wizard contains the default plugin configuration. The same configuration is used for all Android build variants, and our plugin uses the default sensors and default OneAgent configuration values. For this reason, you might want to adjust the configuration of the Dynatrace Android Gradle plugin.

5. optional Enhance mobile user experience data by using the OneAgent SDK for Android.

   With OneAgent SDK for Android, you can enrich the mobile user experience data. For example, user tagging or custom value reporting is only available via the OneAgent SDK.

To customize instrumentation for a specific application, modify the configuration of the Dynatrace Android Gradle plugin in the build file of the application. Other application modules won't be affected by this configuration change.

Projects with multiple application modules and feature modules

When your Android project contains modules that use the com.android.dynamic-feature plugin, you should copy the code snippet from step 3 of the instructions above to a new .gradle file. Apply the generated file in the application module and all feature modules that belong to this application module. To apply a .gradle file, use the following snippet as described in the official Gradle documentation.

gradlecopydownload
apply from: 'other.gradle'

gradlecopydownload
apply(from = "other.gradle.kts")

With this approach, the same configuration is used for all modules that belong to the same application.

Projects with one build file

When your Android project doesn't follow the recommended architecture and has only one build file, both the top-level build file and the module-level build file refer to the same build file.

Follow the steps below to instrument Android projects with only one build file. Use your project's build file where the instructions mention the top-level build file.

1. Ensure that the Maven Central repository is declared.

   Dynatrace is hosted on Maven Central. In the Gradle settings file, verify that mavenCentral() is added to the repositories blocks under pluginManagement and dependencyResolutionManagement. Check the official Android documentation to see what the settings file should look like.

   Projects with previous Android template: Ensure that the Maven Central repository is declared.

   You might need to add mavenCentral() to all repositories blocks in the top-level build file.

2. Add our plugin to the build script classpath.

   In the top-level build file, add the buildscript block with the dependencies block inside and add the classpath of the Dynatrace Android Gradle plugin (com.dynatrace.tools.android:gradle-plugin).

   GroovyKotlin

   gradlecopydownload
   // add this entire block
   buildscript {
       dependencies {
           classpath 'com.dynatrace.tools.android:gradle-plugin:8.+'
       }
   }
   
   // this block already exists
   plugins {
       id 'com.android.application' version '8.1.0' apply false
       id 'com.android.library' version '8.1.0' apply false
   }

   gradlecopydownload
   // add this entire block
   buildscript {
       dependencies {
           classpath("com.dynatrace.tools.android:gradle-plugin:8.+")
       }
   }
   
   // this block already exists
   plugins {
       id("com.android.application") version "8.1.0" apply false
       id("com.android.library") version "8.1.0" apply false
   }

   Projects with previous Android template: Add our plugin to the build script classpath.

   In the top-level build file, find the dependencies block inside the buildscript block, and add the classpath of the Dynatrace Android Gradle plugin (com.dynatrace.tools.android:gradle-plugin) after the build script classpath of the Android Gradle plugin (com.android.tools.build:gradle).

   GroovyKotlin

   gradlecopydownload
   buildscript {
       repositories {
           google()
           mavenCentral() // hosts Dynatrace Android Gradle plugin
       }
       dependencies {
           // build script classpath of Android Gradle plugin
           classpath 'com.android.tools.build:gradle:<version>'
           // build script classpath of Dynatrace Android Gradle plugin; add this line to build.gradle file
           classpath 'com.dynatrace.tools.android:gradle-plugin:8.+'
       }
   }

   gradlecopydownload
   buildscript {
       repositories {
           google()
           mavenCentral() // hosts Dynatrace Android Gradle plugin
       }
       dependencies {
           // build script classpath of Android Gradle plugin
           classpath("com.android.tools.build:gradle:<version>")
           // build script classpath of Dynatrace Android Gradle plugin; add this line to build.gradle.kts file
           classpath("com.dynatrace.tools.android:gradle-plugin:8.+")
       }
   }

   Use version 8.+ so that Gradle can automatically update our plugin when a new minor version is available. When Dynatrace releases a new major version, manually upgrade to the new version—the new major version might contain breaking changes, so manual adjustments are usually required.

3. Apply our plugin and add its configuration snippet.

   Apply the Dynatrace Android Gradle plugin with the com.dynatrace.instrumentation.module plugin ID in the build file. Make sure that com.dynatrace.instrumentation.module is applied after the com.android.application plugin but before the com.google.firebase.firebase-perf plugin if it's also used.

   Then, add the code snippet from step 3 (Apply the Dynatrace plugin and add the plugin configuration) of the Android instrumentation wizard to have the correct applicationId and beaconUrl values.

   GroovyKotlin

   gradlecopydownload
   apply plugin: 'com.android.application'
   ...
   apply plugin: 'com.dynatrace.instrumentation.module'
   
   dynatrace {
       configurations {
           sampleConfig {
               autoStart {
                   applicationId '<YourApplicationID>'
                   beaconUrl '<ProvidedBeaconURL>'
               }
           }
       }
   }

   gradlecopydownload
   apply(plugin = "com.android.application")
   ...
   apply(plugin = "com.dynatrace.instrumentation.module")
   
   configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
       configurations {
           create("sampleConfig") {
               autoStart {
                   applicationId("<YourApplicationID>")
                   beaconUrl("<ProvidedBeaconURL>")
               }
           }
       }
   }

   You can change the sampleConfig configuration name to something more meaningful. You can also define different configurations for different Android build variants. For example, you can report your debug and release variants to different mobile applications in Dynatrace by using variant-specific configurations.

4. Customize the plugin configuration.

   The Gradle snippet that you've copied from the Android instrumentation wizard contains the default plugin configuration. The same configuration is used for all Android build variants, and our plugin uses the default sensors and default OneAgent configuration values. For this reason, you might want to adjust the configuration of the Dynatrace Android Gradle plugin.

5. optional Enhance mobile user experience data by using the OneAgent SDK for Android.

   With OneAgent SDK for Android, you can enrich the mobile user experience data. For example, user tagging or custom value reporting is only available via the OneAgent SDK.