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 SDK | Core 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 SDK | Only in Core SDKs |
|---|---|
| Menu item clicks | Slider value changes |
| Carousel/Pager item scrolls | Date picker value changes |
| Tab item clicks | Time 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 SDK | Core SDKs |
|---|---|
| Live View | Live View with enhanced hierarchy data |
| Visual Labeler | No Visual Labeler support at this time. |
| Explore Events | Explore 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 SDK | Core 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.
| Property | Why it's no longer captured |
|---|---|
| ANDROID_ID | This 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 Type | This 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 Flavor | This 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. |
Users and Installs
The Core SDK does not read from or write to the same storage location as the Classic SDK. Because of this, switching to the Core SDK will cause a temporary spike in new users and install events, as if you were seeing all of your users for the first time. This spike is temporary and will level out once all users have upgraded to a version of your app that uses the Core SDK.
Updated 2 months ago