Configure the DashO Gradle Plugin for Android

Add the DashO Gradle Plugin for Android to your Gradle build, apply it after the Android plugin, and use the dasho closure to configure how DashO protects your Android application or library.

Prerequisites

• An Android application or library project that builds with Gradle.
• DashO installed.
• Compatible versions of DashO, Gradle, the Android Gradle Plugin, Kotlin, and Java. See DashO Gradle Plugin for Android Version Compatibility. 

Add the Plugin

Add the PreEmptive Maven repository and the DashO plugin artifact to the buildscript in your root build.gradle file:

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.+'
    }
}

Apply the DashO plugin after com.android.application or com.android.library in the module-level build file:

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

You can also apply the plugins with the plugins block:

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

For an Android library, replace com.android.application with com.android.library.

Configure the Plugin

After applying com.preemptive.dasho.android, add a dasho closure to the module-level build file. All properties are optional.

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
}

Use the following properties to adjust the integration:

Note: includeAutoGeneratedModules has no effect unless protectProjectFilesOnly is set to true.

The plugin uses the Java version configured for Gradle. You can configure it with the org.gradle.java.home  Gradle property.

If you protect a debug variant, do not use Android Studio Apply Changes for that build. Run a complete build so the DashO protection tasks execute.

Configure the DashO project file

The plugin needs a DashO project file. Choose the procedure that matches your project:

Generate a DashO Project File

1. From the project root, run:
   ./gradlew clean assembleRelease -DGENERATE_DASHO_CONFIG
   The -DGENERATE_DASHO_CONFIG property makes the plugin generate a default Android Mode project file, project.dox. 
2. Review and configure the generated project file before you run the protection build.

Warning: Don't use -DGENERATE_DASHO_CONFIG if the project file already exists. The build reports an error if the property is enabled and a project file is already present.

How the Plugin Finds the Project File

If you set doxFileName, the plugin uses that file. Otherwise, it searches the directory that contains the application-level build.gradle file and uses the most specific file that matches the current variant. This lets you keep different DashO settings for individual variants, build types, or flavors. 

For example, for a freePhoneDebug variant, the plugin searches in this order:

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:

1. freePhoneDebug.dox
2. freePhone.dox
3. free.dox
4. phone.dox
5. debug.dox
6. project.dox

This naming behavior lets you maintain different DashO settings for individual variants, build types, or flavors.

Note: During a standard build, the selected DashO configuration can be used more than once for the variant, including by the resource-encryption and class-protection tasks.

Exclude inputs from protection

Use excludeFromProtection when an input must be available to DashO as a dependency but should not be protected as an input. The value is a regular expression matched, without case sensitivity, against the input filename.

For example:

dasho {
    excludeFromProtection "androidx"
}

This example treats inputs whose filenames contain androidx as dependencies.

Consider the following behavior when defining the expression:

• The expression is matched against the filename, not the complete Maven coordinate.
• A partial filename match is sufficient.
• Do not use an empty expression or an expression such as .* that matches every input. The build fails when every input is excluded.
• Some plugins rename dependency files before DashO processes them. If filenames become non-descriptive, apply com.preemptive.dasho.android before the plugin that renames them.

For example:

plugins {
    id 'com.android.application'
    id 'com.preemptive.dasho.android'
    id 'com.google.firebase.firebase-perf'
}

If you cannot change the plugin order, set protectProjectFilesOnly to true to exclude third-party libraries outside the project directory.

When an application includes a library project, do not protect the library separately unless you also distribute the library as its own protected artifact. Protecting both the library and the application can cause DashO to process the same code more than once.

Configure Resource Encryption for libraries

The plugin automatically obtains the application asset and resource locations from the Android Gradle configuration. If you build both an application and a library and want DashO to encrypt assets or raw resources from the library, configure libraryAssetDirs and libraryResourceDirs.

dasho {
    libraryAssetDirs "../lib/src/main/assets"
    libraryResourceDirs "../lib/src/main/res"
}

Only files in the library resource directory’s raw subdirectory are eligible for Resource Encryption.

Configure Android library dependencies

If DashO reports missing external classes while processing an AAR, enable runtimeJars so the plugin loads the runtime JAR dependencies required by the library:

dasho {
    runtimeJars = true
}

If protectProjectFilesOnly is enabled and generated classes must also be protected, enable includeAutoGeneratedModules:

dasho {
    protectProjectFilesOnly true
    includeAutoGeneratedModules true
}

Run and verify the plugin

Run the Gradle build task for a variant that enabledBuildVariants matches. The plugin adds its protection tasks to that build.

Build a Release Variant

From the project root, run:

./gradlew clean assembleRelease

The plugin uses the project file that doxFilename specifies, or the file it finds with its default discovery rules.

Build a Debug Variant

By default, the plugin protects only release variants. To protect debug builds:

1. Set enabledBuildVariants so it matches the debug variant. enabledBuildVariants is a case-insensitive regular expression, so one value can match both build types:

dasho {
    enabledBuildVariants "release|debug"
}

To protect every variant, use an empty string.

2. From the project root, run:
   ./gradlew clean assembleDebug

Warning: When you protect a debug variant, don't use Android Studio Apply Changes for that build. Run a complete build so the DashO protection tasks run.

Verify the Build

1. Display the installed DashO Android plugin version:
   ./gradlew dashOPluginVersion
2. Check that the build output identifies the DashO version and completes without a DashO error.

Supported build properties

The plugin supports the following Gradle project properties, Java system properties, and environment variables:

You can pass a property on the Gradle command line with -P{name}[={value}] or -D{name}[={value}]:

gradlew build -PDASHO_HOME=<path-to-dasho-home>
gradlew build -DDASHO_HOME=<path-to-dasho-home>

You can also define Gradle project properties in gradle.properties. To supply a Gradle project property through the environment, prefix it with ORG_GRADLE_PROJECT_.

For example:

ORG_GRADLE_PROJECT_DASHO_LICENSE={key[:email]}

Note: GENERATE_DASHO_CONFIG returns an error if the target configuration file already exists.

Configure the license

Use DASHO_LICENSE when the build must provide a DashO license string through a Gradle project property, Java system property, or environment variable.

For example:

gradlew build -PDASHO_LICENSE={key[:email]}

Avoid storing an unprotected license string in source control.

Related articles

• Configuring DashO Home
• Enable R8 for the DashO Android Integration
• Gradle Plugin for Android Troubleshooting