Configure multi-module Android projects with DESK Android Gradle plugin

The DESK Android Gradle plugin scans all subprojects and configures the auto-instrumentation process for your application modules. Most other modules are not affected by the plugin and in some cases, such as Android library modules, you might want to adjust the instrumentation process.

The following section describes the behavior of the plugin for certain module types and architectures.

Android library modules

All Android/Java libraries (and third-party libraries) are auto-instrumented when they are part of your Android application. No additional configuration is needed because 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 library modules, add the OneAgent SDK manually as Gradle dependency.

Note: You must use the same version for the OneAgent SDK and the DESK Android Gradle plugin. It’s recommended that you specify the OneAgent SDK dependency via the DESK Android Gradle plugin.

If you have multiple library projects in your multi-module project and want to use the OneAgent SDK in every library module, use the following Gradle snippet:

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

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

You can also use other Gradle features to fine-tune this behavior. For example, the following Gradle snippets use the module name to determine if the OneAgent SDK must 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.desk.tools.android.DESKPlugin.agentDependency()
            }
        }
    }
}

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

Android projects with dynamic-feature architecture

Android Gradle plugin 3.2 supports dynamic delivery. Apps can consist of a base module and one or more dynamic feature modules. Dynamic feature modules can be loaded on-demand or even as a single instant feature without having the whole app to be installed.

The base module applies the com.android.application plugin whereas the dynamic feature modules apply the com.android.dynamic-feature plugin. When you build the app, the plugin auto-instruments both plugin types. The same configuration is used for all modules.

With the auto-start injection feature, the plugin instruments the Application class of the base module. This ensures that the agent is always running, even when a dynamic feature runs in instant mode.

Instant delivery and manual startup

If you want to deactivate the auto-start injection feature and start the agent manually in your code, beware of the impact it may have on instant-enabled dynamic feature modules. Instant-enabled modules are intended to run on a device without being installed. This means that only the base module and the instant-enabled dynamic feature module are shipped to the device.

For the agent to function properly it must be started in the base module, preferably in the Application class of the base module and not in a class or method that is not invoked in time by the instant module.

Instrumenting Android build variants

If you use product flavors in your modules, use the same product flavor names and dimensions in every module. When you use the missingDimensionStrategy property of the plugin, ensure that each variant in every module is associated with the correct variant-specific configuration by adjusting the variant filter property. You can use the printVariantAffiliation task to determine the associations between variants and configurations.

Android projects with instant-app architecture

Some Android application projects use the com.android.feature plugin together with the com.android.instantapp plugin to create instant apps. This approach was introduced with Android Gradle Plugin 3.0 but is now deprecated. If your Android application project uses this approach, the plugin won't support it. Such projects use two different builds: one to generate an installable APK by using com.android.application plugin and one to build an instant app archive by using com.android.instantappplugin.

The plugin can only auto-instrument the build that generates the installable APK. The instant app build is not supported and therefore the feature APKs in the instantapp-<variant>.zip are not instrumented. You are advised to not deactivate the auto-start injection feature because then you will have to manually start OneAgent. The manual startup will be part of the instant app and will only partially monitor your app because the instant app is not auto-instrumented.

We, therefore, recommend migrating to the newer dynamic feature approach. If migrating does not work for you and you want to monitor your instant app, use the standalone manual instrumentation instead of the plugin.