From Heap Classic SDK to CSQ SDK

Heap Classic SDK

→

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.

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

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

import Heap
import HeapIOSAutocapture
import HeapNotificationAutocapture
import ContentsquareSDK

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
   • Unified CSQ

     Onboard to Unified CSQ, our latest, all-in-one platform offering.

     Reach out to your Customer Success Manager for more information.

   Heap.init("YOUR_ENVIRONMENT_ID", with: [
     // ...options
   ])
   
   CSQ.start(
     environmentID: "YOUR_ENVIRONMENT_ID",
     options: [
       // ...options
     ]
   )

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

   • Standalone
   • Unified CSQ

     Onboard to Unified CSQ, our latest, all-in-one platform offering.

     Reach out to your Customer Success Manager for more information.

   CSQ.start(
     environmentID: "YOUR_ENVIRONMENT_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
   • Unified CSQ

     Onboard to Unified CSQ, our latest, all-in-one platform offering.

     Reach out to your Customer Success Manager for more information.

   CSQ.start(
     environmentID: "YOUR_ENVIRONMENT_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
   • Unified CSQ

     Onboard to Unified CSQ, our latest, all-in-one platform offering.

     Reach out to your Customer Success Manager for more information.

   CSQ.start(
     environmentID: "YOUR_ENVIRONMENT_ID",
     options: [
       // ...options
       .enablePushNotificationAutocapture: true,
       .enablePushNotificationTitleAutocapture: true,
       .enablePushNotificationBodyAutocapture: true
     ]
   )
   
   Heap.NotificationAutocaptureSource.register(captureTitle: true|false, captureBody: true|false)

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

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
}

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.

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.

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

For more information on SDK methods, see the SDK API reference.

GDPR / Identification

Logging

Property tracking

Event tracking

Personal Data Handling and Masking

SDK initialization and manipulation

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.