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:

• iOS Installation.
• iOS Classic Installation

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

Swift Core Changelog

[0.8.5] - 2025-05-16

Fixed

• Fixed support for tvOS devices, which do not have access to persistent storage in the library directory. When running on tvOS, Heap will persist minimal data in UserDefaults under the following keys:

  • heap-environment-{id}: This contains the active SDK state, including the current user, identity, and session information. By default, this will be under 200 bytes, but will grow to include stored data when identify and addEventProperties are used.
  • heap-user-upload-status: This holds upload status for the current user. This will be consistently under 300 bytes.

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

  Swift

  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.