SDK API reference

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

Call optIn after start.

CSQ.optIn()

[CSQ optIn];

No parameters.

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

CSQ.optOut()

[CSQ optOut];

No parameters.

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.

CSQ.identify(identity)

[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 equivalent to calling optOut() then optIn().

CSQ.resetIdentity()

[CSQ resetIdentity];

No parameters.

Get all information relative to the user.

let userID = CSQ.metadata.userID

NSString *userID = [[CSQ metadata] userID];

let sessionID = CSQ.metadata.sessionID

NSString *sessionID = [[CSQ metadata] sessionID];

let projectID = CSQ.metadata.projectID

NSString *projectID = [[CSQ metadata] projectID];

let environmentID = CSQ.metadata.environmentID

NSString *environmentID = [[CSQ metadata] environmentID];

let sessionReplayURL = CSQ.metadata.sessionReplayURL

NSString *sessionReplayURL = [[CSQ metadata] sessionReplayURL];

let identity = CSQ.metadata.identity

NSString *identity = [[CSQ metadata] identity];

No parameters.

Trigger a callback whenever user information is updated.

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

[[CSQ metadata] onChange:^(Information *information) {
// Handle information change
}];

• information   Function  

  Identity to be associated with the current user.

Gets or sets the current log level.

CSQ.debug.logLevel = .debug

[[CSQ debug] setLogLevel:CSQLogLevelDebug];

• level   Enum (CSQ.Log.Level)  

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

Gets or sets the LogChannel to which send log messages.

CSQ.debug.setLogChannel(LogChannel)

[[CSQ debug] setLogChannel:customLogChannel];

• LogChannel   interface  

  The interface where log messages will be routed.

Routes SDK logs to another location such as Timber, Arbor, or similar logging libraries.
The default implementation routes all logs through Logcat.

LogChannel.printLog()

[LogChannel printLog];

No parameters.

Experience Analytics | Added in: 1.0.0

Adds one or multiple dynamic variables to the session properties.
This method allows you to pass an array of DynamicVar objects, each representing a key-value pair that is scoped to the session.

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

CSQ.addDynamicVar([var1, var2])

DynamicVar *var1 = [[DynamicVar alloc] initWithKey:@"key1" value:@"value1"];
DynamicVar *var2 = [[DynamicVar alloc] initWithKey:@"key2" value:@"value2"];

[CSQ addDynamicVar:@[var1, var2]];

• DynamicVar   NSObject  

  The dynamic variable

  key   String (<= 512 chars)  

  Dynamic variable key

  value   Uint32  

  Dynamic variable value

Product Analytics | Added in: 1.0.0

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

CSQ.addUserProperties([Property])

[CSQ addUserProperties:@{@"propertyKey": @"propertyValue"}];

• properties   [Property]  

  A map of user properties.

Product Analytics | Added in: 1.0.0

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

CSQ.addEventProperties([Property])

[CSQ addEventProperties:@{@"propertyKey": @"propertyValue"}];

• properties   [Property]  

  A map of event properties.

Product Analytics | Added in: 1.0.0

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

CSQ.removeEventProperty(property)

[CSQ removeEventProperty:@"propertyKey"];

• property   String  

  The key of the property to remove.

Product Analytics | Added in: 1.0.0

Removes all event-wide properties.

CSQ.clearEventProperties()

[CSQ clearEventProperties];

Experience Analytics | Added in: 1.0.0

Exclude a scrollable view or subclass from Exposure Metric computations.

UIScrollView.excludeFromExposureMetrics(UIScrollView)

[UIScrollView excludeFromExposureMetrics:scrollView];

• UIScrollView   Class  

  See https://developer.apple.com/documentation/uikit/uiscrollview ↗

Experience Analytics | Added in: 1.0.0

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

CSQ.handle(url: URL)

[CSQ handleWithURL:[NSURL URLWithString:@"https://example.com"]];

• url   Struct  

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

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

CSQ.csInApp = YES;

No parameters.

Register a webview for tracking.

CSQ.registerWebView(webView: WKWebView())

[CSQ registerWebView:[[WKWebView alloc] init]];

• webView   WKWebView  

  The webview to register for tracking.

Unregister a webview for tracking.

CSQ.unregisterWebView(webView: WKWebView())

[CSQ unregisterWebView:webView];

• webView   WKWebView  

  The webview to unregister from tracking.

Experience Analytics | Added in: 1.0.0

Send a transaction.

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

Transaction *transaction = [[Transaction alloc] initWithId:@"transactionId" total:100.0];
[CSQ trackTransaction:transaction];

• Transaction   Transaction  

  The transaction object to be sent.

Send a screen view with or without custom variables.

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

[CSQ trackScreenview:@"ScreenName" cvars:@[[CustomVar customVarWithKey:@"key" value:@"value"]]];

• name   String  

  The name of the screen.

• cvars   CustomVar[] (optional)  

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

  key   String (<= 512 chars)  

  Custom variable key

  value   Uint32  

  Custom variable 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: [String, PropertyValue]?)

[CSQ trackEventWithName:@"EventName" properties:@{@"propertyKey": @"propertyValue"}];

• name   String  

  The name of the event to be tracked.

• properties   Map<String, PropertyValue> (optional)  

  Optional properties to associate with the event.

  key   String (<= 512 chars)  

  Property name

  value   Uint32  

  Property value

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)

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

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

[CSQ setUrlMaskingPatterns:@[@"pattern1", @"pattern2"]];

• patterns   Array<String>  

  A list of URL patterns to mask.

Experience Analytics | Added in: 1.0.0

Trigger a callback when the Contentsquare Crash Reporter is initialized.

CSQ.onCrashReporterStart()

[CSQ onCrashReporterStart];

No parameters.

Experience Analytics | Added in: 1.0.0

Track network metrics.

CSQ.trackNetworkMetric(NetworkMetric)

NetworkMetric *networkMetric = [[NetworkMetric alloc] initWithURL:@"https://example.com" duration:1.5];
[CSQ trackNetworkMetric:networkMetric];

• networkMetric   object  

  The network metric to be tracked.

Ignore interactions for a specific view.

CSQ.ignoreInteractions(UIView)

[CSQ ignoreInteractions:view];

• UIView   TODO:?  

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

UIKit | Added in: 1.0.0

Ignore interactions for a specific view.

UIView.csqIgnoreInteractions

view.csqIgnoreInteractions = YES;

No parameters.

Experience Analytics SwiftUI | Added in: 1.0.0

Ignore interactions for a specific view.

View.csqIgnoreInteractions(shouldIgnore: Bool)

[View csqIgnoreInteractions:YES];

• shouldIgnore   Bool  

  Whether to ignore interactions.

Experience Analytics | Added in: 1.0.0

Set the default masking state.
All Android View elements, their subclasses and Jetpack Compose components are fully masked by default.

CSQ.setDefaultMasking(Bool masked)

[CSQ setDefaultMasking:YES];

• masked   Bool  

  The masking state to be set.

Mask a view’s content.

CSQ.mask(UIView)

[CSQ mask:view];

• UIView   UIView  

  The view which content will be masked.

UIKit | Added in: 1.0.0

Mask the content of a view.

UIView.csqMaskContents

view.csqMaskContents = YES;

No parameters.

SwiftUI | Added in: 1.0.0

Mask the content of a view.

View.csqMaskContents(enable: Bool)

[View csqMaskContents:YES];

• enable   Bool  

  Whether to mask the content of the view.

Experience Analytics | Added in: 1.0.0

Mask content for views of a specific type.

CSQ.mask(viewsOfType: UIView.Type)

[CSQ maskViewsOfType:[UIView class]];

• 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.Type)

[CSQ unmaskViewsOfType:[UIView class]];

• viewsOfType   UIView.Type  

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

Mask text.

CSQ.maskTexts(mask: Bool)

[CSQ maskTexts:YES];

• mask   Bool  

  Whether to mask text.

Experience Analytics | Added in: 1.0.0

Mask images.

CSQ.maskImages(mask: Bool)

[CSQ maskImages:YES];

• mask   Bool  

  Whether to mask images.

Experience Analytics | Added in: 1.0.0

Mask text input fields.

CSQ.maskTextInputs(mask: Bool)

[CSQ maskTextInputs:YES];

• mask   Bool  

  Whether to mask text inputs.

UIView.csqIgnoreInteractionsDefault = true

[UIView setCsqIgnoreInteractionsDefault:YES];

Product Analytics UIView | 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

UIView *view = [[UIView alloc] init];
view.csqIgnoreInnerHierarchy = YES;

Product Analytics UIView | Added in: 1.0.0

This has the same effect as csqIgnoreInnerHierarchy but is applied at the class level through an overridable class property. If defined, csqIgnoreInnerHierarchy can still be used to override an individual instance.

let view = UIView()
view.csqIgnoreInnerHierarchyDefault = true

UIView *view = [[UIView alloc] init];
view.csqIgnoreInnerHierarchyDefault = YES;

Product Analytics | Added in: 1.0.0

SDK configuration method for Product Analytics. Must be called before start().

CSQ.configureProductAnalytics(
  environmentID: String,
  additionalOptions:
    [ PRODUCT_ANALYTICS_INITIALIZATION_OPTIONS ]
  )

[CSQ configureProductAnalyticsWithEnvironmentID:@"YOUR_ENVIRONMENT_ID"
                                additionalOptions:@{PRODUCT_ANALYTICS_INITIALIZATION_OPTIONS}
];

• environmentID   String  

  Your Product Analytics environment ID.

• PRODUCT_ANALYTICS_INITIALIZATION_OPTIONS   [Option : Any]  

  Product Analytics initialization options.

Manually start the SDK.

CSQ.start();

[CSQ start];

No parameters.

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

CSQ.stop();

[CSQ stop];

Pause all tracking features.

CSQ.pauseTracking();

[CSQ pauseTracking];

Resume all tracking features.

CSQ.resumeTracking();

[CSQ resumeTracking];

No parameters.

Return the state of the SDK:

• running
• stopped
• paused

CSQ SDK options for Product Analytics passed to CSQ.configureProductAnalytics().

CSQ.configureProductAnalytics(
  environmentID: String,
  additionalOptions: [
    .uploadInterval: TimeInterval,
    .baseUrl: URL,
    .captureVendorId: Bool,
    .captureAdvertiserId: Bool,
    .clearEventPropertiesOnNewUser: Bool,
    .disablePageviewAutocapture: Bool,
    .disablePageviewTitleCapture: Bool,
    .disableInteractionAutocapture: Bool,
    .enableUIKitAutocapture: Bool,
    .enablePushNotificationAutocapture: Bool,
    .enablePushNotificationTitleAutocapture: Bool,
    .enablePushNotificationBodyAutocapture: Bool,
    .messageBatchByteLimit: Int,
    .messageBatchMessageLimit: Int,
    .resumePreviousSession: Bool,
    .pruningLookBackWindow: Bool,
    .disableScreenviewForwardToDXA: Bool,
    .disableScreenviewForwardToPA: Bool
  ]
)

[CSQ configureProductAnalyticsWithEnvironmentID: NSString
  additionalOptions:@{
    CSQProductAnalyticsOptionUploadInterval: NSTimeInterval,
    CSQProductAnalyticsOptionBaseUrl: NSURL,
    CSQProductAnalyticsOptionCaptureVendorId: BOOL,
    CSQProductAnalyticsOptionCaptureAdvertiserId: BOOL,
    CSQProductAnalyticsOptionClearEventPropertiesOnNewUser: BOOL,
    CSQProductAnalyticsOptionDisablePageviewAutocapture: BOOL,
    CSQProductAnalyticsOptionDisablePageviewTitleCapture: BOOL,
    CSQProductAnalyticsOptionDisableInteractionAutocapture: BOOL,
    CSQProductAnalyticsOptionEnableUIKitAutocapture: BOOL,
    CSQProductAnalyticsOptionEnablePushNotificationAutocapture: BOOL,
    CSQProductAnalyticsOptionEnablePushNotificationTitleAutocapture: BOOL,
    CSQProductAnalyticsOptionEnablePushNotificationBodyAutocapture: BOOL,
    CSQProductAnalyticsOptionMessageBatchByteLimit: NSInteger,
    CSQProductAnalyticsOptionMessageBatchMessageLimit: NSInteger,
    CSQProductAnalyticsOptionResumePreviousSession: BOOL,
    CSQProductAnalyticsOptionPruningLookBackWindow: NSInteger,
    CSQProductAnalyticsOptionDisableScreenviewForwardToDXA: BOOL,
    CSQProductAnalyticsOptionDisableScreenviewForwardToPA: BOOL
  }];

Product Analytics Environment ID.

Interval at which event batches should be uploaded to the API.
Defaults to 15 seconds.

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 or not the vendor ID should be included in tracked events if made available by the device.
Defaults to false.

Whether or not the advertiser ID should be included in tracked events if made available by the device.
Defaults to false.

Whether or not to clear event properties when a new user is created.
Defaults to false.

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

Disable pageview title capture.

Disables autocapture of touch events on UIKit, Android Views, and React Native.

Enable Product Analytics iOS View events.

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

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

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

The maximum size, in bytes, to allocate for the local event storage database.
Defaults to -1, meaning there is no limit on database size. Must be greater than or equal to 200KB.

The maximum number of messages to be included in each batch sent to Heap. Setting a lower limit can help reduce network traffic in situations where bandwidth is limited.
Defaults to 100.

Enables Contentsquare behavior of persisting non-expired sessions across app launch.

The number of days to look back when pruning old data in days.
Defaults to 6 days.
Requires an entitlement to use.

Disable forwarding of Product Analytics Pageviews to Experience Analytics.

Disable forwarding of Experience Analytics Screenviews to Product Analytics.