From Heap Core SDK + Contentsquare SDK to CSQ SDK

Heap Core SDK

+

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

You must update the following dependencies based on your current version of the SDK.

CSQ SDK (https://͏github.com/ContentSquare/apple-sdk.git < 1.0)

If you are already using a version of the CSQ SDK earlier than 1.0, update to the latest version.

Heap Core and Contentsquare SDKs ( https://͏github.com/heap/heap-swift-core-sdk.git, https://͏github.com/ContentSquare/CS_iOS_SDK.git)

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

Replace the Heap and Contentsquare dependency imports with a unified CSQ SDK import.

import HeapSwiftCore
import HeapContentsquareIntegrationSDK
import HeapIOSAutocapture
import HeapNotificationAutocapture
import ContentsquareModule
import ContentsquareSDK

@import HeapSwiftCore;
@import HeapContentsquareIntegrationSDK;
@import HeapIOSAutocapture;
@import HeapNotificationAutocapture;
@import ContentsquareModule;
@import ContentsquareSDK;

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

1. Migrate configuration options from Heap.startRecording() to CSQ.configureProductAnalytics().
   • Swift
   • Objective-C

   Heap.startRecording("YOUR_ENVIRONMENT_ID",
   CSQ.configureProductAnalytics(
     environmentID: "YOUR_ENVIRONMENT_ID",
   )

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

   • Swift
   • Objective-C

   CSQ.configureProductAnalytics(
     environmentID: "YOUR_ENVIRONMENT_ID",
     additionalOptions: [
       .enableUIKitAutocapture: true
     ]
   )
   
   Heap.iOSAutocaptureSource.register(isDefault: true)

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

   • Swift
   • Objective-C

   CSQ.configureProductAnalytics(
     environmentID: "YOUR_ENVIRONMENT_ID",
     additionalOptions: [
       .enableUIKitAutocapture: true
     ]
   )
   
   CSQ.start(this)

4. Replace HeapContentsquareIntegration.bind() by configuration options. Note the change in boolean flags controlling data forwarding.

   Sending Heap pageviews to Contentsquare:

   • Swift
   • Objective-C

   HeapContentsquareIntegration.bind(
     sendHeapPageviewsToContentsquare: false,
     sendContentsquareScreenviewsToHeap: true
   )
   
   CSQ.configureProductAnalytics(
     environmentID: "YOUR_ENVIRONMENT_ID",
     additionalOptions: [
       .disableScreenviewForwardToDXA: true,
       .disableScreenviewForwardToPA: false
     ]
   )

   Sending Contentsquare screenviews to Heap:

   • Swift
   • Objective-C

   HeapContentsquareIntegration.bind(
     sendHeapPageviewsToContentsquare: true,
     sendContentsquareScreenviewsToHeap: false
   )
   
   CSQ.configureProductAnalytics(
     environmentID: "YOUR_ENVIRONMENT_ID",
     additionalOptions: [
       .disableScreenviewForwardToDXA: false,
       .disableScreenviewForwardToPA: true
     ]
   )

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

   • Swift
   • Objective-C

   <key>CSDisableAutostart</key>
   <true/>

   Contentsquare.start()

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

import UIKit
import ContentsquareSDK

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

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

#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...
}

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

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.

Contentsquare.start()
Heap.startRecording()
CSQ.start()

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

GDPR / Identification

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

Property tracking

View tracking

CSInApp

Interoperability

Event tracking

Error 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, 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.