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.

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

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.

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

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.

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 Gradle settings file should look like.

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

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).

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

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

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).

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.+'
    }
}

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.+")
    }
}

In the top-level build file, find the plugins block, and add the id com.dynatrace.instrumentation of the Dynatrace Plugin Marker Artifacts. After plugins block add plugin configuration of the Android instrumentation wizard to have the correct applicationId and beaconUrl values.

plugins {
   id 'com.android.application' version '8.5.0' apply false
   id 'com.dynatrace.instrumentation' version '8.+' apply true
}

dynatrace {
    configurations {
        sampleConfig {
            autoStart {
                applicationId = '<YourApplicationID>'
                beaconUrl = '<ProvidedBeaconURL>'
            }
        }
    }
}

plugins {
   id("com.android.application") version "8.5.0" apply false
   id("com.dynatrace.instrumentation") version "8.+" apply true
}

dynatrace {
    configurations {
        create("sampleConfig") {
            autoStart {
                applicationId("<YourApplicationID>")
                beaconUrl("<ProvidedBeaconURL>")
            }
        }
    }
}

Skip step 3. The apply statement is not needed, when you are using the Gradle Plugin DSL.

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.

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.

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

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.

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.

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.

apply from: 'other.gradle'

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

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

It's not possible to use different configurations for the same feature module that belongs to multiple applications.

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.

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 Gradle settings file should look like.

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

Add our plugin to the build script classpath.

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

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

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.+'
    }
}

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.+")
    }
}

plugins {
   id 'com.android.application' version '8.5.0' apply false
   id 'com.dynatrace.instrumentation' version '8.+' apply true
}

dynatrace {
    configurations {
        sampleConfig {
            autoStart {
                applicationId = '<YourApplicationID>'
                beaconUrl = '<ProvidedBeaconURL>'
            }
        }
    }
}

plugins {
   id("com.android.application") version "8.5.0" apply false
   id("com.dynatrace.instrumentation") version "8.+" apply true
}

dynatrace {
    configurations {
        create("sampleConfig") {
            autoStart {
                applicationId("<YourApplicationID>")
                beaconUrl("<ProvidedBeaconURL>")
            }
        }
    }
}

Skip step 3. The apply statement is not needed, when you are using the Gradle Plugin DSL.

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.
apply plugin: 'com.android.application'
...
apply plugin: 'com.dynatrace.instrumentation.module'

dynatrace {
configurations {
sampleConfig {
autoStart {
applicationId '<YourApplicationID>'
beaconUrl '<ProvidedBeaconURL>'
}
}
}
}
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.

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.

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.