---
title: SDK API reference - iOS
description: SDK commands reference including signature, parameter descriptions, and examples
lastUpdated: 11 March 2026
source_url:
  html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/command-reference/
  md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/command-reference/index.md
---

> Documentation index: https://docs.contentsquare.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

## GDPR / Identification

### CSQ.optIn()

**Added in:** `1.0.0`

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

Call [`optIn`](#csqoptin) after [`start`](#csqstart).

```swift
CSQ.optIn()
```

#### Parameters

* No parameters.

### CSQ.optOut()

**Added in:** `1.0.0`

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

```swift
CSQ.optOut()
```

#### Parameters

* No parameters.

### CSQ.identify()

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.

Warning

Changing an identity forces a new user ID and session ID. That is, calling `identify("A"); identify("B")` creates a new user ID and session for `B`.

```swift
CSQ.identify("userIdentity")
```

#### Parameters

* #### identity   String (<= 100 chars)  

  Identity to be associated with the current user.

### CSQ.resetIdentity()

**Added in:** `1.0.0`

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

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

```swift
CSQ.resetIdentity()
```

#### Parameters

* No parameters.

### CSQ.metadata.\*\*\*\*\*

**Added in:** `1.0.0`

Get all the information related to the user and project.

#### CSQ.metadata.userID

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

```swift
let userID = CSQ.metadata.userID
```

#### CSQ.metadata.sessionID

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

```swift
let sessionID = CSQ.metadata.sessionID
```

#### CSQ.metadata.projectID

Project identifier for Experience Analytics.

```swift
let projectID = CSQ.metadata.projectID
```

#### CSQ.metadata.environmentID

Environment identifier for Product Analytics.

```swift
let environmentID = CSQ.metadata.environmentID
```

#### CSQ.metadata.sessionReplayURL

URL of current Session Replay.

```swift
let sessionReplayURL = CSQ.metadata.sessionReplayURL
```

#### CSQ.metadata.identity

Identity associated with the user by calling [`identify()`](#csqidentify).

```swift
let identity = CSQ.metadata.identity
```

### CSQ.metadata.onChange { metadata in }

**Added in:** `1.0.0`

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.

Note

This may not trigger on changes to Product Analytics data.

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

#### Parameters

* #### metadata   Metadata  

  Metadata associated with the current user and project.

## Logging

### CSQ.debug.logLevel

**Added in:** `1.0.0`

Gets or sets the current log level.

```swift
CSQ.debug.logLevel = .debug
```

#### Parameters

* #### level   Enum (CSQ.Log.Level)  

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

### CSQ.debug.logChannel

Product Analytics | **Added in:** `1.0.0`

Gets or sets the `LogChannel` to which send log messages.

```swift
CSQ.debug.logChannel = customLogChannel
```

#### Parameters

* #### LogChannel   interface  

  The interface where log messages will be routed.

### LogChannel.printLog()

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`.

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

#### Parameters

* No parameters.

## Property Tracking

### CSQ.addDynamicVar()

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.

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


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

#### Parameters

* #### dVar   DynamicVar  

  The dynamic variable

  * #### key   String (<= 512 chars)  

    Dynamic variable key

  * #### intValue   UInt32  

    Dynamic variable integer value

  * #### stringValue   String  

    Dynamic variable string value

### CSQ.addUserProperties()

Product Analytics | **Added in:** `1.0.0`

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

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

#### Parameters

* #### properties   \[String: PropertyValue]  

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

### CSQ.addEventProperties()

Product Analytics | **Added in:** `1.0.0`

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

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

#### Parameters

* #### properties   \[String: PropertyValue]  

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

### CSQ.removeEventProperty()

Product Analytics | **Added in:** `1.0.0`

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

```swift
CSQ.removeEventProperty("propertyKey")
```

#### Parameters

* #### key   String  

  The key of the property to remove.

### CSQ.clearEventProperties()

Product Analytics | **Added in:** `1.0.0`

Removes all event-wide properties.

```swift
CSQ.clearEventProperties()
```

## View Tracking

### UIScrollView\.excludeFromExposureMetrics()

Experience Analytics | **Added in:** `1.0.0`

Exclude a scrollable view or subclass from Exposure Metric computations.

```swift
let scrollView = UIScrollView()
scrollView.excludeFromExposureMetrics()
```

## CSInApp

### CSQ.handle()

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](../../experience-analytics/in-app-features/).

```swift
CSQ.handle(url: <CSInAppURL>))
```

#### Parameters

* #### url   URL  

  See [https://developer.apple.com/documentation/foundation/url ↗](https://developer.apple.com/documentation/foundation/url)

### CSQ.csInApp

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.

```swift
CSQ.csInApp = true
```

## Interoperability

### CSQ.registerWebView()

Experience Analytics | **Added in:** `1.0.0`

Register a webview for tracking.

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

#### Parameters

* #### webView   WKWebView  

  The webview to register for tracking.

### CSQ.unregisterWebView()

**Added in:** `1.0.0`

Unregister a webview for tracking.

```swift
CSQ.unregisterWebView(webView)
```

#### Parameters

* #### webView   WKWebView  

  The webview to unregister from tracking.

## Event Tracking

### CSQ.trackTransaction()

Experience Analytics | **Added in:** `1.0.0`

Send a transaction.

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

#### Parameters

* #### Transaction   Transaction  

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

### CSQ.trackScreenview()

**Added in:** `1.0.0`

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

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

#### Parameters

* #### 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

### CSQ.trackEvent()

Product Analytics | **Added in:** `1.0.0`

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

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

#### Parameters

* #### 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`.

## Surveys

### CSQ.triggerSurvey()

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.

```swift
CSQ.triggerSurvey(triggerName)
```

#### Parameters

* #### triggerName   String  

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

#### Example

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

## Error tracking

### CSQ.setUrlMaskingPatterns()

Experience Analytics | **Added in:** `1.0.0`

Sets URL masking patterns.

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

#### Parameters

* #### patterns   \[String]  

  A list of URL patterns to mask.

### CSQ.onCrashReporterStart()

Experience Analytics | **Added in:** `1.0.0`

Trigger a callback when the Contentsquare Crash Reporter is initialized.

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

#### Parameters

* #### onCrashReporterStart   (enabled: Bool -> Void)  

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

### CSQ.sendUserIdentifier()

Experience Analytics | **Added in:** `1.0.0`

Associate the user identifier to the session.

```swift
CSQ.sendUserIdentifier("any_identifier")
```

#### Parameters

* #### userIdentifier   String  

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

### CSQ.trackNetworkMetric()

Experience Analytics | **Added in:** `1.0.0`

Track network metrics.

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

#### Parameters

* #### networkMetric   NetworkMetric  

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

## Personal Data/Masking

### CSQ.ignoreInteractions()

**Added in:** `1.0.0`

Ignore interactions for a specific view.

```swift
CSQ.ignoreInteractions(view)
```

#### Parameters

* #### view   UIView  

  [https://developer.apple.com/documentation/uikit/uiview ↗](https://developer.apple.com/documentation/uikit/uiview)

### UIView\.csqIgnoreInteractions

UIKit IBInspectable | **Added in:** `1.0.0`

Ignore interactions for a specific view.

```swift
view.csqIgnoreInteractions = true
```

#### Parameters

* No parameters.

### View\.csqIgnoreInteractions()

Product Analytics SwiftUI | **Added in:** `1.2.0`

Ignore interactions for a specific view.

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

#### Parameters

* #### shouldIgnore   Bool  

  Whether to ignore interactions.

### CSQ.setDefaultMasking()

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.

```swift
CSQ.setDefaultMasking(true)
```

#### Parameters

* #### masked   Bool  

  The default masking state to be set.

### CSQ.mask(UIView)

**Added in:** `1.0.0`

Mask a view's content.

```swift
CSQ.mask(view)
```

#### Parameters

* #### view   UIView  

  The view which content will be masked.

### CSQ.unmask(UIView)

**Added in:** `1.0.0`

Unmask a view's content.

```swift
CSQ.unmask(view)
```

#### Parameters

* #### view   UIView  

  The view which content will be unmasked.

### UIView\.csqMaskContents

UIKit IBInspectable | **Added in:** `1.0.0`

Mask the content of a view.

```swift
view.csqMaskContents = true
```

#### Parameters

* No parameters.

### View\.csqMaskContents

SwiftUI | **Added in:** `1.0.0`

Mask the content of a view.

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

#### Parameters

* #### enable   Bool  

  Whether to mask the content of the view.

### CSQ.mask(`viewsOfType: UIView.Type`)

Experience Analytics | **Added in:** `1.0.0`

Mask content for views of a specific type.

```swift
CSQ.mask(viewsOfType: UIView.Type)
```

#### Parameters

* #### viewsOfType   UIView\.Type  

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

### CSQ.unmask(`viewsOfType: UIView.Type`)

**Added in:** `1.0.0`

Unmask content for views of a specific type.

```swift
CSQ.unmask(viewsOfType: UIView.self)
```

#### Parameters

* #### viewsOfType   UIView\.Type  

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

### CSQ.maskTexts()

**Added in:** `1.0.0`

Mask all texts.

```swift
CSQ.maskTexts(true)
```

#### Parameters

* #### mask   Bool  

  Whether to mask text.

### CSQ.maskImages()

Experience Analytics | **Added in:** `1.0.0`

Mask images.

```swift
CSQ.maskImages(true)
```

#### Parameters

* #### mask   Bool  

  Whether to mask images.

### CSQ.maskTextInputs()

Experience Analytics | **Added in:** `1.0.0`

Mask text input fields.

```swift
CSQ.maskTextInputs(true)
```

#### Parameters

* #### mask   Bool  

  Whether to mask text inputs.

### UIView\.csqIgnoreInnerHierarchy

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`.

```swift
let view = UIView()
view.csqIgnoreInnerHierarchy = true
```

## SDK Initialization and Management

### CSQ.configureProductAnalytics()

Deprecated Product Analytics | **Added in:** `1.0.0`

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

### CSQ.start()

**Added in:** `1.0.0`

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:**

```swift
CSQ.start()
```

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

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

**CSQ Experience Platform with `dataSourceID`:**

```swift
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 CSQ Experience Platform data source ID. Enables both Product Analytics and Experience Analytics with a single identifier.

* #### options   \[AnalyticsOption: Any] (optional)  

  SDK [configuration options](#sdk-configuration-options).

### CSQ.stop()

**Added in:** `1.0.0`

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

```swift
CSQ.stop()
```

### CSQ.pauseTracking()

**Added in:** `1.0.0`

Pause all tracking features.

```swift
CSQ.pauseTracking()
```

### CSQ.resumeTracking()

**Added in:** `1.0.0`

Resume all tracking features.

```swift
CSQ.resumeTracking()
```

#### Parameters

* No parameters.

### CSQ.startSessionReplay()

**Added in:** `1.10.0`

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`](#sessionreplayautostart) option.

```swift
CSQ.startSessionReplay()
```

### CSQ.stopSessionReplay()

**Added in:** `1.10.0`

Stop Session Replay immediately.

```swift
CSQ.stopSessionReplay()
```

## SDK configuration options

CSQ SDK options passed to [`CSQ.start()`](#csqstart).

```swift
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
  ]
)
```

### `uploadInterval`

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

### `baseURL`

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.

### `disablePageviewAutocapture`

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

### `disablePageviewTitleAutocapture`

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

### `disableInteractionAutocapture`

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

### `enableNativeAutocapture`

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

### `enablePushNotificationAutocapture`

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

### `enablePushNotificationTitleAutocapture`

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

### `enablePushNotificationBodyAutocapture`

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

### `sessionReplayAutoStart`

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

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