Developer Guides
Developer GuidesAPI ReferenceHelp CenterEngineering BlogCommunityOpen App

Heap Gradle Plugin

Suggest Edits

Requirements + Known Limitations

The Heap Gradle Plugin:

  • Is hosted through Maven Central.
  • Supports version 0.1.0 and higher of the Heap Android View Autocapture SDK.
  • Supports version 1.10.5 and higher of the legacy Heap Android Client SDK.
  • Requires version 7.2 or higher of the Android Gradle Plugin.
  • Is fully compatible with Android Gradle Plugin 8.0.

Plugin Installation

Modern Gradle Plugin Syntax

  1. Verify that your project is set up to retrieve plugins and dependencies from Maven Central. Android Studio will likely have configured your project in this way when you created it. To verify, make sure the pluginManagement.repositories block and dependencyResolutionManagement.repositories block in your project’s settings.gradle file (or settings.gradle.kts file) both call mavenCentral() like so:
pluginManagement {
    repositories {
        ...
        mavenCentral()
    }
}
dependencyResolutionManagement {
    repositories {
        ...
        mavenCentral()
    }
    ...
}

pluginManagement {
    repositories {
        ...
        mavenCentral()
    }
}
dependencyResolutionManagement {
    repositories {
        ...
        mavenCentral()
    }
    ...
}
  1. At the top of your application module’s build.gradle file (not the project’s build.gradle file), pull in the io.heap.gradle plugin as shown below.

📘

This has to come after the com.android.application plugin has been applied.

plugins {
    id 'com.android.application'
    ...
    id 'io.heap.gradle' version '0.3.+'
}

plugins {
    id("com.android.application")
    ...
    id("io.heap.gradle") version "0.1.+"
}

Legacy Gradle Plugin Syntax

If you are using legacy Gradle plugin syntax to pull in Android’s build tools, you'll need to integrate the Heap Android Gradle Plugin in the following manner:

  1. In your project’s build.gradle file, configure your buildscript block to use Maven Central as one of its repositories and add the Heap plugin to the class path:
pluginManagement {
    ...
}
buildscript {
    repositories {
        ...
        mavenCentral()
    }
    dependencies {
        ...
        classpath 'io.heap.gradle:heap-plugin:0.3.+'
    }
}
  1. In your application module’s build.gradle file (not the project’s build.gradle) file, apply the io.heap.gradle plugin as shown below.

📘

This has to come after the com.android.application plugin has been applied.

...
apply plugin: 'com.android.application'
apply plugin: 'io.heap.gradle'

Dependency Installation

  1. In the dependencies block of your application module’s build.gradle file, add the desired Heap autocapture SDK as an implementation dependency:
dependencies {
    ...
    // NOTE: Only add one of these depending on your desired install path.
    
    // Heap Android View Autocapture SDK
    implementation 'io.heap.autocapture:heap-autocapture-view:0.3.+'
    // Legacy Heap Android SDK
    implementation 'com.heapanalytics.android:heap-android-client:1.10.+'
}

dependencies {
    ...
    // NOTE: Only add one of these depending on your desired install path.
    
    // Heap Android View Autocapture SDK
    implementation("io.heap.autocapture:heap-autocapture-view:0.1.+")
    // Legacy Heap Android SDK
    implementation("com.heapanalytics.android:heap-android-client:1.10.+")
}
  1. Complete the instructions in the Initializing Heap section.
  2. Build your app!

Initializing Heap

To use Heap on Android, you need to initialize the installed Heap SDK. Please consult the SDK-specific docs for instructions on how to initialize Heap.

Configuration

The Heap Gradle Plugin supports optional extension properties to customize instrumentation behavior and certain capture behaviors. These extension properties can be defined in your application module’s build.gradle file by including an ext block in defaultConfig or in any of your applications build types or product flavors. The table below defines the support extension properties.

📘

All property names are case sensitive.

PropertyTypeDefaultDescription
heapAutoInitBooleanfalseBoolean setting to enable initialization configuration at build time.

If this is false, you must initialize Heap programmatically.

If this is true, you must also set heapEnvId to a stringified 53-bit integer.
heapCaptureAdvertiserIdBooleanfalseBoolean setting to enable Advertiser ID capture.
heapCaptureAndroidIdBooleanfalseBoolean setting to enable Android ID capture.
heapDisableTextCaptureBooleanfalseBoolean setting to disable text capture on views.
heapEnabledBooleantrueBoolean setting to enable build-time instrumentation for autocapture.

If this is set to false, UI interactions will not be autocaptured.
heapEnvIdStringnullThe Environment ID to use for initialization configuration at build time.

This setting only takes effect if heapAutoInit is set to true. It must be set to the 53-bit stringified integer Env ID that you wish to send data to.

Setting heapEnvId to an invalid or empty string when heapAutoInit is set to true will result in Heap failing to initialize at run-time. Likewise, failure to set heapEnvId or setting heapEnvId to null when heapAutoInit is true will result in Heap failing to initialize at run-time.

📘

Changes from Legacy Instrumentor (heap-android-gradle)

  1. heapEnabled defaults to true for the Heap Gradle Plugin. The legacy plugin (heap-android-gradle) defaults to false.
  2. heapCaptureAdvertiserId only takes effect if heapAutoInit is set to true for the Heap View Autocapture SDK. The legacy autocapture SDK would apply the advertiser ID setting without respect to the heapAutoInit setting. (The new core SDK has affordances to enable/disable advertiser ID capture for programmatic initialization.)

Updated 11 months ago