From Heap Core SDK to CSQ SDK

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

→

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

You must update the following dependency 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.

Swift Package Manager
Cocoapods

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

https://github.com/ContentSquare/apple-sdk.git
https://github.com/ContentSquare/apple-sdk-prereleases.git

Set the Dependency Rule to Exact Version 1.1.0-rc.1.
To ensure the library can start properly, add -ObjC as a linker flag under Build Settings > Linking - General > Other Linker Flags.

Update the CSQ SDK version:

pod 'ContentsquareSDK', '~> 0.4.0'
pod 'ContentsquareSDK', '~> 1.0.0'

Run pod install within your project directory.
Build your app target.

Heap Core SDK (`https://͏github.com/heap/heap-swift-core-sdk.git`)

Replace the Heap Swift Core SDK by the CSQ SDK.

Swift Package Manager
Cocoapods

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

https://github.com/heap/heap-swift-core-sdk.git
https://github.com/ContentSquare/apple-sdk-prereleases.git

Set the Dependency Rule to Exact Version 1.1.0-rc.1.
To ensure the library can start properly, add -ObjC as a linker flag under Build Settings > Linking - General > Other Linker Flags.

Update your pods:

pod 'HeapSwiftCore', '0.8.1'
pod 'ContentsquareSDK', '~> 1.0.0'

Run pod install within your project directory.
Build your app target.

Library imports

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

Swift
Objective-C

import HeapSwiftCore
import ContentsquareSDK

@import HeapSwiftCore;
@import ContentsquareSDK;

SDK start

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

Migrate configuration options from Heap.startRecording() to CSQ.configureProductAnalytics().

Swift
Objective-C

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

[Heap startRecording:@"YOUR_ENVIRONMENT_ID"];
[CSQ configureProductAnalyticsWithEnvironmentID:@"YOUR_ENVIRONMENT_ID"
  additionalOptions:@{
    CSQProductAnalyticsOptionUploadInterval: @(5),
    CSQProductAnalyticsOptionBaseUrl: @"https://example.com/",
    CSQProductAnalyticsOptionCaptureVendorId: @(YES),
    CSQProductAnalyticsOptionDisablePageviewTitleCapture: @(YES)
  }];

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)

[CSQ configureProductAnalyticsWithEnvironmentID:@"YOUR_ENVIRONMENT_ID"
  additionalOptions:@{
    CSQProductAnalyticsOptionEnableUIKitAutocapture: @(YES)
  }];

[HeapiOSAutocaptureSource registerWithIsDefault:YES];

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)

[CSQ configureProductAnalyticsWithEnvironmentID:@"YOUR_ENVIRONMENT_ID"
  additionalOptions:@{
    CSQProductAnalyticsOptionEnableUIKitAutocapture: @(YES)
  }];

[CSQ start];

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

Swift
Objective-C

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.

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.

Heap.startRecording()
CSQ.start()

For more information on SDK methods, see the SDK API 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 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.