From Contentsquare SDK to CSQ SDK

This guide provides a step-by-step upgrade process from your current installation of Contentsquare Mobile SDK to the latest version of the CSQ 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.

Dependency upgrades

Replace the Contentsquare SDK by the CSQ SDK.

Swift Package Manager
Cocoapods

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

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

Set the Dependency Rule to Exact Version 1.4.0.
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 'ContentsquareModule', '4.35.1'
pod 'ContentsquareSDK', '1.4.0'

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

Library imports

Replace the Contentsquare SDK import with a unified CSQ SDK import.

Swift
Objective-C

import ContentsquareModule
import ContentsquareSDK

@import ContentsquareModule;
@import ContentsquareSDK;

SDK start

Start the CSQ SDK manually using CSQ.start(). Unlike earlier versions, it no longer starts automatically.

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    CSQ.start()
    return true
  }
}

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?
    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
      CSQ.start()
    }
}

@main
struct MyApp: App {
    init() {
      CSQ.start()
    }
    var body: some Scene {
      WindowGroup {
        ContentView()
      }
    }
  }

class AppDelegate: NSObject, UIApplicationDelegate {
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
      CSQ.start()
      return true
  }
}

@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
    var body: some Scene {
    WindowGroup {
        ContentView()
    }
  }
}

(Optional) If you were relying on the Contentsquare SDK autostart, remove the CSDisableAutostart property and calls to Contentsquare.start().
- Swift
- Objective-C
Info.plist
<key>CSDisableAutostart</key> <true/>
AppDelegate.swift
Contentsquare.start()
Info.plist
<key>CSDisableAutostart</key> <true/>
AppDelegate.m
[Contentsquare 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.

Contentsquare.start()
CSQ.start()

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

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()`

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/ContentSquare/CS_iOS_SDK.git.

Your import ContentsquareModule declarations have been updated to import ContentsquareSDK.

You no longer have references to Contentsquare. methods in your codebase.

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