Android View Autocapture Installation

Requirements + Known Limitations

  • The Heap Android View Autocapture SDK requires a minimum SDK version of 21 or higher.
  • The Heap Android View Autocapture SDK requires the Heap Android Core SDK in order to work.
  • The Heap Android View Autocapture SDK requires the Heap Android Gradle Plugin (Plugin ID: io.heap.gradle) in order to perform autocapture. The legacy plugin (com.heapanalytics.android:heap-android-gradle) will not work.
  • The Heap Android View Autocapture SDK does not currently support automatically capturing interactions from UI elements built with Jetpack Compose. To capture interactions on UI elements built with Jetpack Compose, please refer to our Android Core documentation.

📘

For notes on the latest SDK versions, see our Android changelog.

Autocapture Installation

The following three things are required to use the Heap Android View Autocapture SDK successfully:

  1. Installation of the Heap Android Core SDK.
  2. Installation and application of the Heap Gradle Plugin.
  3. Installation of the Heap Android View Autocapture SDK.

For installation of the Heap Android Core SDK, please refer to the Installation section of the Heap Android Core SDK documentation. For installation of the Heap Gradle Plugin, please refer to the Installation section of the Heap Gradle Plugin documentation. Please complete these two steps before continuing with autocapture installation.

Dependency Installation

Once you have completed the steps for installing the Heap Android Core SDK and Heap Gradle Plugin, perform the following steps to install the Heap Android View Autocapture SDK dependency.

  1. In the dependencies block of your application module’s build.gradle file (the same block that contains the Heap Android Core SDK dependency), add the Heap Android View Autocapture SDK as an implementation dependency:
dependencies {  
    ...  
    implementation 'io.heap.autocapture:heap-autocapture-view:0.2.+'  
}
dependencies {  
    ...  
    implementation("io.heap.autocapture:heap-autocapture-view:0.1.+")  
}
  1. Complete the instructions in the Initializing Heap and Completing Setup sections.

  2. Build your app!

Initializing Heap

To use Heap on Android, you need to initialize the Heap Android View Autocapture SDK. There are two different ways to do this:

  1. Initialization configuration at build time
  2. Programmatic initialization

🚧

These two initialization methods are mutually exclusive: if you opt to configure initialization at build time, this configuration will take precedence and programmatic initialization will be a no-op.

Initialization Configuration at Build Time

Initialization configuration at build time offers a simple, transparent way to tailor the initialization parameters by build variant. This can be useful, for example, if you have different environment IDs for staging and production builds. Initialization configuration at build time configures your application so that Heap is immediately initialized when the application process starts. If you want more control over when Heap gets initialized, you should use programmatic initialization.

If you choose to configure initialization at build time, you do NOT need to follow the instructions in the Initializing Heap Android Core section of the Heap Android Core SDK documentation.

  1. To initialize Heap automatically, add the following extension properties to defaultConfig in your application module’s build.gradle file:
android {  
    defaultConfig {  
        // Add this section to configure Heap initialization and event capture.  
        ext {  
          heapAutoInit = true  
          heapEnvId = "YOUR_ENVIRONMENT_ID"  
        }  
        ...  
    }  
    ...  
}
android {  
    defaultConfig {  
        // Add this section to configure Heap initialization and event capture.  
        (this as ExtensionAware).extensions.extraProperties.apply {  
          set("heapAutoInit", true)  
          set("heapEnvId", "YOUR_ENVIRONMENT_ID")  
        }  
        ...  
    }  
    ...  
}

Programmatic Initialization

Programmatic initialization allows you to initialize Heap in code and have more control over when initialization happens. This can be useful, for example, if you want to initialize Heap only after a user has completed a login flow in your application.

  1. Follow the instructions in the Initializing Heap Android Core section of the Heap Android Core SDK Documentation to have the core SDK start recording.
  2. At the point where you want to start the View Autocapture SDK, call ViewAutocaptureSDK.register in the manner shown in the code snippet below. Typically, you would do this in the onCreate method of either an Application subclass or the Activity with the android.intent.action.MAIN action set in AndroidManifest.xml though you can start autocapture at any point of your choosing. Note that, while ViewAutocaptureSDK.register can be called before the Heap Android Core SDK is recording, it will only start recording events at the time that Heap.startRecording is called, and any UI interactions that occurred before the start of recording will not be captured.
import io.heap.autocapture.ViewAutocaptureSDK  
import io.heap.core.Heap  
...

class MainActivity : AppCompatActivity() {  
  override fun onCreate(savedInstanceState: Bundle?) {  
    super.onCreate(savedInstanceState)  
    // Replace YOUR_ENVIRONMENT_ID with the ID of the Heap environment you wish to send data to.  
    Heap.startRecording(applicationContext, "YOUR_ENVIRONMENT_ID")
    // Call ViewAutocaptureSDK.register() to get Activity pageviews and autocaptured UI events.  
    ViewAutocaptureSDK.register()  
    ...  
  }  
  ...  
}
import io.heap.autocapture.ViewAutocaptureSDK;  
import io.heap.core.Heap;  
...

class MainActivity extends AppCompatActivity {  
  @Override  
  protected void onCreate(Bundle savedInstanceState) {  
    super.onCreate(savedInstanceState);
    // Replace YOUR_ENVIRONMENT_ID with the ID of the Heap environment you wish to send data to.  
    Heap.startRecording(getApplicationContext(), "YOUR_ENVIRONMENT_ID");
    // Call ViewAutocaptureSDK.register() to get Activity pageviews and autocaptured UI events.  
    ViewAutocaptureSDK.register();  
    ...  
  }  
  ...  
}

Completing Setup

Follow the instructions in the Completing Setup section of the Heap Android Core SDK Documentation.

Configuration

XML Resource Configuration

The Heap Android View Autocapture SDK allows users to ignore UI interactions and redact text on specific View objects by setting the appropriate tags on the objects' XML elements. A tag on a View to ignore UI interactions will prevent the SDK from capturing any UI interactions on that View or its children. A tag on a View to redact text will instruct the SDK to redact any text in that View or its children whenever a UI interaction is captured on those Views.

Examples:

<!-- Button clicks are not captured. -->
<Button
    android:id="@+id/ignore_button"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Taps on this button are not captured."
    android:tag="heapIgnoreInteractions" />
<!-- Button clicks are captured but text is redacted. -->
<Button
    android:id="@+id/redact_button"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="This text is redacted"
    android:tag="heapRedactText" />

The Heap Android View Autocapture SDK also provides API calls to ignore interactions and redact text programmatically if it is not possible to do so in your XML layout resources.

API

ViewAutocaptureSDK

  • Type: Kotlin object / Java class
  • Import: io.heap.autocapture.ViewAutocaptureSDK

The public-facing API for the Heap Android View Autocapture SDK.

📘

All methods are static.

fun register(isDefault: Boolean = false)

Description
Registers the Heap Android View Autocapture SDK. Once registered, the SDK will autocapture UI interactions and source pageviews.

Parameters

  • isDefault (optional): Whether or not the Heap View Autocapture SDK should be the default source. This setting informs the Heap Android Core SDK to use the Heap Android View Autocapture SDK as a fallback for assigning pageview information to events if those events do not have a currently registered source or if their source fails to return a valid pageview. Defaults to false.

Return Value

None.

fun deregister()

Description

De-registers the Heap Android View Autocapture SDK. Upon de-registration, the SDK will cease to autocapture UI interactions and source pageviews.

Parameters
None.

Return Value
None.

fun ignoreInteractions(view: View?)

Description

Marks a View object as one on which to ignore all user interactions. Any interactions with children of the View object, if it is a ViewGroup, are also ignored.

While this method allows an app to dynamically mark a View to be ignored, it is also possible to mark a View statically by setting its android:tag attribute to "heapIgnoreInteractions" in the appropriate XML layout resource.

Parameters

  • view: The nullable View on which to ignore interactions. If the View is null, this is a no-op.

Return Value

None.

fun redactText(view: View?)

Description

Marks a View object as one on which to redact all text. Any interactions with children of the View object, if it is a ViewGroup, will also have the text redacted.

While this method allows an app to dynamically mark a View to redact text, it is also possible to mark a View statically by setting its android:tag attribute to "heapRedactText" in the appropriate XML layout resource.

Parameters

  • view: The nullable View on which to redact text. If the View is null, this is a no-op.

Return Value

None.

Performance Impact FAQ

Performance

  • Question: What is the performance impact of Heap on a Mobile app?
    • Answer: Heap adds virtually zero performance overhead. Heap never blocks the UI thread of the application and RAM is only allocated to process events right before they’re persisted or sent to the server.
  • Question: Does Heap do a ton of main thread writes that could impact the responsiveness of the application?
    • Answer: Heap does not perform any data persistence or networking activity on the main thread. All data persistence and networking operations take place on a background thread.
    • Answer: Heap does perform a very small amount of view traversal on the UI thread to fetch event properties from the corresponding UI objects. This operation is very fast, does not utilize findViewById, and only involves simple property access. All data that is gathered on the UI thread is sent to a background thread for processing.

Network

  • Question: Are events stored if there is no internet connection or are they dropped? & how many events get stored?
    • Answer: All event data is stored in a SQLite database in application private storage. While online, this database should never grow to more than a few dozen events. While offline, all events are stored in the database until they’re able to be uploaded to the server. However, all data more than 6 days old will be routinely pruned from the database to prevent the database from growing endlessly.
    • Question: Does this behavior differ between core & autocapture SDKs?
      • Answer: No. Autocapture data is sent to Core for storage.
  • Question: How does Heap's event tracking impact network bandwidth?
    • Answer: Heap sends event data in small batches every 15 seconds while connected to the internet. While offline, network data remains in storage and no uploads are attempted.
    • Question: What about network data consumption?
      • Answer: Events on Android are roughly 0.5KB in size. Even if we estimate that a typical user produces 2,000 events per day, this only amounts to a single megabyte of data consumption.
    • Question: How does Heap mitigate impacting bandwidth?
      • Answer: Heap batches event data to be sent to the server every 15 seconds to prevent constant network access. Heap also only sends a maximum of 100 events at a time, amounting to roughly 100KB of data per upload. Additionally, if any network errors occur, Heap pushes back the upload process for a full minute to wait for network conditions to improve.

Device

  • Question: Is the user battery life impacted because Heap is running?
    • Answer: Heap should not impact battery life in any meaningful way. Events are batched to be sent periodically to prevent constant network access. This upload frequency should closely match the frequency of network activity of regular app usage for connected applications. If the target application doesn’t not routinely access the network, Heap’s upload interval can be increased to reduce network access and mitigate any unnecessary battery usage.

Storage

  • Question: How much memory does the Heap SDK add to app bundles?
    • Answer: Android Core adds about 500KB to app bundles. Android View Autocapture adds about 130KB.
  • Question: Where does Heap store user ID and session ID information?
    • Answer: Heap stores all event data in a SQLite database in private application storage. Some event metadata, such as environment ID, is stored in a file in private application storage.

Build Features

  • Question: What is the expected build-time impact of adding the Heap SDK?
    • Answer: Android Core is a regular Android dependency that doesn’t rely on any build time instrumentation. As such, adding Android Core does not result in a longer build time.
    • Answer: Android View Autocapture adds a small amount of build time overhead to perform code instrumentation. The exact amount of overhead depends on a number of different factors, such as the speed of the machine producing the build and the number of class files in the application. In testing with large open source applications, we noticed build times increasing 15-25% on clean rebuilds of an application without the use of a build cache. However, rebuilds of application with an existing build cache (typical of a developer making some code changes and rebuilding to test those changes) only saw a 1-5 second increase depending on the number of changes made between builds.
  • Question: What effect will build-time obfuscation tools like ProGuard or R8 have on Heap’s ability to capture data?
    • Answer: Android Core does not use any class name mappings and thus would be unaffected by obfuscation tools. Android View Autocapture contains build-time logic for mapping obfuscated class names so that they appear unobfuscated when collected and ingested by Heap. This build-time logic is known to work with ProGuard, DexGuard, and R8, but may also work with other obfuscation tools.