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

Classic SDKCore SDKs
Autocapture by default.Custom tracking foundation with autocapture available
Advanced configuration needed to disable autocapture.Easily add autocapture on top of custom tracking with minimal code updates.
Instrumentor/Gradle plugin required for some properties to be properly captured.All essential properties are captured without the instrumentor/Gradle plugin.

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

Only in Classic SDKOnly in Core SDKs
Menu item clicksSlider value changes
Carousel/Pager item scrollsDate picker value changes
Tab item clicksTime picker value changes

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

Classic SDKCore SDKs
Live ViewLive View with enhanced hierarchy data
Visual LabelerNo Visual Labeler support at this time.
Explore EventsExplore Events

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

Classic SDKCore SDKs
Custom Tracking - API 14+Custom Tracking - API 16+
Autocapture - API 14+Autocapture - API 21+
AGP Support - 4.0+AGP Support - 7.2+

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.

PropertyWhy it's no longer captured
ANDROID_IDThis property was originally intended to be a unique identifier across every device. In practice, some firmware versions present the same ANDROID_ID across many different devices. We recommend using the advertiser ID and identity APIs to distinguish user/device combinations.
Build TypeThis property was mainly used to distinguish between debug and release builds of an app. We recommend only sending release data to production environments and sending debug data to development environments instead.
Build FlavorThis property was used to distinguish different flavors of a given app (i.e. free vs paid). Since it's common to change the application ID when changing the build flavor, we decided to no longer capture this property and only use the application ID and app version to differentiate different builds.