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

Contentsquare SDK

CSQ 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 one of the two 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.

  1. 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
  2. Set the Dependency Rule to Exact Version 1.1.0-rc.1.

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

Contentsquare SDK (https://͏github.com/ContentSquare/CS_iOS_SDK.git)

Replace the Contentsquare SDK by the CSQ SDK.

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

    https://github.com/ContentSquare/CS_iOS_SDK.git
    https://github.com/ContentSquare/apple-sdk-prereleases.git
  2. Set the Dependency Rule to Exact Version 1.1.0-rc.1.

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

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

import ContentsquareModule
import ContentsquareSDK
  1. 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
    }
    }
  2. (Optional) If you were relying on the Contentsquare SDK autostart, remove the CSDisableAutostart property and calls to Contentsquare.start().

    Info.plist
    <key>CSDisableAutostart</key>
    <true/>
    AppDelegate.swift
    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()
...
}

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()
CSQ.start()

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

GDPR / Identification

Contentsquare SDKCSQ SDK
Contentsquare.optIn()CSQ.optIn()
Contentsquare.optOut()CSQ.optOut()
Contentsquare.userIDCSQ.metadata.userID
Contentsquare.projectIDCSQ.metadata.projectID
Contentsquare.sessionNumberCSQ.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 SDKCSQ SDK
Contentsquare.logLevel { get set }CSQ.debug.logLevel { get set }

Property tracking

Contentsquare SDKCSQ SDK
Contentsquare.send(dynamicVar: DynamicVar(key: String, value: UInt32))

Contentsquare.send(dynamicVar: DynamicVar(key: String, value: String))
CSQ.addDynamicVar(DynamicVar)

View tracking

Contentsquare SDKCSQ SDK
UIScrollView.excludeFromExposureMetric()UIScrollView.excludeFromExposureMetrics()

CSInApp

Contentsquare SDKCSQ SDK
Contentsquare.handle(url: URL)CSQ.handle(url: URL)
Contentsquare.csInAppCSQ.csInApp

Interoperability

Contentsquare SDKCSQ SDK
Contentsquare.onSessionReplayLinkChange(callback)CSQ.metadata.onChange(Metadata)
Contentsquare.register(webView: WKWebView)CSQ.registerWebView(WKWebView)
Contentsquare.unregister(webView: WKWebView)CSQ.unregisterWebView(WKWebView)

Event tracking

Contentsquare SDKCSQ 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 SDKCSQ SDK
ErrorAnalysis.setUrlMaskingPatterns([String])CSQ.setURLMaskingPatterns([String])
ErrorAnalysis.onCrashReporterStart()CSQ.onCrashReporterStart()
HTTPMetricNetworkMetric
HTTPMetric.stop()CSQ.trackNetworkMetric(NetworkMetric)
ErrorAnalysis.getInstance().newNetworkMetric(url, ErrorAnalysis.HttpMethod.GET)CSQ.trackNetworkMetric(NetworkMetric(id, httpMethod, optionalId))

Personal Data Handling and Masking

Contentsquare SDKCSQ 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 SDKCSQ SDK
Contentsquare.start() CSQ.start()
Contentsquare.stopTracking()CSQ.pauseTracking()
Contentsquare.resumeTracking()CSQ.resumeTracking()

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.