Migrate to Dynatrace Android Gradle plugin version 8.x

Android Agent SDK

Property files for ConfigurationBuilder

Support for adjusting the Android Agent 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:

Download
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:

Download
apply plugin: 'com.dynatrace.instrumentation'
dynatrace {
    configurations {
        sampleConfig {
            autoStart {
                applicationId '<YourApplicationID>'
                agentPath '<YourAgentPathUrl>'
            }
        }
    }
}

Note

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-instrumentation properties for auto-start injection are available only for earlier versions:

  • DTXApplicationID
  • DTXAgentStartupPath

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

Download
dynatrace {
    configurations {
        sampleConfig {
            autoStart {
                applicationId '<YourApplicationID>'
                agentPath '<YourAgentPathUrl>'
            }
        }
    }
}

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.

Download
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 Android Agent 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.

Download
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.

Download
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.

Download
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
Download
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 JavaScript agent 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
Download
dynatrace {
    configurations {
        sampleConfig {
            hybridWebView {
                enabled true
                domains '<domain1>', '<domain2>'
                domains '<anotherDomain>'
            }
        }
    }
}

For details, see Hybrid apps that use the JavaScript agent 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.

Download
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.

Download
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.

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

Agent 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.

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