DESK Android Gradle plugin
The DESK Android Gradle plugin can only be used for Android projects that use the Android Gradle plugin to build the app. The DESK Android Gradle must be applied to the root, either build.gradle
or build.gradle.kts
, file. This approach allows the plugin to properly configure the Android sub-projects and establish the auto-instrumentation process as part of the Android build process.
The DESK Android Gradle plugin is hosted on JCenter and Maven Central.
Note: See supported Android Gradle plugin versions for version interoperability. All technical information of the Android Gradle plugin is available at DSL reference.
Requirements
- Gradle 5.0 or higher
- Android Gradle plugin 3.1 or higher
- JVM 8
Note: The JVM version must match the Java version of the .class
files. A lower JVM version can’t be used because the classes and their dependencies are analyzed by the auto-instrumentor. If you use a third-party library that contains Java 9 .class
files, the auto-instrumentation process won't work when the app is built with JRE 8.
Instrumentation
The DESK Android Gradle plugin uses bytecode instrumentation to instrument your app. It can instrument the source files of all subprojects and third-party libraries. Performance-wise, bytecode instrumentation is quick and has a low impact on the build time. By providing support for incremental builds and the build cache, the instrumentation of apps will be almost unnoticed.
Instrumentation-specific capabilities
- Java 8 and Kotlin: The DESK Android Gradle plugin supports the instrumentation of Java 8 and Kotlin classes. It also supports other JVM languages.
- Obfuscations and optimization: The auto-instrumentation process is completed before the R8 Gradle task. If you use another tool for obfuscation, you must ensure that the obfuscation task is executed after the auto-instrumentation process.
- Security and APK-hardening tools: Bytecode instrumentation happens before obfuscation and before Android Dexer (D8) transforms the
.class
bytecode into.dex
bytecode that can be executed in the Android Runtime. Therefore, the plugin can ensure maximum compatibility with other security-focused and APK-hardening tools that calculate checksums for the DEX code, such as DexGuard and Arxan.
Instrumentation-specific limitations
The Android Gradle plugin only instruments the AndroidManifest.xml
and other .class
files. It doesn’t instrument the following components:
- Native code, such as code written with the NDK
- Web components, such as
.html
and.js
files - Resource files, such as layout
.xml
files
Compatibility with other monitoring tools
Most features of the plugin are compatible with other performance monitoring plugins. However, some of its features can be affected by other performance-monitoring plugins. For example, excluding certain classes and methods might not work as intended because the actual logic could be moved to other internal classes from the performance-monitoring library.
Build
Build-specific capabilities
The DESK Android Gradle plugin supports Gradle build-specific capabilities, including the following:
- Faster incremental builds by modifying only classes and libraries, thereby reducing instrumentation time.
- Build Cache to save build time by reusing outputs produced by other builds.
- Instant Run by reducing the time taken to update the APK with code and resource changes.
- Apply Changes for pushing code and resource changes to a running app without having to restart it. The app must be restarted only when the configuration of the plugin or OneAgent is changed.
- Build processes for Android App Bundles(AABs) and APKs.
- Multiple APK builds via the
Split
feature so that the instrumentation step is executed only once. - Support for Kotlin DSL in
build.gradle.kts
files.
Build-specific limitations
- Android library projects: The plugin supports only the auto-instrumentation of the Android application project. It doesn’t support the auto-instrumentation of stand-alone Android library projects. The internal libraries are auto-instrumented when added as a dependency to the Android application project.
- The
instantapp
module: The plugin doesn’t support the auto-instrumentation of theinstantapp
module. It only supports the auto-instrumentation of theapplication
module that generates the APK or the AAB file.
Note: We recommend that you switch to the instant-enabled app bundle project architecture.
Configuration
The Android Gradle plugin provides a wide range of configuration options to customize your Android application build and the monitored mobile user experience data.
The Gradle snippet from the Instrumentation page and the Gradle snippets from the documentation contain sample names for variant-specific configuration, such as sampleConfig
. To understand this better, see how variant-specific configurations are used.
Configure monitoring capabilities
The following options can be used to customize OneAgent SDK for Android monitoring capabilities and fine-tune the auto-instrumentation process:
- User action monitoring
- Lifecycle monitoring
- Web request monitoring
- Crash reporting
- Location monitoring
Configure instrumentation processes
The plugin also provides additional configuration options to customize the instrumentation process:
- Variant-specific configurations
- Auto-instrumentation deactivation
- Auto-start injection
- Exclusion of certain classes and methods
- Adjusting test case instrumentation
Adjust OneAgent configuration
The following configuration options can be used to adjust the default OneAgent configuration:
These options are especially useful when used along with auto-start injection. They can also be used to adjust the OneAgent configuration when approached with the manual startup, but you must be careful because the settings can easily be overridden with ConfigurationBuilder
.
Configure multi-module Android projects
The plugin scans all sub-projects and configures the auto-instrumentation process for your application modules. Most other modules are unaffected by the plugin. In the following cases, you might want to adjust the instrumentation process.