---
title: SDK API reference - Flutter
description: SDK commands reference including signature, parameter descriptions, and examples
lastUpdated: 11 March 2026
source_url:
  html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/command-reference/
  md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/command-reference/index.md
---

> Documentation index: https://docs.contentsquare.com/llms.txt
> Use this file to discover all available pages before exploring further.

The SDK API provides the following methods with their signatures, parameters, and usage examples.

## GDPR / Identification

### CSQ().optIn()

**Added in:** `1.0.0`

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

Call [`optIn`](#csqoptin) after [`start`](#csqstart).

```dart
await CSQ().optIn();
```

#### Parameters

* No parameters.

### CSQ().optOut()

**Added in:** `1.0.0`

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

```dart
await CSQ().optOut();
```

#### Parameters

* No parameters.

### CSQ().identify()

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.

Warning

Changing an identity forces a new user ID and session ID. That is, calling `identify("A"); identify("B")` creates a new user ID and session for `B`.

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

#### Parameters

* #### userIdentifier  String (<= 100 chars)  

  Identity to be associated with the current user.

### CSQ().resetIdentity()

**Added in:** `1.0.0`

If the user was previously identified with [`identify()`](#csqidentify), this creates a new unidentified user and session. This is technically similar to calling [`optOut()`](#csqoptout) then [`optIn()`](#csqoptin).

This should be called only after Product Analytics is configured and the SDK started.

```dart
await CSQ().resetIdentity();
```

#### Parameters

* No parameters.

### CSQ().metadata

**Added in:** `1.0.0`

Get all the information related to the user and project.

#### CSQ().metadata.userId

Identifier of the current user.

```dart
final userId = CSQ().metadata.userId;
```

#### CSQ().metadata.sessionId

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

```dart
final sessionId = CSQ().metadata.sessionId;
```

#### CSQ().metadata.projectId

Project identifier for Experience Analytics.

```dart
final projectId = CSQ().metadata.projectId;
```

#### CSQ().metadata.environmentId

Environment identifier for Product Analytics.

```dart
final environmentId = CSQ().metadata.environmentId;
```

#### CSQ().metadata.sessionReplayUrl

URL of current Session Replay.

```dart
final sessionReplayUrl = CSQ().metadata.sessionReplayUrl;
```

#### CSQ().metadata.identity

Identity associated with the user by calling [`identify()`](#csqidentify).

```dart
final identity = CSQ().metadata.identity;
```

### CSQ().metadata.onChange()

**Added in:** `1.0.0`

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

Note

This may not trigger on changes to Product Analytics data.

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


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

#### Parameters

* #### handler  void Function(Metadata metadata)  

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

## Logging

### CSQ().debug.setLogLevel()

**Added in:** `1.0.0`

Sets the current log level.

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

#### Parameters

* #### logLevel  Enum (LogLevel)  

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

## Property Tracking

### CSQ().addDynamicVar()

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.

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


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

#### Parameters

* #### 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).

### CSQ().addUserProperties()

Product Analytics | **Added in:** `1.0.0`

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

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

#### Parameters

* #### properties  Map\<String, dynamic>  

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

### CSQ().addEventProperties()

Product Analytics | **Added in:** `1.0.0`

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

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

#### Parameters

* #### properties  Map\<String, dynamic>  

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

### CSQ().removeEventProperty()

Product Analytics | **Added in:** `1.0.0`

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

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

#### Parameters

* #### name  String  

  The key of the property to remove.

### CSQ().clearEventProperties()

Product Analytics | **Added in:** `1.0.0`

Removes all event-wide properties.

```dart
await CSQ().clearEventProperties();
```

## Interoperability

### CSQWebViewWrapper

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](https://docs.contentsquare.com/en/webview-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

```dart
// 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),
  ),
)
```

#### Parameters

* #### delegate  WebViewWrapperDelegate  

  The delegate that supplies the WebView widget to be wrapped.

## Event Tracking

### CSQ().trackTransaction()

Experience Analytics | **Added in:** `1.0.0`

Send a transaction.

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

#### Parameters

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

### CSQ().trackScreenview()

**Added in:** `1.0.0`

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

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

#### Parameters

* #### 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

### CSQ().trackEvent()

Product Analytics | **Added in:** `1.0.0`

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

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

#### Parameters

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

## Error tracking

### CSQ().setURLMaskingPatterns()

Experience Analytics | **Added in:** `1.0.0`

Sets URL masking patterns.

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

#### Parameters

* #### patterns  List\<String>  

  A list of URL patterns to mask.

### CSQ().collectFlutterError()

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

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

#### Parameters

* #### details  FlutterErrorDetails  

  The Flutter error information.

* #### presentErrorDetails  bool (optional)  

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

### CSQ().collectError()

Experience Analytics | **Added in:** `1.0.0`

Sends a report of a caught error.

Typically used inside a `runZonedGuarded` error handler:

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

#### Parameters

* #### error  Object  

  The error object that was caught.

* #### stackTrace  StackTrace  

  The associated stack trace.

### CSQ().sendUserIdentifier()

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.

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

#### Parameters

* #### userIdentifier  String  

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

## Personal Data/Masking

### `CSQMask`

**Added in:** `1.0.0`

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.

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

#### Parameters

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

## SDK Initialization and Management

### CSQ().start()

**Added in:** `1.0.0`

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

```dart
// 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(),
  ),
);
```

#### Parameters

* #### 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](#analytics-options).

* #### maskingConfig  CSQMaskingConfig (optional)  

  Masking configuration for the SDK. See [privacy and sensitive data](../../product-analytics/privacy-and-sensitive-data/).

### CSQ().configureProductAnalytics()

**Added in:** `1.0.0`

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

Deprecated

`CSQ().configureProductAnalytics()` is deprecated and will be removed in August 2026.

Use `CSQ().start(startConfig: StartConfig.withEnvironmentId(...))` instead.

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

#### Parameters

* #### environmentId  String  

  Your Product Analytics environment ID.

* #### options  ProductAnalyticsOptions (optional)  

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

### CSQ().stop()

**Added in:** `1.0.0`

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

```dart
await CSQ().stop();
```

### CSQ().pauseTracking()

**Added in:** `1.0.0`

Pause all tracking features.

```dart
await CSQ().pauseTracking();
```

### CSQ().resumeTracking()

**Added in:** `1.0.0`

Resume all tracking features.

```dart
await CSQ().resumeTracking();
```

#### Parameters

* No parameters.

## Session Replay controls

### CSQ().startSessionReplay()

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

```dart
await CSQ().startSessionReplay();
```

#### Parameters

* No parameters.

### CSQ().stopSessionReplay()

Experience Analytics | **Added in:** `4.2.0`

Stops Session Replay on-demand.

```dart
await CSQ().stopSessionReplay();
```

#### Parameters

* No parameters.

## Analytics options

CSQ SDK options for Product Analytics passed to [`CSQ().start()`](#csqstart) via `StartConfig`.

```dart
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,
    ),
  ),
);
```

### `id` (`environmentId`)

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

### `id` (`dataSourceId`)

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.

### `baseUrl`

URI object specifying the base URI for the desired API endpoint. The CSQ SDK resolves paths using this base URI and ignores any pre-existing path elements.

### `disablePageviewAutocapture`

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

### `disablePageviewTitleAutocapture`

iOS only

Disable pageview title capture.

### `disableInteractionAutocapture`

Disables autocapture of touch interactions.

### `enablePushNotificationAutocapture`

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

### `enablePushNotificationTitleAutocapture`

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

### `enablePushNotificationBodyAutocapture`

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

### `enableInteractionsAutocapture`

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

### `sessionReplayAutoStart`

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