DESK Gradle plugin for Android app auto-instrumentation

The DESK Gradle plugin does not support the instrumentation of Android App Bundles.

The DESK Gradle plugin is based on the Android Gradle plugin. The DESK Gradle plugin inserts auto-instrumentation at the end of the Android build task sequence. Auto-instrumentation gets triggered by the Android build process and instruments your newly build APK file. The instrumented APK file is also automatically signed with the specified certificate. The DESK Gradle plugin stores the instrumented and signed APK file under the same name in the same location (<project>/<module>/build/outputs/apk/<productFlavor>/<buildType>/<app_name>.apk). The advantage of this approach is that the Run button from the Android Studio can use the instrumented APK file and can install it on your device/emulator.

Supported Android Gradle plugin versions

The DESK Gradle plugin is hosted on JCenter and Maven Central. For details on DESK Gradle plugin version and Android Gradle plugin version interoperability, please see supported Android Gradle plugin versions.

Run auto-instrumentation using DESK Gradle plugin

To run auto-instrumentation using DESK Gradle plugin:

Click Applications in the navigation menu.

Select your mobile application.

Click the browse button (...) in the top right corner and select Edit.

Click Instrumentation in the left menu.

Select Google Android.

Select the Gradle tab. In this tab, you will find the following Gradle snippet that is already populated with the configuration values from your mobile app:

Gradle snippet Gradle snippet prior to OneAgent 7.2.2

buildscript {
repositories {
  jcenter()
  }
  dependencies {
   classpath 'com.desk.tools:android:7.+'
  }
}

apply plugin: 'com.desk.tools.android'
desk {
 defaultConfig {
   applicationId '<YourApplicationID>'
   beaconURL '<ProvidedBeaconURL>'
 }
}

Alternatively, you can deactivate the auto-start injection feature from the auto-instrumentor with the DTXAutoStart property. In this case you don't need to specify the DTXApplicationID and the DTXBeaconURL properties, because you have to specify these values in the manual startup call. You have to add the startup call manually into the Application.onCreate method and load the auto-instrumentation configuration with the DESKConfigurationBuilder.loadDefaultProperties(Context) method. For more information, see the OneAgent SDK for Mobile section.

DESK.startup(this, new DESKConfigurationBuilder("YourApplicationID", "ProvidedBeaconURL")
	.loadDefaultProperties(context)
	...
	.buildConfiguration());

Gradle configuration for SaaS

buildscript {
repositories {
  jcenter()
  }
  dependencies {
   classpath 'com.desk.tools:android:7.+'
  }
}

apply plugin: 'com.desk.tools.android'
desk {
 defaultConfig {
   applicationId '<YourApplicationID>'
   environmentId '<YourEnvironmentID>'
   cluster '<ProvidedClusterUrl>'
 }
}

Gradle configuration for Managed

For DESK Managed you have to enable the DTXManagedCluster property.

buildscript {
 repositories {
   jcenter()
 }
 dependencies {
   classpath 'com.desk.tools:android:7.+'
 }
}

apply plugin: 'com.desk.tools.android'
desk {
 defaultConfig {
   applicationId '<YourApplicationID>'
   environmentId '<YourEnvironmentID>'
   cluster '<YourSecurityGatewayUrl>'
   agentProperties 'DTXManagedCluster': 'true'
 }
}

Or deactivate the auto-start injection feature from the auto-instrumentor with the DTXAutoStart property. In this case you don't need to specify the DTXApplicationID, DTXAgentEnvironment, DTXClusterURL and DTXManagedCluster properties, because you have to specify these values in the manual startup call. You have to add the startup call manually into the Application.onCreate method and load the auto-instrumentation configuration with the DESKConfigurationBuilder.loadDefaultProperties(Context) method. For more information, see the OneAgent SDK for Mobile section.

DESK.startup(this, new DESKConfigurationBuilder("YourApplicationID", "YourEnvironmentID", "ProvidedClusterUrl", /* only for Managed: */ true)
	.loadDefaultProperties(context)
	...
	.buildConfiguration());

Copy this Gradle snippet into your module's build.gradle file and the DESK Gradle plugin will automatically instrument your mobile app on every build. Of course, if you are familiar with Gradle, you can customize the Gradle snippet. In this case, you have to ensure that the DESK Gradle plugin dependency is added to your build script. Additionally, the apply statement and the desk extension block must be added to the same build.gradle file that also contains the apply statement of the Android Gradle plugin.

You can optionally perform additional configuration.

Use advanced auto-instrumentation settings

The DESK Gradle plugin lets you customize auto-instrumentation with the agentProperties plugin property. Every auto-instrumentation property can be used. The property syntax is a key-value list, where the elements are separated by a comma and the key-value pair is separated by a colon. For example:

desk {
  defaultConfig {
    applicationId '<YourApplicationID>'
    beaconURL '<ProvidedBeaconURL>'
    agentProperties 'DTXCrashReportingEnabled': 'false', 'DTXAutoActionTimeoutMilliseconds': '1000'
  }
}

In case you have a multidex app, check the auto-instrumentation properties specific for multidex apps.

Use OneAgent SDK for Mobile to enrich mobile user experience data

When you plan to enrich mobile user experience data using OneAgent SDK for Mobile, you have to add the SDK library as a dependency to your project. The DESK Gradle plugin can automate this process for you. You can thus automatically update the Mobile OneAgent library with the DESK Gradle plugin and ensure that the Mobile OneAgent library and the auto-instrumentation will always have the same version. You can enable the Mobile OneAgent API by adding the following Gradle snippet to your build.gradle file:

dependencies {
	implementation desk.agent()
}

Note:

For multi-dex applications, ensure all OneAgent for Android classes are in the primary .dex file. Use the multiDexKeepProguard Android plugin property and add the line
-keep class com.desk.android.** { *; }
to the provided file. For example:

buildTypes {
    release {
        multiDexKeepProguard file('<your_keep_file>')
    }
}

Report to different mobile applications

When your Android build generates different mobile apps with the Product Flavors feature from the Android Gradle plugin, then you can also specify different configurations. The DESK Gradle plugin checks for every product flavor, if you've specified a configuration in the productFlavors block of the desk extension. If no configuration is available, the defaultConfig configuration is used. This feature is very useful, when you don't want to pollute your production monitoring with the monitoring data from the R&D and acceptance team.

desk {
  defaultConfig {
    applicationId '<DEV_ApplicationID>'
    beaconURL '<ProvidedBeaconURL>'
  }

  productFlavors {
    prod {
      applicationId '<PROD_ApplicationID>'
      beaconURL '<ProvidedBeaconURL>'
    }
  }
}

Use a Gradle property to deactivate auto-instrumentation

Currently the DESK Gradle plugin contains no option to deactivate auto-instrumentation dynamically. Instead you can use a Gradle property to activate or deactivate the plugin. For example:

if(project.hasProperty('instrument')) {
  apply plugin: 'com.desk.tools.android'
  desk {
    defaultConfig {
      applicationId '<YourApplicationID>'
      beaconURL '<ProvidedBeaconURL>'
    }
  }
}

You can activate the DESK Gradle plugin by adding the -Pinstrument parameter to your build command. If you want to build an instrumented release version, execute the
gradlew assembleRelease -Pinstrument
command. This feature is very useful, when the mobile app should only be instrumented in the CI build.

Start your next build.

Signing

The DESK Gradle plugin uses the signing configuration and logic from the Android Gradle plugin. You don't have to add any additional settings to the DESK Gradle plugin.

android {
    ...
    defaultConfig {  }
    signingConfigs {
        release {
            storeFile file("my-release-key.jks")
            storePassword "password"
            keyAlias "my-alias"
            keyPassword "password"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            ...
        }
    }
}

Limitations

Do NOT use whitespaces in your project path.
Do NOT use the Android Studio feature Instant Run. With Android Studio version 2 and later, Android introduced the new feature Instant Run. This feature significantly reduces the app update time. The DESK Gradle plugin for Android does not support Instant Run APKs and the corresponding Gradle build process. You should disable the Instant Run setting. To do this, open the Settings and navigate to Build, Execution, Deployment > Instant Run. Then clear the Enable Instant Run check box.
The APK Signature Scheme v3 is currently not supported.

See the auto-instrumentation limitations for more information.