Migrate to DESK Android Gradle plugin version 8.x

OneAgent SDK

Property files for ConfigurationBuilder

Support for adjusting the OneAgent configuration with properties files is not available in the DESK Android Gradle plugin version 8.x. This change includes the following methods:

loadDefaultProperties(Context)
loadProperties(Context, InputStream)
loadProperties(Context, Map<String,String>)
loadPropertiesFromAssets(Context, String)

Use the correct ConfigurationBuilder methods.

Method error codes

Support for method error codes has been dropped and all affected method signatures have been adjusted.

Run auto-instrumentation script auto-instrumentation script

If you are running the auto-instrumentation script from the command line, use the DESK Android Gradle plugin. Version 8.x does not support a standalone auto-instrumentation process. In the DESK Android Gradle plugin version 8.x the auto-instrumentation process is fully integrated into the Android build and can't be executed outside of a build with the Android Gradle plugin.

DESK Android Gradle plugin

The DESK Android Gradle plugin version 8.x uses a different approach for instrumenting your Android application project. Therefore, several changes must be made to migrate to this plugin version. This version can't be used along with any previous versions of the plugin. Therefore, we recommend that your remove all build.gradle file modifications from the plugin version you are currently using and then perform the steps in the following sections to migrate to DESK Android Gradle plugin version 8.x.

Plugin adjustments

The group and artifact id of the plugin have changed. The build script class path is om.desk.tools.android:gradle-plugin:

Groovy Kotlin

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:<version>'
        // add this line to your build.gradle file
        classpath 'com.desk.tools.android:gradle-plugin:8.+'
    }
}

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:<version>")
        // add this line to your build.gradle file
        classpath("com.desk.tools.android:gradle-plugin:8.+")
    }
}

Also the plugin id and the DSL are different:

Groovy Kotlin

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

apply(plugin = "com.desk.instrumentation")
configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            autoStart {
                applicationId("<YourApplicationID>")
                beaconUrl("<ProvidedBeaconURL>")
            }
        }
    }
}

Note: Apply and configure the plugin in the root build.gradle file. This change gives the DESK Android Gradle plugin access to all modules of your Android application project. For details, see Instrumentation via DESK Android Gradle plugin.

Auto-start injection

The following auto-instrumention properties for auto-start injection are available only for earlier versions:

DTXApplicationID
DTXBeaconURL
DTXAgentEnvironment
DTXClusterURL
DTXManagedCluster

For the DESK Android Gradle plugin version 8.x, use the following applicationId and beaconUrl properties:

Groovy Kotlin

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

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            autoStart {
                applicationId("<YourApplicationID>")
                beaconUrl("<ProvidedBeaconURL>")
            }
        }
    }
}

For details, see Auto-start injection.

Disabled auto-start injection

For DESK Android Gradle plugin 8.x, use the autoStart.enabled DSL property to deactivate lifecycle monitoring. The DTXAutoStart auto-instrumentation property is available only for earlier versions.

Groovy Kotlin

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

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            autoStart.enabled(false)
        }
    }
}

You don't have to use the ConfigurationBuilder.loadDefaultProperties(Context) method to load the auto-instrumentation configuration. The DESK Android Gradle plugin version 8.x adjusts OneAgent automatically based on your DSL configuration. For details, see Deactivate auto-start injection.

Crash reporting

For DESK Android Gradle plugin 8.x, use the crashReporting DSL property to deactivate crash reporting. The DTXCrashReportingEnabled auto-instrumentation property is available only for earlier versions.

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            crashReporting false
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            crashReporting(false)
        }
    }
}

For details, see Crash reporting.

Lifecycle monitoring

For DESK Android Gradle plugin 8.x, use the lifecycle.enabled DSL property to deactivate lifecycle monitoring. The DTXCrashReportingEnabled auto-instrumentation property is available only for earlier versions.

Groovy Kotlin

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

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            lifecycle.enabled(false)
        }
    }
}

For details, see Lifecycle monitoring.

Web request monitoring

The following auto-instrumention properties are available only for earlier versions:

DTXInstrumentWebRequestTagging
DTXInstrumentWebRequestTiming

For the DESK Android Gradle plugin version 8.x, use the webRequests.enabled DSL property to deactivate web request monitoring.

Groovy Kotlin

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

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            webRequests.enabled(false)
        }
    }
}

For details, see Web request monitoring.

Note: Obfuscation is supported, so you can remove the ProGuard rule -keep class okhttp3.** { *; }.

User action monitoring

The following auto-instrumention properties are available only for earlier versions:

DTXInstrumentAutoUserAction
DTXAutoActionTimeoutMilliseconds
DTXAutoActionMaxDurationMilliseconds
DTXSendEmptyAutoAction

For the DESK Android Gradle plugin version 8.x, use the following DSL properties:

enabled
timeout
maxDuration
emptyActions

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            userActions {
                // your user action monitoring configuration
            }
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            userActions {
                // your user action monitoring configuration
            }
        }
    }
}

For details, see User action monitoring.

Auto-instrumentation properties for multidex apps

The following auto-instrumention properties are available only for earlier versions:

DTXMultiDexKeep
DTXMultiDexKeepFile
DTXPrimaryDexLimit
DTXSecondaryDexLimit

Multidex customization is not needed in DESK Android plugin version 8.x.

Hybrid apps that use the RUM JavaScript tag inside a WebView

The following auto-instrumention properties are available only for earlier versions:

DTXHybridApplication
DTXSetCookiesForDomain

For the DESK Android Gradle plugin version 8.x, use the following DSL properties:

enabled
domains

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            hybridWebView {
                enabled true
                domains '<domain1>', '<domain2>'
                domains '<anotherDomain>'
            }
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            hybridWebView {
                enabled(true)
                domains("<domain1>", "<domain2>")
                domains("<anotherDomain>")
            }
        }
    }
}

For details, see Hybrid apps that use the RUM JavaScript tag inside a WebView.

Exclude certain classes and methods

The following auto-instrumention properties are available only for earlier versions:

DTXIncludeAllPackages
DTXIncludePackages
DTXExcludePackages

All classes are instrumented in the DESK Android Gradle plugin version 8.x. However, you can exclude classes and methods via the ExcludeOptions DSL.

Adjust version code and name

The following auto-instrumentation properties are available only for earlier versions:

DTXVersionCode
DTXVersionName

The DESK Android Gradle plugin version 8.x is part of the Android build process. You don't have to adjust these values outside the build process because there is no standalone auto-instrumentation process.

The version code and name values for your APK are obtained from the Android Gradle plugin DSL.

Location monitoring

For DESK Android Gradle plugin 8.x, use the locationMonitoring DSL property. The DTXInstrumentGPSLocation auto-instrumentation property is available only for earlier versions.

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            locationMonitoring true
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            locationMonitoring(true)
        }
    }
}

For details, see Location monitoring.

Data privacy

For DESK Android Gradle plugin 8.x, use the userOptIn DSL property. The DTXUserOptIn auto-instrumentation property is available only for earlier versions.

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            userOptIn true
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            userOptIn(true)
        }
    }
}

For details, see Data privacy.

Deactivate certificate validation

For DESK Android Gradle plugin 8.x, use the certificateValidation DSL property. The DTXAllowAnyCert auto-instrumentation property is available only for earlier versions.

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            debug {
                certificateValidation false
            }
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            debug {
                certificateValidation(false)
            }
        }
    }
}

OneAgent debug logging

For DESK Android Gradle plugin 8.x, use the agentLogging DSL property. The DTXLogLevel auto-instrumentation property is available only for earlier versions.

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            debug {
                agentLogging true
            }
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            debug {
                agentLogging(true)
            }
        }
    }
}