From Classic to Core - Android Edition

If you're using Heap's Classic Android SDK and you're thinking about upgrading to our latest Core SDK offerings, there are a few differences you'll want to be aware of to help inform that decision.

SDK Configuration

Heap's Classic Android SDK is an "autocapture by default" solution. This means that the SDK is built to primarily enable autocapture with custom tracking being a secondary use case. Advanced configuration is required to disable the autocapture behaviors in the Classic SDK, but disabling autocapture can also lead to some properties, such as library version or build type, not being captured.

In the Core SDKs, we've reworked our offerings so that we start with custom tracking and a set of standard APIs first. Everything you need to track events, identify users, and add user and event properties is available through our custom tracking SDK. If you want to add autocapture on top of that, it's as easy as adding our autocapture SDK and Gradle plugin, along with a single line of code, to get that setup. No advanced configuration is needed to enable or disable autocapture.

Configuration Summary

Autocaptured Events

Both the Heap Classic and Core SDKs provide robust autocapture solutions for Android. However, there are a few differences between what is captured with each. In our Classic SDK there were a few events that were a bit noisy and not particularly useful for analysis. In order to reduce the noise and make analysis easier, we’ve changed the raw events that we capture. These new events are more meaningful and precise. We continue to invest in new autocapture capabilities to be delivered using our Core SDK offerings.

Autocapture Events Unique to Each SDK

Event Definition

Heap Classic events are commonly defined through either Live View or the Visual Labeler. The Visual Labeler has the added benefit of being able to define an event using the hierarchy of the UI component that was interacted with, which isn't visible for events defined through Live View with the Classic SDK.

In Heap Core, events are primarily defined through Live View. The Visual Labeler is not currently supported for Heap Core. Autocaptured events from Heap Core will include their hierarchy in Live View to allow this property to be used in definitions.

🚧

Visual Labeler Support

If the Visual Labeler is a core part of your workflow in Heap, we do not recommend switching from Classic to Core at this time.

Definition Methods

Version Support

Heap Classic supports API versions 14 and above. Our legacy instrumentor plugin can be used with the Classic SDK to support Android Gradle Plugin (AGP) version 4.0 through 7.4. To use Heap Classic with AGP 8.0+, Heap Classic installs will need to migrate to the Heap Gradle Plugin.

Heap Core supports API versions 16 and above for our custom tracking solution and API versions 21 and above for autocapture. The Core autocapture solution also requires the Heap Gradle Plugin which supports AGP versions 7.2 and above. These changes allow us to better support our customers with tracking for watches, TV, and automotive while also taking advantage of TLS v1.2 which is only available in API 16+.

Miscellaneous Properties

In Heap Core, we made the decision to stop capturing certain properties due to their lack of usefulness. These properties can be found below.