Gradle Plugin for Android Configuration – Preemptive Support Center

To use the DashO™ Gradle Plugin for Android, first add it to your Gradle build and then configure it further in your buildscript.

Adding the Plugin

To apply the DashO Gradle Plugin for Android, you need to include it as a buildscript dependency on your build, which in turn requires you to add the PreEmptive Maven Repository as a buildscript repository:

buildscript {
    repositories {
        maven { url 'https://maven.preemptive.com' }
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:4.1.1'
        classpath 'com.preemptive.dasho:dasho-android:1.4.+'
    }
}

You will also need to apply the plugin after the appropriate Android plugin (i.e., com.android.application or com.android.library):

apply plugin: 'com.android.application'
apply plugin: 'com.preemptive.dasho.android'

plugins {
    id 'com.android.application'
    id 'com.preemptive.dasho.android'
}

Configuring the Plugin

The plugin can be configured via the dasho closure in your buildscript at any point after the com.preemptive.dasho.android plugin has been applied.

dasho {
    debug false
    doxFilename "project.dox"
    enabledBuildVariants "release"
    excludeFromProtection null
    home "/Applications/PreEmptive Protection DashO x.y/Contents/Java"
    javaOptions "-Xmx128m", "-Xms96m"
    libraryAssetDirs "../lib/src/main/assets"
    libraryResourceDirs "../lib/src/main/res"
    searchVersion "11"
    verbose false
}

The following properties are available for the dasho closure:

Name	Functionality	Default
`debug`	If enabled, the plugin will run DashO with the `--debug` and `--printStackTraces` options, and will print the command used to invoke DashO.	`false`
`doxFilename`	Defines the name of the DashO configuration file that DashO should use when protecting your Android project. This should refer to a file in your project directory. Note that backslashes (`\`) in this path must be escaped (`\\`) or replaced with forward slashes (`/`).	See Default DashO Configuration File
`enabledBuildVariants`	Defines the build variants that the plugin should protect. Accepts a regular expression; the plugin will protect a build variant if the variant's name contains a match for the expression, case insensitively. A blank value (`""`) will match all variants.	`release` (Matches all release variants)
`excludeFromProtection`	Defines inputs that should be excluded from protection. Accepts a regular expression; any inputs whose name contains a match by the expression, case insensitively, will be passed to DashO as a dependency instead of an input.	null (See documentation)
`protectProjectFilesOnly`	Defines whether the DashO obfuscation should skip all the jars/classes outside project directory. Accepts true or false; Default value is false but if set to true, all jars/classes outside project directory are excluded from DashO protection.	false
`home`	DashO Home; where to find `DashOPro.jar`. Don't set if specifying `searchVersion` or otherwise allowing the plugin to locate DashO automatically.	No default
`javaOptions`	Additional JVM options to use when invoking Java to run DashO. Accepts one or more Strings.	No additional options
`libraryAssetDirs`	An optional location of referenced or related library assets to be encrypted. Added in v1.2.0. Accepts one or more paths.	Don't encrypt the libraries' assets
`libraryResourceDirs`	An optional location of referenced or related library resources to be encrypted. Currently, only resources in the `raw` subdirectory will be encrypted. Added in v1.2.0. Accepts one or more paths.	Don't encrypt the libraries' raw resources
`searchVersion`	Configures the plugin to search for DashO Home given a string in the format `{major}[.{minor}]` (e.g. `11` or `11.2`). Don't set if specifying `home`.	No default
`verbose`	If enabled, the plugin will run DashO with the `--verbose` and `--printStackTraces` options, and will print the command used to invoke DashO.	`false`

The dasho closure is not required if you don't need to set any of its properties, all of which are optional.

Notes:
The DashO Gradle Plugin for Android will use the same version of Java as configured for Gradle when running DashO. This can be configured with the org.gradle.java.home setting.

The DashO Gradle Plugin for Android is not compatible with either Instant Run or Apply Changes functionality in Android Studio. If you enable DashO to run on debug build variants, you will need to disable Instant Run or not use Apply Changes.

Default DashO Configuration File

If you do not specify a DashO Configuration File with the doxFilename property of the dasho closure, the DashO Gradle Plugin for Android will search for a project file matching the current variant.

As an example, suppose you have the following build flavors and types configured:

android {
    buildTypes {
        debug { }
        release { }
    }
    flavorDimensions 'monetization', 'deviceType'
    productFlavors {
        free { dimension 'monetization' }
        paid { dimension 'monetization' }
        phone { dimension 'deviceType' }
        tablet { dimension 'deviceType' }
    }
}

For the build variant freePhoneDebug, the DashO Gradle Plugin for Android would look for project files in the same directory as the application-level build.gradle, using the first project file found in the following list:

freePhoneDebug.dox
freePhone.dox
free.dox
phone.dox
debug.dox
project.dox

Note:
The configuration file will be used twice per build variant during a standard build. Once by the encryptResources task and once by the transformClassesWithDashOFor{buildVariant} task.

Excluding from Protection

The dasho closure contains an excludeFromProtection property which allows inputs to be excluded from protection by DashO. The setting accepts a regular expression. All inputs whose name contains a match for the expression will be passed to DashO as a dependency. By default nothing is excluded.

For example, if your project has dependencies like:

 dependencies {
     implementation 'androidx.appcompat:appcompat:1.0.2'
     implementation 'androidx.recyclerview:recyclerview:1.0.0'
     implementation project(':imageViewerLibrary')
 }

...setting excludeFromProtection "androidx" will pass the androidx jars as dependencies to DashO.

This setting can be helpful if you are running a single build from which you distribute both a library (AAR) and an application (APK). You can configure DashO to protect both the library and the application and then set excludeFromProtection ":library" in your application's build.gradle file. If you are only distributing the application, do not protect the library independently; it will be protected with the application so long as you do not exclude it.

Notes:
The regular expression only needs to case-insensitively match part of the name. So view would match androidx.recyclerview:recyclerview:1.0.0 and :imageViewerLibrary.

The build will fail if you configure excludeFromProtection to match everything (e.g. excludeFromProtection ".*" or excludeFromProtection "").

Some plugins may corrupt the names making it impossible to match the original names. For example, the Firebase Performance plugin will change the name androidx.annotation:annotation:1.0.0 to something like 0a1124bfce06f9f05e9f92edcabdc725-classes. If you encounter corrupted names, please apply com.preemptive.dasho.android before those plugins (e.g. com.google.firebase.firebase-perf).

Resource Encryption

The plugin will pass resource information to DashO for Resource Encryption. It automatically finds the asset and resource directories based on your Gradle configuration. If you are building both an application and a library and would like the library's assets and raw resources encrypted, configure the libraryAssetDirs and libraryResourceDirs properties in the closure.

Running with the plugin

Once you have applied the plugin it should automatically integrate with the Android plugin. You can run gradlew dashOPluginVersion to display the full version of the plugin.

Supported Properties

The plugin supports the following properties which can be set as a Gradle project property, a Java system property or an environment variable:

DASHO_HOME - Specifies DashO Home.
DASHO_LICENSE - Specifies the license to be used by DashO. Supported by v1.3.0 and later.
DISABLE_DASHO - DashO will not process the classes if this property exists. No value is needed. All values other than false are interpreted as true.
GENERATE_DASHO_CONFIG - Tells DashO to generate a default Android Mode configuration file. No value is needed. All values other than false are interpreted as true.
SHOW_DASHO_CMD - The command line arguments used when launching DashO will be shown if this property exists. No value is needed. All values other than false are interpreted as true.

These properties can be passed on the gradlew command line via -P{name}[={value}] or -D{name}[={value}] or set in the environment.

A Gradle project property can be set in a gradle.properties file, on the command line as a -P argument (e.g. -PDASHO_LICENSE={key[:email]}) or in a system environment variable prefixed with ORG_GRADLE_PROJECT_ (e.g. ORG_GRADLE_PROJECT_DASHO_LICENSE={key[:email]}). A Java property can be set on the command line as a -D argument (e.g. -DDASHO_LICENSE={key[:email]}).

Note: An error will occur when using the GENERATE_DASHO_CONFIG property if the configuration file already exists.

License Configuration

If you need to configure the license to be used by DashO, you can specify the license string via DASHO_LICENSE as mentioned above.