SDK API reference

The SDK API provides the following methods with their signatures, parameters, and usage examples.

Get user consent. Calling this API generates a user ID and initiates tracking.

Call optIn after start.

CSQ.optIn()

Revoke user consent, remove stored userID. Stop CSQ SDK, flush, and clear all data.

CSQ.optOut()

Product Analytics | Added in: 1.0.0

Assigns an identity to be associated with the current user.

This assigns the identity to all events for the user ID and lets the analysis module merge multiple user IDs with the same identity.

This should be called only after Product Analytics is configured and the SDK started. It's safe to call multiple times with the same value. Always provide a value that will be unique to this user. Setting values like "guest", "anonymous", "unauthenticated" or similar will merge all those users into a single user profile.

CSQ.identify("userIdentity")

If the user was previously identified with identify(), this creates a new unidentified user and session. This is technically similar to calling optOut() then optIn().

This should be called only after Product Analytics is configured and the SDK started.

CSQ.resetIdentity()

Get all the information related to the user and project.

Identifier of the current user. This is an identifier from Product Analytics by default or Experience Analytics if PA is not active.

let userID = CSQ.metadata.userID

Session identifier. This is an identifier from Experience Analytics by default or Product Analytics if Experience Analytics is not active.

let sessionID = CSQ.metadata.sessionID

Project identifier for Experience Analytics.

let projectID = CSQ.metadata.projectID

Environment identifier for Product Analytics.

let environmentID = CSQ.metadata.environmentID

URL of current Session Replay.

let sessionReplayURL = CSQ.metadata.sessionReplayURL

Identity associated with the user by calling identify().

let identity = CSQ.metadata.identity

A block triggered each time user information is updated. For example when sessionReplayURL becomes available or userID updates. Set this block to subscribe to the updates. Contentsquare will call this block with updated metadata.

CSQ.metadata.onChange { metadata in
  // Handle information change
}

Gets or sets the current log level.

CSQ.debug.logLevel = .debug

Product Analytics | Added in: 1.0.0

Gets or sets the LogChannel to which send log messages.

CSQ.debug.logChannel = customLogChannel

Product Analytics | Added in: 1.0.0

Implement this function to route SDK logs to another location such as CocoaLumberjack, SwiftyBeaver, or similar logging libraries. The default implementation routes all logs through os_log.

class CustomLogChannel: LogChannel {
  func printLog(logLevel: Log.Level, message: () -> String, source: String?, file: String, line: UInt) {
    // your implementation
  }
}

Experience Analytics | Added in: 1.0.0

Adds dynamic variables to the session properties. This method allows you to pass DynamicVar object, representing a key-value pair that is scoped to the session.

let var1 = DynamicVar(key: "key1", value: "value1")
let var2 = DynamicVar(key: "key2", value: 2)

CSQ.addDynamicVar(var1)
CSQ.addDynamicVar(var2)

Product Analytics | Added in: 1.0.0

Add a collection of properties to be associated with the current user.

CSQ.addUserProperties(["propertyKey"": "propertyValue"])

Product Analytics | Added in: 1.0.0

Add a collection of properties to be associated with all future events.

CSQ.addEventProperties(["propertyKey": "propertyValue"])

Product Analytics | Added in: 1.0.0

Removes a single property from the collection of event-wide properties.

CSQ.removeEventProperty("propertyKey")

Product Analytics | Added in: 1.0.0

Removes all event-wide properties.

CSQ.clearEventProperties()

Product Analytics | Added in: 1.13.0

Overriding this property replaces the autocaptured screen name for the given class.

extension SignUpFlowViewController {
    open override class var csqScreenNameOverride: String? {
        "Main Signup Flow"
    }
}

For more details check our Product Analytics documentation.

Product Analytics | Added in: 1.2.0

Provide the screen name for a SwiftUI screenview.

TransactionView().csqScreenName("TransactionScreen")

For more details check our Product Analytics documentation.

Experience Analytics | Added in: 1.0.0

Exclude a scrollable view or subclass from Exposure Metric computations.

let scrollView = UIScrollView()
scrollView.excludeFromExposureMetrics()

Experience Analytics | Added in: 1.0.0

Allows the Contentsquare SDK to monitor CS in-app features activation through a custom URL scheme.

For more details check our CSInApp documentation.

CSQ.handle(url: <CSInAppURL>))

Experience Analytics | Added in: 1.0.0

Boolean to manually activate or deactivate in-app features.

When CSQ.csInApp = true, the in-app function is activated automatically at app start.

CSQ.csInApp = true

Experience Analytics | Added in: 1.0.0

Register a webview for tracking.

let webView = WKWebView()
CSQ.registerWebView(webView)

Unregister a webview for tracking.

CSQ.unregisterWebView(webView)

Experience Analytics | Added in: 1.0.0

Send a transaction.

let transaction = Transaction(id: "transactionId", total: 100.0, currency: .usd)
CSQ.trackTransaction(transaction)

Send a screen view with or without custom variables. Requires Experience Analytics to be started.

CSQ.trackScreenview(name: "ScreenName", cvars: [CustomVar(index: 1, name: "name", value: "value")])

Product Analytics | Added in: 1.0.0

Creates an event message to be tracked and sent to the API.

CSQ.trackEvent(name: String, properties: ["propertyKey": "propertyValue"]?)

Experience Analytics Voice of Customer | Added in: 1.0.0

Triggers a survey by referencing a predefined trigger name.

This method allows your mobile app to trigger surveys at specific moments in the user journey. Triggers act as flexible placeholders that are not bound to individual surveys, enabling your business team to assign or update surveys later without requiring code changes.

CSQ.triggerSurvey(triggerName)

// Trigger a survey after a purchase is completed
CSQ.triggerSurvey("purchase-complete")

Experience Analytics | Added in: 1.0.0

Sets URL masking patterns.

CSQ.setUrlMaskingPatterns(["pattern1", "pattern2"])

Experience Analytics | Added in: 1.0.0

Trigger a callback when the Contentsquare Crash Reporter is initialized.

CSQ.onCrashReporterStart { enabled in
  // do your work here, e.g. start Firebase Crashlytics
}

Experience Analytics | Added in: 1.0.0

Associate the user identifier to the session.

CSQ.sendUserIdentifier("any_identifier")

Experience Analytics | Added in: 1.0.0

Track network metrics.

let networkMetric = NetworkMetric(url: "https://example.com", httpMethod: "GET")
CSQ.trackNetworkMetric(networkMetric)

Ignore interactions for a specific view.

CSQ.ignoreInteractions(view)

UIKit IBInspectable | Added in: 1.0.0

Ignore interactions for a specific view.

view.csqIgnoreInteractions = true

Product Analytics SwiftUI | Added in: 1.2.0

Ignore interactions for a specific view.

Text("Hello World!").csqIgnoreInteractions(shouldIgnore: true)

Experience Analytics | Added in: 1.0.0

Set the default masking state. All UIView elements, their subclasses and SwiftUI components are fully masked by default.

CSQ.setDefaultMasking(true)

Mask a view's content.

CSQ.mask(view)

Unmask a view's content.

CSQ.unmask(view)

UIKit IBInspectable | Added in: 1.0.0

Mask the content of a view.

view.csqMaskContents = true

SwiftUI | Added in: 1.0.0

Mask the content of a view.

Text("Hello World!").csqMaskContents(true)

Experience Analytics | Added in: 1.0.0

Mask content for views of a specific type.

CSQ.mask(viewsOfType: UIView.Type)

Unmask content for views of a specific type.

CSQ.unmask(viewsOfType: UIView.self)

Mask all texts.

CSQ.maskTexts(true)

Experience Analytics | Added in: 1.0.0

Mask images.

CSQ.maskImages(true)

Experience Analytics | Added in: 1.0.0

Mask text input fields.

CSQ.maskTextInputs(true)

Mark a view's content to be collected encrypted in Session Replay, instead of being masked. Encryption only applies to views that display text; applying it to a container view has no effect on the views inside it. Call it before you add the view to the view hierarchy.

CSQ.encrypt(view: view)

Mark a view's content to be collected encrypted in Session Replay, instead of being masked. Encryption only applies to views that display text; applying it to a container view has no effect on the views inside it.

Text("Hello World!").csqEncrypt()

Remove the encryption mark previously set with CSQ.encrypt(). Call it for reusable views, such as table or collection view cells, so the encryption state doesn't carry over to new content.

CSQ.clearEncrypt(view: view)

Product Analytics UIKit IBInspectable | Added in: 1.0.0

If set on a view or view controller, all touches inside that control will be attributed to it rather than child views. This can be helpful in blocking sensitive parts of an interaction and keeping implementation details out of a view hierarchy. For example, Contentsquare uses this property internally to suppress inner touches on UIDatePicker.

let view = UIView()
view.csqIgnoreInnerHierarchy = true

Deprecated Product Analytics | Added in: 1.0.0

SDK configuration method for Product Analytics. Use CSQ.start() instead, which combines configuration and initialization in a single call.

Start the SDK. This method combines configuration and initialization in a single call.

There are three overloads depending on whether you want Experience Analytics, Product Analytics, or CSQ Experience Platform.

Experience Analytics only:

CSQ.start()

Product Analytics (optionally with Experience Analytics extension) with environmentID:

CSQ.start(
  environmentID: "YOUR_ENVIRONMENT_ID",
  options: [
    .enableNativeAutocapture: true
  ]
)

CSQ Experience Platform with dataSourceID:

CSQ.start(
  dataSourceID: "YOUR_DATASOURCE_ID",
  options: [
    .enableNativeAutocapture: true
  ]
)

Stop all activity from the SDK. Once run no requests, telemetry collection, or logs will be generated.

CSQ.stop()

Pause all tracking features.

CSQ.pauseTracking()

Resume all tracking features.

CSQ.resumeTracking()

The SDK doesn't send a screenview that you track while tracking is paused. If you navigate to a new screen while tracking is paused and then call CSQ.resumeTracking(), the new screen has no screenview unless you send it yourself. For example, this happens when you pause tracking on a sensitive screen and resume it on the next one.

To avoid this, follow this sequence on the screen displayed after the pause:

1. Send the screenview of the screen with CSQ.trackScreenview().
2. Call CSQ.resumeTracking() when the screen is about to be visible, for example in viewWillAppear (UIKit) or onAppear (SwiftUI), right after sending the screenview.

The following example pauses tracking on a sensitive screen and resumes it on the next screen:

// Sensitive screen
override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    CSQ.stop()
}

// Screen displayed after the sensitive screen
override func viewDidLoad() {
    super.viewDidLoad()
    CSQ.trackScreenview("tracked screen") // 1. Send the screenview first
}

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    CSQ.resumeTracking()               // 2. Then resume tracking
}

// Sensitive screen
struct SensitiveView: View {
    var body: some View {
        // ...
        .onAppear {
            CSQ.stop()
        }
    }
}

// Screen displayed after the sensitive screen
struct NextView: View {
    var body: some View {
        // ...
        .onAppear {
            CSQ.trackScreenview("Tracked screen") // 1. Send the screenview first
            CSQ.resumeTracking()               // 2. Then resume tracking
        }
    }
}

Enable and eventually start Session Replay independently of other CSQ SDK features, allowing for on-demand collection. To use this functionality, disable the automatic start of Session Replay at SDK initialization using the .sessionReplayAutoStart option.

CSQ.startSessionReplay()

Stop Session Replay immediately.

CSQ.stopSessionReplay()

CSQ SDK options passed to CSQ.start().

CSQ.start(
  // optional: environmentID: String | dataSourceID: String
  options: [
    .uploadInterval: TimeInterval,
    .baseURL: URL, // EU: "https://mh.ba.contentsquare.net"; https://mh.bf.contentsquare.net (default)
    .disablePageviewAutocapture: Bool,
    .disablePageviewTitleAutocapture: Bool,
    .disableInteractionAutocapture: Bool,
    .enableNativeAutocapture: Bool,
    .enablePushNotificationAutocapture: Bool,
    .enablePushNotificationTitleAutocapture: Bool,
    .enablePushNotificationBodyAutocapture: Bool,
    .sessionReplayAutoStart: Bool
  ]
)

The interval in seconds between event batch uploads. Accepts a TimeInterval (Double) value.

The CSQ API endpoint to use:

• https://mh.ba.contentsquare.net — EU-hosted environments
• https://mh.bf.contentsquare.net — all other environments (default)

Whether source pageview events will be auto-captured. Defaults to false.

Whether autocapture of pageview titles is disabled. Defaults to false.

Disables autocapture of touch events on UIKit views. Defaults to false.

Whether to enable autocapture of native UIKit view interaction events. Defaults to false.

Whether the SDK will auto capture interaction events on notifications. Defaults to false.

Whether to capture the title of the notification where an interaction was performed. enablePushNotificationAutocapture must be set to true. Defaults to false.

Whether to capture the body text of the notification where an interaction was performed. enablePushNotificationAutocapture must be set to true. Defaults to false.

Whether Session Replay starts automatically at SDK launch. Defaults to true.

Set to false to disable automatic start and control Session Replay manually.