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

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 Core SDK](https://docs.contentsquare.com/heap-logo.png)

**Heap Core 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.

## Dependency upgrades

Replace the Heap Swift Core SDK by the CSQ SDK.

* Swift Package Manager

  1. In your XCode project > `Package Dependencies`, update your packages:

     ```diff
     https://github.com/heap/heap-swift-core-sdk.git
     https://github.com/heap/heap-ios-autocapture-sdk.git
     https://github.com/heap/heap-notification-autocapture-sdk.git
     https://github.com/ContentSquare/apple-sdk.git
     ```

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

  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 'HeapSwiftCore', '~> 9.1.0'
     pod 'HeapIOSAutocapture', '~> 0.8.0'
     pod 'HeapNotificationAutocapture', '~> 0.8.0'
     pod 'ContentsquareSDK', '1.6.1'
     ```

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

  3. Build your app target.

## Library imports

Replace the Heap Core SDK import with a unified CSQ SDK import.

* Swift

  ```diff
  import HeapSwiftCore
  import HeapIOSAutocapture
  import HeapNotificationAutocapture
  import ContentsquareSDK
  ```

* Objective-C

  ```diff
  @import HeapSwiftCore;
  @import HeapIOSAutocapture;
  @import HeapNotificationAutocapture;
  @import ContentsquareSDK;
  ```

## SDK start

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

1. Delete `Heap.startRecording()` and migrate configuration options to `CSQ.configureProductAnalytics()`.

   * Swift

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


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

   * Objective-C

     ```objective-c
     [Heap.shared startRecording:@"YOUR_ENVIRONMENT_ID" with:@{
       // ...options
     }];


     [CSQ configureProductAnalyticsWithEnvironmentID:@"YOUR_ENVIRONMENT_ID"
       additionalOptions:@{
         // ...options
       }];
     ```

   Deprecated configuration options

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

   * `startSessionImmediately`
   * `disableInteractionTextCapture`
   * `disableInteractionAccessibilityLabelCapture`
   * `enableInteractionReferencingPropertyCapture`
   * `interactionHierarchyCaptureLimit`

   See [supported options](../command-reference/#product-analytics-initialization-options) for more information.

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

   * Swift

     ```swift
     CSQ.configureProductAnalytics(
       environmentID: "YOUR_ENVIRONMENT_ID",
       additionalOptions: [
         // ...options
         .enableUIKitAutocapture: true
       ]
     )


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

   * Objective-C

     ```objective-c
     [CSQ configureProductAnalyticsWithEnvironmentID:@"YOUR_ENVIRONMENT_ID"
       additionalOptions:@{
         // ...options
         CSQProductAnalyticsOptionEnableUIKitAutocapture: @(YES)
       }];


     [HeapiOSAutocaptureSource registerWithIsDefault:YES];
     ```

3. Add a call to `CSQ.start(this)` after the configuration call.

   * Swift

     ```swift
     CSQ.configureProductAnalytics(
       environmentID: "YOUR_ENVIRONMENT_ID",
       additionalOptions: [
         // ...options
       ]
     )


     CSQ.start()
     ```

   * Objective-C

     ```objective-c
     [CSQ configureProductAnalyticsWithEnvironmentID:@"YOUR_ENVIRONMENT_ID"
       additionalOptions:@{
         // ...options
       }];


     [CSQ start];
     ```

## Get user consent

The CSQ SDK treats users as opted-out by default.

Implement the [`optIn()`](../command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID.

* Swift

  ```swift
  import UIKit
  import ContentsquareSDK


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


  @objc func optInButtonTapped(_ sender: UIButton) {
      CSQ.start()
      CSQ.optIn()
      ...
  }
  ```

* Objective-C

  ```objective-c
  #import <UIKit/UIKit.h>
  #import <ContentsquareSDK/ContentsquareSDK.h>
  [optinButton addTarget:self action:@selector(optInButtonTapped:) forControlEvents:UIControlEventTouchUpInside];


  - (void)optInButtonTapped:(UIButton *)sender {
      [CSQ start];
      [CSQ optIn];
      // Additional initialization or navigation 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.

In most cases, this process consists in updating the namespace and method names, with no changes to parameters.

```diff
Heap.shared.startRecording()
CSQ.start()
```

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

### GDPR / Identification

| Heap Core 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 Core 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 Core 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 Core SDK | CSQ SDK |
| - | - |
| `Heap.shared.track()` | `CSQ.trackEvent(name: String, properties: [String, PropertyValue]?)` |

### Personal Data Handling and Masking

| Heap Core 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 Core SDK | CSQ SDK |
| - | - |
| Heap SDK initialization options | `CSQ.configureProductAnalytics(environmentID: "YOUR_ENVIRONMENT_ID", additionalOptions: [ options ])` See [supported options](../command-reference/#product-analytics-initialization-options) for more information. |
| `Heap.shared.startRecording(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-swift-core-sdk.git`.

Your `import HeapSwiftCore` 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.