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

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 Product 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("key1", "value1")
CSQ.addDynamicVar("key2", 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 can be number, string, boolean, or bigint.

Product Analytics | Added in: 6.0.0

Enables logging to the console for Product Analytics events and diagnostics.

CSQ.logToConsole();

Product Analytics | Added in: 6.0.0

Sets the log channel for Product Analytics logging.

import { LogChannel } from '@contentsquare/react-native-bridge';

CSQ.setLogChannel(LogChannel.LOG);

• logChannel   LogChannel  

  The log channel to use. Available values:

  • LogChannel.LOG
  • LogChannel.TRACE
  • LogChannel.DEBUG
  • LogChannel.INFO
  • LogChannel.WARN
  • LogChannel.ERROR
  • LogChannel.NONE

Product Analytics | Added in: 6.0.0

Sets the log level for Product Analytics logging.

import { LogLevel } from '@contentsquare/react-native-bridge';

CSQ.setLogLevel(LogLevel.INFO);

• logLevel   LogLevel  

  The log level to use. Available values:

  • LogLevel.TRACE
  • LogLevel.DEBUG
  • LogLevel.INFO
  • LogLevel.WARN
  • LogLevel.ERROR
  • LogLevel.NONE

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

Starts Session Replay. Use this when you have set sessionReplayAutoStart to false to manually control when Session Replay starts. Calling this method does not force Session Replay collection — it enables the module to begin evaluating sampling rules.

import { CSQ } from "@contentsquare/react-native-bridge";

CSQ.startSessionReplay();

Stops Session Replay collection. Any data collected before this call is preserved and uploaded according to the SDK upload schedule.

import { CSQ } from "@contentsquare/react-native-bridge";

CSQ.stopSessionReplay();

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 AnalyticsThis will ignore text and accessibility labels inside the masked view for event tracking.

• allowInnerHierarchy   boolean  

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

• allowProps   boolean  

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

• allowText   boolean  

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

• allowAccessibilityLabel   boolean  

  Product AnalyticsAllows 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 AnalyticsThis will ignore text and accessibility labels inside the masked view for event tracking.

allowInnerHierarchy   boolean  

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

allowProps   boolean  

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

allowText   boolean  

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

allowAccessibilityLabel   boolean  

Product AnalyticsAllows accessibilityLabel capture.

Deprecated | Product Analytics | Added in: 6.0.0

Product Analytics is now configured using the options parameter of start().

Start and configure the SDK. Use StartConfig to specify the product configuration.

import { CSQ, StartConfig } from '@contentsquare/react-native-bridge';

// Experience Analytics only (DXA)
CSQ.start(StartConfig.dxa());

// Product Analytics (Standalone)
CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID"));

// Product Analytics (Unified CSQ)
CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID"));

// Product Analytics with options
CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", {
  enableRNAutocapture: true
}));

• StartConfig.dxa()   CSQConfig  

  Start the SDK with Experience Analytics (DXA) only.

• StartConfig.withEnvironmentId(id, options?)   CSQConfig  

  Start the SDK with Product Analytics using an environment ID.

  • id (string) — Your Product Analytics environment ID.
  • options (AnalyticsOptions, optional) — Product Analytics initialization options.

• StartConfig.withDataSourceId(id, options?)   CSQConfig  

  Start the SDK with Product Analytics using a data source ID (Unified CSQ).

  • id (string) — Your Unified CSQ data source ID.
  • options (AnalyticsOptions, optional) — Product Analytics initialization 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();

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

type AnalyticsOptions = {
  enableRNAutocapture?: boolean;
  disableInteractionAutocapture?: boolean;
  disablePageviewAutocapture?: boolean;
  baseUrl?: string;
  uploadInterval?: number;
  disableInteractionTextCapture?: boolean;
  disableInteractionAccessibilityLabelCapture?: boolean;
  sessionReplayAutoStart?: boolean;
  // Native specific options
  enablePushNotificationAutocapture?: boolean;
  enablePushNotificationTitleAutocapture?: boolean;
  enablePushNotificationBodyAutocapture?: boolean;
  enableViewAutocapture?: boolean;
  // iOS specific options
  disablePageviewTitleAutocapture?: boolean;
};

Enable React Native view autocapture.
Defaults to false.

Disables autocapture of touch events on React Native Views.
Defaults to false.

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

URI specifying the base URL for the desired API endpoint.

The interval, in milliseconds, between event uploads.

Disables text capture for React Native interactions. Defaults to false.

Disables accessibility label capture for React Native interactions. Defaults to false.

Whether the SDK starts Session Replay automatically when the SDK starts. When set to false, you must call CSQ.startSessionReplay() to start Session Replay. Defaults to true.

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

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

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

Whether the SDK will auto capture UI interactions and source pageviews. Defaults to false.

Disable pageview title capture.