If you're using Heap's Classic iOS 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 your decision.

SDK Configuration

Heap's Classic iOS SDK is an "autocapture by default" solution. This means that the SDK is built primarily to enable autocapture with custom tracking being a secondary use case. Advanced configuration is required to disable the autocapture behaviors in the Classic SDK.

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, 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

For the most part, the same set of events are captured in version 0.4.0 of Core Autocapture SDK as version 9.1.0 of Classic SDK. That said, you will see some changes if upgrading from a previous version of Classic SDK.

Changes introduced in Core Autocapture SDK

• Touch events are no longer emitted when a user scrolls a scroll view. This filters out events that looked like taps but were actually swipes.

Changes introduced in Classic SDK 9.0.0

• The pageview logic has been updated so there is no longer one pageview per view controller. Instead, only view controllers in standard containers like UINavigationController are captured. There is also improved accuracy of pageview information on events in multi-window iPad apps and UISplitViewController .
• Gesture events are no longer captured.
• Common controls like UISwitch and UITextField emit field edit events on change. Controls like UIDatePicker no longer emit touch events for each interaction on its internal components.

Autocaptured Properties

While the Classic and Core SDKs capture most of the same fields, some data is captured differently which may prevent Classic SDK event definitions from matching the Core SDK.

Class names are captured using Swift

The Classic SDK used NSStringFromClass to populate the Hierarchy and View Controller fields. This was fine for views written in Objective-C or with simple Swift definitions, but would yield "mangled" names for nested and generic definitions. The default behavior for the Core SDK is to use sanitized Swift class names. If migrating from the Classic SDK, the useObjectiveCClassNames initialization option will revert to the Classic SDK behavior.

Hierarchy depth

The Classic SDK would capture the entire view hierarchy up to a depth of 30 views/responders. The Core SDK stops capturing when it encounters the hosting view controller or window. This yields shorter hierarchy strings constrained to their pageview. We don't expect this to affect most view definitions, but it's something to be aware of.

Text capture

The text capture algorithm is the same between the Classic and Core SDKs but additional refinements have been added when encountering a variety of views like UITableViewCell with content configurations. Text also now appears as a tt attribute on hierarchy nodes to support more complex event definition.

Pageview accessibility properties have been removed

The Core SDK no longer captures view controller accessibilityIdentifier and accessibilityLabel. Apple doesn't officially support accessibilityIdentifier on view controllers and the property's behavior would actually change when frameworks like MapKit were loaded. accessibilityLabel likewise doesn't have a clearly defined behavior on view controllers. Pageview title capture has been improved considerably, and should be used alongside the View Controller property for defining pageview events.

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

Version 9.1.0 of the Classic SDK supports a minimum deployment target of iOS 12.0 and above. The Core SDK, minus autocapture, also supports iOS 12.0 and above. The Autocapture SDK supports iOS 13.0 and above.

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.