Migrate to Dynatrace 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 Dynatrace 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

If you are running the auto-instrumentation script from the command line, use the Dynatrace Android Gradle plugin. Version 8.x does not support a standalone auto-instrumentation process. In the Dynatrace 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.

Dynatrace Android Gradle plugin

The Dynatrace 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 Dynatrace Android Gradle plugin version 8.x.

Plugin adjustments

The group and artifact ID of the plugin have changed. The build script class path is com.dynatrace.tools.android:gradle-plugin:

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

Also the plugin id and the DSL are different:

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

Apply and configure the plugin in the root build.gradle file. This change gives the Dynatrace Android Gradle plugin access to all modules of your Android application project. For details, see Instrumentation via Dynatrace 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 Dynatrace Android Gradle plugin version 8.x, use the following applicationId and beaconUrl properties:

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

For details, see Auto-start injection.

Disabled auto-start injection

For Dynatrace 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.

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

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

Crash reporting

For Dynatrace 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.

dynatrace {
    configurations {
        sampleConfig {
            crashReporting false
        }
    }
}

For details, see Crash reporting.

Lifecycle monitoring

For Dynatrace 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.

dynatrace {
    configurations {
        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 Dynatrace Android Gradle plugin version 8.x, use the webRequests.enabled DSL property to deactivate web request monitoring.

dynatrace {
    configurations {
        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 Dynatrace Android Gradle plugin version 8.x, use the following DSL properties:

  • enabled
  • timeout
  • maxDuration
  • emptyActions
dynatrace {
    configurations {
        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 Dynatrace 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 Dynatrace Android Gradle plugin version 8.x, use the following DSL properties:

  • enabled
  • domains
dynatrace {
    configurations {
        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 Dynatrace 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 Dynatrace 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 Dynatrace Android Gradle plugin 8.x, use the locationMonitoring DSL property. The DTXInstrumentGPSLocation auto-instrumentation property is available only for earlier versions.

dynatrace {
    configurations {
        sampleConfig {
            locationMonitoring true
        }
    }
}

For details, see Location monitoring.

Data privacy

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

dynatrace {
    configurations {
        sampleConfig {
            userOptIn true
        }
    }
}

For details, see Data privacy.

Deactivate certificate validation

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

dynatrace {
    configurations {
        sampleConfig {
            debug {
                certificateValidation false
            }
        }
    }
}

OneAgent debug logging

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

dynatrace {
    configurations {
        sampleConfig {
            debug {
                agentLogging true
            }
        }
    }
}