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.

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. This is an identifier from Experience Analytics by default or Product Analytics if Experience Analytics is not active.

final sessionId = CSQ().metadata.sessionId;

Project identifier for Experience Analytics.

final projectId = CSQ().metadata.projectId;

Environment identifier for Product 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.

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

// Start PA or PA + DXA with environment ID (Standalone)
await CSQ().start(
  startConfig: StartConfig.withEnvironmentId(
    id: 'YOUR_ENVIRONMENT_ID',
    options: AnalyticsOptions(),
  ),
);

// Start PA or PA + DXA with data source ID (Unified CSQ)
await CSQ().start(
  startConfig: StartConfig.withDatasourceId(
    id: 'YOUR_DATASOURCE_ID',
    options: AnalyticsOptions(),
  ),
);

• startConfig   StartConfig (optional)  

  Analytics configuration. Defaults to StartConfig.dxa(). Use StartConfig.withEnvironmentId() to start Product Analytics (Standalone) or StartConfig.withDatasourceId() for Unified CSQ.

• startConfig.id   String  

  Your Product Analytics environment ID (Standalone) or data source ID (Unified CSQ).

• startConfig.options   AnalyticsOptions  

  Product Analytics initialization options.

• maskingConfig   CSQMaskingConfig (optional)  

  Masking configuration for the SDK. See privacy and sensitive data.

Configure Product Analytics before calling CSQ().start().

await CSQ().configureProductAnalytics(
  environmentId: 'YOUR_ENVIRONMENT_ID',
  options: const ProductAnalyticsOptions(
    enableInteractionsAutocapture: true,
  ),
);
await CSQ().start();

• environmentId   String  

  Your Product Analytics environment ID.

• options   ProductAnalyticsOptions (optional)  

  Legacy Product Analytics options. Prefer AnalyticsOptions through startConfig when migrating to CSQ().start(...).

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.

Experience Analytics | Added in: 4.2.0

Starts Session Replay on-demand.

Use this API when Session Replay automatic start is disabled with AnalyticsOptions.sessionReplayAutoStart: false.

await CSQ().startSessionReplay();

No parameters.

Experience Analytics | Added in: 4.2.0

Stops Session Replay on-demand.

await CSQ().stopSessionReplay();

No parameters.

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

await CSQ().start(
  startConfig: StartConfig.withEnvironmentId(
    id: 'YOUR_ENVIRONMENT_ID',
    options: AnalyticsOptions(
      baseUrl: Uri.parse('https://example.com/'),
      enableInteractionsAutocapture: false,
      disablePageviewAutocapture: false,
      disablePageviewTitleAutocapture: false,
      disableInteractionAutocapture: false,
      enablePushNotificationAutocapture: false,
      enablePushNotificationTitleAutocapture: false,
      enablePushNotificationBodyAutocapture: false,
      sessionReplayAutoStart: true,
    ),
  ),
);

Product Analytics environment ID. Passed as a parameter to the StartConfig.withEnvironmentId factory.

Unified CSQ data source ID. Enables both Product Analytics and Experience Analytics with a single identifier. Passed as a parameter to the StartConfig.withDatasourceId factory.

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

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

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

Set to false to disable automatic start and control Session Replay manually with CSQ().startSessionReplay() and CSQ().stopSessionReplay().