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 (CSQ Experience Platform)
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 CSQ Experience Platform.

• startConfig.id  String  

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

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

CSQ Experience Platform 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().