All notable changes to the Heap iOS library will be documented in this file. For steps to install Heap on iOS, see the installation docs for the desired library:

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Swift Core Changelog

[0.8.4] - 2025-05-02

Fixed

Heap.shared is now compatible with Swift 6 language mode.

Changed

Internal improvements for the Contentsquare SDK.

[0.8.3] - 2025-04-09

Fixed

Fixed ABI regression that impacted notification autocapture and the integration SDK.

[0.8.2] - 2025-03-31

Changed

Updated API endpoint from c.us.heap-api.com to mh.bf.contentsquare.net.

[0.8.1] - 2025-03-07

Fixed

Fixed an issue where the framework's Info.plist had an invalid minimum OS version, preventing App
Store releases.

[0.8.0] - 2025-02-12

Changes

The SDK is now distributed as a dynamic XCFramework.
The SDK now depends on the binary-distributed CSSwiftProtobuf instead of SwiftProtobuf from source.
The interfaces from HeapSwiftCoreInterfaces have been merged into this project.

🚧
**This is a breaking change that requires updates to the latest versions of HeapIOSAutocapture,
HeapNotificationAutocapture, and HeapContentsquareIntegration.**
If an error appears at build time, either about a version mismatch or a missing module, update the corresponding packages and clear the build folder.

The minimum deployment targets have increased to macOS 11, iOS 13, tvOS 13, and watchOS 6.0.

Added

Added support for visionOS.

[0.7.2] - 2024-10-08

Fixed

Zero length events (Heap.shared.track("")) are no longer uploaded to the server, where they were
being rejected.

[0.7.1] - 2024-08-28

Added

The SDK now sends identity to the Live data feed.

[0.7.0] - 2024-08-20

Added

Added new interfaces for upcoming autocapture release.

[0.6.1] - 2024-05-23

Fixed

Fixed session creation from integration code.

[0.6.0] - 2024-05-22

Added

Added new startRecording option, resumePreviousSession, which resumes the previous session on
start if the session has not yet expired.
Added new signature stopRecording(deleteUser: Bool) which deletes the current user state.
Subsequent calls to startRecording will have a new user and session as a result.
Added several internal interfaces to support an upcoming integration.

[0.5.3] - 2024-04-10

Changed

Improved trace logging for failed Sqlite queries.

[0.5.2] - 2024-03-28

Added

Added enableInteractionReferencingPropertyCapture, which will be used in heap-ios-autocapture
0.5.0 and later to enable "Target Ivar" capture. The feature is off-by-default to avoid edge
conditions that can cause Swift's Mirror functionality to crash.

Deprecated

Deprecated disableInteractionReferencingPropertyCapture in favor of off-by-default behavior.

[0.5.1] - 2024-02-26

Fixed

Native track calls now preserve session expiration dates set by heap.js when using
Heap.attachWebView.

Added

Added Heap.shared.environmentId, which returns the current environment ID or nil if not
recording.
Added sourceProperties to trackInteraction (for use by autocapture frameworks).

[0.5.0] - 2023-11-30

Fixed

Fixed crash on Heap.attachWebView when called twice on the same web view prior to iOS 15.
Now, subsequent calls are ignored.
Fixed small memory leak when an attached WKWebView is deallocated. This was caused by the
WKUserContentController maintaining a strong self reference when it has message handlers
attached. This change may trigger a warning message from WebKit on WKWebView deallocation,
which can be resolved by calling Heap.detachWebView when removing the web view.
Heap.removeHeapJsCookie is now public.

Changed

Heap.shared.resetIdentity() and Heap.shared.identify() no longer clear event properties by
default when a new user is identified.

The previous behavior is available using the option .clearEventPropertiesOnNewUser.
Changed uploader behavior around server errors.

Added

Added option .clearEventPropertiesOnNewUser to continue using existing SDK behavior where event
properties are cleared when a new user is identified.
Added Heap.detachWebView. This method removes most integrations added with
Heap.attachWebView with the exception of the heap.js cookie. This method is optional and
intended to be used before deallocating a WKWebView.

[0.4.0] - 2023-08-31

Added

Added .captureVendorId option to enable capture of iOS Vendor ID and
Initial iOS Vendor ID from UIDevice.current.identifierForVendor.
This supports a behavior change discussed in the Changed section.

Changed

Target Text and Target accessibilityLabel are now trimmed of whitespace.
Properties from addEventProperties will no longer show up on sessions, matching Classic SDK behavior. Pageviews and events are not affected by the change.
The SDK no longer captures iOS Vendor ID and Initial iOS Vendor ID by default.
This change allows developers to opt into Vendor ID tracking after they've validated
their use complies with Apple's user privacy and data use guidelines.
To enable these properties, use the .captureVendorId option in startRecording.

[0.3.1] - 2023-07-25

Fixed

Fixed code signing on macOS. The issue was caused by the HeapSwiftCoreInterfaces zip file not
preserving symlinks.

Added

Exposed +[HeapSourceInfo sourceInfoWithName:version:platform:properties:] and
-[Heap track:properties:sourceInfo:] to Objective-C.

[0.3.0] - 2023-06-06

Added

Added app version change and install events. These will fire when an environment first
encounters a different application identifier, app name, or version at session start.

Changed

Changed process to retrieve iOS device model. sysctlbyname is now used to retrieve the
detailed hardware identifier (e.g., "iPhone10,3"). This results in more specific
model identification than the generic UIDevice.model approach which is now used
as a fallback.

[0.2.1] - 2023-05-22

Fixed

Added missing Objective-C module to HeapSwiftCoreInterfaces to unblock CocoaPods release.

[0.2.0] - 2023-05-16

Added

Added option startSessionImmediately to begin tracking sessions immediately.

Changed

Default behavior for sessions has been changed (startSessionImmediately = false).
Tracking of sessions is now delayed until one of the following is called:
- Heap.shared.track()
- Heap.shared.trackPageview()
- Heap.shared.trackInteraction()
- Heap.shared.uncommittedInteractionEvent()
- Heap.shared.fetchSessionId()

[0.1.2] - 2023-03-29

Changed

Split out public APIs into a ABI-stable XCFramework to better support heap-ios-autocapture-sdk.

Fixed

Removed usage of unsafeFlags in Package.swift.

[0.1.1] - 2023-03-20

Fixed

Omits properties containing empty keys and values.

[0.1.0] - 2023-03-10

Added

Manual capture SDK.
Support methods and classes for runtime bridges.
Support methods and classes for autocapture sources.
Support for manual capture within WKWebView.
Support for platforms targeting Swift: macOS, watchOS, iOS, iPadOS, tvOS.

iOS Autocapture Changelog

[0.8.0] - 2025-02-12

Changed

Set minimum HeapSwiftCore version to 0.8.0.
heapRedactText now automatically redacts accessibility labels in the same scope, overriding
heapReactAccessibilityLabel. This reduces the risk of accidental text collection on sensitive
elements.

[0.7.0] - 2024-08-28

Changed

Bumped the HeapSwiftCore dependency to 0.7.0.

[0.5.0] - 2024-04-01

Fixed

Fixed code signing when targeting Catalyst. The issue was caused by the zip file not preserving symlinks.

Changed

"Target IVar" capture is now disabled by default since certain code patterns can cause Swift's Mirror to crash. This can be re-enabled by starting Heap with .enableInteractionReferencingPropertyCapture: true.

[0.4.0] - 2023-10-16

Fixed

Fixed a bug where Heap could remove action listeners on custom subclasses of UIControl, when
the target of the action listener was the control.
(heap/heap-ios-autocapture-sdk#2)
Fixed a bug where pageview view controller names did not reflect naming changes made in 0.3.0.

Added

Added open heapText, heapTextChildren, and heapTextRecursionVisibility
variables to UIView to support overriding Target Text on custom views.

[0.3.0] - 2023-08-07

Added

Added option .useObjectiveCClassNames to use Classic SDK naming logic for view and view
controller names. This option will be useful for Classic SDK users when evaluating the new
autocapture SDK, as names will be consistent with existing event definitions for views.

Changed

Updated view and view controller names to include parent types, such as enum or
struct when used for code organization.

For example, the following code will produce Home.ViewController instead of ViewController:
```
enum Home {
    class ViewController: UIViewController { ... }
}
```
Increased HeapSwiftCore dependency from 0.1.2 to 0.3.0 to ensure
improvements are automatically included when updating.
When a control has multiple actions, the first action that is called will be used for
Action Method, rather than the last. This matches the behavior of the Classic SDK.

[0.2.1] - 2023-05-22

Fixed

Updated minimum HeapSwiftCore CocoaPods version to 0.2 so it's not pinned to 0.1.x.

[0.2.0] - 2023-05-16

Added

Added Objective-C access to the register function.
Added support for capturing other component change events while UITextField and UITextView are active.

Fixed

Fixed capture of bar button item text.
Relaxed filtering rules to capture _ prefixed selectors in Target Selector.
Fixed an issue where textFieldShouldBeginEditing was being called an extra time when switching between text fields. (heap/heap-ios-autocapture-sdk#1)
Fixed duplicate pageview that could occur if a session was started by a view controller appearing.

[0.1.2] - 2023-03-29

Fixed

Restructured package so HeapSwiftCore can be used as a dependency.

[0.1.1] - 2023-03-29

Fixed

Fixed error when sending nil to certain sendEvent arguments.

[0.1.0] - 2023-03-10

Added

Autocapture SDK targeting iOS 13.0+ and Xcode 14.0+.

Swift Notification Autocapture Changelog

[0.8.0] - 2025-02-12

Changed

Set minimum HeapSwiftCore version to 0.8.0.

[0.7.0] - 2024-08-28

Added

Notification autocapture SDK.

Classic iOS Changelog

[9.1.0] - 2022-11-03

Changed

Moved data storage out of NSUserDefaults.

Fixed

Fixed issue with double-encoded session properties.
Fixed data purge logic when queues are in an invalid state.

[9.0.2] - 2022-11-03

Fixed

Fixed issue with double-encoded session properties.

[8.2.2] - 2022-11-03

Fixed

Fixed issue with double-encoded session properties.

[8.2.1] - 2022-07-26

Fixed

Fixed issue causing pageview ids not to rotate.

[9.0.0] - 2022-07-20

Added

Added new properties UIView.heapRedactText and
UIView.heapRedactAccessibilityLabel for redacting text properties from
touch events.
Added new property UIView.heapIgnoreInnerHierarchy for omitting inner view
hierarchies from touch events. The default behavior for a view can be set
by overriding the static heapIgnoreInnerHierarchyDefault property.

Fixed

Improved attribution of pageviews in multi-window iPad apps.
Fixed performance issues when Heap uploads fail for a prolonged period of
time. This includes a recovery mechanism where Heap will reset its internal
data stores when initialized in an impacted state.

Changed

Gesture recognizers autocapture has become opt-out by default. They can be
enabled with the enableGestureAutocapture property on HeapOptions.
Heap.resetIdentity() has been updated to be consistent with web autocapture.
The session will no longer reset for anonymous users and it doesn't clear
event properties.
Heap.identify(...) has been updated to be consistent with web autocapture.
It will now start a new session when transitioning between two non-anonymous
users.

Breaking changes

Deprecated methods have been removed from the Heap SDK.
Dropped support for iOS versions below 12.0.
Dropped support for Visual Labeling (aka Event Visualizer) prior to iOS 13.0.
Heap will function as expected, but pairing gestures, the QR code, and
[Heap startEVPairing] will have no effect on iOS 12 devices.

[8.2.0] - 2022-04-05

Added

Added options to disable various title, ivar, and accessibility label capture with the disableTitleCapture, disableIvarCapture, and disableAccessibilityLabelCapture properties on HeapOptions.
Added an option to disable view controller autocapture with the disableViewControllerAutocapture property on HeapOptions.
Improved logging of React Native events in the console.
Added support for React Native in Event Visualizer.

Fixed

Fixed graphical defects in Event Visualizer screenshots. The SDK will automatically revert back to fast screenshots if a performance issue is detected, but it can also be manually enabled with the useFastEVScreenshotCapture property on HeapOptions.

[8.1.0] - 2022-02-24

Added

Added [Heap sessionId] and [Heap identity] for retrieving the values currently sent with events.
Added option to disable gesture recognizer events with disableGestureAutocapture property on HeapOptions.

Changed

Heap now performs method swizzling during [Heap initialize:] but can be made to perform it earlier via [Heap instrumentAutocaptureWithOptions:].

Fixed

Improved capture of view controller titles.
Fixed infinite recursion crash in SwiftUI previews.
Resolved (null) pageview properties.

[8.0.0] - 2021-10-12

Breaking Changes

Adopted the XCFramework, will require minor code changes for both manual and Cocoapods installs.

Added

Included Heap.xcframework with support for M1 Macs.
Added options to support proxying requests.

Fixed

Fixed a failure that would occur when calling -[UISegmentedControl setSelectedSegmentIndex:-1] shortly after it was touched.
Improved handling of malformed event properties.
Fixed tracking of Storyboard-created gesture recognizers on pre-iOS 13 devices.

[7.5.1] - 2021-05-24

Fixed

Fixed a race condition where the SDK would "bail" on boot if an appId wasn't set yet.

[7.5.0] - 2021-05-04

Added

Updated to allow the size of captured view ancestry chains to be configured.

Fixed

Constrain view ancestry capture updated to 30 elements so CPU usage isn't unbounded.

[7.4.1] - 2021-01-12

Fixed

Fixed a "duplicate symbols for architecture" error that could appear when building the Debug scheme.

[7.4.0] - 2021-01-08

Added

Allow pairing with the Event Visualizer using a QR code.

Fixed

Fixed an issue where two-pass selector processing could sometimes overwrite events that didn't represent touches.

[7.3.0] - 2020-09-25

Added

Support for screen views in the Event Visualizer.

Fixed

Non-numeric app IDs are no longer allowed when the Heap library is being initialized.
Overhauled the Event Visualizer to make it more consistent with autocaptured data.
Fixed an issue where interactions with UISegmentedControl instances wouldn't show up in the Event Visualizer.

[7.2.0] - 2020-08-27

Added

Support for iOS 14 (beta 5).
Capture app background/foreground visiblity status for every autocaptured event.

[7.1.1] - 2020-07-13

Fixed

Fixed an issue where certain UTF-16 strings were truncated incorrectly, possibly causing a crash.

[7.1.0] - 2020-07-01

Added

Allow the disabling of tracking events using setTrackingEnabled: or the disableTracking property on HeapOptions.

[7.0.2] - 2020-07-13

Fixed

Fixed an issue where certain UTF-16 strings are truncated incorrectly, possibly causing a crash.

[7.0.1] - 2020-06-30

Fixed

Fixed an issue where calls to Heap track from a background thread could be dropped.

[7.0.0] - 2020-06-17

Breaking changes

Dropped support for iOS versions below 10.0.

Added

Allow disabling autocapture when an app has been backgrounded through a disableAutocaptureWhenBackgrounded property on HeapOptions.
Expose heapIgnore as a property, as opposed to only through User Defined Runtime Attributes in the Interface Builder.

Changed

Use an improved format for sending events to Heap.

[6.8.1] - 2020-06-04

Fixed

Fixed an issue where the Event Visualizer pairing popup would not be displayed for apps using UISceneDelegate.
Fixed an issue where the Event Visualizer pairing popup would appear, then immediately disappear.
Fixed an issue where install/upgrade events would not fire for certain installations.

[6.8.0] - 2020-05-18

Added

Send telemetry data to Heap when the library detects an internal error.

Fixed

Fixed an issue where the Event Visualizer would break pairing when the device goes to sleep.
Fixed an issue where a call to Heap resetIdentity would be ignored if it was immediately preceded by a call to Heap identify.
Fixed an issue where the Event Visualizer would receive no data from apps whose application delegate didn't contain a window property.

[6.7.1] - 2020-05-18

Fixed

Fixed an issue where the Event Visualizer would receive no data from apps whose application delegate didn't contain a window property.

[6.7.0] - 2020-04-03

Added

Added the ability to capture the IDFA (identifier for advertisers) and IDFV (identifier for vendors).

Fixed

Fixed an issue where the Heap userId API would return nil for non-anonymous users.
Fixed an issue where view ancestry data would be dropped for retried requests.

[6.6.3] - 2020-05-18

Fixed

Fixed an issue where the Event Visualizer would receive no data from apps whose application delegate didn't contain a window property.

[6.6.2] - 2020-04-03

Fixed

Fixed an issue where the Heap userId API would return nil for non-anonymous users.
Fixed an issue where view ancestry data would be dropped for retried requests.

[6.6.1] - 2020-03-11

Fixed

Fixed a thread-safety issue related to sessionization logic - previously, calls to Heap identify and Heap track could potentially result in a crash if called from a background thread.

[6.6.0] - 2020-01-23

Added

Added new initialize function for more explicit initialization of the Heap library.
Added disableTextCapture initialization option to disable capturing the text of click events for PII purposes.
Added debug initialization option to start debug logging of Heap activity via NSLog.
Added support for reporting view hierarchies.

Fixed

Fixed an issue (particularly manifesting in iOS 13) where the View Controller on an event could incorrectly be attributed to a dismissed modal view.
Improved Event Visualizer pairing alert and screenshot capture.

Deprecated

setAppId has been deprecated, please use initialize instead.

[6.5.4] - 2020-03-11

Fixed

Fixed a thread-safety issue related to sessionization logic - previously, calls to Heap identify and Heap track could potentially result in a crash if called from a background thread.

[6.5.3] - 2019-12-11

Fixed

Many non-alphanumeric characters are properly escaped for transmission.

[6.5.2] - 2019-12-10

Fixed

Fixed an issue where some debug noise was not suppressed in console log output.

[6.5.1] - 2019-12-05

Fixed

Fixed an issue where first-time app install events were not being properly recorded.

[6.5.0] - 2019-12-03

Added

Added new methods for tracking events from frameworks.
Capture view ancestry information for all touch & fieldedit events.
Capture target text for ASButtonNode instances from the Texture library.

Fixed

The Event Visualizer trigger gesture works on UIWindow instances instantiated after app launch.
Stability improvements for UISegmentedControl autocapture.
Suppress recording spurious system view controllers, particularly those used by iOS 13.

[6.4.1] - 2019-11-20

Fixed

Fixed issues with incorrect view controller class names being captured on iOS 13.

[6.4.0] - 2019-10-04

Changed

Pageviews are now triggered when child view controllers are presented.

[6.3.0] - 2019-09-06

Added

Added protection to avoid possible crashes, disabling capture when errors occur.

Fixed

Fixed instrumentation of UISegmentedControls on iOS 9.
Fixed an error that would occur when opening multiple Event Visualizer sessions.

[6.2.1] - 2019-08-13

Fixed

Fixed a bug related to user ID generation across app restarts.

[6.2.0] - 2019-07-24

Fixed

The gesture used to initiate Event Visualizer pairing mode was discovered to have interactions with app background audio, so was modified to a different gesture.

[6.1.0] - 2019-07-12

Added

Add the [Heap startEVPairing] and [Heap stopEVPairing] APIs; this enables programmatic control of the event visualizer pairing mode.
Allow entering the event visualizer pairing mode from an iOS simulator using the Hardware → Shake Gesture command.

Changed

Improve sessionization semantics; sessions now expire after 5 idle minutes, regardless of the app's background/foreground state.

[6.0.0] - 2019-07-09

Breaking changes

Dropped support for iOS versions below 9.0.

Added

Enhanced the pairing flow for the iOS event visualizer.

[5.4.1] - 2019-06-20

Fixed

Fixed an issue related to UISegmentedControl components in OS versions earlier than iOS 10 that wasn't fixed adequately in the last release.

[5.4.0] - 2019-06-18

Added

Exposed a programmatic way to reset the user identity.

Fixed

Fixed an issue where observing UISegmentedControl components would crash on an OS earlier than iOS 10.
Fixed an issue where accessibility identifiers could be accessed off the main queue.

[5.3.1] - 2019-06-07

Added

Capture app lifecycle events (installation & upgrade).

Fixed

Fixed an issue where the incorrect target text was being reported for touches on UISegmentedControl instances.

[5.2.0] - 2019-04-24

Fixed

The accessibilityIdentifier for UIBarButtonItems is now reported with touch events.

[5.1.0]

Added

Events triggered by ViewControllers now include the title property of the ViewController.

[5.0.8]

Fixed

Fixed a crash with the Event Visualizer for apps built on Xcode 10.

[5.0.7]

Fixed a crash caused when Heap was loaded along with Firebase/Performance.

[5.0.6]

Fixed a situation that could cause events to have the wrong screenview properties.

[5.0.5]

Fixed

Fixed possible crash when view controller class is nil.

[5.0.4]

Fixed

Moved some code from a background thread to main thread to satisfy XCode's Main Thread Checker diagnostic.

[5.0.3]

Fixed

addUserProperties failed to work if user was already identified.

[5.0.1]

Fixed

Fixed the view controller name sent to the Event Visualizer on touch events.

[5.0.0]

Fixed

Correctly capture names of several types of nested view controllers.
Removed deprecated form of identify API.

[4.0.1]

Added

Include this changelog in the package on CocoaPods

[4.0.0]

Added

Improved library documentation.
Annotated methods to improve usability from Swift.
Allow hiding views from Heap by adding a boolean user defined attribute
called heapIgnore in Interface Builder and setting it to true.

Fixed

Changed view controller capture to more accurately represent the current
view.

Deprecated

These methods were already deprecated in 3.0.0, but we're highlighting them here as we intend to remove them in a future release.

The identifyDeprecated: method is (obviously) deprecated, and should be replaced by identify:. See user identities and properties documentation for the correct usage.
The setEventProperties: and unsetEventProperty: methods are deprecated, and should be replaced by addEventProperties: and removeEventProperty: respectively. The new methods are aliases, so simply replacing calls will work.

Swift Core Changelog

[0.8.4] - 2025-05-02

Fixed

Changed

[0.8.3] - 2025-04-09

Fixed

[0.8.2] - 2025-03-31

Changed

[0.8.1] - 2025-03-07

Fixed

[0.8.0] - 2025-02-12

Changes

🚧**This is a breaking change that requires updates to the latest versions of HeapIOSAutocapture,

Added

[0.7.2] - 2024-10-08

Fixed

[0.7.1] - 2024-08-28

Added

[0.7.0] - 2024-08-20

Added

[0.6.1] - 2024-05-23

Fixed

[0.6.0] - 2024-05-22

Added

[0.5.3] - 2024-04-10

Changed

[0.5.2] - 2024-03-28

Added

Deprecated

[0.5.1] - 2024-02-26

Fixed

Added

[0.5.0] - 2023-11-30

Fixed

Changed

Added

[0.4.0] - 2023-08-31

Added

Changed

[0.3.1] - 2023-07-25

Fixed

Added

[0.3.0] - 2023-06-06

Added

Changed

[0.2.1] - 2023-05-22

Fixed

[0.2.0] - 2023-05-16

Added

Changed

[0.1.2] - 2023-03-29

Changed

Fixed

[0.1.1] - 2023-03-20

Fixed

[0.1.0] - 2023-03-10

Added

iOS Autocapture Changelog

[0.8.0] - 2025-02-12

Changed

[0.7.0] - 2024-08-28

Changed

[0.5.0] - 2024-04-01

Fixed

Changed

[0.4.0] - 2023-10-16

Fixed

Added

[0.3.0] - 2023-08-07

Added

Changed

[0.2.1] - 2023-05-22

Fixed

[0.2.0] - 2023-05-16

Added

Fixed

[0.1.2] - 2023-03-29

Fixed

[0.1.1] - 2023-03-29

Fixed

🚧
**This is a breaking change that requires updates to the latest versions of HeapIOSAutocapture,