Free trial

Configure DESK Android Gradle plugin for instrumentation processes

The following configuration options allow you to customize the instrumentation process of the DESK Android Gradle plugin.

Variant-specific configurations

The plugin allows you to specify multiple variant-specific configurations, where each variant-specific configuration can be applied to multiple Android build variants. You must provide a variant-specific configuration for every variant. If the plugin is unable to find a variant-specific configuration for a certain Android build variant, it cancels the build and throws an error. This protection feature can be deactivated with the strictMode property.

The association is determined by the regex, that is specified in the variantFilter property, and the variant name of the Android build variant. The regex is case-sensitive and if no product flavor is defined, the build type in the variant name is lower case. If multiple variant-specific configurations match the same variant, the first configuration is selected and applied.

The following sample shows how you can specify a variant-specific configuration in the desk block:

desk {
    configurations {
        dev {
            // build type name is upper case because a product flavor is used
            variantFilter "Debug"
            // other variant-specific properties
        }
        demo {
            // the first product flavor name is always lower case
            variantFilter "demo"
            // other variant-specific properties
        }
        prod {
            // build type name is upper case because a product flavor is used
            variantFilter "Release"
            // other variant-specific properties
        }
    }
}

For example, you can have an app that has two product flavors, demo and paid, and two default build types, debug and release. The plugin can be used to specify a variant-specific configuration for all debug build variants, demoDebug and paidDemo, and another two variant-specific configurations for the two variants, demoRelease and paidRelease.

The association between variant-specific configurations from the plugin and the Android build variants can be printed with the printVariantAffiliation task. For example, the following sample shows the console output of the above example:

> Task :app:printVariantAffiliation
Variant 'demoDebug' will use configuration 'dev'
Variant 'demoRelease' will use configuration 'demo'
Variant 'paidDebug' will use configuration 'dev'
Variant 'paidRelease' will use configuration 'prod'

Separate development and production monitoring data

If you don't want to pollute your production monitoring data with monitoring data from your debug builds, separate the development data from the production monitoring data.

To do this, create two mobile apps in DESK. Generate two variant-specific configurations and use the provided applicationId and beaconUrl values from the Instrumentation page.

desk {
    configurations {
        debug {
            variantFilter "[dD]ebug"
            autoStart {
                applicationId '<DebugApplicationID>'
                beaconUrl '<ProvidedBeaconURL>'
            }
        }
        prod {
            variantFilter "[rR]elease"
            autoStart {
                applicationId '<ProductionApplicationID>'
                beaconUrl '<ProvidedBeaconURL>'
            }
        }
    }
}

If you prefer to not monitor your debug builds, disable the variant-specific configuration that is responsible for your debug builds.

desk {
    configurations {
        debug {
            variantFilter "[dD]ebug"
            enabled false
        }
        prod {
            variantFilter "[rR]elease"
            autoStart {
                applicationId '<ProductionApplicationID>'
                beaconUrl '<ProvidedBeaconURL>'
            }
        }
    }
}

Deactivate auto-instrumentation

You can deactivate auto-instrumentation for all variants or for a specific variant.

Deactivate all variants

To deactivate auto-instrumentation for all variants, deactivate the plugin with the pluginEnabled property. The plugin still adds OneAgent SDK as Gradle dependency to ensure that the compiler can compile the manually instrumented source files.

With this setting, the verification step of the plugin is deactivated. Also, the auto-start feature is deactivated and the app stops being monitored. If you start the agent manually, the app is monitored, but OneAgent can capture only mobile user experience data that is instrumented by manual calls to the OneAgent SDK.

You can deactivate auto-instrumentation for all variants or for a specific variant.

desk {
    pluginEnabled false
    configurations {
        dev {
            // variant-specific properties
        }
        prod {
            // variant-specific properties
        }
    }
}

Deactivate one variant

If you want to deactivate auto-instrumentation for a specific variant, explicitly deactivate the variant-specific configuration via the enabled property. The following example shows how you can deactivate all debug build types (variant demoDebug and paidDebug):

desk {
    configurations {
        dev {
            enabled false
            variantFilter "Debug"
        }
        prod {
            // variant-specific properties
        }
    }
}

Auto-start injection

To obtain the correct startup parameters, go to the DESK Instrumentation page of your mobile app. Use the preconfigured snippet that is already populated with the configuration values from your mobile app. All OneAgent start-up related properties are part of the AutoStart DSL and must be configured via the autoStart block:

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

The auto-start injection feature starts OneAgent in the Application.onCreate method. If your app supports Direct Boot, you have to deactivate the auto-start injection feature. You should also read the section Adjust OneAgent communication to ensure that OneAgent is able to transmit the data to the cluster.

Deactivate auto-start injection

You can deactivate the auto-start injection feature with the enabled property. You cannot specify the applicationId and the beaconUrl properties because these values must be used in the manual startup call.

desk {
    configurations {
        sampleConfig {
            autoStart.enabled false
        }
    }
}

Add the startup call manually to the Application.onCreate method. For more information, see Start OneAgent in the OneAgent SDK documentation.

DESK.startup(this, new DESKConfigurationBuilder("YourApplicationID", "ProvidedBeaconURL")
	... // additional configuration
	.buildConfiguration());

Note: Additional configuration changes specified via DESKConfigurationBuilder override the configuration values defined via the Android Gradle plugin DSL.

Exclude certain classes and methods

Auto-instrumentation instruments all packages by default. If you want to exclude certain classes, you have two options:

Exclude a list of packages, classes, and methods via the packages, classes, and methods properties 

desk {
    configurations {
        sampleConfig {
            exclude {
                packages "com.mypackage", "com.another.example"
                classes "com.example.MyClass"
                methods "com.example.ExampleClass.exampleMethod", "com.example.ExampleClass\$InnerClass.anotherMethod"
            }
        }
    }
}

These properties contain some additional features:

  • packages automatically excludes sub-packages
  • classes automatically excludes inner classes
  • methods automatically excludes all methods with the same name (regardless of the method signature)

Note: Escape the $ character for inner classes as shown in the above example.

Use the custom exclude filter

This option allows you to define a finer granular exclusion logic via additional filter rules. In the filter you can define a regex for className, methodName, and methodDescription.

  • For the className property, the fully qualified name is used.
  • A class name matches when the specified expression is found somewhere in the class name
  • A method name matches when the specified expression is found somewhere in the method name
  • A method description matches when the specified expression is found somewhere in the method description
desk {
    configurations {
        sampleConfig {
            exclude {
                // exclude all inner classes
                filter {
                    className "\$"
                }

                // exclude all methods that fulfill this requirements
                filter {
                    // the class is part of the "com.example" package
                    className "^com\\.example\\."
                    // the method name contain the phrase "webrequest" (uppercase notation is ignored for two letters)
                    methodName "[wW]eb[rR]equest"
                    // where the last parameter is a String and where the return value is void
                    methodDescription "Ljava/lang/String;\\)V"
                }
            }
        }
    }
}

Adjust test case instrumentation

The plugin only executes the auto-instrumentation step when the app is built. Therefore, the behavior of local unit tests and instrumented unit tests is different.

Local unit tests

Local unit tests directly use the classes generated by the Java (or Kotlin) compiler and the auto-instrumentation step of the plugin is never executed. Because method calls to OneAgent SDK are placed in the source code, they are also available and executed in your local unit tests. However, OneAgent is not started and the method calls are ignored.

Local unit tests with Robolectric

Robolectric allows you to simulate Android in your local unit tests. Like regular unit tests, Robolectric uses the classes generated by the compiler that are not auto-instrumented. But if you have deactivated auto-start injection and started OneAgent manually in the Application class, the agent runs and monitors your Robolectric test cases. In this case, adjust your configuration by either separating development and production monitoring data or using a different build type for unit tests.

Instrumented unit tests

To run instrumented unit tests on a device or emulator, the Android build generates two APK files. First, the APK file of the app you want to test is generated. The plugin is part of this build process and auto-instruments the APK file. The Android build generates a test APK that contains the class for testing the other APK. The plugin is also part of this build process. But it will notice that a test APK is generated and therefore doesn’t auto-instrument these test APKs.

Because the APK is instrumented, every instrumented unit test is monitored. In this case, you should adjust your configuration by either separating development and production monitoring data or using a different build type for unit tests.

Use a different build type for unit tests

For a customized instrumentation behavior for your unit tests, generate a new build type for your unit tests with the plugin.

android {
    buildTypes {
        // build type used for unit tests in the CI
        CI {
            initWith debug
            applicationIdSuffix ".debugTesting"
        }
    }
}

For example, if you want to monitor your debug builds used by the developers and you don't want to monitor the unit test execution in the CI, use the following configuration:

desk {
    configurations {
        developer {
            variantFilter "[dD]ebug"
            autoStart {
                applicationId '<DebugApplicationID>'
                beaconUrl '<ProvidedBeaconURL>'
            }
        }
        ciTesting {
            // deactivate instrumentation for CI tests
            variantFilter "CI"
            enabled false
        }
        prod {
            variantFilter "[rR]elease"
            autoStart {
                applicationId '<ProductionApplicationID>'
                beaconUrl '<ProvidedBeaconURL>'
            }
        }
    }
}

Note: When developers execute the unit tests with the debug variant, unit tests are monitored because the instrumentation is deactivated only for the CI variant.