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

No parameters.

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

CSQ.optOut()

No parameters.

Product Analytics | Ajouté à la version : 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")

• identity   String (<= 100 chars)  

  Identity to be associated with the current user.

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

No parameters.

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
}

• metadata   Metadata  

  Metadata associated with the current user and project.

Gets or sets the current log level.

CSQ.debug.logLevel = .debug

• level   Enum (CSQ.Log.Level)  

  Possible values: none, trace, debug, info, warn, error, or important.

Product Analytics | Ajouté à la version : 1.0.0

Gets or sets the LogChannel to which send log messages.

CSQ.debug.logChannel = customLogChannel

• LogChannel   interface  

  The interface where log messages will be routed.

Product Analytics | Ajouté à la version : 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
  }
}

No parameters.

Experience Analytics | Ajouté à la version : 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)

• dVar   DynamicVar  

  The dynamic variable

  key   String (<= 512 chars)  

  Dynamic variable key

  intValue   UInt32  

  Dynamic variable integer value

  stringValue   String  

  Dynamic variable string value

Product Analytics | Ajouté à la version : 1.0.0

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

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

• properties   [String: PropertyValue]  

  A dictionary of user properties. PropertyValue can be String, Substring, Bool, Double, Float, Int, Int64, Int32, Int16 or Int8.

Product Analytics | Ajouté à la version : 1.0.0

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

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

• properties   [String: PropertyValue]  

  A dictionary of event properties. PropertyValue can be String, Substring, Bool, Double, Float, Int, Int64, Int32, Int16 or Int8.

Product Analytics | Ajouté à la version : 1.0.0

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

CSQ.removeEventProperty("propertyKey")

• key   String  

  The key of the property to remove.

Product Analytics | Ajouté à la version : 1.0.0

Removes all event-wide properties.

CSQ.clearEventProperties()

Experience Analytics | Ajouté à la version : 1.0.0

Exclude a scrollable view or subclass from Exposure Metric computations.

let scrollView = UIScrollView()
scrollView.excludeFromExposureMetrics()

Experience Analytics | Ajouté à la version : 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>))

• url   URL  

  See https://developer.apple.com/documentation/foundation/url ↗

Experience Analytics | Ajouté à la version : 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 | Ajouté à la version : 1.0.0

Register a webview for tracking.

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

• webView   WKWebView  

  The webview to register for tracking.

Unregister a webview for tracking.

CSQ.unregisterWebView(webView)

• webView   WKWebView  

  The webview to unregister from tracking.

Experience Analytics | Ajouté à la version : 1.0.0

Send a transaction.

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

• Transaction   Transaction  

  The transaction object to be sent. Initialized with id, total, and ISO 4217 currency enum.

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")])

• name   String  

  The name of the screen.

• cvars   CustomVar[] (optional)  

  An array of custom variables to attach to the screen view.

  index   UInt32  

  Custom variable index

  key   String (<= 512 chars)  

  Custom variable key

  value   String (<= 256 chars)  

  Custom variable value

Product Analytics | Ajouté à la version : 1.0.0

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

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

• name   String  

  The name of the event to be tracked.

• properties   [String: PropertyValue>] (optional)  

  Optional properties to associate with the event. PropertyValue can be String, Substring, Bool, Double, Float, Int, Int64, Int32, Int16 or Int8.

Experience Analytics Voice of Customer | Ajouté à la version : 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)

• triggerName   String  

  The name of the trigger associated with the survey. This should match the trigger name configured in the Contentsquare platform.

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

Experience Analytics | Ajouté à la version : 1.0.0

Sets URL masking patterns.

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

• patterns   [String]  

  A list of URL patterns to mask.

Experience Analytics | Ajouté à la version : 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
}

• onCrashReporterStart   (enabled: Bool -> Void)  

  Closure triggered when crash reporter is started. Passes a boolean indicating if crash reporter is actually enabled.

Experience Analytics | Ajouté à la version : 1.0.0

Associate the user identifier to the session.

CSQ.sendUserIdentifier("any_identifier")

• userIdentifier   String  

  The user identifier to track. Should be max 100 characters long.

Experience Analytics | Ajouté à la version : 1.0.0

Track network metrics.

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

• networkMetric   NetworkMetric  

  NetworkMetric object for a network request to collect HTTP network errors.

Ignore interactions for a specific view.

CSQ.ignoreInteractions(view)

• view   UIView  

  https://developer.apple.com/documentation/uikit/uiview ↗

UIKit IBInspectable | Ajouté à la version : 1.0.0

Ignore interactions for a specific view.

view.csqIgnoreInteractions = true

No parameters.

Product Analytics SwiftUI | Ajouté à la version : 1.2.0

Ignore interactions for a specific view.

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

• shouldIgnore   Bool  

  Whether to ignore interactions.

Experience Analytics | Ajouté à la version : 1.0.0

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

CSQ.setDefaultMasking(true)

• masked   Bool  

  The default masking state to be set.

Mask a view's content.

CSQ.mask(view)

• view   UIView  

  The view which content will be masked.

Unmask a view's content.

CSQ.unmask(view)

• view   UIView  

  The view which content will be unmasked.

UIKit IBInspectable | Ajouté à la version : 1.0.0

Mask the content of a view.

view.csqMaskContents = true

No parameters.

SwiftUI | Ajouté à la version : 1.0.0

Mask the content of a view.

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

• enable   Bool  

  Whether to mask the content of the view.

Experience Analytics | Ajouté à la version : 1.0.0

Mask content for views of a specific type.

CSQ.mask(viewsOfType: UIView.Type)

• viewsOfType   UIView.Type  

  The class type of the view whose content will be masked.

Unmask content for views of a specific type.

CSQ.unmask(viewsOfType: UIView.self)

• viewsOfType   UIView.Type  

  The class type of the view whose content will be unmasked.

Mask all texts.

CSQ.maskTexts(true)

• mask   Bool  

  Whether to mask text.

Experience Analytics | Ajouté à la version : 1.0.0

Mask images.

CSQ.maskImages(true)

• mask   Bool  

  Whether to mask images.

Experience Analytics | Ajouté à la version : 1.0.0

Mask text input fields.

CSQ.maskTextInputs(true)

• mask   Bool  

  Whether to mask text inputs.

Product Analytics UIKit IBInspectable | Ajouté à la version : 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 | Ajouté à la version : 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 Unified CSQ.

Experience Analytics only:

CSQ.start()

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

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

Unified CSQ with dataSourceID:

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

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

• environmentID   String (optional)  

  Your Product Analytics environment ID.

• dataSourceID   String (optional)  

  Your Unified CSQ data source ID. Enables both Product Analytics and Experience Analytics with a single identifier.

• options   [AnalyticsOption: Any] (optional)  

  SDK configuration options.

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

No parameters.

CSQ SDK options passed to CSQ.start().

CSQ.start(
  // optional: environmentID: String | dataSourceID: String
  options: [
    .uploadInterval: TimeInterval,
    .baseURL: URL,
    .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.

URI object specifying the base URI for the desired API endpoint. The Heap SDK resolves paths using this base URI and ignores any pre-existing path elements.

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.