SDK API reference

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: 6.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. Please 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("user_identity");

• identity   string (<= 100 chars)  

  Identity to be associated with the current user.

Product Analytics | Added in: 6.0.0

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

Experience Analytics | Added in: 6.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.

Get all the information related to the user and project. Refer to the CSQMetadata object.

CSQ.onMetadataChange(callback: (metadata: CSQMetadata) => void) => {
  // Handle metadata change
});

• callback   (metadata: CSQMetadata) => void  

  Callback function triggered when metadata changes.

CSQMetadata object contains information related to the user and project.

interface CSQMetadata {
    userID: string | null;
    sessionID: string | null;
    identity: string | null;
    environmentID: string | null;
    projectID: string | null;
    sessionReplayURL: string | null;
}

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

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

Project identifier for Experience Analytics.

Environment identifier for Experience Analytics.

URL of current session replay.

Identity associated with the user by calling identify().

Experience Analytics | Added in: 6.0.0

Adds dynamic variables to the session properties.
This method allows you to pass a key and a value parameters, representing a key-value pair that is scoped to the session. You can also add, as a last parameter, a function that we will call so you can handle it gracefully

CSQ.addDynamicVar(key: "key1", value: "value1")
CSQ.addDynamicVar(key: "key2", value: 2, (errorObject) => {
  console.log(errorObject.toString());
});

• key   string  

  Dynamic variable key

• value   string  

  Dynamic variable value

• callback   (error: Error) => void (optional)  

  Optional callback function to handle errors.

Product Analytics | Added in: 6.0.0

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

CSQ.addUserProperties({
  propertyKey: "propertyValue",
});

• properties   Record<string, PropertyValue  

  A dictionary of user properties. PropertyValue can be number, string, boolean, bigint

Product Analytics | Added in: 6.0.0

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

CSQ.addEventProperties({
  propertyKey: "propertyValue",
});

• properties   Record<string, PropertyValue>  

  A dictionary of event properties. PropertyValue can be number, string, boolean, bigint

Product Analytics | Added in: 6.0.0

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

CSQ.removeEventProperty("propertyKey")

• name   string  

  The key of the property to remove.

Product Analytics | Added in: 6.0.0

Removes all event-wide properties.

CSQ.clearEventProperties()

Experience Analytics | Added in: 6.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.handleUrl("sample_url")

• urlString   string | null | undefined  

  The url handled by React Native Linking API ↗.

Experience Analytics | Added in: 6.0.0

Allows Contentsquare SDK to track webviews.

<CSQWebView>
  <WebView
    source={{
      uri: "https://test-url.com",
    }}
  />
</CSQWebView>

• children   ReactElement  

  The webview to register for tracking. CSQWebView supports react-native-webview ↗.

Experience Analytics | Added in: 6.0.0

Send a transaction.

CSQ.trackTransaction(10, Currency.EUR, "transactionId");

• value   number  

  The monetary value of the transaction.

• currency   Currency | string  

  The ISO 4217 currency code of the transaction.

• transactionId   string | null (optional)  

  An optional identifier for the transaction.

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

CSQ.trackScreenview(name: "ScreenName", cvars: [{index: 0, key: "key", value: "value"}])

• name   String  

  The name of the screen.

• cvars   CustomVar[] (optional)  

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

  index   number  

  Custom variable index

  key   string (<= 512 chars)  

  Custom variable key

  value   string (<= 256 chars)  

  Custom variable value

Product Analytics | Added in: 6.0.0

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

CSQ.trackEvent('event', { some_property: 100 });

• eventName   string  

  The name of the event to be tracked.

• properties   Record<string, PropertyValue> (optional)  

  Optional properties to associate with the event. PropertyValue in Swift can be String, Substring, Bool, Double, Float, Int, Int64, Int32, Int16 or Int8 or in Objective-C NSString and NSNumber (including BOOL).

Experience Analytics | Added in: 6.0.0

Sets URL masking patterns.

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

• patterns   string[]  

  A list of URL patterns to mask.

Experience Analytics | Added in: 6.0.0

Trigger a native crash for testing purposes.

CSQ.triggerNativeCrash()

Experience Analytics | Added in: 6.0.0

Set the default masking state.
All Views are fully masked by default.

CSQ.setDefaultMasking(true)

• masked   Bool  

  The default masking state to be set.

Allows to mask content for session replay and suppress events for view inside <CSQMask> and all its children.__ By default, session replay masking is enabled, and event tracking is disabled.

<CSQMask>
  <View>
    ...
  </View>
</CSQMask>

• isSessionReplayMasked   boolean  

  The view which content will be masked.

• ignoreTextOnly   boolean  

  Product Analytics This will ignore text and accessibility labels inside the masked view for event tracking.

• allowInnerHierarchy   boolean  

  Product Analytics Allows the full hierarchy to be exposed, but without properties or text capture.

• allowProps   boolean  

  Product Analytics Allows property capture, but will exclude text-containing properties if the below options are omitted.

• allowText   boolean  

  Product Analytics Allows text capture. It can be used alongside allowProps to expose text-containing properties.

• allowAccessibilityLabel   boolean  

  Product Analytics Allows accessibilityLabel capture.

• children   ReactElement  

  The view which masking rules will be applied to.

Higher Order Component (HOC) to mask content for session replay and suppress events for view inside WithCSQMask and all its children.

• WrappedComponent   ReactElement  

  The component which masking rules will be applied to.

• maskOptions   CSQMaskProps  

  Masking options to be applied to the wrapped component.

isSessionReplayMasked   boolean  

The view which content will be masked.

ignoreTextOnly   boolean  

Product Analytics This will ignore text and accessibility labels inside the masked view for event tracking.

allowInnerHierarchy   boolean  

Product Analytics Allows the full hierarchy to be exposed, but without properties or text capture.

allowProps   boolean  

Product Analytics Allows property capture, but will exclude text-containing properties if the below options are omitted.

allowText   boolean  

Product Analytics Allows text capture. It can be used alongside allowProps to expose text-containing properties.

allowAccessibilityLabel   boolean  

Product Analytics Allows accessibilityLabel capture.

Product Analytics | Added in: 6.0.0

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

CSQ.configureProductAnalytics("YOUR_ENVIRONMENT_ID", {
  enableAutocapture: true
});

• envId   string  

  Your Product Analytics environment ID.

• productAnalyticsOptions   ProductAnalyticsOptions (optional)  

  Product Analytics initialization options.

Start the SDK.

CSQ.start();

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

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

type ProductAnalyticsOptions = {
  enableRNAutocapture?: boolean;
  disableInteractionAutocapture?: boolean;
  disablePageviewAutocapture?: boolean;
  disableScreenviewForwardToDXA?: boolean;
  disableScreenviewForwardToPA?: boolean;
  clearEventPropertiesOnNewUser?: boolean;
  resumePreviousSession?: boolean;
  baseUrl?: string;
  uploadInterval?: number;
  captureVendorId?: boolean;
  captureAdvertiserId?: boolean;
  // Native specific options
  enablePushNotificationAutocapture?: boolean;
  enablePushNotificationTitleAutocapture?: boolean;
  enablePushNotificationBodyAutocapture?: boolean;
  messageBatchMessageLimit?: number;
  pruningLookBackWindow?: number;
  enableViewAutocapture?: boolean;
  // Android specific options
  maximumDatabaseSize?: number;
  maximumBatchCountPerUpload?: number;
  // iOS specific options
  disablePageviewTitleAutocapture?: boolean;
  messageBatchByteLimit?: number;
};

Enable React Native view autocapture.
Defaults to false.

Disables autocapture of touch events on React Native Views, when enableRNAutocapture is true.

Disables pageview autocapture, when enableRNAutocapture is true.

Disable forwarding of Product Analytics Pageviews to Experience Analytics.
Defaults to false.

Disable forwarding of Experience Analytics Screenviews to Product Analytics.

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

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

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.

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

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

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

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.

Whether or not the SDK will auto captureUI interactions and source pageviews. 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 batches to send per upload cycle. This can be used in conjunction with messageBatchMessageLimit to control the amount of data that is uploaded in a given cycle.

Disable pageview title capture.