---
title: From Heap Core SDK + Contentsquare SDK to CSQ SDK - iOS
description: Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK
lastUpdated: 30 June 2026
source_url:
  html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-heap-and-cs-sdk/
  md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-heap-and-cs-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/experience-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 Contentsquare and Heap Mobile to the latest version of the CSQ SDK.

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

**Heap Core SDK**

\+

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

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

If you are loading both Heap and Contentsquare SDK, replace these dependencies by the CSQ SDK.

CocoaPods support is ending

CocoaPods trunk becomes read-only on December 2, 2026. After this date, Contentsquare will no longer publish new SDK versions via CocoaPods. [Migrate to Swift Package Manager (SPM)](https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/) to continue receiving updates.

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

   ```diff
   https://github.com/heap/heap-swift-core-sdk.git
   https://github.com/ContentSquare/CS_iOS_SDK.git
   https://github.com/heap/heap-ios-cs-integration-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.12.3`.

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

Migrating from CSQ SDK 0.x?

Update the version for the `apple-sdk` package. Skip the Heap dependency lines. All other steps in this guide still apply.

In your Xcode project > `Package Dependencies`, update the `apple-sdk` version:

* Remove the existing `https://github.com/ContentSquare/apple-sdk.git` package.
* Re-add `https://github.com/ContentSquare/apple-sdk.git` and set the Dependency Rule to `Exact Version` `1.12.3`.

Previously no version was pinned. An exact version is now required.

## Library imports

Replace the Heap and Contentsquare imports with the CSQ SDK import.

```diff
import HeapSwiftCore
import HeapContentsquareIntegrationSDK
import HeapIOSAutocapture
import HeapNotificationAutocapture
import ContentsquareModule
import ContentsquareSDK
```

## SDK start

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

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

   * Product Analytics

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


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

   * CSQ Experience Platform (Early Access)

     ```swift
     Heap.shared.startRecording("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()`

   * Product Analytics

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


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

   * CSQ Experience Platform (Early Access)

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


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

3. Remove `HeapContentsquareIntegration.bind()`.

   Sending Heap pageviews to Contentsquare

   **AppDelegate.swift**

   ```swift
   HeapContentsquareIntegration.bind(
     sendHeapPageviewsToContentsquare: false,
     sendContentsquareScreenviewsToHeap: true
   )
   ```

   Note

   Make sure you don't have calls to `CSQ.trackScreenview()` if you have autocapture enabled.

   Sending Contentsquare screenviews to Heap

   * Product Analytics

     **AppDelegate.swift**

     ```swift
     HeapContentsquareIntegration.bind(
       sendHeapPageviewsToContentsquare: true,
       sendContentsquareScreenviewsToHeap: false
     )


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

   * CSQ Experience Platform (Early Access)

     **AppDelegate.swift**

     ```swift
     HeapContentsquareIntegration.bind(
       sendHeapPageviewsToContentsquare: true,
       sendContentsquareScreenviewsToHeap: false
     )


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

4. (Optional) If you were relying on the Contentsquare SDK autostart, remove the `CSDisableAutostart` property and calls to `Contentsquare.start()`.

   **Info.plist**

   ```xml
   <key>CSDisableAutostart</key>
   <true/>
   ```

   **AppDelegate.swift**

   ```swift
   Contentsquare.start()
   ```

## Get user consent

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

* Experience Analytics

  ```swift
  import UIKit
  import ContentsquareSDK


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


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

* CSQ Experience Platform (Early Access)

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

## 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
Contentsquare.start()
Heap.shared.startRecording("YOUR_ENVIRONMENT_ID")
CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID")
```

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.

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

### Product Analytics (Heap Core SDK)

### 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.start(environmentID: "YOUR_ENVIRONMENT_ID", options: AnalyticsOptions(...))` See [supported options](../command-reference/#sdk-configuration-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()` |

### Experience Analytics (Contentsquare SDK)

### GDPR / Identification

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.optIn()` | `CSQ.optIn()` |
| `Contentsquare.optOut()` | `CSQ.optOut()` |
| `Contentsquare.sendUserIdentifier()` | `CSQ.sendUserIdentifier()` |
| `Contentsquare.userID` | `CSQ.metadata.userID` |
| `Contentsquare.projectID` | `CSQ.metadata.projectID` |
| `Contentsquare.sessionNumber` | `CSQ.metadata.sessionID` |

Deprecated

**Contentsquare.forgetMe()**

You can use `CSQ.optOut()` instead to forget user id and stop tracking. If needed call `CSQ.optIn()` when you want to resume tracking.

### Logging

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.logLevel { get set }` | `CSQ.debug.logLevel { get set }` |

### Property tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.send(dynamicVar: DynamicVar(key: String, value: UInt32))` `Contentsquare.send(dynamicVar: DynamicVar(key: String, value: String))` | `CSQ.addDynamicVar(DynamicVar)` |

### View tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `UIScrollView.excludeFromExposureMetric()` | `UIScrollView.excludeFromExposureMetrics()` |

### CSInApp

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.handle(url: URL)` | `CSQ.handle(url: URL)` |
| `Contentsquare.csInApp` | `CSQ.csInApp` |

### Interoperability

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.onSessionReplayLinkChange(callback)` | `CSQ.metadata.onChange { metadata in }` |
| `Contentsquare.register(webView: WKWebView)` | `CSQ.registerWebView(WKWebView)` |
| `Contentsquare.unregister(webView: WKWebView)` | `CSQ.unregisterWebView(WKWebView)` |

### Event tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.send(transaction: CustomerTransaction)` | `CSQ.trackTransaction(Transaction)` |
| `Contentsquare.send(screenViewWithName name: String)` / `Contentsquare.send(screenViewWithName name: String, cvars: [CustomVar] = [])` | `CSQ.trackScreenview(String)/CSQ.trackScreenview(String, cvars: [CustomVar])` |

### Error tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `ErrorAnalysis.setUrlMaskingPatterns([String])` | `CSQ.setURLMaskingPatterns([String])` |
| `ErrorAnalysis.onCrashReporterStart()` | `CSQ.onCrashReporterStart()` |
| `HTTPMetric` | `NetworkMetric` |
| `HTTPMetric.stop()` | `CSQ.trackNetworkMetric(NetworkMetric)` |
| `ErrorAnalysis.getInstance().newNetworkMetric(url, ErrorAnalysis.HttpMethod.GET)` | `CSQ.trackNetworkMetric(NetworkMetric(id, httpMethod, optionalId))` |

### Personal Data Handling and Masking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.setDefaultMasking(boolean masked)` | `CSQ.setDefaultMasking(boolean masked)` |
| `Contentsquare.mask(viewsOfType: UIView.Type)` | `CSQ.mask(viewsOfType: UIView.Type)` |
| `Contentsquare.mask(view: UIView)` | `CSQ.mask(UIView)`/ `UIView.csqMaskContents (UIKit)` |
| `View.csMasking(Bool)` | `View.csqMaskContents(enable: Boolean) (SwiftUI)` |
| `Contentsquare.unmask(UIView)` | `CSQ.unmask(UIView)` |
| `Contentsquare.unmask(viewsOfType: UIView.Type)` | `CSQ.unmask(viewsOfType: UIView.Type)` |
| `Contentsquare.maskTexts(mask: Boolean)` | `CSQ.maskTexts(mask: Boolean)` |
| `Contentsquare.maskImages(mask: Boolean)` | `CSQ.maskImages(mask: Boolean)` |
| `Contentsquare.maskTextInputs(mask: Boolean)` | `CSQ.maskTextInputs(mask: Boolean)` |

### SDK initialization and manipulation

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.start()` | `CSQ.start()` |
| `Contentsquare.stopTracking()` | `CSQ.pauseTracking()` |
| `Contentsquare.resumeTracking()` | `CSQ.resumeTracking()` |

## Number of sessions

Session timeout definition changed:

* **Before**: 30 minutes after app goes to background
* **Now**: 30 minutes after last event

This may affect session counts and aligns with web and market standards.

## 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`, `https://github.com/ContentSquare/CS_iOS_SDK.git`.

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

You no longer have references to `Heap.` (except if you are using webviews), `HeapContentsquareIntegration.`, or `Contentsquare.` methods in your codebase.

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


```json
{"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK + Contentsquare SDK to CSQ SDK","description":"Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-heap-and-cs-sdk/","inLanguage":"en","dateModified":"2026-06-30T16:49:52+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}}
```