SDK API reference

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

Call optIn after start.

await CSQ().optIn();

No parameters.

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

await CSQ().optOut();

No parameters.

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.

await CSQ().identify(userIdentifier: 'userIdentity');

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

await CSQ().resetIdentity();

No parameters.

Get all the information related to the user and project.

Identifier of the current user.

final userId = CSQ().metadata.userId;

Session identifier.

final sessionId = CSQ().metadata.sessionId;

Project identifier for Experience Analytics.

final projectId = CSQ().metadata.projectId;

Environment identifier for Experience Analytics.

final environmentId = CSQ().metadata.environmentId;

URL of current Session Replay.

final sessionReplayUrl = CSQ().metadata.sessionReplayUrl;

Identity associated with the user by calling identify().

final identity = CSQ().metadata.identity;

Listen for changes to user metadata. For example when sessionReplayUrl becomes available or userId updates.

final subscription = CSQ().metadata.onChange((metadata) {
  // Handle information change
});

// Cancel when no longer needed
subscription.cancel();

• handler   void Function(Metadata metadata)  

  Callback triggered whenever metadata changes. Called immediately with current metadata if available.

Sets the current log level.

await CSQ().debug.setLogLevel(LogLevel.debug);

• logLevel   Enum (LogLevel)  

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

Experience Analytics | Added in: 1.0.0

Adds dynamic variables to the session properties. This method allows you to pass DynamicVar objects, representing key-value pairs that are scoped to the session.

final var1 = DynamicVar.fromString(key: 'key1', value: 'value1');
final var2 = DynamicVar.fromInt(key: 'key2', value: 2);

await CSQ().addDynamicVar(var1);
await CSQ().addDynamicVar(var2);

• dynamicVar   DynamicVar  

  The dynamic variable

  key   String (<= 50 chars)  

  Dynamic variable key

  value   int or String  

  Dynamic variable value. Use DynamicVar.fromInt for integer values (0 to 2³² - 1) or DynamicVar.fromString for string values (<= 255 chars).

Product Analytics | Added in: 1.0.0

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

await CSQ().addUserProperties(properties: {'propertyKey': 'propertyValue'});

• properties   Map<String, dynamic>  

  A map of user properties. Supported value types: String, num, bool. All other types will be ignored.

Product Analytics | Added in: 1.0.0

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

await CSQ().addEventProperties(properties: {'propertyKey': 'propertyValue'});

• properties   Map<String, dynamic>  

  A map of event properties. Supported value types: String, num, bool. All other types will be ignored.

Product Analytics | Added in: 1.0.0

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

await CSQ().removeEventProperty(name: 'propertyKey');

• name   String  

  The key of the property to remove.

Product Analytics | Added in: 1.0.0

Removes all event-wide properties.

await CSQ().clearEventProperties();

Experience Analytics | Added in: 1.0.0

Widget that enables CSQ tracking inside a WebView. Wrap your WebView widget with CSQWebViewWrapper and pass a delegate that supplies the WebView.

To enable WebView support, you must also implement the CSQ WebView JavaScript Tracking Tag in the web pages loaded by the WebView.

Two delegate types are available depending on your WebView package:

• UserScriptWebViewWrapperDelegate — for packages like flutter_inappwebview that support user scripts
• JSChannelWebViewWrapperDelegate — for packages like webview_flutter that use JavaScript channels

// Using UserScriptWebViewWrapperDelegate (for example flutter_inappwebview)
CSQWebViewWrapper(
  delegate: UserScriptWebViewWrapperDelegate(
    builder: (context, userScript) {
      return InAppWebView(
        initialUserScripts: UnmodifiableListView([
          UserScript(
            source: userScript,
            injectionTime: UserScriptInjectionTime.AT_DOCUMENT_START,
          ),
        ]),
      );
    },
  ),
)

// Using JSChannelWebViewWrapperDelegate (for example webview_flutter)
CSQWebViewWrapper(
  delegate: JSChannelWebViewWrapperDelegate(
    addJavaScriptChannel: (handler) {
      webViewController.addJavaScriptChannel(
        handler.channelName,
        onMessageReceived: (jsMessage) {
          handler.onMessageReceived(jsMessage.message);
        },
      );
    },
    builder: (context) => WebViewWidget(controller: webViewController),
  ),
)

• delegate   WebViewWrapperDelegate  

  The delegate that supplies the WebView widget to be wrapped.

Experience Analytics | Added in: 1.0.0

Send a transaction.

final transaction = Transaction(
  price: 100.0,
  currency: Currency.USD,
  id: 'transactionId',
);
await CSQ().trackTransaction(transaction);

• transaction   Transaction  

  The transaction object to be sent.

  price   double  

  The total transaction amount.

  currency   Currency  

  ISO 4217 currency enum value. For example:

  • Currency.USD,
  • Currency.EUR,
  • Currency.GBP.

  id   String (optional)  

  Optional transaction identifier.

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

await CSQ().trackScreenview(
  screenName: 'ScreenName',
  customVars: [CustomVar(index: 1, name: 'name', value: 'value')],
);

• screenName   String  

  The name of the screen.

• customVars   List<CustomVar> (optional)  

  A list of custom variables to attach to the screen view.

  index   int  

  Custom variable index

  name   String (<= 512 chars)  

  Custom variable name

  value   String (<= 256 chars)  

  Custom variable value

Product Analytics | Added in: 1.0.0

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

await CSQ().trackEvent(
  eventName: 'EventName',
  properties: {'propertyKey': 'propertyValue'},
);

• eventName   String  

  The name of the event to be tracked.

• properties   Map<String, dynamic> (optional)  

  Optional properties to associate with the event. Supported value types: String, num, bool. All other types will be ignored.

Experience Analytics | Added in: 1.0.0

Sets URL masking patterns.

await CSQ().setURLMaskingPatterns(patterns: ['pattern1', 'pattern2']);

• patterns   List<String>  

  A list of URL patterns to mask.

Experience Analytics | Added in: 1.0.0

Sends a report of an error caught by the Flutter framework.

Typically used by assigning it to FlutterError.onError:

FlutterError.onError = (details) {
  CSQ().collectFlutterError(details: details);
};

• details   FlutterErrorDetails  

  The Flutter error information.

• presentErrorDetails   bool (optional)  

  Whether to print the error details in the console. Defaults to true.

Experience Analytics | Added in: 1.0.0

Sends a report of a caught error.

Typically used inside a runZonedGuarded error handler:

runZonedGuarded(() {
  // your app code
}, (error, stackTrace) {
  CSQ().collectError(error: error, stackTrace: stackTrace);
});

• error   Object  

  The error object that was caught.

• stackTrace   StackTrace  

  The associated stack trace.

Experience Analytics | Added in: 1.0.0

Associate a user identifier with the session. This identifier is immediately hashed so no Personal Data can ever be accessed.

await CSQ().sendUserIdentifier(userIdentifier: 'any_identifier');

• userIdentifier   String  

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

Applies masking rules to its descendants. Use this widget to mask sensitive content such as personal information, passwords, or any data you don't want collected.

CSQMask(
  config: const CSQMaskingConfig(
    maskTexts: true,
    maskImages: true,
    maskTextFields: true,
    maskInteractions: true,
  ),
  child: const Text('Sensitive content'),
)

• config   CSQMaskingConfig  

  The masking configuration.

  maskTexts   bool (optional)  

  Mask widgets that render text (for example Text, RichText).

  maskTextFields   bool (optional)  

  Mask text input widgets (for example TextField, TextFormField).

  maskImages   bool (optional)  

  Mask image widgets (for example Image).

  maskSvgImages   bool (optional)  

  Mask SVG images.

  maskCharts   bool (optional)  

  Mask fl_chart widgets.

  maskCustomPaints   bool (optional)  

  Mask CustomPaint widgets.

  maskInteractions   bool (optional)  

  Prevent user interactions from being captured.

• child   Widget  

  The widget whose descendants will be masked.

Start the SDK. Should be called as early as possible in the app's lifecycle.

// DXA only (default):
await CSQ().start();

// Product Analytics with environment ID:
await CSQ().start(
  startConfig: StartConfig.withEnvironmentId(
    id: 'YOUR_ENVIRONMENT_ID',
    options: ProductAnalyticsOptions(
      enableInteractionsAutocapture: true,
    ),
  ),
);

// Product Analytics with data source ID:
await CSQ().start(
  startConfig: StartConfig.withDatasourceId(
    id: 'YOUR_DATASOURCE_ID',
  ),
);

• startConfig   StartConfig (optional)  

  The SDK start configuration. Defaults to StartConfig.dxa().

  StartConfig.dxa()    

  Experience Analytics only (default).

  StartConfig.withEnvironmentId(id, options)    

  Product Analytics with environment ID.

  StartConfig.withDatasourceId(id, options)    

  Product Analytics with data source ID.

• maskingConfig   CSQMaskingConfig (optional)  

  Global Session Replay masking configuration. See CSQMask.

Product Analytics | Added in: 1.0.0

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

await CSQ().configureProductAnalytics(
  environmentId: 'YOUR_ENVIRONMENT_ID',
  options: PRODUCT_ANALYTICS_INITIALIZATION_OPTIONS,
);

• environmentId   String  

  Your Product Analytics environment ID.

• options   ProductAnalyticsOptions (optional)  

  Product Analytics initialization options.

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

await CSQ().stop();

Pause all tracking features.

await CSQ().pauseTracking();

Resume all tracking features.

await CSQ().resumeTracking();

No parameters.

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

await CSQ().configureProductAnalytics(
  environmentId: 'YOUR_ENVIRONMENT_ID',
  options: ProductAnalyticsOptions(
    uploadInterval: Duration(seconds: 15),
    baseUrl: Uri.parse('https://example.com/'),
    captureVendorId: false,
    captureAdvertiserId: false,
    clearEventPropertiesOnNewUser: false,
    disablePageviewAutocapture: false,
    disablePageviewTitleAutocapture: false, // iOS only
    disableInteractionAutocapture: false,
    enablePushNotificationAutocapture: false,
    enablePushNotificationTitleAutocapture: false,
    enablePushNotificationBodyAutocapture: false,
    messageBatchByteLimit: null, // iOS only
    messageBatchMessageLimit: 100,
    resumePreviousSession: false,
    pruningLookBackWindow: 6, // Android only
    maximumDatabaseSize: -1, // Android only
    maximumBatchCountPerUpload: 5, // Android only
    enableInteractionsAutocapture: false,
    disableScreenviewForwardToDXA: false,
    disableScreenviewForwardToPA: false,
  ),
);

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 SDK resolves paths using this base URI and ignores any pre-existing path elements.

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

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

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

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

Disable pageview title capture.

Disables autocapture of touch interactions.

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.

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 Contentsquare Product Analytics. 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.

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 uploaded in a given cycle. Defaults to 5.

Whether to enable automatic capture of Flutter UI interactions. Defaults to false.

Disable forwarding of Product Analytics Pageviews to Experience Analytics.

Disable forwarding of Experience Analytics Screenviews to Product Analytics.