---
title: From Heap Classic SDK to CSQ SDK - iOS
description: Steps to migrate from a Heap Classic install to the CSQ SDK
lastUpdated: 03 June 2026
source_url:
  html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-from-heap-classic-sdk/
  md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-from-heap-classic-sdk/index.md
---

> Documentation index: https://docs.contentsquare.com/llms.txt
> Use this file to discover all available pages before exploring further.

Faster implementation using agent skills

Use [Agent skills](https://docs.contentsquare.com/csq-sdk-ios/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically.

This guide provides a step-by-step upgrade process from your current installation of Heap Mobile to the latest version of the CSQ SDK.

![Heap Classic SDK](https://docs.contentsquare.com/heap-classic-logo.png)

**Heap Classic SDK**

→

![CSQ SDK](https://docs.contentsquare.com/csq-logo.png)

**CSQ SDK**

The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions.

Upgrading to the latest version ensures you benefit from all our newest features and product enhancements.

Key differences from Heap Classic SDK

* **Custom tracking first**: CSQ SDK starts with custom tracking APIs; you should use autocapture (vs Classic's autocapture-by-default approach)
* **Improved event accuracy**: No touch events during scrolls; refined pageview logic for `UINavigationController` and multi-window iPad apps; no gesture events
* **Swift class names**: Uses Swift names by default instead of Objective-C mangled names (configurable via `useObjectiveCClassNames`)
* **Shorter hierarchies**: Captures up to view controller/window instead of 30-level depth
* **Live View only**: Visual Labeler not supported; hierarchy data now visible in Live View
* **Opt-out by default**: Must call `CSQ.optIn()` to start tracking
* **Separate storage**: Expect temporary spike in new users/installs during migration
* **Removed properties**: No longer captures view controller `accessibilityIdentifier` and `accessibilityLabel` on pageviews

## Dependency upgrades

Replace the Heap Classic SDK dependencies by the CSQ SDK dependency.

* Swift Package Manager

  1. In your XCode project > `Package Dependencies`, update the repository location:

     ```diff
     https://github.com/heap/heap-ios-sdk.git
     https://github.com/ContentSquare/apple-sdk.git
     ```

  2. Set the Dependency Rule to `Exact Version` `1.10.0`.

  3. To ensure the library can start properly, add `-ObjC` as a linker flag under `Build Settings` > `Linking - General` > `Other Linker Flags`.

* CocoaPods

  1. Update your pods:

     **Podfile**

     ```diff
     pod 'Heap', '~> 9.1.0'
     pod 'ContentsquareSDK', '1.10.0'
     ```

  2. Run `pod install` within your project directory.

  3. Build your app target.

## Library imports

Replace the Heap Classic SDK import with the CSQ SDK import.

```diff
import Heap
import HeapIOSAutocapture
import HeapNotificationAutocapture
import ContentsquareSDK
```

## SDK start

Follow these steps to start the CSQ SDK with your current configuration.

1. Delete `Heap.init()` and migrate configuration to the unified `CSQ.start()` method.

   * Standalone

     ```swift
     Heap.init("YOUR_ENVIRONMENT_ID", with: [
       // ...options
     ])


     CSQ.start(
       environmentID: "YOUR_ENVIRONMENT_ID",
       options: [
         // ...options
       ]
     )
     ```

   * CSQ Experience Platform

     ```swift
     Heap.init("YOUR_ENVIRONMENT_ID", with: [
       // ...options
     ])


     CSQ.start(
       dataSourceID: "YOUR_DATASOURCE_ID",
       options: [
         // ...options
       ]
     )
     ```

   Deprecated configuration options

   The following Heap SDK configuration options are not ported to the CSQ SDK:

   * `startSessionImmediately`
   * `disableInteractionTextCapture`
   * `disableInteractionAccessibilityLabelCapture`
   * `enableInteractionReferencingPropertyCapture`
   * `interactionHierarchyCaptureLimit`
   * `captureVendorID`
   * `captureAdvertiserID`
   * `clearEventPropertiesOnNewUser`
   * `messageBatchMessageLimit`
   * `messageBatchByteLimit`
   * `resumePreviousSession`

   See [supported options](../command-reference/#sdk-configuration-options) for more information.

2. Recommended for UIKit Enable Autocapture with `.enableNativeAutocapture: true` and remove the call to `Heap.iOSAutocaptureSource.register()`

   * Standalone

     ```swift
     CSQ.start(
       environmentID: "YOUR_ENVIRONMENT_ID",
       options: [
         // ...options
         .enableNativeAutocapture: true
       ]
     )


     Heap.iOSAutocaptureSource.register(isDefault: true)
     ```

   * CSQ Experience Platform

     ```swift
     CSQ.start(
       dataSourceID: "YOUR_DATASOURCE_ID",
       options: [
         // ...options
         .enableNativeAutocapture: true
       ]
     )


     Heap.iOSAutocaptureSource.register(isDefault: true)
     ```

3. (Optional) To start HeapNotification, add `.enablePushNotificationAutocapture: true` and remove the call to `Heap.NotificationAutocaptureSource.register()`.

   * Standalone

     ```swift
     CSQ.start(
       environmentID: "YOUR_ENVIRONMENT_ID",
       options: [
         // ...options
         .enablePushNotificationAutocapture: true
       ]
     )


     Heap.NotificationAutocaptureSource.register()
     ```

   * CSQ Experience Platform

     ```swift
     CSQ.start(
       dataSourceID: "YOUR_DATASOURCE_ID",
       options: [
         // ...options
         .enablePushNotificationAutocapture: true
       ]
     )


     Heap.NotificationAutocaptureSource.register()
     ```

4. (Optional) Configure HeapNotification using `.enablePushNotificationTitleAutocapture` and `.enablePushNotificationBodyAutocapture` and remove the call to `Heap.NotificationAutocaptureSource.register()`.

   * Standalone

     ```swift
     CSQ.start(
       environmentID: "YOUR_ENVIRONMENT_ID",
       options: [
         // ...options
         .enablePushNotificationAutocapture: true,
         .enablePushNotificationTitleAutocapture: true,
         .enablePushNotificationBodyAutocapture: true
       ]
     )


     Heap.NotificationAutocaptureSource.register(captureTitle: true|false, captureBody: true|false)
     ```

   * CSQ Experience Platform

     ```swift
     CSQ.start(
       dataSourceID: "YOUR_DATASOURCE_ID",
       options: [
         // ...options
         .enablePushNotificationAutocapture: true,
         .enablePushNotificationTitleAutocapture: true,
         .enablePushNotificationBodyAutocapture: true
       ]
     )


     Heap.NotificationAutocaptureSource.register(captureTitle: true|false, captureBody: true|false)
     ```

## Get user consent

Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking.

* Standalone

  ```swift
  import UIKit
  import ContentsquareSDK


  // In viewDidLoad()
  optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside)


  @objc func optInButtonTapped(_ sender: UIButton) {
    CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID")
    CSQ.optIn()
    // Continue with post-consent navigation or UI update
  }
  ```

* CSQ Experience Platform

  ```swift
  import UIKit
  import ContentsquareSDK


  // In viewDidLoad()
  optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside)


  @objc func optInButtonTapped(_ sender: UIButton) {
    CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID")
    CSQ.optIn()
    // Continue with post-consent navigation or UI update
  }
  ```

Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more.

Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code.

## Update APIs

Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption.

```diff
Heap.init("YOUR_ENVIRONMENT_ID")
CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID")
```

For more information on SDK methods, see the [SDK API reference](../command-reference/).

### GDPR / Identification

| Heap Classic SDK | CSQ SDK |
| - | - |
| `Heap.shared.identify(string)` | `CSQ.identify(String)` |
| `Heap.shared.resetIdentity()` | `CSQ.resetIdentity()` |
| `Heap.shared.userId` | `CSQ.metadata.userID` |
| `Heap.shared.sessionId` | `CSQ.metadata.sessionID` |
| `Heap.shared.getEnvironmentId` | `CSQ.metadata.environmentID` |
| `Heap.shared.identity` | `CSQ.metadata.identity` |

### Logging

| Heap Classic SDK | CSQ SDK |
| - | - |
| `Heap.shared.logLevel { get set }` | `CSQ.debug.logLevel { get set }` |
| `Heap.shared.logChannel { get set }` | `CSQ.debug.logChannel(LogChannel)` |
| `Heap.shared.printLog()` | `LogChannel.printLog()` |

### Property tracking

| Heap Classic SDK | CSQ SDK |
| - | - |
| `Heap.shared.addUserProperties(properties: [String: HeapPropertyValue])` | `CSQ.addUserProperties([Property])` |
| `Heap.shared.addEventProperties(properties: [String: HeapPropertyValue])` | `CSQ.addEventProperties([Property])` |
| `Heap.shared.removeEventProperty(name: String)` | `CSQ.removeEventProperty(name: String)` |
| `Heap.shared.clearEventProperties()` | `CSQ.clearEventProperties()` |

### Event tracking

| Heap Classic SDK | CSQ SDK |
| - | - |
| `Heap.shared.track()` | `CSQ.trackEvent(name: String, properties: [String, PropertyValue]?)` |

### Personal Data Handling and Masking

| Heap Classic SDK | CSQ SDK |
| - | - |
| `View.heapIgnoreInteractions` | `CSQ.ignoreInteractions(View)` / `CSQ.ignoreInteractions(UIView)` / `UIView.csqIgnoreInteractions (UIKit)` / `View.csqIgnoreInteractions(shouldIgnore:Boolean)(SwiftUI)` |
| `View.heapRedactText` / `View.heapRedactAccessibilityLabel` | `CSQ.mask(UIView)` / `UIView.csqMaskContents (UIKit)`/ `View.csqMaskContents(enable: boolean) (SwiftUI)` |
| `view.setTag(R.id.heapRedactText, false)` | `CSQ.unmask(UIView)` / `UIView.csqMaskContents (UIKit)` / `View.csqMaskContents(enable: Boolean) (SwiftUI)` |
| Initialization options `disableInteractionTextCapture` and `disableInteractionAccessibilityLabelCapture` | `CSQ.maskTexts(mask: Boolean)` |
| `UIView.heapIgnoreInteractionsDefault` | `csqIgnoreInteractionsDefault` |
| `UIView.heapIgnoreInnerHierarchy` | `csqIgnoreInnerHierarchy` |
| `UIView.heapIgnoreInnerHierarchyDefault` | `csqIgnoreInnerHierarchyDefault` |

### SDK initialization and manipulation

| Heap Classic SDK | CSQ SDK |
| - | - |
| Heap SDK initialization options | `CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID", options: AnalyticsOptions(...))` See [supported options](../command-reference/#sdk-configuration-options) for more information. |
| `Heap.shared.init(context, id)` | `CSQ.start()` |
| `Heap.shared.stopRecording(deleteUser = true)` | `CSQ.stop()` |
| `Heap.shared.stopRecording(deleteUser = false)` | `CSQ.pauseTracking()` |

## Checklist

Congratulations! You're all set. Use this checklist to ensure everything is correctly updated.

Ensure that your build files no longer reference `https://github.com/heap/heap-ios-sdk.git`.

Your `import Heap` declarations have been updated to `import ContentsquareSDK`.

You no longer have references to `Heap.` methods in your codebase.

All calls to the CSQ SDK use the `CSQ.` namespace.