--- title: Getting Started - Android (classic) description: Integrate the Contentsquare SDK into your Android app in minutes (installation, user consent, screen tracking, and testing) lastUpdated: 03 June 2026 source_url: html: https://docs.contentsquare.com/en/android/ md: https://docs.contentsquare.com/en/android/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). Welcome to the SDK implementation guide! This guide is designed to help you seamlessly integrate our SDK into your application. By following the outlined steps, you'll be able to collect and analyze data from your app, within just a few minutes. ## Install the SDK Our Android SDK is shipped as an Android library (AAR) which you need to add as a dependency to your Gradle file. See [Compatibility](compatibility/) for more information. ### Include the SDK For distribution of our API we use **Maven Central Repository** which is supported by the Android build system by default. To add our SDK (or library), add the following line to your application's dependency list. * Groovy **build.gradle** ```groovy implementation "com.contentsquare.android:library:4.52.1" ``` * Kotlin **build.gradle.kts** ```kotlin implementation("com.contentsquare.android:library:4.52.1") ``` The SDK autostarts when your application launches, requiring no manual initialization. If you are using an older Kotlin version, see [Compatibility](compatibility/). ### Validate SDK integration Start your application, and check logs for this output: ```text CSLIB: Contentsquare SDK 4.52.1 starting in app: com.example.testapp ``` ## Check the logs Contentsquare provides logging capabilities that allow you to inspect the raw event data logged by your app in Android Studio, or on the Contentsquare platform. To view all logs, you must [enable in-app features](#enable-in-app-features): logging is linked to in-app features being enabled or disabled. ### Viewing logs in Android Studio To view SDK logs: 1. Plug your Android phone into your computer (or use an emulator) 2. Open Android Studio and start your app 3. Open the `Logcat` view and select your phone or emulator 4. Filter logs by `CSLIB`  ### Enable in-app features In-app features are essential for your implementation, as it includes key functionalities like screenshot creation and replay configuration. To enable in-app features within your app, make sure your app is launched in the background. To do so, start it and press the Android home button. Then, follow the appropriate method described as follows. If access is blocked by the Android OS, you may need to allow the restricted settings first. To do this, go to your device settings, navigate to **Apps**, tap on your app, open the **More** menu (three dots), and then tap on **Allow restricted settings**. #### On a device: scan the QR code In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.  Note On Android, some devices have a built-in QR code reader feature in the default camera app. If that is not the case for you, use the [QR & Barcode Reader by TeaCapps ↗](https://play.google.com/store/apps/details?id=com.teacapps.barcodescanner\&hl=en\&gl=US). #### On an emulator: use the ADB command If you are using an emulator, use the ADB command to enable in-app features. In Contentsquare, select the Mobile icon in the menu top bar then select your application ID, and "Copy this ADB command".  The following command is copied to the clipboard: ```shell adb shell "am start -W -a android.intent.action.VIEW -d cs-{{packageName}}://contentsquare.com?activationKey={{uniqueActivationKey}}\&userId={{userId}}" ``` To run the ADB command: 1. Plug your Android phone into your Computer (or use an emulator). 2. Make sure that only one phone or emulator is connected or running. 3. Start Android Studio. 4. Open the Terminal view. 5. Paste the ADB command into the Terminal and press `Enter`. 6. Switch to your phone or emulator and follow the steps on the screen. ### Contentsquare Log Visualizer Log Visualizer is a feature integrated into the Contentsquare SDK. As you navigate and interact with your app, it provides a live view of events detected by the SDK, visible directly on the [Contentsquare platform ↗](https://app.contentsquare.com/#/analyze/mobile-log). Prerequisite To use Log Visualizer, `Activate SDK logs stream` must be toggled on within in-app settings. 1. Start your app. 2. Select the Mobile icon in the menu top bar then select `Log Visualizer`. 3. Select the device to inspect. At this stage, you should see an 'App start' or 'App show' event being logged.  ## Get user consent Contentsquare collects usage data from your app users. To start tracking, you need your users' consent for being tracked. ### User opt-in The SDK treats users as **opted-out by default.** To start tracking, forward user consent with `optIn()`. Calling this method generates a user ID and initiates tracking. Handle user consent by implementing a UI for privacy preferences. Assuming you have an opt-in screen with a button to give consent, the code could look like this: * Java ```java import com.contentsquare.android.Contentsquare; Button optinButton = ... optinButton.setOnClickListener(view -> { Contentsquare.optIn(); // Then finish initialization and move to the next screen... }); ``` * Kotlin ```kotlin import com.contentsquare.android.Contentsquare val optinButton: Button = ... optinButton.setOnClickListener { Contentsquare.optIn() // Then finish initialization and move to the next screen... } ``` Going further For advanced configuration regarding user consent or personal data handling, see [Privacy](https://docs.contentsquare.com/en/android/privacy/). ## Track your first screens Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel. ### Sending screenview events Screen tracking is achieved by sending a `screenview` event each time a new screen is displayed on the user's device. To trigger a screenview each time an activity becomes visible, place the call in the `onResume()` method (XML layouts only): * Java ```java import com.contentsquare.android.Contentsquare; public class MyActivity extends Activity { @Override public void onResume() { super.onResume(); // Send screenView Contentsquare.send("screen_name"); } } ``` * Kotlin ```kotlin import com.contentsquare.android.Contentsquare class MyActivity : Activity() { override fun onResume() { super.onResume() // Send screenView Contentsquare.send("screen_name") } } ``` #### Jetpack Compose support To enable Jetpack Compose support, add a new dependency to your Gradle build file. * Groovy **build.gradle** ```groovy implementation 'com.contentsquare.android:compose:4.52.1' ``` * Kotlin **build.gradle.kts** ```kotlin implementation("com.contentsquare.android:compose:4.52.1") ``` Attention must be paid to recompositions. The call should be wrapped using `TriggeredOnResume` to ensure only one screenview is triggered when a given screen is presented to the user. ```kotlin import com.contentsquare.android.Contentsquare import com.contentsquare.android.compose.analytics.TriggeredOnResume @Composable fun MyComposable(data: Data) { TriggeredOnResume { Contentsquare.send("screen_name") } // ... } ``` ### Implementation recommendations From a functional perspective, a screenview should be triggered in the following cases: * When the screen appears on the device * When a modal or pop-up is displayed * When a modal or pop-up is closed, returning the user to the screen * When the app is brought back to the foreground (after being minimized) Specific triggers Depending on how your app is built (Popups, Webviews, Redirections, etc...), you might need specific implementation use cases for triggering screenview events. See the [dedicated section on screen tracking](https://docs.contentsquare.com/en/android/track-screens/#implementation-recommendations). #### Tracking app launch Most events collected by the SDK require a screenview event to be sent first so they can be associated with that screen; otherwise, they will be discarded. If you need to collect events from the moment the app launches, you should trigger a screenview event immediately after the SDK has started. Refer to [our guide](https://docs.contentsquare.com/en/android/track-screens/#when-to-send-your-first-screenview) for implementation examples. #### Screen name handling It is necessary to provide a name for each screen when calling the screenview API. As a general rule, keep distinct screen names under 100. As they are used to map your app in Contentsquare, you will want something comprehensive. The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side. More on [screen name handling](https://docs.contentsquare.com/en/android/track-screens/#how-to-name-screens). Tracking plan To get the most out of your data, it's best to follow a tracking plan. This way, you'll capture every step of the user's journey without missing important interactions, giving you a complete picture of how your app is used. ## Test your setup Testing your SDK implementation is essential to make sure data is being accurately captured and reported. To test your setup, simulate user interactions in your app and check that the events are logged correctly in our analytics platform. You can also use debugging tools such as Android Studio or Log Visualizer to monitor data transmission and ensure everything is running smoothly. ### Visualize events in Contentsquare Use [Log Visualizer](#contentsquare-log-visualizer) to view incoming events within the Contentsquare pipeline. This allows you to monitor the stream in real time. By simulating user activity, you see incoming screenview and gesture events.  ### Visualize data in Contentsquare Data availability Data must be sessionized (meaning all events for a single session are gathered together) before it can be visualized. This requires the session to have ended, which happens 30 minutes after the last event is received. Therefore, you can expect to see the first replays 30 minutes after the last interaction with the app. #### In Journey Analysis [Open Journey Analysis ↗](https://app.contentsquare.com/#/analyze/navigation-path) in Contentsquare and visualize the user journeys main steps across your app, screen by screen.  See how to use Journey Analysis on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271761254161). #### In Session Replay [Open Session Replay ↗](https://app.contentsquare.com/#/session-replay) in Contentsquare and replay the full user session across your app.  See how to use Session Replay on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561) ## Sample app To explore some of these features in context, check our Android sample app. ### [android-sample-app](https://github.com/ContentSquare/android-sample-app) [A sample app giving an example implementation of the Contentsquare SDK](https://github.com/ContentSquare/android-sample-app) [Kotlin](https://github.com/ContentSquare/android-sample-app) ## Next steps While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior. Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking. Proceed with these how-to's to refine your implementation. [Custom Variables](https://docs.contentsquare.com/en/android/track-custom-variables/)Collect additional details about the screen or the user. [Dynamic Variables](https://docs.contentsquare.com/en/android/track-dynamic-variables/)Collect additional information about the session. [Transactions tracking](https://docs.contentsquare.com/en/android/track-transactions/)Associate user's session with their potential purchases and corresponding revenue. [WebViews](https://docs.contentsquare.com/en/android/track-webviews/)For native apps which embark web applications or pages. [Session Replay](https://docs.contentsquare.com/en/android/session-replay/)Collect data for Session Replay in compliance personal data masking. [Error Analysis](https://docs.contentsquare.com/en/android/error-analysis/)Track API errors and application crashes with automated collection and privacy-safe debugging tools. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started","description":"Integrate the Contentsquare SDK into your Android app in minutes (installation, user consent, screen tracking, and testing)","url":"https://docs.contentsquare.com/en/android/","inLanguage":"en","dateModified":"2026-06-03T22:01:55+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Getting Started - Capacitor description: Integrate Contentsquare SDKs into your Capacitor apps in minutes (installation, user consent, screen tracking, and testing) lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/ md: https://docs.contentsquare.com/en/capacitor/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Welcome to the SDK implementation guide! This guide is designed to help you seamlessly integrate our SDK into your application. By following the outlined steps, you'll be able to collect and analyze data from your app, within just a few minutes. ## Install the SDK The SDK is shipped as a Capacitor plugin which you need to add as a dependency to your Capacitor application. See [Compatibility](compatibility/) for more information. ### Include the SDK Install the plugin as follows, specifying the exact version you want to install if needed: ```shell npm install @contentsquare/capacitor-plugin npx cap sync ``` You do not need to do anything to start the SDK. Now that the SDK is a dependency of your app, it will autostart itself when your application starts. ### Validate SDK integration Start your application, and check logs for this output: * Android Studio ```text CSLIB: Contentsquare SDK 7.1.1 starting in app: com.example.testapp ``` * Xcode ```text CSLIB ℹ️ Info: Contentsquare SDK v7.1.1 starting in app: com.example.testapp ``` ## Check the logs Contentsquare provides logging capabilities that allow you to inspect the raw event data logged by your app in Android Studio, Xcode, or on the Contentsquare platform. To view all logs, you must [enable in-app features](#enable-in-app-features): logging is linked to in-app features being enabled or disabled. ### Viewing local logs in IDE * Android To view SDK logs: 1. Plug your Android phone into your computer (or use an emulator) 2. Open Android Studio and start your app 3. Open the `Logcat` view and select your phone or emulator 4. Filter logs by `CSLIB`  * iOS 1. Unless you are using a simulator, ensure the device you are using is connected to your Mac or is on the same Wi-Fi network. 2. Open the macOS Console app or Xcode. For the macOS Console app, make sure info messages are included at [Choose Action > Include Info Messages ↗](https://support.apple.com/guide/console/customize-the-log-window-cnsl35710/mac). 3. Filter logs by `CSLIB`.  ### Implement in app-features Note This step only applies to iOS. In-app features are essential for your implementation, as it includes key functionalities like screenshot creation and replay configuration. To allow Contentsquare users to enable in-app features, perform these tasks: 1. [Add the custom URL scheme in your app Info](#1-add-the-custom-url-scheme-in-your-app-info) 2. [Call the SDK when the app is launched via a deeplink](#2-call-the-sdk-when-the-app-is-launched-via-a-deeplink) #### 1. Add the custom URL scheme in your app Info You have to allow your app to be opened via a custom URL scheme which can be done using one of the following methods: ##### Xcode 1. Open your project settings 2. Select the app target 3. Select the `Info` settings 4. Scroll to `URL Types` 5. Set the URL scheme to `cs-$(PRODUCT_BUNDLE_IDENTIFIER)` ##### Text editor 1. Open the `Info.plist` of your project 2. Add the following snippet: **Info.plist** ```xml CFBundleURLTypes CFBundleURLSchemes cs-$(PRODUCT_BUNDLE_IDENTIFIER) ``` #### 2. Call the SDK when the app is launched via a deeplink Depending on the project, there are multiple ways to handle the deeplink opening. Choose the method matching your project structure: * AppDelegate In your `AppDelegate` class, complete or implement the function `application(app, open url:, options:)` with: `Contentsquare.handle(url: url)` * SceneDelegate In your `WindowSceneDelegate` class, you need to: 1. Update `func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions)` with: ```swift if let url = connectionOptions.urlContexts.first?.url { Contentsquare.handle(url: url) } ``` 2. Complete or implement `func scene(_ scene: UIScene, openURLContexts URLContexts: Set)` with: ```swift if let url = URLContexts.first?.url { Contentsquare.handle(url: url) } ``` * SwiftUI In the `body` of your main App struct, add the `onOpenURL` modifier and call the `Contentsquare` SDK to handle the URL: ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { MyView() .onOpenURL { url in Contentsquare.handle(url: url) } } } } ``` ### Enable in-app features To enable in-app features within your app, you have to **first make sure your app is launched in the background**. Then, follow the appropriate method described as follows. #### On a device: scan the QR code * Android In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.  * iOS In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.  #### On an emulator/simulator * Android In Contentsquare, select the Mobile icon in the menu top bar then select your application ID, and "Copy this ADB command".  * iOS In Contentsquare, select the Mobile icon in the menu top bar then select your Bundle ID, and select "Copy this link". Paste it in Safari on your simulator to trigger the in-app features.  ### Contentsquare Log Visualizer Log Visualizer is a feature integrated into the Contentsquare SDK. As you navigate and interact with your app, it provides a live view of events detected by the SDK, visible directly on the [Contentsquare platform ↗](https://app.contentsquare.com/#/analyze/mobile-log). Prerequisite To use Log Visualizer, `Activate SDK logs stream` must be toggled on within in-app settings. 1. Start your app. 2. Select the Mobile icon in the menu top bar then select `Log Visualizer`. 3. Select the device to inspect. At this stage, you should see an 'App start' or 'App show' event being logged. * Android  * iOS  ## Get user consent Contentsquare collects usage data from your app users. To start tracking, you need your users' consent for being tracked. Warning You are responsible for handling the UI asking users for their consent and allowing them to manage their privacy settings. Consult our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ### User opt-in The SDK treats users as **opted-out by default.** Forward user consent with `optIn()`. Calling this method generates a user ID and initiates tracking. ```javascript import { ContentsquarePlugin } from "@contentsquare/capacitor-plugin"; ContentsquarePlugin.optIn(); ``` Going further For advanced configuration regarding user consent or personal data handling, see [Privacy](https://docs.contentsquare.com/en/capacitor/privacy/). ## Track your first screens Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel. ### Sending screenview events Screen tracking is achieved by sending a `screenview` event each time a new screen is displayed on the user's device. ```javascript import { ContentsquarePlugin } from "@contentsquare/capacitor-plugin"; ContentsquarePlugin.sendScreenName(screenName).catch((err) => { // Handle error }); ``` ### Implementation recommendations From a functional perspective, a screenview should be triggered in the following cases: * When the screen appears on the device * When a modal or pop-up is displayed * When a modal or pop-up is closed, returning the user to the screen * When the app is brought back to the foreground (after being minimized) #### Screen name handling It is necessary to provide a name for each screen when calling the screenview API. As a general rule, keep distinct screen names under 100. As they are used to map your app in Contentsquare, you will want something comprehensive. The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side. More on [screen name handling](https://docs.contentsquare.com/en/capacitor/track-screens/#how-to-name-screens). Tracking plan To get the most out of your data, it's best to follow a tracking plan. This way, you'll capture every step of the user's journey without missing important interactions, giving you a complete picture of how your app is used. ## Test your setup Testing your SDK implementation is essential to make sure data is being accurately captured and reported. To test your setup, simulate user interactions in your app and check that the events are logged correctly in our analytics platform. You can also use debugging tools such as Android Studio, Xcode, or Log Visualizer to monitor data transmission and ensure everything is running smoothly. ### Visualize events in Contentsquare Use [Log Visualizer](#contentsquare-log-visualizer) to view incoming events within the Contentsquare pipeline. This allows you to monitor the stream in real time. By simulating user activity, you see incoming screenview and gesture events. * Android  * iOS  ### Visualize data in Contentsquare Data availability Data must be sessionized (meaning all events for a single session are gathered together) before it can be visualized. This requires the session to have ended, which happens 30 minutes after the last event is received. Therefore, you can expect to see the first replays 30 minutes after the last interaction with the app. #### In Journey Analysis [Open Journey Analysis ↗](https://app.contentsquare.com/#/analyze/navigation-path) in Contentsquare and visualize the user journeys main steps across your app, screen by screen.  See how to use Journey Analysis on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271761254161). #### In Session Replay [Open Session Replay ↗](https://app.contentsquare.com/#/session-replay) in Contentsquare and replay the full user session across your app.  See how to use Session Replay on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561) ## Sample app To explore some of these features in context, check our Capacitor sample app. ### [capacitor-sample-app](https://github.com/ContentSquare/capacitor-sample-app) [A sample app giving an example implementation of the Contentsquare SDK](https://github.com/ContentSquare/capacitor-sample-app) [TypeScript](https://github.com/ContentSquare/capacitor-sample-app) ## Next steps While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior. Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking. Proceed with these how-to's to refine your implementation. [Dynamic Variables](https://docs.contentsquare.com/en/capacitor/track-dynamic-variables/)Collect additional information about the session. [Transactions tracking](https://docs.contentsquare.com/en/capacitor/track-transactions/)Associate user's session with their potential purchases and corresponding revenue. [Session Replay](https://docs.contentsquare.com/en/capacitor/session-replay/)Collect data for Session Replay in compliance personal data masking. [Error Analysis](https://docs.contentsquare.com/en/capacitor/error-analysis/)Track API errors and application crashes with automated collection and privacy-safe debugging tools. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started","description":"Integrate Contentsquare SDKs into your Capacitor apps in minutes (installation, user consent, screen tracking, and testing)","url":"https://docs.contentsquare.com/en/capacitor/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: What is Data Connect? - Data Connect description: Connect Contentsquare data with your warehouse or data lake for deeper business reporting, in-depth analysis, and customer modeling lastUpdated: 18 March 2026 source_url: html: https://docs.contentsquare.com/en/connect/ md: https://docs.contentsquare.com/en/connect/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Data Connect is built for data teams. It automatically syncs Contentsquare behavioral data into your data warehouse, so you can run complex SQL-based analysis and combine it with other datasets in your organization (CRM, ERP, marketing tools, and more). Note Data Connect is available for [Enterprise and Pro (optional) ↗](https://contentsquare.com/pricing/) plans. ## Why use Data Connect? * **Combine various datasets.** Combine Contentsquare data with your existing datasets in one place, using the tools and query language your team already knows. * **Full SQL access.** Run complex analytical queries directly in your data warehouse on structured data. * **Feed your data pipelines.** Build downstream reporting, monitoring, and alerting workflows on top of Contentsquare data. * **Power ML and AI workflows.** Use Contentsquare's behavioral data to train ML models or enrich AI agents. * **Quick to set up.** Data Connect is self-serve and writes directly to your warehouse. No engineering work required to get started. ## How does it work? * Data Connect syncs data to your warehouse on a fixed schedule. Each sync is incremental, automatically appending fresh data in batches. * Data is organized using a structured [data schema](https://docs.contentsquare.com/en/connect/data-schema/), with each user interaction broken down into the following core tables: sessions, pageviews, and events. * Supported warehouses: [Amazon Redshift, Google BigQuery, Snowflake, Amazon S3, Databricks](https://docs.contentsquare.com/en/connect/data-warehouses-overview/). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"What is Data Connect?","description":"Connect Contentsquare data with your warehouse or data lake for deeper business reporting, in-depth analysis, and customer modeling","url":"https://docs.contentsquare.com/en/connect/","inLanguage":"en","dateModified":"2026-03-18T17:28:59+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Getting Started - Cordova description: Integrate Contentsquare SDKs into your Cordova apps in minutes (installation, user consent, screen tracking, and testing) lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/cordova/ md: https://docs.contentsquare.com/en/cordova/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Welcome to the SDK implementation guide! This guide is designed to help you seamlessly integrate our SDK into your application. By following the outlined steps, you'll be able to collect and analyze data from your app, within just a few minutes. ## Install the SDK The Contentsquare Plugin for Cordova is a plugin between the Contentsquare SDKs for iOS and Android, and your Cordova JavaScript code. It allows for the use of our solution both in native and JavaScript parts of your app. The Contentsquare functionality is provided through an NPM package including only the plugin and dependencies to specific versions of the SDKs. See [Compatibility](compatibility/) for more information. ### Include the SDK Install the plugin as follows, specifying the exact version you want to install if needed: ```shell cordova plugin add @contentsquare/cordova-plugin ``` If your app is written in TypeScript, you can also install the types definitions package. ```shell npm install -D @contentsquare/cordova-plugin-types ``` #### Use the plugin in your JavaScript code The plugin defines a `ContentsquarePlugin` object. Although the object is in the global scope, features provided by this plugin are not available until after the deviceready event. ```javascript document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { // ContentsquarePlugin is now available } ``` You do not need to do anything to start the SDK. Now that the SDK is a dependency of your app, it will autostart itself when your application starts. ### Validate SDK integration Start your application, and check logs for this output: * Android Studio ```text CSLIB: Contentsquare SDK 0.3 starting in app: com.example.testapp ``` * Xcode ```text CSLIB ℹ️ Info: Contentsquare SDK v0.3 starting in app: com.example.testapp ``` ## Check the logs Contentsquare provides logging capabilities that allow you to inspect the raw event data logged by your app in Android Studio, Xcode, or on the Contentsquare platform. To view all logs, you must [enable in-app features](#enable-in-app-features): logging is linked to in-app features being enabled or disabled. ### Viewing local logs in IDE * Android To view SDK logs: 1. Plug your Android phone into your computer (or use an emulator) 2. Open Android Studio and start your app 3. Open the `Logcat` view and select your phone or emulator 4. Filter logs by `CSLIB`  * iOS 1. Unless you are using a simulator, ensure the device you are using is connected to your Mac or is on the same Wi-Fi network. 2. Open the macOS Console app or Xcode. For the macOS Console app, make sure info messages are included at [Choose Action > Include Info Messages ↗](https://support.apple.com/guide/console/customize-the-log-window-cnsl35710/mac). 3. Filter logs by `CSLIB`.  ### Implement in app-features In-app features are essential for your implementation, as it includes key functionalities like screenshot creation and replay configuration. To allow Contentsquare users to enable in-app features, perform these tasks: 1. [Install the Cordova plugin to handle URL schemes](#1-install-the-cordova-plugin-to-handle-url-schemes) 2. [Call the SDK when your app is opened with the custom URL](#2-call-the-sdk-when-your-app-is-opened-with-the-custom-url) #### 1. Install the Cordova plugin to handle URL schemes In order for your application to open when you scan the QR code or enter the URL we provide in a web browser, you have to install a Cordova plugin which will handle the URL scheme. ```javascript cordova plugin add cordova-plugin-customurlscheme --variable URL_SCHEME=cs-{package-id} // Example: // my package id is 'com.mycompany.myapp' // cordova plugin add cordova-plugin-customurlscheme --variable URL_SCHEME=cs-com.mycompany.myapp ``` #### 2. Call the SDK when your app is opened with the custom URL Then, you will need to link your app with our SDK. When your application is started via a deeplink, a specific global JavaScript function, handleOpenURL(), is automatically called in your App. You will have to define this function in the 'window' global scope and you will need to call a function of our API via the Contentsquare Cordova Plugin. ```javascript window.handleOpenURL = function (url) { console.log("received url: " + url); ContentsquarePlugin.handleURL(url); }; ``` ### Enable in-app features To enable in-app features within your app, you have to **first make sure your app is launched in the background**. Then, follow the appropriate method described as follows. #### On a device: scan the QR code * Android In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.  * iOS In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.  #### On an emulator/simulator * Android In Contentsquare, select the Mobile icon in the menu top bar then select your app ID, and "Copy this ADB command".  * iOS If you have access to the Contentsquare platform, you can open the in-app features modal from the menu then select your app ID, and select "Copy this link". Paste it in Safari on your simulator to trigger the in-app features.  ### Contentsquare Log Visualizer Log Visualizer is a feature integrated into the Contentsquare SDK. As you navigate and interact with your app, it provides a live view of events detected by the SDK, visible directly on the [Contentsquare platform ↗](https://app.contentsquare.com/#/analyze/mobile-log). Prerequisite To use Log Visualizer, `Activate SDK logs stream` must be toggled on within in-app settings. 1. Start your app. 2. Select the Mobile icon in the menu top bar then select `Log Visualizer`. 3. Select the device to inspect. At this stage, you should see an 'App start' or 'App show' event being logged. * Android  * iOS  ## Get user consent Contentsquare collects usage data from your app users. To start tracking, you need your users' consent for being tracked. Warning You are responsible for handling the UI asking users for their consent and allowing them to manage their privacy settings. Consult our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ### User opt-in The SDK treats users as **opted-out by default.** To start tracking, use `optIn()`. The `optIn()` API enables tracking via Contentsquare by generating a user ID and initiating tracking. This method should be called after receiving consent from the user. For example, call `optIn()` when the user accepts your app's privacy policy or tracking terms: ```javascript import React, { useState } from "react"; import { View, Text, Button } from "react-native"; import Contentsquare from "@contentsquare/react-native-bridge"; const PolicyConsentScreen = () => { const [isTrackingAccepted, setIsTrackingAccepted] = useState(false); const handleAcceptPolicy = () => { setIsTrackingAccepted(true); Contentsquare.optIn(); // Opt-in for CS Tracking }; return ( Please accept our privacy policy to proceed. ); }; export default PolicyConsentScreen; ``` Going further For advanced configuration regarding user consent or personal data handling, see [Privacy](https://docs.contentsquare.com/en/android/privacy/). ## Track your first screens Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel. ### Sending screenview events Screen tracking is achieved by sending a screenview event each time a new screen is displayed on the user's device. ```javascript import { ContentsquareCDVPlugin } from '@contentsquare/cordova-plugin-types'; declare var ContentsquarePlugin: ContentsquareCDVPlugin; ContentsquarePlugin.sendScreenName("ScreenName", (result)=>{ // Success }, (err)=>{ // Handle error }); ``` ### Implementation recommendations From a functional perspective, a screenview should be triggered in the following cases: * When the screen appears on the device * When a modal or pop-up is displayed * When a modal or pop-up is closed, returning the user to the screen * When the app is brought back to the foreground (after being minimized) #### Screen name handling It is necessary to provide a name for each screen when calling the screenview API. As a general rule, keep distinct screen names under 100. As they are used to map your app in Contentsquare, you will want something comprehensive. The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side. More on [screen name handling](https://docs.contentsquare.com/en/cordova/track-screens/#how-to-name-screens). Tracking plan To get the most out of your data, it's best to follow a tracking plan. This way, you'll capture every step of the user's journey without missing important interactions, giving you a complete picture of how your app is used. ## Test your setup Testing your SDK implementation is essential to make sure data is being accurately captured and reported. To test your setup, simulate user interactions in your app and check that the events are logged correctly in our analytics platform. You can also use debugging tools such as Android Studio, Xcode, or Log Visualizer to monitor data transmission and ensure everything is running smoothly. ### Visualize events in Contentsquare Use [Log Visualizer](#contentsquare-log-visualizer) to view incoming events within the Contentsquare pipeline. This allows you to monitor the stream in real time. By simulating user activity, you see incoming screenview and gesture events. * Android  * iOS  ### Visualize data in Contentsquare Data availability Data must be sessionized (meaning all events for a single session are gathered together) before it can be visualized. This requires the session to have ended, which happens 30 minutes after the last event is received. Therefore, you can expect to see the first replays 30 minutes after the last interaction with the app. #### In Journey Analysis [Open Journey Analysis ↗](https://app.contentsquare.com/#/analyze/navigation-path) in Contentsquare and visualize the user journeys main steps across your app, screen by screen.  See how to use Journey Analysis on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271761254161). #### In Session Replay [Open Session Replay ↗](https://app.contentsquare.com/#/session-replay) in Contentsquare and replay the full user session across your app.  See how to use Session Replay on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561) ## Sample app To explore some of these features in context, check our Cordova sample apps. ### [cordova-sample-app](https://github.com/ContentSquare/cordova-sample-app) [A sample app giving an example implementation of the Contentsquare SDK](https://github.com/ContentSquare/cordova-sample-app) [TypeScript](https://github.com/ContentSquare/cordova-sample-app) ## Next steps While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior. Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking. Proceed with these how-to's to refine your implementation. [Dynamic Variables](https://docs.contentsquare.com/en/cordova/track-dynamic-variables/)Collect additional information about the session. [Transactions tracking](https://docs.contentsquare.com/en/cordova/track-transactions/)Associate user's session with their potential purchases and corresponding revenue. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started","description":"Integrate Contentsquare SDKs into your Cordova apps in minutes (installation, user consent, screen tracking, and testing)","url":"https://docs.contentsquare.com/en/cordova/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Getting Started - Flutter (classic) description: Load and validate the Contentsquare Flutter SDK installation in your app lastUpdated: 10 June 2026 source_url: html: https://docs.contentsquare.com/en/flutter/ md: https://docs.contentsquare.com/en/flutter/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). Welcome to the SDK implementation guide! This guide is designed to help you seamlessly integrate our SDK into your application. By following the outlined steps, you'll be able to collect and analyze data from your app, within just a few minutes. ## Install the SDK With Flutter CLI: ```shell flutter pub add contentsquare ``` This will add a line like this to your package's pubspec.yaml (and run an implicit `flutter pub get`): **pubspec.yaml** ```yaml dependencies: contentsquare: ^4.4.4 ``` See [Compatibility](compatibility/) for more information. ## Start the SDK 1. Import the SDK ```dart import 'package:contentsquare/contentsquare.dart'; ``` 2. Add a call to start the SDK as early as possible, ideally in the `main()` function of your app. **main.dart** ```dart import 'package:contentsquare/contentsquare.dart'; import 'package:flutter/material.dart'; void main() async { await Contentsquare().start(); runApp(const MyApp()); } ``` Alternatively you can start the SDK after user consent, for example on a button press: ```dart class UserConsentScreen extends StatelessWidget { @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: Text('User Consent'), ), body: Center( child: ElevatedButton( onPressed: () async { await Contentsquare().start(); }, child: Text('Agree with Terms and Conditions'), ), ), ); } } ``` 3. After calling `start()` you need to call `optIn()` to start tracking. ```dart class UserConsentScreen extends StatelessWidget { @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: Text('User Consent'), ), body: Center( child: ElevatedButton( onPressed: () async { await Contentsquare().start(); await Contentsquare().optIn(); }, child: Text('Agree with Terms and Conditions'), ), ), ); } } ``` ## Validate SDK integration Start your application, and check logs for this output: ```text ┌─────────────────────────────────────────────────────────────────────────────── │ 🔔 IMPORTANT 🔔 (CSLIB 4.4.4) ├─────────────────────────────────────────────────────────────────────────────── │ Contentsquare Flutter SDK 4.4.4 starting in app: │ com.example.testapp └─────────────────────────────────────────────────────────────────────────────── ``` ## Check the logs Contentsquare provides logging capabilities that allow you to inspect the raw event data logged by your app in Android Studio, Xcode, or on the Contentsquare platform. To view all logs, you must [enable in-app features](#enable-in-app-features): logging is linked to in-app features being enabled or disabled. ### Viewing local logs in IDE * Android Studio To view SDK logs: 1. Plug your Android phone into your computer (or use an emulator) 2. Open Android Studio and start your app 3. Open the `Logcat` view and select your phone or emulator 4. Filter logs by `CSLIB`  * Xcode 1. Unless you are using a simulator, ensure the device you are using is connected to your Mac or is on the same Wi-Fi network. 2. Open the macOS Console app or Xcode. For the macOS Console app, make sure info messages are included at [Choose Action > Include Info Messages ↗](https://support.apple.com/guide/console/customize-the-log-window-cnsl35710/mac). 1. Filter logs by `CSLIB`.  ### Enable In-app features In-app features are essential for your implementation, as it includes key functionalities like screenshot creation and replay configuration. To enable in-app features within your app, you have to **first make sure your app is launched in the background**. Then, follow the appropriate method described as follows. #### On a device: scan the QR code * Android In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.  * iOS In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.  #### On an emulator/simulator * Android In Contentsquare, select the Mobile icon in the menu top bar then select your application ID, and "Copy this ADB command".  * iOS In Contentsquare, select the Mobile icon in the menu top bar then select your Bundle ID, and select "Copy this link". Paste it in Safari on your simulator to trigger the in-app features.  ### Contentsquare Log Visualizer Log Visualizer is a feature integrated into the Contentsquare SDK. As you navigate and interact with your app, it provides a live view of events detected by the SDK, visible directly on the [Contentsquare platform ↗](https://app.contentsquare.com/#/analyze/mobile-log). Prerequisite To use Log Visualizer, `Activate SDK logs stream` must be toggled on within in-app settings. 1. Start your app. 2. Select the Mobile icon in the menu top bar then select `Log Visualizer`. 3. Select the device to inspect. At this stage, you should see an 'App start' or 'App show' event being logged. * Android  * iOS  ## Android permissions When using the Contentsquare Flutter SDK on Android, the underlying native SDK requires specific permissions to function correctly. These permissions are automatically included from the Contentsquare SDK into your app's `AndroidManifest.xml` at build time. For the full list and detailed explanations, you can refer to the [Contentsquare Android SDK Required Permissions documentation](https://docs.contentsquare.com/en/android/security/#app-permissions). Important These permissions are mandatory and used exclusively for analytics purposes, in compliance with GDPR and CNIL (French regulation) requirements. ## Track your first screens Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel. ### Sending screenview events Screen tracking is achieved by sending a `screenview` each time a screen is displayed on the user's device. Important Sending at least one screen event is required to start tracking. **home.dart** ```dart import 'package:contentsquare/contentsquare.dart'; import 'package:flutter/material.dart'; class Home extends StatefulWidget { @override _HomeState createState() => _HomeState(); } class _HomeState extends State { @override void initState() { super.initState(); Contentsquare().send('Home'); } @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: const Text('Home'), ), body: const Center( child: Text('Welcome to Contentsquare!'), ), ); } } ``` ### Implementation recommendations For more detailed information on how to track screens, refer to the complete [screen tracking](https://docs.contentsquare.com/en/flutter/track-screens/) guide. ## Test your setup Testing your SDK implementation is essential to make sure data is being accurately captured and reported. To test your setup, simulate user interactions in your app and check that the events are logged correctly in our analytics platform. You can also use debugging tools such as Android Studio, Xcode, or Log Visualizer to monitor data transmission and ensure everything is running smoothly. ### Visualize events in Contentsquare Use [Log Visualizer](#contentsquare-log-visualizer) to view incoming events within the Contentsquare pipeline. This allows you to monitor the stream in real time. By simulating user activity, you see incoming screenview and gesture events. * Android  * iOS  ### Visualize data in Contentsquare Data availability Data must be sessionized (meaning all events for a single session are gathered together) before it can be visualized. This requires the session to have ended, which happens 30 minutes after the last event is received. Therefore, you can expect to see the first replays 30 minutes after the last interaction with the app. #### In Journey Analysis [Open Journey Analysis ↗](https://app.contentsquare.com/#/analyze/navigation-path) in Contentsquare and visualize the user journeys main steps across your app, screen by screen.  See how to use Journey Analysis on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271761254161). #### In Session Replay [Open Session Replay ↗](https://app.contentsquare.com/#/session-replay) in Contentsquare and replay the full user session across your app.  See how to use Session Replay on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561) ## Next Steps While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior. Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking. Proceed with these how-to's to refine your implementation. [Custom Variables](https://docs.contentsquare.com/en/flutter/track-custom-variables/)Collect additional details about the screen or the user. [Dynamic Variables](https://docs.contentsquare.com/en/flutter/track-dynamic-variables/)Collect additional information about the session. [Transactions tracking](https://docs.contentsquare.com/en/flutter/track-transactions/)Associate user's session with their potential purchases and corresponding revenue. [WebViews](https://docs.contentsquare.com/en/flutter/track-webviews/)For native apps which embark web applications or pages. [Session Replay](https://docs.contentsquare.com/en/flutter/session-replay/)Collect data for Session Replay in compliance personal data masking. [Error Analysis](https://docs.contentsquare.com/en/flutter/error-analysis/)Track API errors and application crashes with automated collection and privacy-safe debugging tools. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started","description":"Load and validate the Contentsquare Flutter SDK installation in your app","url":"https://docs.contentsquare.com/en/flutter/","inLanguage":"en","dateModified":"2026-06-10T08:20:02+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Getting Started - iOS (classic) description: Integrate the Contentsquare SDK into your iOS app in minutes (installation, user consent, screen tracking, and testing) lastUpdated: 01 July 2026 source_url: html: https://docs.contentsquare.com/en/ios/ md: https://docs.contentsquare.com/en/ios/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). Welcome to the SDK implementation guide! This guide is designed to help you seamlessly integrate our SDK into your application. By following the outlined steps, you'll be able to collect and analyze data from your app, within just a few minutes. Warning **CocoaPods is no longer supported.** If you're using CocoaPods, [migrate to Swift Package Manager](https://docs.contentsquare.com/en/ios/migrate-from-cocoapods/) to continue receiving updates. ## Install the SDK Our iOS SDK is shipped as a `.xcframework` which you need to add as a dependency of your project. See [Compatibility](compatibility/) for more information. ### Include the SDK The SDK requires Xcode 16.0 or later. If you are using an earlier version of Xcode, contact your Contentsquare representative for more information. * Swift Package Manager 1. In Xcode, add the following link via `File > Add Packages…`: ```plaintext https://github.com/ContentSquare/CS_iOS_SDK.git ``` 2. Remove `https://github.com/apple/swift-protobuf.git` if you added it before Contentsquare iOS SDK version 4.35.1. 3. To ensure the library can start properly you will need to add `-ObjC` as a linker flag under `Build Settings` > `Linking` > `Other Linker Flags`. * Manual Our SDK can be linked dynamically or statically: #### Dynamic linking ##### Get the manual integration framework 1. Go to the [iOS SDK GitHub repository ↗](https://github.com/ContentSquare/CS_iOS_SDK/releases). 2. Find the newest version available (unless instructed otherwise by your CS contact). 3. Under `Assets` you should be able to find `ContentsquareModuleDynamicManually.xcframework.zip`, download the file. ##### Include the framework 1. Unzip `ContentsquareModuleDynamicManually.xcframework.zip` and you should see a folder named `ContentsquareModule` containing: * `ContentsquareModule.xcframework` * `CSSwiftProtobuf.xcframework` * `CSCrashReporter.xcframework` 2. Copy `ContentsquareModule` to any folder in your project. 3. In your `target` -> `General` -> `Frameworks, Libraries and Embedded Content`, add `ContentsquareModule.xcframework`, `CSSwiftProtobuf.xcframework` and `CSCrashReporter.xcframework` by clicking "+" -> "Add Other..." -> "Add Files...". 4. Clean build folder and run. #### Static linking ##### Get the manual integration framework 1. Go to the [iOS SDK GitHub repository ↗](https://github.com/ContentSquare/CS_iOS_SDK/releases). 2. Find the newest version available (unless instructed otherwise by your CS contact). 3. Under `Assets` you should be able to find `ContentsquareModuleStaticManually.xcframework.zip`, download the file. ##### Include the framework 1. Unzip `ContentsquareModuleStaticManually.xcframework.zip` and you should see a folder named `ContentsquareModule` containing: * `ContentsquareModule.xcframework` * `Resources/ContentsquareBundle.bundle` * `CSSwiftProtobuf.xcframework` * `CSCrashReporter.xcframework` 2. Copy `ContentsquareModule` to any folder in your project. 3. In your `target` -> `General` -> `Frameworks, Libraries and Embedded Content`, add `ContentsquareModule.xcframework`, `CSSwiftProtobuf.xcframework` and `CSCrashReporter.xcframework` by clicking "+" -> "Add Other..." -> "Add Files...". 4. Add `ContentsquareBundle.bundle` to your target, make sure it has been added to your `target` -> `Build Phases` -> `Copy Bundle Resources`. 5. To ensure the library can start properly you will need to add `-ObjC` as a linker flag under `Build Settings` > `Linking` > `Other Linker Flags`. 6. Clean build folder and run. The SDK autostarts when your application launches, requiring no manual initialization. ### Validate SDK integration Start your application, and check logs for this output: ```text CSLIB ℹ️ Info: Contentsquare SDK v4.52.1 starting in app: com.example.testapp ``` ## Check the logs Contentsquare provides logging capabilities that allow you to inspect the raw event data logged by your app in Xcode, the macOS Console app, or on the Contentsquare platform. To view all logs, you must [enable in-app features](#enable-in-app-features): logging is linked to in-app features being enabled or disabled. ### Viewing logs in Xcode or the Console app To view SDK logs: 1. If using an actual device, make sure it is plugged to your Mac or is on the same Wi-Fi network. 2. Start the macOS Console app or Xcode. If using the Console app, make sure that info messages are included: [Choose Action > Include Info Messages ↗](https://support.apple.com/guide/console/customize-the-log-window-cnsl35710/mac). 3. Filter logs by `CSLIB`  ### Implement in-app features In-app features are essential for your implementation, as it includes key functionalities like screenshot creation and replay configuration. To allow Contentsquare users to enable in-app features: 1. [Add the custom URL scheme in your app Info](#1-add-the-custom-url-scheme-in-your-app-info) 2. [Call the SDK when the app is launched via a deeplink](#2-call-the-sdk-when-the-app-is-launched-via-a-deeplink) #### 1. Add the custom URL scheme in your app Info You have to allow your app to be opened via a custom URL scheme which can be done using one of the following methods: ##### Xcode 1. Open your project settings 2. Select the app target 3. Select the `Info` settings 4. Scroll to `URL Types` 5. Set the URL scheme to `cs-$(PRODUCT_BUNDLE_IDENTIFIER)` ##### Text editor 1. Open the `Info.plist` of your project 2. Add the following snippet: **Info.plist** ```xml CFBundleURLTypes CFBundleURLSchemes cs-$(PRODUCT_BUNDLE_IDENTIFIER) ``` #### 2. Call the SDK when the app is launched via a deeplink Depending on the project, there are multiple ways to handle the deeplink opening. Choose the method matching your project structure: * AppDelegate In your `AppDelegate` class, complete or implement the function `application(app, open url:, options:)` with: `Contentsquare.handle(url: url)` * SceneDelegate In your `WindowSceneDelegate` class, you need to: 1. Update `func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions)` with: ```swift if let url = connectionOptions.urlContexts.first?.url { Contentsquare.handle(url: url) } ``` 2. Complete or implement `func scene(_ scene: UIScene, openURLContexts URLContexts: Set)` with: ```swift if let url = URLContexts.first?.url { Contentsquare.handle(url: url) } ``` * SwiftUI In the `body` of your main App struct, add the `onOpenURL` modifier and call the `Contentsquare` SDK to handle the URL: ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { MyView() .onOpenURL { url in Contentsquare.handle(url: url) } } } } ``` ### Enable in-app features #### On a device: scan the QR code In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.  #### On a simulator: with the custom link If you are using a simulator, use the custom link to enable in-app features. In Contentsquare, select the Mobile icon in the menu top bar then select your Bundle ID, and select "Copy this link". Paste it in Safari on your simulator to trigger the in-app features.  #### On a simulator: with the Terminal In a Terminal console, open a URL in your current simulator with the following command (replacing `CUSTOM_LINK` with yours): ```shell xcrun simctl openurl booted "CUSTOM_LINK" ``` ### Contentsquare Log Visualizer Log Visualizer is a feature integrated into the Contentsquare SDK. As you navigate and interact with your app, it provides a live view of events detected by the SDK, visible directly on the [Contentsquare platform ↗](https://app.contentsquare.com/#/analyze/mobile-log). Prerequisite To use Log Visualizer, `Activate SDK logs stream` must be toggled on within in-app settings. 1. Start your app. 2. Select the Mobile icon in the menu top bar then select `Log Visualizer`. 3. Select the device to inspect. At this stage, you should see an 'App start' or 'App show' event being logged.  ## Get user consent Contentsquare collects usage data from your app users. To start tracking, you need your users' consent for being tracked. ### User opt-in The SDK treats users as **opted-out by default.** To start tracking, forward user consent with `optIn()`. Calling this method generates a user ID and initiates tracking. Handle user consent by implementing a UI for privacy preferences. * Swift ```swift Contentsquare.optIn() ``` * Objective-C ```objective-c [Contentsquare optIn]; ``` Going further For advanced configuration regarding user consent or personal data handling, see [Privacy](https://docs.contentsquare.com/en/ios/privacy/). ## Track your first screens Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel. ### Sending screenview events Screen tracking is achieved by sending a `screenview` event each time a new screen is displayed on the user's device. As a general rule of thumb, you should send your screenviews in `viewWillAppear(_ animate: Bool)` when using UIKit, in `.onAppear()` when using SwiftUI. * Swift ```swift import ContentsquareModule Contentsquare.send(screenViewWithName: String, cvars: [CustomVar] = []) ``` * Objective-C ```objective-c @import ContentsquareModule; [Contentsquare sendWithScreenViewWithName:(NSString * _Nonnull)]; // or [Contentsquare sendWithScreenViewWithName:(NSString * _Nonnull) cvars:(NSArray * _Nonnull)]; // To add custom variables to screen tracking ``` ### Implementation recommendations From a functional perspective, a screenview should be triggered in the following cases: * When the screen appears on the device * When a modal or pop-up is displayed * When a modal or pop-up is closed, returning the user to the screen * When the app is brought back to the foreground (after being minimized) Specific triggers Depending on how your app is built (Popups, Webviews, Redirections, etc...), you might need specific implementation use cases for triggering screenview events. See the [dedicated section in our Guide](https://docs.contentsquare.com/en/ios/track-screens/#implementation-recommendations). #### Tracking app launch Most events collected by the SDK require a screenview event to be sent first so they can be associated with that screen; otherwise, they will be discarded. If you need to collect events from the moment the app launches, you should trigger a screenview event immediately after the SDK has started. Refer to [our guide](https://docs.contentsquare.com/en/ios/track-screens/#when-to-send-your-first-screenview) for implementation examples. #### Screen name handling It is necessary to provide a name for each screen when calling the screenview API. As a general rule, keep distinct screen names under 100. As they are used to map your app in Contentsquare, you will want something comprehensive. The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side. More on [screen name handling](https://docs.contentsquare.com/en/ios/track-screens/#how-to-name-screens). Tracking plan To get the most out of your data, it's best to follow a tracking plan. This way, you'll capture every step of the user's journey without missing important interactions, giving you a complete picture of how your app is used. ## Test your setup Testing your SDK implementation is essential to make sure data is being accurately captured and reported. To test your setup, simulate user interactions in your app and check that the events are logged correctly in our analytics platform. You can also use debugging tools such as Xcode, macOS Console App, or Log Visualizer to monitor data transmission and ensure everything is running smoothly. ### Visualize events in Contentsquare Use [Log Visualizer](#contentsquare-log-visualizer) to view incoming events within the Contentsquare pipeline. This allows you to monitor the stream in real time. By simulating user activity, you see incoming screenview and gesture events.  ### Visualize data in Contentsquare Data availability Data must be sessionized (meaning all events for a single session are gathered together) before it can be visualized. This requires the session to have ended, which happens 30 minutes after the last event is received. Therefore, you can expect to see the first replays 30 minutes after the last interaction with the app. #### In Journey Analysis [Open Journey Analysis ↗](https://app.contentsquare.com/#/analyze/navigation-path) in Contentsquare and visualize the user journeys main steps across your app, screen by screen.  See how to use Journey Analysis on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271761254161). #### In Session Replay [Open Session Replay ↗](https://app.contentsquare.com/#/session-replay) in Contentsquare and replay the full user session across your app.  See how to use Session Replay on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561) ## Sample app To explore some of these features in context, check our iOS sample app. ### [iOS-sample-app](https://github.com/ContentSquare/iOS-sample-app) [A sample app giving an example implementation of the Contentsquare SDK](https://github.com/ContentSquare/iOS-sample-app) [Swift](https://github.com/ContentSquare/iOS-sample-app) ## Next Steps While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior. Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking. Proceed with these how-to's to refine your implementation. [Custom Variables](https://docs.contentsquare.com/en/ios/track-custom-variables/)Collect additional details about the screen or the user. [Dynamic Variables](https://docs.contentsquare.com/en/ios/track-dynamic-variables/)Collect additional information about the session. [Transactions tracking](https://docs.contentsquare.com/en/ios/track-transactions/)Associate user's session with their potential purchases and corresponding revenue. [WebViews](https://docs.contentsquare.com/en/ios/track-webviews/)For native apps which embark web applications or pages. [Session Replay](https://docs.contentsquare.com/en/ios/session-replay/)Collect data for Session Replay in compliance personal data masking. [Error Analysis](https://docs.contentsquare.com/en/ios/error-analysis/)Track API errors and application crashes with automated collection and privacy-safe debugging tools. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started","description":"Integrate the Contentsquare SDK into your iOS app in minutes (installation, user consent, screen tracking, and testing)","url":"https://docs.contentsquare.com/en/ios/","inLanguage":"en","dateModified":"2026-07-01T21:01:22+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Getting Started - React Native (classic) description: Integrate the Contentsquare React Native bridge into your apps in minutes (installation, user consent, screen tracking, and testing) lastUpdated: 10 June 2026 source_url: html: https://docs.contentsquare.com/en/react-native/ md: https://docs.contentsquare.com/en/react-native/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). Welcome to the SDK implementation guide! This guide is designed to help you seamlessly integrate our SDK into your application. By following the outlined steps, you'll be able to collect and analyze data from your app, within just a few minutes. React Native new architecture If your app enables React Native's New Architecture, make sure to check our [compatibility](compatibility/) page for more details. ## Install the SDK The Contentsquare Bridge for React Native integrates the Contentsquare SDKs for both iOS and Android with your React Native JavaScript code. See [Compatibility](compatibility/) for more information. ### Include the SDK The Contentsquare Bridge is available as an [NPM package ↗](https://www.npmjs.com/package/@contentsquare/react-native-bridge), which includes the bridge and the necessary dependencies for specific versions of the SDKs. To install the bridge, open a terminal and run the following commands from your application's root directory: ```shell npm install @contentsquare/react-native-bridge cd ios && pod install ``` iOS Specific Note Since React Native projects for iOS are in Objective-C and our SDK is in Swift, you need to embed the Swift standard libraries. In your project's target Build Settings, set **Embedded Content Contains Swift Code** to YES. Ensure CocoaPods version 1.10.0 or later is installed (`pod --version`). If not, update with `[sudo] gem install cocoapods`. This is required to link the SDK and bridge, as CocoaPods only added support for XCFrameworks in late 2020. ### Importing the Bridge The Contentsquare module is the main module and the default export of our bridge. The Currency module is only used to send Transactions, and contains all supported currencies. ```javascript import Contentsquare, { Currency } from "@contentsquare/react-native-bridge"; ``` ### Start the SDK Starting the SDK should happen as early as possible in your app's lifecycle, ideally in the main component or entry point of your React Native application. 1. Add a call to `Contentsquare.start()` within a `useEffect` hook in your main component, such as `App.js` or `index.js`: ```javascript import { Contentsquare } from "@contentsquare/react-native-bridge"; useEffect(() => { Contentsquare.start(); }, []); ``` 2. Start your application, and check logs for this output: ```text [INFO] CSQ 6.4.2 for Product Analytics is attempting to start. ``` ## Get user consent The CSQ SDK treats users as opted-out by default. Implement the [`optIn()`](https://docs.contentsquare.com/en/react-native/privacy/#opt-in) API to forward user consent to the SDK and generate a user ID. ```javascript import { Contentsquare } from "@contentsquare/react-native-bridge"; Contentsquare.optIn(); ``` ### Validate SDK integration Start your application, and check logs for this output: ```text [INFO] CSQ 6.4.2 for Product Analytics is attempting to start. ``` ## Check the logs Contentsquare provides logging capabilities that allow you to inspect the raw event data logged by your app in Android Studio, Xcode, or on the Contentsquare platform. To view all logs, you must [enable in-app features](#enable-in-app-features): logging is linked to in-app features being enabled or disabled. ### Viewing local logs in IDE * Android To view SDK logs: 1. Plug your Android phone into your computer (or use an emulator) 2. Open Android Studio and start your app 3. Open the `Logcat` view and select your phone or emulator 4. Filter logs by `CSLIB`  * iOS 1. Unless you are using a simulator, ensure the device you are using is connected to your Mac or is on the same Wi-Fi network. 2. Open the macOS Console app or Xcode. For the macOS Console app, make sure info messages are included at [Choose Action > Include Info Messages ↗](https://support.apple.com/guide/console/customize-the-log-window-cnsl35710/mac). 3. Filter logs by `CSLIB`.  ### Enable in-app features In-app features are essential for your implementation, as it includes key functionalities like screenshot creation and replay configuration. To enable in-app features within your app, you have to **first make sure your app is launched in the background**. Then, follow the appropriate method described as follows. #### On a device: scan the QR code * Android In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.  * iOS In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.  #### On an emulator/simulator * Android In Contentsquare, select the Mobile icon in the menu top bar then select your application ID, and "Copy this ADB command".  * iOS In Contentsquare, select the Mobile icon in the menu top bar then select your Bundle ID, and select "Copy this link". Paste it in Safari on your simulator to trigger the in-app features.  ### Contentsquare Log Visualizer Log Visualizer is a feature integrated into the Contentsquare SDK. As you navigate and interact with your app, it provides a live view of events detected by the SDK, visible directly on the [Contentsquare platform ↗](https://app.contentsquare.com/#/analyze/mobile-log). Prerequisite To use Log Visualizer, `Activate SDK logs stream` must be toggled on within in-app settings. 1. Start your app. 2. Select the Mobile icon in the menu top bar then select `Log Visualizer`. 3. Select the device to inspect. At this stage, you should see an 'App start' or 'App show' event being logged. * Android  * iOS  ## Get user consent Contentsquare collects usage data from your app users. To start tracking, you need your users' consent for being tracked. ### User opt-in The SDK treats users as **opted-out by default.** To start tracking, forward user consent with optIn(). Calling this method generates a user ID and initiates tracking. For example, you can call `optIn()` when the user accepts your app's privacy policy or tracking terms. ```javascript import React, { useState } from "react"; import { View, Text, Button } from "react-native"; import Contentsquare from "@contentsquare/react-native-bridge"; const PolicyConsentScreen = () => { const [isTrackingAccepted, setIsTrackingAccepted] = useState(false); const handleAcceptPolicy = () => { setIsTrackingAccepted(true); Contentsquare.optIn(); }; return ( Please accept our privacy policy to proceed. ); }; export default PolicyConsentScreen; ``` Going further For advanced configuration regarding user consent or personal data handling, see [Privacy](https://docs.contentsquare.com/en/android/privacy/). ## Android permissions When using the Contentsquare Flutter/React Native SDK on Android, the underlying native SDK requires specific permissions to function correctly. These permissions are automatically included from the Contentsquare SDK into your app's `AndroidManifest.xml` at build time. For the full list and detailed explanations, you can refer to the [Contentsquare Android SDK Required Permissions documentation](https://docs.contentsquare.com/en/android/security/#app-permissions). Important These permissions are mandatory and used exclusively for analytics purposes, in compliance with GDPR and CNIL (French regulation) requirements. ## Track your first screens Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel. ### Sending screenview events Screen tracking is achieved by sending a `screenview` event each time a new screen is displayed on the user's device. #### Sending Screenview Events using the React Navigation Library The sending of screenview events can be handled within the `NavigationContainer` in [React Navigation ↗](https://reactnavigation.org/docs/navigation-container/), which centralizes the logic and helps avoid unnecessary calls. ```javascript // This associates the screen name sent to Contentsquare to the screen name defined in the code const screenEventByScreenName: Record = { Home: 'Home', ProductList: 'Product List', ProductDetails: 'Product #1', }; export const Navigation = () => { const navigationRef = useNavigationContainerRef(); const routeNameRef = useRef(); return ( { // Getting initial route name from navigation and sending a screen view event with Contentsquare SDK const currentRouteName = navigationRef.getCurrentRoute()?.name; if (currentRouteName && screenEventByScreenName[currentRouteName]) { Contentsquare.send(screenEventByScreenName[currentRouteName]); } }} onStateChange={() => { // Getting route name from navigation and sending a screen view event with Contentsquare SDK const currentRouteName = navigationRef.getCurrentRoute()?.name; routeNameRef.current = currentRouteName; if (currentRouteName && screenEventByScreenName[currentRouteName]) { Contentsquare.send(screenEventByScreenName[currentRouteName]); } }} > ); }; ``` ### Implementation recommendations From a functional perspective, a screenview should be triggered in the following cases: * When the screen appears on the device * When a modal or pop-up is displayed * When a modal or pop-up is closed, returning the user to the screen * When the app is brought back to the foreground (after being minimized) #### Tracking app launch Most events collected by the SDK require a screenview event to be sent first to associate the events with the correct screen. If a screenview event is not sent, the events will be discarded. To ensure proper tracking from the moment the app launches, trigger a screenview event immediately after the SDK has started. #### Screen name handling It is necessary to provide a name for each screen when calling the screenview API. As a general rule, keep distinct screen names under 100. As they are used to map your app in Contentsquare, you will want something comprehensive. The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side. More on [screen name handling](https://docs.contentsquare.com/en/react-native/track-screens/#how-to-name-screens). Tracking plan To get the most out of your data, though, it's best to follow a tracking plan. This way, you'll capture every step of the user's journey without missing important interactions, giving you a complete picture of how your app is used. ## Test your setup Testing your SDK implementation is essential to make sure data is being accurately captured and reported. To test your setup, simulate user interactions in your app and check that the events are logged correctly in our analytics platform. You can also use debugging tools such as Android Studio, Xcode, or Log Visualizer to monitor data transmission and ensure everything is running smoothly. ### Visualize events in Contentsquare Use [Log Visualizer](#contentsquare-log-visualizer) to view incoming events within the Contentsquare pipeline. This allows you to monitor the stream in real time. By simulating user activity, you see incoming screenview and gesture events. * Android  * iOS  ### Visualize data in Contentsquare Data availability Data must be sessionized (meaning all events for a single session are gathered together) before it can be visualized. This requires the session to have ended, which happens 30 minutes after the last event is received. Therefore, you can expect to see the first replays 30 minutes after the last interaction with the app. #### In Journey Analysis [Open Journey Analysis ↗](https://app.contentsquare.com/#/analyze/navigation-path) in Contentsquare and visualize the user journeys main steps across your app, screen by screen.  See how to use Journey Analysis on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271761254161). #### In Session Replay [Open Session Replay ↗](https://app.contentsquare.com/#/session-replay) in Contentsquare and replay the full user session across your app.  See how to use Session Replay on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561) ## Sample app To explore some of these features in context, check our React Native sample apps. ### [react-native-sample-app](https://github.com/ContentSquare/react-native-sample-app) [Sample apps illustrating how to use the Contentsquare Bridge for React Native in your app](https://github.com/ContentSquare/react-native-sample-app) [TypeScript](https://github.com/ContentSquare/react-native-sample-app) ## Next Steps While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior. Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking. Proceed with these how-to's to refine your implementation. [Custom Variables](https://docs.contentsquare.com/en/react-native/track-custom-variables/)Collect additional details about the screen or the user. [Dynamic Variables](https://docs.contentsquare.com/en/react-native/track-dynamic-variables/)Collect additional information about the session. [Transactions tracking](https://docs.contentsquare.com/en/react-native/track-transactions/)Associate user's session with their potential purchases and corresponding revenue. [WebViews](https://docs.contentsquare.com/en/react-native/track-webviews/)For native apps which embark web applications or pages. [Session Replay](https://docs.contentsquare.com/en/react-native/session-replay/)Collect data for Session Replay in compliance personal data masking. [Error Analysis](https://docs.contentsquare.com/en/react-native/error-analysis/)Track API errors and application crashes with automated collection and privacy-safe debugging tools. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started","description":"Integrate the Contentsquare React Native bridge into your apps in minutes (installation, user consent, screen tracking, and testing)","url":"https://docs.contentsquare.com/en/react-native/","inLanguage":"en","dateModified":"2026-06-10T08:20:02+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: The Main Tracking Tag - Web description: The Contentsquare Main Tracking Tag or Main tag is the core 'pixel' or 'code snippet' to implement on your domain to collect analytics data lastUpdated: 16 July 2026 source_url: html: https://docs.contentsquare.com/en/web/ md: https://docs.contentsquare.com/en/web/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare Main Tracking Tag or **Main tag** is the core 'pixel' or 'code snippet' that needs to be implemented on your domain to collect analytics data. It can be implemented **through a Tag Management System (TMS) or on the site's template**. Find step-by-step guides below. before the implementation, you need to gather the following information: * A **Contentsquare Tag ID** will be provided after kicking off the Contentsquare partnership. This 13-character unique ID can be used only on agreed domains — no data will be sent from elsewhere. * You can provide **up to 20 custom variables** to enrich the analysis context with details about the pages or the user. They're usually collected from your datalayer or any other JavaScript object implemented throughout the site. ## AI-assisted setup Use the Contentsquare wizard or skills to set up, update, and configure Web Tracking Tag with your AI coding assistant. Disclaimer This skill guides your AI coding agent through the SDK installation and implementation. The agent you use (Cursor, Claude Code, Copilot) is your own tool and operates under your settings and permissions. Contentsquare is not responsible for how your agent interprets or applies the instructions contained in these files. ### Contentsquare wizard Run the wizard in your project directory. It configures your AI coding assistant, installs the matching Contentsquare integration, and verifies the installation. ```shell npx @contentsquare/wizard install ``` Supports GitHub Copilot, Cursor, and Claude Code. Requires Node.js ≥ 18 and an AI coding agent with MCP support. ### Manual setup Use this path when you prefer to configure your AI coding assistant yourself. #### 1. Add the Contentsquare skill Choose how to install the Contentsquare skill. * Copilot CLI Add the Contentsquare marketplace, then install the plugin for Web Tracking Tag: ```shell copilot plugin marketplace add ContentSquare/agents copilot plugin install contentsquare-web@contentsquare ``` * Claude Code Add the Contentsquare marketplace, then install the plugin for Web Tracking Tag: ```shell /plugin marketplace add ContentSquare/agents /plugin install contentsquare-web@contentsquare ``` * Cursor Install **contentsquare** from the [Cursor marketplace ↗](https://cursor.com/marketplace), or add the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents) directly. Cursor reads the `.cursor-plugin` catalog in the repository. * Other agents Install the Contentsquare skill pack with the open `skills.sh` ecosystem: ```shell npx skills add contentsquare/agents ``` * From source Download or clone the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents), then copy `skills/contentsquare-web-tag-install` into the location your AI coding assistant scans for skills: | AI coding assistant | Skill location | | - | - | | GitHub Copilot | `.github/skills/` or `.agents/skills/` | | Cursor | `.cursor/rules/` or the project root | | Claude Code | `.claude/skills/` or the project root | | Other compatible agents | `.agents/skills/` | #### 2. Ask your AI coding assistant After installing the skill, paste this prompt into your AI coding assistant: ```text Add Contentsquare to my website using tag ID YOUR_TAG_ID. ``` Prefer to set things up manually? Use one of the following [Tag Management System](#google-tag-manager-template) guides, or the [Custom HTML](#custom-html) snippet. ## Google Tag Manager (Template) 1. Open your container and go to the **templates** section.  2. Select **Search gallery**.  3. Type in **`contentsquare`** and select the **Contentsquare - Main tag** option.  4. Click **Add to workspace**.  5. Confirm your choice by selecting **Add**  6. Go to the Tags section and click the **New** button to create a new tag.  7. Configure it by selecting the top-right button.  8. Search for **`contentsquare`** and select the **Contentsquare - Main tag** template that you've previously added to your container.  9. Give a title to the tag and input your Tag ID in the dedicated field. To configure Custom Variables, enter: * The index, from 1 to 20 - unique numbers only. * The name. * The value itself, which will be taken from one of your GTM Variables. * The scope — select `Page & Visit (2 & 3)`, or `Single Page App (nextPageOnly 4)` if your website/part of it is a Single Page Application. Check with Contentsquare contact if unsure. 10. Select the trigger: `All Pages` or `DOM Ready` (when data layer has been fully loaded). We suggest **All Pages**, as long as your selected variables will be populated by then.  11. (Optional) Mask Personal Data within the GTM GUI. Select the appropriate Personal Data masking method, depending on the type of personal information you're looking to mask: * **Define CSS Selectors** for text nodes.  * **CSS Selectors** and **Data Attributes** for element attributes.  12. Save your changes and go back to your container. You should now see both the template and the newly created tag.  ## Google Tag Manager (Custom HTML) 1. Add a **new tag** on your workspace.  2. Select **"Choose a tag type to begin setup..."**.  3. In the list, pick the **"Custom HTML"** tag.  4. Depending on your data layer availability, take a look at the following code examples and populate it with the information required: * Implementing the tag and **pushing** data layer variables to Contentsquare: ```html ``` * Implementing the tag **without pushing** data layer variables to Contentsquare: ```html ```  5. Select **"Choose a trigger to make this tag fire..."**.  6. In the list, pick the "All pages" trigger, **provided the Datalayer will have been loaded** before firing our tag.  7. Name your tag (for instance *Contentsquare Main Tag*), then click **"Save"**.  ## Tealium 1. Add a **new tag** to your containers by choosing "Contentsquare UX Analytics"  2. Add your **"TAG ID"** and click "next" twice, keeping the default configuration. If you do not have custom variables, click **"Finish"** and the installation is over.  3. (Optional) Add custom variables: * Choose a datalayer Variable in the UDO list and select **Select Destination** * Select "Custom" * Add a variable Name * Click **Add** * Click **Close** and the mapped variable will appear   4. Click **"Apply"** or **repeat STEP 3 for additional variables**.  ## Adobe Launch ### Installing the Contentsquare extension 1. Search for Contentsquare within **Extensions** and select **Install**.  2. Enter your **Tag ID** (should be provided by your Contentsquare Implementation team).  If you want to disable the Contentsquare tag from being injected but still want to use other features, expand the **Additional Configuration** section and select the **Disable tag injection** checkbox.  If you want to have your WebView tag automatically injected when in WebView mode, expand the **Additional Configuration** section, select the **Configure WebView Tag** checkbox and insert your WebView Tag ID (provided by Contentsquare).  3. To pass information to Contentsquare via custom variables, select **Add New Variable** and fill the following fields: * The index, from 1 to 20 - unique numbers only. * The name. * The value itself, which will be taken from one of your GTM Variables. * The scope — select `Page & Visit (2 & 3)`, or `Single Page App (nextPageOnly 4)` if your website/part of it is a Single Page Application. Check with your Contentsquare contact if you're unsure. Use **Data Elements** in the value fields, as they are the Launch built-in method of passing information between extensions.  4. (Optional) Select **Add P**II** Masking**.  5. Upon activating Personal Data Masking, select the appropriate masking method, depending on the type of personal information you're looking to mask: * Masking textual Personal Data using CSS selectors:  Make sure that your CSS selectors are valid.  * If non-textual personal information needs to be masked, use the below text box and template:  6. Save your changes to your working library and move to the next step. ### Firing the Main Tag Navigate to **Rules**, and open an existing rule or create a new one. ### Event Configuration Depending on your needs, [select the event](https://docs.contentsquare.com/en/web/custom-page-events/#adobe-launch) to be used from the **Core** extension. ### Default implementation Take a look at some of the viable examples below: #### Page Bottom  #### DOM ready  ### Action Configuration Select the **Main Tracking Tag Installation action** from the Contentsquare extension  If you don't need to further amend the path or the queries sent, **you can leave the action as it** is and press 'Keep Changes'  Should you need to override the path or the query, you can do so by selecting the element and writing the string to be used as a substitute. You can also create Data Elements and use them in these fields  Once you're done, your new rule should look similar to the following  You can now press save and move on to the next rule. ## Commanders Act 1. Add a **new tag** to your containers by choosing "Contentsquare - Tag Main (builder)".  2. Add your previously provided Tag ID.  3. Add the desired Custom Variables: * At "Add customs variables" select "yes" * Fill all request variables by adding a name and pick the matching variable from the datalayer.  The Contentsquare Main Tag is ready to be deployed. ## Shopify The Contentsquare Shopify app is the recommended installation method for all Shopify stores. It ensures comprehensive coverage of your storefront (Home, Product, Collections, etc.) and offers exclusive features for Shopify Plus merchants. Follow [installation instructions](#shopify-installation) which include how to migrate from a [legacy setup](#shopify-legacy-manual-installation-deprecated). ### Available features The Contentsquare Shopify app enables the following features based on your Shopify plan: | | **Shopify non-Plus plans** | **Shopify Plus plan** | | - | - | - | | **On Storefront** | ✅ All Contentsquare capabilities | ✅ All Contentsquare capabilities | | **On Checkout** | • pageview tracking • e-commerce events | All non-Plus features + **Session Replay** + **Zoning & Heatmaps** | See the [Shopify pricing page ↗](https://www.shopify.com/pricing) for information about their plans. ### E-commerce tracking The app automatically tracks e-commerce events at every step of the checkout process. This data is essential for building accurate mappings and segmenting your audience. This works seamlessly for both single-page and multi-step checkout configurations. **Data collected:** * `orderID` — Unique transaction identifier * `amount` — Transaction total * `currency` — Transaction currency code These data points become immediately available for segmentation and filtering in your Contentsquare workspace, for Contentsquare Pro and Enterprise plans. ### Installation #### Step 0: Remove legacy integration Warning If you previously installed Contentsquare using the [custom web pixel](#shopify-legacy-manual-installation-deprecated), remove it before proceeding. Running both implementations will cause duplicate data collection. 1. Go to **Settings** > **Customer events**. 2. Find the Contentsquare pixel and select **Disconnect**. #### Step 1: Install and configure the Contentsquare Shopify app 1. Install the [Contentsquare app ↗](https://apps.shopify.com/contentsquare) from the Shopify App Store. 2. In Shopify, open the Contentsquare app and go to the **Contentsquare data collection** section. 3. In **Data privacy contact**, enter the email address of the Data Protection Officer (DPO) or the person responsible for handling privacy requests. Contentsquare uses this address to forward privacy requests received from your visitors. 4. In **Connect to your Contentsquare projects**, map each automatically detected domain to a Tag ID: * Find each Tag ID in the Contentsquare [Integration Catalog ↗](https://app.contentsquare.com/#/integrations/catalog) (search for **Shopify**). * To send all of the store's domains to the same Contentsquare project, enter the same Tag ID for every domain. * To split domains across several Contentsquare projects, enter the matching Tag ID for each domain. * The same Shopify store can send data to several Contentsquare projects, and a single Contentsquare project can receive data from several Shopify stores or domains. 5. Click **Save**. 6. In the **Verify your domain configuration** dialog, review which domains will and will not be collected. Click **Go back and fix** to add missing Tag IDs, or **Save anyway** to confirm. Unmapped domains lose checkout tracking Checkout data is not collected for domains without a Tag ID. Storefront tracking continues for those domains as long as the Contentsquare tag is enabled on the storefront (see Step 2). #### Step 2: Enable Contentsquare on storefront Already using a TMS? Skip this step if Contentsquare is already deployed via GTM or hard-coded. If GTM is also on checkout pages, exclude them from your GTM implementation to avoid duplicates. 1. Click **Add Contentsquare to storefront**. 2. In the Shopify theme editor, click **Save**. #### Step 3: Enable Contentsquare on checkout Warning [Element Masking](https://docs.contentsquare.com/en/web/personal-data-handling/#remove-contentpersonal-data-from-the-collected-html) and [Element Unmasking](https://docs.contentsquare.com/en/web/personal-data-handling/#display-content-in-a-fully-masked-html-page) are not supported on Shopify checkout pages. Only Page Masking is supported. 1. Ensure **Page Masking (Automasking)** is applied to all checkout pages: * Information * Shipping * Payment * Thank you * Order status See how to manage page masking for [Free and Growth plans ↗](https://support.contentsquare.com/hc/en-us/articles/42799500061841-How-to-manage-tracking-data-collection-data-masking-and-IP-blocking) / [Pro and Enterprise plans ↗](https://support.contentsquare.com/hc/en-us/articles/40613380970385-How-to-set-up-and-manage-Page-Masking) 2. Click **Enable data collection on checkout** to capture pageviews on checkout pages. This also enables Session Replays, Heatmaps, and Zoning for Shopify Plus plans. #### Advanced: Custom variables (Storefront) To send custom variables to Contentsquare, define them before the main tracking tag loads. Reference data from Liquid objects or tags: ```html ``` See [custom variables](https://docs.contentsquare.com/en/web/sending-custom-vars/#defining-custom-vars). #### Advanced: Dynamic variables (Storefront) Dynamic variables can be sent at any point during the pageview — they don't need to be defined before the Contentsquare tag loads. Reference data from Liquid objects or tags: ```html ``` See [dynamic variables](https://docs.contentsquare.com/en/web/sending-dynamic-vars/#defining-dynamic-vars). ### Legacy manual installation (deprecated) Deprecation notice **This deployment method is deprecated.** Contentsquare has launched a [Shopify app](#shopify) that streamlines the implementation process for all Shopify customers. **For Shopify Plus customers:** The Shopify app is required to capture user sessions during the checkout flow. Checkout session tracking is **only available** through the Contentsquare Shopify app on Shopify Plus plans. This legacy implementation method does not support checkout session capture. Deprecated configuration (click to expand) Note To configure Contentsquare tags in your Shopify account, you need to be an admin on the account. #### Base configuration 1. Within the main menu, select **Online Store > Themes**, then click the **Actions** drop-down menu, and **Edit Code**.  2. Under `Layout`, select the **theme.liquid** file. 3. Within the code editor, scroll down to the closing `` tag. 4. Copy the code below and replace `YOUR_TAG_ID` with your Contentsquare Tag ID: ```html ``` 5. Paste the code above the closing `` tag.  6. Click `Save`. #### Track the Checkout flow with Contentsquare Custom Web Pixel (Legacy) Checkout liquid deprecations Checkout Extensibility replaces `checkout.liquid`: * For Checkout pages — deadline August 13, 2024, * For Thank you and Order status pages — deadline August 28, 2025. See how to deal with these changes below. Tracking the Checkout flow is done via a custom pixel to add to your Shopify checkout. This custom pixel allows for sending a pageview and a dynamic variable to Contentsquare within each step of the checkout, for mapping and segmentation purposes, and track e-commerce transactions, all in one script. This solution works for both single page and multi-step checkout scenarios. Events collected are: * `checkout_started` * `checkout_contact_info_submitted` * `checkout_address_info_submitted` * `checkout_shipping_info_submitted` * `payment_info_submitted` * `checkout_completed` * Ecommerce data: * `orderID` * `amount` * `currency` Once collected, these events are available for segmentation and filtering:  Limitations with Shopify Checkout Extensibility * Custom variables are not part of the current pixel code tracking — you need to customize the script to send them in the checkout, * No replay or Zoning metrics are available in the Checkout, * The Contentsquare custom code in the checkout flow sends a pageview based on Shopify events. By default, it is **not subjected to user cookie consent**. Make sure to add your own cookie policy logic to the code provided below. ##### Adding the custom pixel to your checkout 1. Select `Settings` in the Shopify admin section. 2. Select `Customer events` then `Add custom pixel`. 3. Enter a name for the pixel such as `Contentsquare Checkout`. 4. Copy and paste the code below and replace `{{YOUR_TAG_ID}}` with your Contentsquare Tag ID: ```javascript /* *Name: Shopify CS Integration *Version: 2.2.1 */ const csTagID = "{{YOUR_TAG_ID}}"; const csTypeVendorPrefix = "CMS_SH_"; let submittedEvents = []; function sendToCS(csKey, csValue, csPV, eventContext) { csKey = csTypeVendorPrefix + csKey; setTimeout(function () { let setQuery; 127 collapsed lines if (csPV && eventContext) { const hash = eventContext.window.location.hash; const query = eventContext.window.location.search; setQuery = "?" + csPV; if (hash) { setQuery = hash.replace("#", "?__") + csPV; } else { if (query) { setQuery = "?__" + csPV; } } _uxa.push(["trackPageview", eventContext.window.location.pathname + setQuery]); } _uxa.push([ "trackDynamicVariable", { key: csKey, value: csValue, }, ]); }, 500); } function sendEcomCS(orderID, amount, currency) { _uxa.push([ "ec:transaction:create", { id: orderID, revenue: amount, currency: currency, }, ]); _uxa.push(["ec:transaction:send"]); } analytics.subscribe("page_viewed", (event) => { if ( event.context.window.location.pathname.indexOf("/checkouts") > -1 && event.context.window.location.pathname.indexOf("/processing") === -1 ) { if (typeof CS_CONF === "undefined") { window._uxa = window._uxa || []; _uxa.push([ "setPath", event.context.window.location.pathname + event.context.window.location.hash.replace("#", "?__"), ]); const mt = document.createElement("script"); mt.type = "text/javascript"; mt.async = true; mt.src = "//t.contentsquare.net/uxa/" + csTagID + ".js"; document.getElementsByTagName("head")[0].appendChild(mt); } else { _uxa.push([ "trackPageview", event.context.window.location.pathname + event.context.window.location.hash.replace("#", "?__"), ]); } } }); analytics.subscribe("checkout_started", (event) => { if (!submittedEvents.includes(event.name)) { submittedEvents.push(event.name); sendToCS("Checkout Started", "true", event.name, event.context); } }); analytics.subscribe("checkout_contact_info_submitted", (event) => { if (!submittedEvents.includes(event.name)) { submittedEvents.push(event.name); sendToCS("Checkout Contact Info Submitted", "true", event.name, event.context); } }); analytics.subscribe("checkout_address_info_submitted", (event) => { if (!submittedEvents.includes(event.name)) { submittedEvents.push(event.name); sendToCS("Checkout Address Info Submitted", "true", event.name, event.context); } }); analytics.subscribe("payment_info_submitted", (event) => { if (!submittedEvents.includes(event.name)) { submittedEvents.push(event.name); sendToCS("Payment Info Submitted", "true", event.name, event.context); } }); analytics.subscribe("checkout_shipping_info_submitted", (event) => { if (!submittedEvents.includes(event.name)) { submittedEvents.push(event.name); sendToCS("Checkout Shipping Info Submitted", "true", event.name, event.context); } }); analytics.subscribe("checkout_completed", (event) => { if (!submittedEvents.includes(event.name)) { submittedEvents.push(event.name); sendToCS("Checkout Completed", "true", event.name, event.context); const data = event.data || ""; const checkout = data.checkout || ""; const order = checkout.order || ""; const orderID = order.id; const totalPrice = checkout.totalPrice || ""; const amount = totalPrice.amount; const currency = totalPrice.currencyCode; if ( typeof orderID != "undefined" && typeof amount != "undefined" && typeof currency != "undefined" ) { sendEcomCS(orderID, amount, currency); } } }); ``` 5. Select **Save** then **Connect**. Note If you are injecting the CS tags in the checkout via any other means (Tag Management System, or the soon to be deprecated "additional scripts" section in the Shopify checkout setting), make sure you block the firing of the CS Main Tag and E-Commerce tag from these other means. For instance, if you have a CS E-Commerce tag in GTM, pause this tag in GTM as this new pixel you have just implemented tracks the entire checkout and the e-commerce transactions. 6. Test that pageviews are sent in the checkout. Make a transaction to test the e-commerce transaction is also sent as expected. #### Sending custom variables To send custom variables to Contentsquare, define them before the Contentsquare main tag. Modify the keys and values to your needs: you can get values from your Liquid Objects or Liquid Tags. ```html ``` For more information, see the [setCustomVariable command](sending-custom-vars/). #### Sending dynamic variables You can send dynamic variables at any point in the pageview, they do not need to be set before the Contentsquare tag is loaded. Modify the keys and values to your needs: you can get values from your Liquid Objects or Liquid Tags. ```html ``` For more information, see the [trackDynamicVariable command](sending-dynamic-vars/). ## Salesforce websites Starting with Tracking Tag version `15.201.10`, Contentsquare supports Salesforce websites: * **Lightning Web Components (LWC)** are supported out of the box. * **Salesforce Experience Cloud websites** built with Experience Builder are supported when the tag is implemented with the privileged script tag and the expected Salesforce security settings. * This scope includes both **Aura** and **Lightning Web Runtime (LWR)** templates. * No Salesforce app, plugin, or AppExchange package is required: the standard Contentsquare tracking script is all that is needed, deployed via [HTML](#custom-html) or a tag manager. For Experience Builder websites, follow these guidelines: 1. **Add Trusted URLs** In **Salesforce Setup** (gear icon > Setup), search for **Trusted URLs** and add two entries: **Contentsquare data collection** * **API name:** `Contentsquare.net` * **URL:** `https://*.contentsquare.net` * **CSP Context:** All * **Active:** Selected * **CSP Directives:** `connect-src (scripts)`, `img-src (images)`, `frame-src (iframe content)` **Contentsquare platform** * **API name:** `Contentsquare.com` * **URL:** `https://*.contentsquare.com` * **CSP Context:** All * **Active:** Selected * **CSP Directives:** `connect-src (scripts)`, `frame-src (iframe content)` 2. **Configure CSP settings** In **Experience Builder > Settings > Security & Privacy**, set **Security Level** to **Relaxed CSP: Permit Access to Inline Scripts and Allowed Hosts**. Then under **Trusted Sites for Scripts**, click **+ Add Trusted Site**, add Contentsquare (Name) and `https://t.contentsquare.net` (URL). 3. **Add the privileged script wrapper** In **Experience Builder > Settings > Advanced > Head Markup**, place the following [privileged script tag ↗](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/advanced_privileged_script.htm). This is an empty wrapper required by Salesforce LWS to expose global variables through the shadow DOM — it does not load the tracking script itself: ```html ``` * `_uxa`: Required if you use Tag commands (for example, to mask sensitive data or track artificial pageviews). * `CS_CONF`: Required if you use the [Tracking Setup Assistant extension ↗](https://chrome.google.com/webstore/detail/contentsquare-tracking-se/pfldcnnaiaiaogmpfdjjpdkpnigplfca). * `UXAnalytics`: Prevents the tracking tag from initializing more than once. 4. **Add the Contentsquare tracking tag** Add the standard Contentsquare tracking tag after the wrapper, either via your tag manager or directly in the same Head Markup field. The final Head Markup should look like this: ```html ``` ### Troubleshooting `Uncaught [object Object]` error when saving Head Markup The tracking script payload was pasted inside the `` tag. Remove the payload. Only the empty wrapper should be in Head Markup. The tracking script belongs in your tag manager or as a separate ` ``` This code creates a function which will add an asynchronous call to a script and then run the function. This is a way to avoid other elements loading being blocked on the page. This reduces the impact of the tag on the website's performance. Note **`async` vs `defer`** The previous loader sets `mt.async = true` because `defer` has no effect on scripts created dynamically via `document.createElement`. The browser ignores it, and the script loads asynchronously by default. If you are pasting a static ` ``` `defer` is only honored on parser-inserted ` ``` Position the tag before the closing `` marker within each page of your website. To have the most reliable traffic count without slowing down the display of the page, load the script as soon as the page is displayed ([`DOMContentLoaded` event ↗](https://developer.mozilla.org/en-US/docs/Web/API/Window/DOMContentLoaded_event)). Waiting for the whole page to load [`load` event ↗](https://developer.mozilla.org/en-US/docs/Web/API/Window/load_event) may impact the integrity of paths passed on and the amount of visits. Do not forget to include all subdomains and the potential pages called by iFrames. ## What it contains The tag contains: * A `CS_CONF` object gathering configuration elements of your own account, such as used domain, inclusion percentages, etc. * The latest Tag version. ## Checking the loading of the main tag Use the [Contentsquare Tracking Setup Assistant Chrome Extension ↗](https://chrome.google.com/webstore/detail/contentsquare-tracking-se/pfldcnnaiaiaogmpfdjjpdkpnigplfca) to confirm the main is loaded and that a first pageview is sent. Tag configuration and pageviews To check that the Tag configuration is appropriate, run the following script in Google Chrome's developer tools (`F12` or `⌘`+`⇧`+`C`), within the `top` JavaScript context. ```javascript if (typeof CS_CONF != "undefined") { if (CS_CONF["status"] == 1) { console.log( "%c UXA: OK on " + CS_CONF.hostnames.join(",") + (CS_CONF.allowSubdomains ? " and subdomains" : " but not on subdomains"), "color:green", ); } else { console.log("%c UXA: No, " + CS_CONF["status"], "color:red"); } } else { console.log("%c Not loaded", "color:red"); } if (document.cookie.indexOf("_cs_ex") >= 0) { console.log("%c Browser excluded by cookie.", "color:red"); } ``` A success message displayed in green should be returned. If a red message displays, check [Who is included in the analysis?](who-is-included-in-the-analysis/). ## Advanced settings ### The `_uxa` object The tag is based on a `window._uxa` object which receives instructions from the `push()` function. It is thus possible to send instructions even before the library has finished loading by initializing the `window._uxa` variable via an array. We use the fact that arrays interpret the `push()` function natively. This is why all instructions sent to the tag work the following way: ```javascript window._uxa = window._uxa || []; window._uxa.push(); ``` The first line creates an array (`[]`) if the `_uxa` variable does not already exist. The second line adds an instruction to it. If the library is already loaded, the instruction will be run immediately. If it has not loaded yet, the instruction will be run when the library has loaded. In both cases, this guarantees that the execution order of the commands will not generate an error. ### CORS Request You can call the main tag with CORS requests (Cross-origin resource sharing, [more on this here ↗](https://developer.mozilla.org/en/docs/Web/API/GlobalEventHandlers/onerror#Notes)). You just need to add `crossorigin="anonymous"` to the ` ``` This code creates a function which will add an asynchronous call to a script and then run the function. This is a way to avoid other elements loading being blocked on the page. This reduces the impact of the tag on your website's performance. ### Google Tag Manager (Custom HTML) If your page loads in both a web and WebView environment, you should use a variable to determine whether the page is running in a WebView context before integrating the tracking tag. The Contentsquare Android and iOS SDK injects a `window.CS_isWebView` variable into the WebView to simplify the integration. 1. Add a new tag on your workspace.  2. Select "Choose a tag type to begin setup…".  3. In the list, pick the "Custom HTML" tag.  4. Copy and paste the following code in the Tag Configuration HTML section: ```html ```  5. Select "Choose a trigger to make this tag fire…" and pick "All Pages" from the list.  Warning `window.CS_isWebView` is available since Contentsquare's iOS SDK 4.36.0, Android SDK 4.32.0, React Native Bridge 3.9.0 or Flutter Plugin 4.13.0. If you have a custom way of checking if the page is loaded in a WebView, replace `window.CS_isWebView` with your solution. ## Validate WebView tracking To verify WebView tracking, refer to the documentation available for [iOS](https://docs.contentsquare.com/en/ios/track-webviews/#validate-webview-tracking) and [Android](https://docs.contentsquare.com/en/android/track-webviews/#validating-the-implementation-on-the-web-side). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"WebView Tracking","description":"Enable WebView tracking in your mobile app by adding the Contentsquare Web Tracking Tag on web pages called by your mobile app","url":"https://docs.contentsquare.com/en/webview-tracking-tag/","inLanguage":"en","dateModified":"2026-07-29T20:54:18+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Changelog - Android (classic) description: The Contentsquare Android SDK changelog lastUpdated: 10 August 2026 source_url: html: https://docs.contentsquare.com/en/android/changelog/ md: https://docs.contentsquare.com/en/android/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). 📬 Stay updated! ## 4.52.1 - 2026.08.06 **Analytics** * Extended `doNotTrack` API for single Views only * **Bug fix:** Added missing support for custom views inheriting from WebView **WebViews** * **Bug fix:** fixing duplicate taps for WebView child classes **Session Replay** * Improved Image capture for Coil libraries on Jetpack Compose * Improved capture synchronization to capture screen transitions * **Bug fix:** resolved a few memory leaks when a dialog is captured **Core** * **Bug fix:** no more install and upgrade event fired on every app relaunch * **Bug fix:** resolved a ANR issue when migrating from CS SDK before 4.50.0 * **Bug fix:** resolved a crash when migrating from CS SDK before 4.50.0 * **Bug fix:** resolved a few memory leaks ## 4.52.0 - 2026.07.27 **Analytics** * Added support for Android multi-window mode and activity resizing * Added support for screenshots when using PA autocapture screenviews only * **Bug fix:** Fixed background issue for WebViews embedded in Jetpack Compose **Session Replay** * Improved Image capture for Jetpack Compose * **Bug fix:** Fixed an issue detecting Jetpack Compose bottom sheet position * **Bug fix:** Prevent potential Personal Data leaks on some scrollable containers on Jetpack Compose **WebViews** * **Bug fix:** fixed a synchronisation issue that could result in a "Webview Not Tracked" in the Session Replay Player * **Bug fix:** fixed an issue where coming back from background into a webview would result in a "Webview Not Tracked" in the Session Replay Player ## 4.51.2 - 2026.07.03 **Analytics** * **Bug fix:** Ensured gesture listener attachment is executed on the main thread to prevent potential crashes on some screens. **Session Replay** * Optimized Session Replay to degrade the capture rate to 1 FPS instead of stopping completely when main thread performance impact is detected. * **Bug fix:** Fixed an issue where Session Replay could fail to start when used with Autocapture. **WebViews** * **Bug fix:** Aligned native Android behavior to respect the server-side kill-switch for disabling tag injection in WebViews. * **Bug fix:** Fixed a crash that could occur when registering or unregistering WebViews before the SDK is fully initialized. **Error Analysis** * Update Error Analysis Crash Plugin to 1.9.1 fixing an issue where the mapping id resource was silently dropped from the merged resources on Android Gradle Plugin ≤ 8.11, causing crashes to be sent without their mapping id and preventing backend deobfuscation. ## 4.51.1 - 2026.06.29 **Core** * **Bug fix:** Fixed an issue where the configured sampling rate could be ignored in some rare cases ## 4.51.0 - 2026.06.05 **Core** * **Security** Resolved a security vulnerability where the SDK deeplink feature could be exploited via crafted deeplinks to arbitrarily modify SDK configuration. * **Bug fix:** Fixed persisting PA-DXA session synchronization issues where session counts and screen quantities diverged between DXA and PA collection. **Analytics** * **Bug fix:** Fixed an issue where screenshot can not be generated when tracking is paused. **Session Replay** * Session Replay can now resume collection within the same session after a performance-based stop, restarting at LOW quality and re-evaluating start/stop rules. * Compose capture robustness work, foundation for better SR capture in Compose-heavy apps tied to harmonized masking. * Removed obsolete MultiWindow Feature Flag as the newer image processor rollout progresses. * **Bug fix:** Fixed an issue where button text disappeared in the live app but was correctly captured in the Session Replay. * **Bug fix:** Fixed missing images in Session Replay for Compose apps when harmonized masking is enabled . * **Bug fix:** Addressing Session Replay rendering issues where certain screens display only wide empty elements instead of actual content. **Error Analysis** * Update Error Analysis Crash Plugin to 1.9.0 to add Android Gradle Plugin 9 compatibility * Update Error Analysis Network Plugin to 1.8.0 to add Android Gradle Plugin 9 compatibility ## 4.50.0 - 2026.05.04 **Core** * **Breaking change:** `Contentsquare.optIn(context)` deprecated API has been removed, use `Contentsquare.optIn()` * **Breaking change:** `Contentsquare.optOut(context)` deprecated API has been removed, use `Contentsquare.optOut()` * **Breaking change:** `Contentsquare.getUserId()` API now returns `null` instead of `"UNKNOWN"` string when the SDK has not been started or is under initialization **Analytics** * The Session timeout definition changes from **30 minutes after being in background** to **30 minutes after last event**. See [Session definition](https://docs.contentsquare.com/en/android/how-the-sdk-works/#session-definition). This change may impact reported session counts in the Contentsquare platform. The underlying data collection remains unchanged; only the session-splitting logic is affected. * Heatmaps: Improved tap data accuracy for screens with multiple scroll containers **Session Replay** * Add new API to stop Session Replay on demand * Improve masking of digits in strings ## 4.44.2 - 2026.06.25 **Analytics** * **Bug fix:** Prevent crash in `ViewTreeObserver.dispatchOnPreDraw()` ## 4.44.1 - 2026.03.03 **Analytics** * **Bug fix:** Improved invisible overlay detection to resolve an issue where long screenshots were not scrollable * **Bug fix:** Fixed duplicate tap event in tracked WebViews ## 4.44.0 - 2026.02.17 **Session Replay** * Improve UI change detection to prevent unplayable screens * **Bug fix:** improve synchronisation of session between Heap and Contentsquare * **Bug fix:** resolved an internal `java.util.ConcurrentModificationException` * **Bug fix:** resolved an internal `java.lang.NullPointerException` * **Bug fix:** improve masking stability **Errors** * Now setUrlMaskingPatterns can be called before the SDK start * OkHttp 5 compatibility with Network Plugin 1.7.0 * Sanity checked added to URL masking patterns resolving a `java.util.regex.PatternSyntaxException` * **Bug fix:** validate URL patterns when setUrlMaskingPatterns is called ## 4.43.8 - 2026.01.05 **Errors** * Fixed API Error URL not masked until SDK is fully initialized ## 4.43.7 - 2026.01.02 **Session Replay** * **Bug fix:** resolved a masking issues when multi-window is enabled ## 4.43.6 - 2025.12.26 **Core** * **Bug fix:** resolves crash in WindowCallbackWrapper ## 4.43.5 - 2025.12.19 **Analytics** * Add support of material `ModalBottomSheetLayout` for Zoning and Heatmap analysis, using the `CsqTag()` API **Core** * Improve compatibility with DexGuard ## 4.43.4 - 2025.12.16 **Session Replay** * **Bug fix:** Improve memory management to avoid memory leak * **Bug fix:** Prevent crash during activity destroy process **Analytics** * **Bug fix:** Fixed an issue where heatmap positions were not tracked correctly on some Compose screens with lazy scroll elements. * **Bug fix:** Improved invisible overlay detection to resolve an issue where long screenshots were not scrollable. **Core** * Migrated from Android `ContentProvider` to AndroidX Startup for initialization * **Bug fix:** Resolved `java.lang.NullPointerException` crash on `FileProvider` ## 4.43.3 - 2025.11.28 **Zoning Analytics** * Modifier.excludeFromGestureRecognition() now excludes the marked Composable from the screenshot ## 4.43.2 - 2025.11.24 **Session Replay** * **Bug fix:** Resolved `java.util.ConcurrentModificationException` crash on Session Replay touch listener. **Analytics** * **Bug fix:** Resolved `java.lang.ArrayIndexOutOfBoundsException` crash with Exposure Metrics. **Core** * Improved SDK initialization performance by moving certain operations off the main thread ## 4.43.1 - 2025.11.14 **Core** * Improved communication for cross-platform technologies ## 4.43.0 - 2025.11.13 **Core** * Removed the `forgetMe` API. **Analytics** * Fixed an issue where screenshot button was not visible after visiting In-app settings. * Fixed compatibility issues with Jetpack Compose 1.10. **Session Replay** * Improved gesture detection to reliably identify the targeted view. ## 4.42.0 - 2025.10.16 **Core** * Various technical improvements and optimizations. **Session Replay** * Introduction of Harmonised Masking in Closed Beta Phase ## 4.41.1 - 2025.10.07 **Analytics** * Fixed a crash when Jetpack Compose Node is not attached **Session Replay** * Fixed a bug that cause parent masking not being propagated to child views on some scenarios * Improve capture of Native views inside Jetpack Compose ## 4.41.0 - 2025.09.05 Warning `forgetMe` API has been deprecated more than one year and will be removed soon in a future release. See the [Privacy section](https://docs.contentsquare.com/en/android/privacy/#forget-me) for more details. **Analytics** * Fixed an issue when the very first item of a RecyclerView is bigger than the scrollable area **Core** * Fixed an issue regarding Activity Context not fully initialized ## 4.40.1 - 2025.08.12 **Core** * Resolved an issue with pro-guard and Session Replay on demand ## 4.40.0 - 2025.08.01 **Session Replay** * Image and Text masking configuration in the CSQ Console * Added new APIs to start Session Replay on demand * Added new APIs to support Event-Triggered Replays **Analytics** * **Bug fix:** Fixed a potential crash when generating scroll metrics on certain Compose screens * Improve heatmap data accuracy for Compose lazy lists and grids ## 4.39.4 - 2025.07.22 * Removes React Native `CSMask` views custom logic. ## 4.39.3 - 2025.07.01 **Session Replay** * **Bug fix:** Fix blank screens in Jetpack Compose when the dialogs and bottom sheets capture was enabled. * **Bug fix:** Fixed an issue causing an inconsistent tag injection for Webviews in Capacitor apps. * **Bug fix:** Fixed an issue causing unreliable Session Replay starts in Capacitor apps. * Improved Session Replay screen change consistency on Capacitor apps ## 4.39.2 - 2025.06.26 **Core** * **Bug fix:** Resolved a crash in an internal class caused from invocation on a background thread. ## 4.39.1 - 2025.06.18 * **Bug fix:** Fixed an issue causing compatibility problems between Flutter apps and multi-window support in Session Replay ## 4.39.0 - 2025.06.10 **Survey** * Introducing [Surveys](../surveys/) (Beta). You can now integrate surveys into your apps using the designated trigger and collect feedback from end users. **Analytics** * Improved screenshots of Jetpack Compose screens with scroll items with space in between * Improved detection of transparent overlays for Android Views * **Bug fix:** stop and resume tracking were not working properly when in-app features are enabled * **Bug fix:** fixed memory leak in Exposure Metrics * **Bug fix:** unable to take a screenshot of the lower part of the screen **Session Replay** * Added support for capturing bottom sheets, dialogs, and menus ## 4.38.2 - 2025.05.16 * Added support for new React Native masking custom components. ## 4.38.1 - 2025.04.30 **WebViews** * **Bug fix:** Fixed missing local assets ## 4.38.0 - 2025.04.25 **Session Replay** * **Bug fix:** Prevent data loss if there is an unexpected processing error **Error Analysis** * **Bug fix:** Do not encrypt empty query parameters ## 4.37.0 - 2025.04.02 **Analytics** * Public API methods returning values will return default value during SDK initialization. You can use `Contentsquare.wasInitialized()` to be sure that the SDK is initialized, impacted methods: * `Contentsquare.getUserId()` * `Contentsquare.getProjectId()` * `Contentsquare.getSessionNumber()` **Session Replay** * **Bug fix:** Improve animation detection logic. **WebViews** * **Bug fix:** Fixed a crash in React Native where Android Webview API could return null, before Android API 29. **Core** * **Bug fix:** Resolved `java.lang.VerifyError` crash that occurred in debug mode when customer app had `EnableAndroidTestCoverage = true`, caused by JaCoCo instrumentation in an internal SDK class. ## 4.36.3 - 2025.03.26 **Core** * **Bug fix:** Fixed an issue where webviews could malfunction if no parent activity was present. ## 4.36.2 - 2025.03.21 **Core** * **Bug fix:** Resolved a bug that cause `optIn`/`optOut` being ignored if the SDK was not yet started. ## 4.36.1 - 2025.03.13 **Core** * **Bug fix:** Resolved `java.lang.VerifyError` crash caused by JaCoCo plugin in an internal SDK class. * **Bug fix:** Resolved a bug where a network callback is registered too many times and pass the limit of 100 callbacks while using `CsWebViewClient` API. **Session Replay** * **Bug fix:** Resolved a bug where API changed in Android 15 crash with `java.lang.NoSuchMethodError` from `java.util.List`. ## 4.36.0 - 2025.02.10 **Analytics** * Add `Contentsquare.doNotTrack(View)` API * Added support for empty, transparent overlays in Jetpack Compose, both for the screenshot and the events * **Bug fix:** Exposure Metrics scroll value was incorrect for RecyclerViews **Error Analysis** * API Errors Improvement - avoid encrypting empty data **Session Replay** * Full masking configuration by App/SDK version in the CSQ Console **Core** * Support network connection type 5G * **Bug fix:** Resolved `java.util.ConcurrentModificationException` crash in an internal SDK class. ## 4.35.0 - 2025.01.02 **Error Analysis** * Update Error Analysis Crash Plugin to 1.7.0 to improve compatibility with Gradle Configuration Cache * Update Error Analysis Network Plugin to 1.6.0 to improve compatibility with competitors and with Gradle Configuration Cache **Analytics** * Long Screenshot: Added support for `LazyVerticalGrid` * Session number will be incremented when app or SDK version number changed * **Bug fix:** Long Screenshot, fixed crash with empty `LazyColumn` items * **Bug fix:** Only configuration calls will be queued before the initialization of the SDK is started, for example SR masking, exclusion of Activities from tracking, exclusion from Exposure Metrics * **Bug fix:** Clickable Compose elements will be preferred during gesture detection * **Bug fix:** URL of the End of Screen Event was incorrect * **Bug fix:** Stored events on disk will be sent with correct user ID after user expired **Session Replay** * To prevent Personal Data leaks, masked views are systematically blurred without considering their vertical position in the view hierarchy or any transparent view covering them. * `resumeTracking` now waits for the next screenview before resuming Session Replay * Session Replay is stopped when [ComponentCallbacks.onLowMemory ↗](https://developer.android.com/reference/android/content/ComponentCallbacks#onLowMemory\(\)) or [ComponentCallbacks2.onTrimMemory ↗](https://developer.android.com/reference/android/content/ComponentCallbacks2#onTrimMemory\(int\)) happens **Core** * **Bug fix:** Fix `UnknownFormatConversionException` crash occurring in the internal `logger` ## 4.34.1 - 2024.12.13 **Analytics** * **Bug fix:** Fix `NullPointerException` while accessing a `WeakReference`. ## 4.34.0 - 2024.10.25 **Analytics** * Fixed unstable event URLs for Compose screens * Handle obfuscated `View` classes in Target View Paths * Exclusion of scrollable views from Exposure Metrics * Prevent opening of CS In-App features if the SDK is not started * Improved synchronisation between Analytics and Session Replay ## 4.33.2 - 2024.10.18 **Core** * **Bug fix:** Fix an issue where SDK tracking would incorrectly re-enable after calling the stop tracking API when the app resumed from the background. **Session Replay** * **Bug fix:** Fixed missing views when Animation detection is used with Compose Material 3 library - Beta ## 4.33.1 - 2024.10.07 **Core** * **Bug fix:** Update WebViewClient usage for WebViewBridge ## 4.33.0 - 2024.10.02 **Core** * **Bug fix:** In-app button now shown when SDK started manually from an Activity * **Bug fix:** Incorrect display of crashes in Log Viz * Add new API to read the current Project ID * Add new API to read the current session number **Analytics** * Long Screenshot: Add support for huge number of items for lazy Compose lists ## 4.32.1 - 2024.09.10 **Core** * **Bug fix:** `minVersion` check for feature flags. ## 4.32.0 - 2024.09.02 **Core** * Reduced library dependencies: com.google.android.material * **Bug fix:** Fixed crash in Telemetry **Analytics** * Long Screenshot: Added support for list items bigger than the screen * Compose: New API for excluding composables from gesture detection * **Bug fix:** Fixed TriggeredOnResume was called too often **Session Replay** * Animation detection to prevent Personal Data leaks - Beta * Session Replay can now be blocked for certain application versions based on a pattern or range. **Error Analysis** * Collect Telemetry performance metrics for API v2 * **Bug fix:** Fixed duplicate API Error logs **WebViews** * Automatically injects the global variable `window.CS_isWebView` in your pages to help you detect if they are loaded from a WebView. ## 4.31.0 - 2024.08.02 **Analytics** * Long Screenshot feature is now in General Availability for Android Views screens * **Bug fix:** Fix two long screenshot display issues when using a RecyclerView * **Bug fix:** Fix memory leak **Error Analysis** * OkHttpInterceptor can now be used with API Error v2 * API Error v2: Increase body attribute size limit from 50 to 100 characters **Session Replay** * Support of dynamic masking for Flutter in CS in-app * Support of dynamic masking for WebViews in CS in-app **WebViews** * Added Automatic Tag Injection to track locally hosted pages. ## 4.30.0 - 2024.07.01 **Analytics** * Long Screenshot is applied to the last scrollable view receiving user interaction * **Bug fix:** Fix a bug where screen names with special characters would cause a crash of the SDK * **Bug fix:** Long screenshot now captures correctly RecyclerView items * **Bug fix:** Fix erroneous Zoning for screens with mixed Compose views and Android views ## 4.29.1 - 2024.06.11 **Error Analysis** * **Bug fix:** API Error reporting can now work with event streams ## 4.29.0 - 2024.05.29 **Analytics** * Long screenshot properly captures webviews on Compose screens * Long screenshot capture can be paused on Compose screens * Fix erroneous userID after calling optOut/optIn **Error Analysis** * Update Error Analysis Crash Plugin to 1.5.0 to support mapping file auto upload ## 4.28.0 - 2024.04.19 **Core** * **ForgetMe:** This API is now deprecated. See the [Privacy section](https://docs.contentsquare.com/en/android/privacy/#forget-me) for more details. * API calls made before SDK initialization will be queued until SDK start **Analytics** * Implement capture Screenshot / Long Screenshot on Compose screens * Code refactor to improve robustness and quality * Fix an issue in Zoning where some elements cannot be zones * Fix incorrect screen names in Log Viz **Session Replay** * Improve Session Replay link API on logs **Error Analysis** * Update API Error data collection * Increase response body size limit to 5kb ## 4.27.1 - 2024.03.29 **Analytics** * Fix an issue in Zoning that could impact some screens built with Compose ## 4.27.0 - 2024.03.27 **Session Replay** * Display gesture events in Session Replay event stream * Fixed a StackOverflowError crash caused by a concurrency issue **Analytics** * Improve the Long Screenshot capture, adding the support of more UI components ## 4.26.0 - 2024.02.20 **Session Replay** * Add new callback API for updates on replay link * Deprecate existing API to get replay link **Analytics** * Downgraded dependencies, so that consumers of the `library` artifact can stick with `compileSdk` 33 (`compose` requires `compileSdk` 34) * Compose beta: Added support for Jetpack Compose 1.6.0 * Fixed a crash for WebViews when `optIn` or `optOut` was not called from main thread ## 4.25.0 - 2024.01.29 **Session Replay** * Change Session Replay start behavior (starting processor only once after first screen view event) * Fixed a crash on Protobuf messages serialization **Analytics** * Fixed performance issue caused by SDK initialization on app start-up * Add capability to Zoning when capturing Long Screenshot of vertically scrollable Compose content * Re-enable regular screenshot for Compose * Fixed a crash: Port out of range **Error Analysis** * Remove Apache HTTP Client support * Remove Error Analysis Maven artifact; It's now embedded in the Main Android SDK artifact Warning Starting from version 4.25.0, there is no dedicated Error Analysis artifact: it's now embedded in the main SDK. Remove the now legacy error analysis module from your build file to avoid the following error: ```plaintext > Task :app:checkDebugDuplicateClasses FAILED FAILURE: Build failed with an exception. * What went wrong: Execution failed for task ':app:checkDebugDuplicateClasses'. > A failure occurred while executing com.android.build.gradle.internal.tasks.CheckDuplicatesRunnable > Duplicate class com.contentsquare.android.ErrorAnalysisModule found... ``` ## 4.24.1 - 2024.01.16 **Session Replay** * Fixed an out-of-sync issue with Flutter, occurring in the first screen view and resulting in a blank screen. * Introduction of Flutter notification for CSInApp states ## 4.24.0 - 2023.12.15 **Analytics** * Exposure metrics feature is now part of the SDK (Beta phase). It will help you measure engagement directly in zoning by showing which zones are attracting clicks, or on the contrary being ignored. * Fixed a crash when calling `Contentsquare.sendUserIdentifier()` * Fixed a crash when app is put in background * Internal package reorganization **Session Replay** * Fixed an issue where images might be stretched in the replay * Fixed a delay that might happen when screen change * Code refactor to improve robustness and quality **Error Analysis** * Internal package reorganization * Added a log when API Error collection is enabled through Error Analysis module ## 4.23.1 - 2023.11.24 **Session Replay** * Fixed a bug on Composable masking where `sessionReplayMask()` was not propagated to child nodes **Error Analysis Android SDK** * Fix a crash due to instrumented bytecode ## 4.23.0 - 2023.11.20 **Analytics** * Support Jetpack Compose for Zoning - beta * Local + Auth Assets Support **Session Replay** * WebView support. See [Session Replay WebView documentation](https://docs.contentsquare.com/en/android/session-replay/#configure-webviews) * Fix an issue on individual masking for Jetpack Compose, when Compose screen contains embedded Android views **Misc** * Fixed performance issue caused by SDK initialization on app start-up ## 4.22.0 - 2023.10.18 **Analytics** * Long Screenshot - beta **Error Analysis Android SDK** * WebView errors: Collect JS, API, and custom errors occurring in WebViews. More info on [WebView errors](https://docs.contentsquare.com/en/webview-tracking-tag/error-analysis/) **Track WebView** * Introducing new WebView tracking relying on [Web Tracking Tag](https://docs.contentsquare.com/en/webview-tracking-tag/). ## 4.21.0 - 2023.08.29 **Analytics** * Support of custom variables ## 4.20.0 - 2023.07.13 **Session Replay** * Support Jetpack Compose technology **Error Analysis** * Handle error source for cross-platform compatibility ## 4.19.0 - 2023.06.14 **Session Replay** * Fixed an issue where the set default masking API is not working when the API is called before SDK initialization. * Add a new API 'sendUserIdentifier' to search a replay based on a personal user identifier [See the Session Replay Send user identifier section](https://docs.contentsquare.com/en/android/session-replay/#send-user-identifier). **Error Analysis** * Fixed an issue where crash controller remove existing crash handler when start and stop lifecycle are out of order. * Fixed a bug where send network error event is called twice. **Misc** * Improved SDK initialization lifecycle logic. * Added a feature flag for user identifier collection. ## 4.18.2 - 2023.05.30 **Error Analysis** * Fixed a bug that was preventing the Error Analysis module from starting. * Fixed a potential crash in using instrumented HttpURLConnection for API Error collection. ## 4.18.1 - 2023.05.16 **Bug fix** * Fix a bug where the Contentsquare SDK would cause a crash on Dual-SIM devices using Android API 33. ## 4.18.0 - 2023.05.10 **Error Analysis** * Extended crash report to include stack traces and system threads. * Improved stability in API Error Handling. ## 4.17.0 - 2023.04.07 **Error Analysis** * Collect basic crashes and send them to both Session Replay and Analytics * API Error details are gzipped and subject to a maximum size * Deprecated internal trace extension function, in favor of new public version ## 4.16.0 - 2023.03.06 Warning Session Replay Technical Limitation: views with an alpha channel will be displayed as white rectangles in the replay. This issue will be fixed in the next SDK version. **Session Replay** * Improved masking logic, the transparent view will be masked by default. * Improved Session Replay data batch generation. * Fixed screen number discrepancy issue between Session Replay and Analytics event. * Fixed an issue where the set default masking API is not working properly. * Fixed a bug where sometimes Session Replay continues to collect with 0% collection rate. **Error Analysis** * Collect API error details. * Add a log to warn if an event has been captured before 1st screen view. * Change error-analysis implementation for library to API. * Add a public method to mask API error by template URL. * Rename public API `CsErrorAnalysis` to `ErrorAnalysis`. * Update Error Analysis network plugin 1.1.0. Warning Error Analysis Android SDK 4.16.0 is incompatible with Error Analysis plugin 1.0.0 and lower version. ## 4.15.0 - 2022.12.20 **Session Replay** New events added when the application enters background or foreground modes **Error Analysis** * Collect failed network requests **Misc** * Remove the need for manually editing your config file with ProGuard/R8 rules ## 4.14.0 - 2022.11.03 **Log Visualizer** * Log Visualizer is enabled by default with in-app features **Session Replay** * Added the Start event * Catch hardware bitmap crash and display error message * Fixed bug when using static screenshot with 0 width/height SurfaceView * Fixed bug with Dynamic Variable with wrong App versions **Misc** * Display public log when request has failed * Client logs for WebViews ## 4.13.1 - 2022.09.19 **Bug fix** * Fixed an issue introduced in 4.13.0 where Contentsquare SDK makes the app crash when the automatic SDK initialization is disabled ## 4.13.0 - 2022.09.19 Warning This version has a bug where Contentsquare SDK makes the app crash when the automatic SDK initialization is disabled. Use version 4.13.1 or later. **Analytics** * Display screen name on the "screenshot in progress/success/fail" screens **Dynamic Variables** * Key length increased from 50 to 512 chars **Session Replay** * Display information if the quality used have changed (Network switch, configuration changed...) * Fixed an issue where the SDK starts if the app is auto-started in background after a reboot * Fixed an issue where after opted out and opted in again, we have a log with an `UNKNOWN` user id * Fixed a crash after opted out and opted in again * Fixed a crash after opted in without activity ## 4.12.0 - 2022.08.10 **Session Replay** * Fixed an issue where the Session Replay feature is not working properly when using stop and resume tracking API. * Added a mechanism to flush the replay data of the current session when the app is put in the background. **In-app features** * Fixed a bug where in-app settings screen and button disappears after enabling share replay link. **SDK Log Visualizer** * Removed the need of the Log Visualizer enabled feature flag from SDK configuration. **Bug fix** * Fixed an issue where gesture tracking is not working correctly after opt-out and opt-in. * Fixed an issue where screen view is lost if executed immediately after opt-in. * Fixed a crash issue related to SharedPreferences concurrent modification. **Misc** * Minor internal code improvement leading to SDK size decreased and fewer methods count. ## 4.11.0 - 2022.07.07 * **Dagger:** Dagger dependency has been removed from the SDK. * **Included in tracking:** When the in-app features are enabled, the device is now always included in tracking. **Session Replay** * Fixed an issue where Session Replay would not start after an app restart. * Improved the quality adjustment mechanism triggered by impact on the main thread: Session Replay can stop completely now. Quality level will now get back to its initial value once there is no more impact detected. * Decrease in data consumption thanks to image identification algorithm improvement (less duplicates). * **Screenshot:** Display error message when capturing screenshot before screenview. * **Bug fix**: Fixed an issue where CS in-app features menu caused a crash while using the opt-out and opt-in operations * **Misc:** Minor improvements and bug fixes. ## 4.10.0 - 2022.06.03 * **Contentsquare visual identity:** Updated Contentsquare logo and screenshot button to match the new visual identity. **Session Replay** Fixed a bug for which some views captured were not rendered while replaying a user session. * **WebViews tracking:** Update of the WebViews injection mechanism to support new events sent by the WebView Tracking Tag (Dynamic variable, Transaction, Opt-in, Opt-out) [See the WebView Tracking Tag documentation](https://docs.contentsquare.com/en/webview-tracking-tag/). * **Misc:** Minor improvements and bug fixes. ## 4.9.0 - 2022.04.15 **Session Replay** Add feature to select different quality levels for Wi-Fi and Cellular [See the Session Replay Quality Levels section](https://docs.contentsquare.com/en/android/session-replay/#quality-levels) **Session Replay** Fixed a bug on unMask API; fixed rendering bugs; * **In-app features:** Fixed a bug where screenshot button does not disappear when app is put in background. * **Misc:** Minor improvements and bug fixes. ## 4.8.0 - 2022.03.18 **Session Replay** Added logs when starting and stopping; * **Screenshots:** Multiple bug fixes on screenshot button and capture. * **Misc:** Minor improvements and bug fixes. ## 4.7.0 - 2022.01.14 **Session Replay** Optimization of quality and data consumption. * **Remove Jetifier:** Agera dependency has been removed, which was using Android Support Library. Jetifier is not required anymore. * **Misc:** Minor improvements and bug fixes. ## 4.6.0 - 2021.12.15 **Session Replay** new Replay link API to integrate with third-party tools (VoC, crash reporting); Session Replay can be accessed directly within minutes with direct link; replay link button added to in-app features settings; hardware bitmaps are now supported; data consumption optimization; fixed regression on masking API. * **Misc:** Minor improvements and bug fixes. ## 4.5.0 - 2021.11.18 **Session Replay** Misc improvements. * **SDK Log Visualizer:** This new module lets you see the live stream of events detected by our SDK (logs) directly in Contentsquare. Check out the [Viewing logs in the Contentsquare platform section](https://docs.contentsquare.com/en/android/in-app-features/#viewing-logs-in-the-contentsquare-platform). * **Misc:** Minor improvements and bug fixes. ## 4.4.0 - 2021.10.18 * **Drop support for Android Jelly Bean (API Levels 16, 17, and 18):** As Google Play services is discontinuing updates for Jelly Bean (API levels 16, 17, and 18), the minimum supported version is now **Android 4.4 KitKat (API level 19)**. **Session Replay** WebViews masked by default; performance and quality optimizations; * **Disable Session Replay for specific app versions:** Introducing capability to disable Session Replay for specific app versions (controlled from back office). * **Logs:** Reduced noise to keep only relevant logs. You can just filter on `CSLIB` * **Permission:** Removed overlay permission request for Android <=5.1 * **Misc:** Minor improvements and bug fixes. ## 4.3.0 - 2021.08.10 * **Disable auto-start:** Option to start the SDK in a manual method instead of starting automatically. Check out the [Disabling Automatic SDK Initialization section](https://docs.contentsquare.com/en/android/disable-autostart/) ## 4.2.1 - 2021.07.07 * Fixed an issue introduced in 4.2.0 that affected gestures tracking on the first activity after app start ## 4.2.0 - 2021.06.14 **Session Replay** Session Replay feature is now part of the SDK and disabled by default. This feature is only accessible to customers participating in the Early Access program. For more information reach out to your Contentsquare contact. * **Gestures:** Fixed issue that caused gestures to be attached to the wrong view in some cases. * **Misc:** Minor improvements and bug fixes. ## 4.1.0 - 2021.02.16 * **WebView:** WebView tracking back-office setting has been removed. WebView tracking is now always enabled. * **SDK start:** At SDK start, a unique config file per package name is fetched on our server: * Fixed an issue that prevented to display a log informing when no config file is created for the package name * Changed the config retrieval logic to respect package name case-sensitivity (we used to lower case package name) * **Dagger dependency**: Updated from 2.25 to 2.31.2 * **Misc:** Minor improvements and bug fixes. ## 4.0.0 - 2020.10.29 * **In-app features activation:** A simpler and unified way to enable features living inside the SDK (Screenshot Capture and Logs) along with its tracking capabilities. [Enable in-app features section](https://docs.contentsquare.com/en/android/in-app-features/#enable-in-app-features) * **Screenshot**: Introducing static screenshot to workaround edge cases where screenshots are not rendered properly. See [Static screenshot section](https://docs.contentsquare.com/en/android/in-app-features/#screenshot-capture) * **Webview:** Minor improvement to enable webview zoning analysis **Upgrading from a previous version**: Update the dependency to point to `com.contentsquare.android:library:4.0.0` and make sure to remove the code snippet from your AndroidManifest.xml that was used to enable screenshot mode. ## 3.2.0 - 2020.07.30 * **Drop support for Android 4.0.3 (API Level 15).** Minimum supported version is now Android 4.1 (API level 16). * **Screenshots:** Improved support for screen with SwipeRefreshLayout * **Dynamic Variables:** Key and value are now trimmed when maximum length is exceeded. If key or value are empty, the SDK now sends the literal string "cs-empty" instead. * **Transaction currency:** Lower and Uppercase are both supported. * **Session:** Fixed a bug preventing a session to be closed when app was killed. This led to following session to be discarded. * Minor improvements and bug fixes. ## 3.1.0 - 2020.04.15 * **New logs:** This version brings completely redesigned logs for better understanding of the SDK behavior. See dedicated section [Debugging and logging](https://docs.contentsquare.com/en/android/in-app-features/#debugging-and-logging). * Enable Logging via ADB SHELL on all Android versions * Minor improvement related to screenview tracking on React Native apps * Minor improvements and bug fixes ## 3.0.0 - 2020.03.20 * **Breaking change:** the main class `ContentSquare` is renamed `Contentsquare` (lower-case `s`). * **Screenshot mode**: Now you can display the **Screenshot Activation Dialog** using a deep link. * **Track Transactions - Currency:** We now provide the ability to pass the currency as an "alphanumeric code" (example: "USD") on top of the "numeric code" (example: "840"). See the dedicated section [Track transactions](https://docs.contentsquare.com/en/android/track-transactions/). * Fixed an issue where SDK version was not properly set * Minor improvements and bug fixes ## 2.3.1 - 2020.03.03 * Gesture tracking: Fix an issue with Android Toolbar ## 2.3.0 - 2020.01.27 * Enable Logging via ADB SHELL (Logging support for Android 10) * App hide event is now triggered 700ms after the application is put in background (before it was 5 seconds) * Screenshot improvements for webViews * Add validation for dynamic variables key and value length * Remove the rule that prevents to have 2 consecutive screenview events with the same screen name * Renamed the Pause tracking API to Stop tracking API * Minor improvements and bug fixes ## 2.2.1 - 2019.11.19 * Fixing theme issue conflict on Screenshot Mode ## 2.2 - 2019.10.02 **/!\ *This version is the first one not supporting Android Support (AndroidX only). If you are still using Android Support, use version 2.1.3.*** * **Dynamic Variables:** Send custom data to Contentsquare for session segmentation. [Dynamic Variables API](https://docs.contentsquare.com/en/android/track-dynamic-variables/) * **Screenshot mode launched at App start:** No need to shake the device to trigger Screenshot Mode dialog. Benefits: works on a simulator and avoids conflict with features based on shake detection. * **RecyclingViews tracking:** We improve the gestures tracking accuracy for those elements. * Minor improvements and bug fixes ## 2.1.3 - 2019.09.30 **/!\ *This version is the last version supporting Android Support. Upcoming versions will only support AndroidX.*** * **Track screens**: Implement the new [Track Screen API](https://docs.contentsquare.com/en/android/track-screens/) to accurately track `screen_view` events for all your app screens. * **User Consent required by default**: The default privacy setting for every new app will be set to opted-out by default. This means every new user will be opted-out until the [Opt-in API](https://docs.contentsquare.com/en/android/privacy/#opt-in) will be called. [See dedicated documentation section](https://docs.contentsquare.com/en/android/privacy/). * Workaround on an issue caused by the New Relic SDK * Screenshots improvements * Minor improvements and bug fixes ## Versions 2.1.0 to 2.1.2 were pre-released only ## 2.0.1 - 2019.07.04 * **AndroidX support**: SDK is now published in 2 versions, the main one supporting AndroidX and the other supporting the Original Android Support. * **Screenshot mode** * **WebView tracking** * Minor improvements and bug fixes ## 1.6.3 - 2019.03.07 * Minor improvements and bug fixes ## 1.6.2 - 2019.02.28 * Minor improvements and bug fixes ## 1.6.1 - 2019.02.18 * Minor improvements and bug fixes ## 1.6 - 2018.11.09 * Add screen URL customization. * Change the transaction API packages: **If you were already using this feature, update the import in your code**. * Changed Transaction class path from `com.contentsquare.android.internal.api.Transaction` to the `com.contentsquare.android.api.Transaction` * Change the Currencies class path from `com.contentsquare.android.internal.api.Currencies` to the `com.contentsquare.android.api.Currencies` * Minor improvements ## 1.5.1 - 2018.10.18 * Minor bug fix ## 1.5 - 2018.10.15 * **Add Flush event requests on app hide** * **Change OS version tracking**: now collecting OS version *8.0* instead of Android API Level * **Change Device info tracking**: now collecting `Device manufacturer` and `Device Model` in 2 distinct fields (((`dma` and `dmo`))) * Improve around gesture tracking on unresponsive views * Minor improvements and bug fixes ## 1.4 - 2018.07.26 * **Add Send transactions**: Transactions events can now be sent using the dedicated public API. [See dedicated documentation section](https://docs.contentsquare.com/en/android/track-transactions/) * Add screen density tracking: stored in the request meta data. Its values can vary between (0.75 and 10). * Improvements and bug fixes ## 1.3.1 - 2018.05.30 * Minor improvements and bug fixes ## 1.3 - 2018.05.29 * **Add Privacy Handling Public API**: SDK is now GDPR compliant and offers public APIs handling privacy. * Improvements and bug fixes ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare Android SDK changelog","url":"https://docs.contentsquare.com/en/android/changelog/","inLanguage":"en","dateModified":"2026-08-10T14:30:30+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Collected data points - Android (classic) description: Events and metadata collected by the Android SDK lastUpdated: 05 June 2026 source_url: html: https://docs.contentsquare.com/en/android/collected-data-points/ md: https://docs.contentsquare.com/en/android/collected-data-points/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). The Android SDK collects request metadata, gesture events, lifecycle events, transactions, dynamic variables, and Exposure Metrics, all serialized as JSON and sent to the server in batches. * The events are in JSON format, which lists the properties and their description in comment. * Events are sent to the server in batches. * A batch is a subset of events originating from one session. A session can send events in more than one batch. * The batch size is defined in a run configuration file specific to each app (50 events by default). ## Requests meta data Each batch has a common header, a set of device specific, and repeatable information and an array of events, which is immutable. The header is composed at the moment of sending, so it has to be constant info ONLY. The array in the payload is data stored at the moment of collection. The structure of the batches of events will have the following format: ```javascript { pid:8, // int - ProjectId - represented in the mobile config format uid:"ac1529a7-59f6-49d9-b254-6f0a22f57284", // String - uuid Unique user ID dt:4, // int - device type (loosely enforced enum - [sdk-phone : 4, sdk-tablet :5]) dma:"Samsung", // String - device manufacturer. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. dmo:"SG", // String - device model. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. os:"10.0", // String - os version (Android version name 8.0, 9.0, 10.0) l:"en_US", // String - Language in iso-639 format https://www.ibabbleon.com/iOS-Language-Codes-ISO-639.html tz:"Europe/Paris", // String - timezone https://en.wikipedia.org/wiki/List_of_tz_database_time_zones now:1522159618000, // long - timestamp when the batch was sent to:{ // object - type origin of the event an:"appname" // String - application name st:"sdk-android", // String - type of sdk sf:"release", // string - sdk flavor/variant [release/debug/god] }, r:{ // Device - resolution. w:1080, // int - width h:1920 // int - height d: 1.5 // The device density as float. Its values can vary between (0.75 and 10) }, pl:[] // JSON array payload - list of event objects, see below } ``` ## Events ### Events meta data All events have a common first part (don't confuse it with the header explained above). This common section is data which is common for all events by type but is gathered at the moment the event occurred. This common section is a part of the actual event payload. ```javascript { upt:1522, // long - system update in milliseconds euid:"euid", // String - event UUID url:"app-and://identifier/mainPath/secondaryPath?title=screeName", // String - screenName is passed in the title query Parameter scn:4, // int - the number of screens already shown in the session c:3, // int - connectivity type [-1 - offline, 0 - error, 1 - wifi, 2 - 2g, 3 - 3g, 4 - 4g] ci:"verizon", // String - carrier_id when user is on mobile network o:1, // int - orientation [0 = portrait, 1 = landscape] vo:{ // object - version origin of the event sv:"2.1", // string version of the sdk sb:4, // int - sdk build number av:"appVersion", // String - application version af:"appFlavor" // String - application string - [release/debug/god] ab:1 // int - application build number }, sn:1, // int - session id (positive int) t:12894726459435 // long - timestamp of the event (in milliseconds) } ``` All event specific properties are appended to this JSON object. ### App Start This event describes the absolute start of the app. The trigger for this event is the absolute start of the app. This is the first event sent when the SDK is invoked. ```javascript ea: 0; // int - event action - defined above ``` ### App Show This event is sent when the user brings the app in the foreground (switching from another app, exiting lock screen, etc.). This event means the app is focused. ```javascript ea: 1; // int - event action - defined above ``` ### App Hide This event is sent when the user exits (minimizes) the app, or switches to something else. This event means the app is not focused and the session might end, but we have not completely ended the session yet, as the user might return. ```javascript ea: 2; // int - event action - defined above ``` ### Screenview Everything starts with a View event. This is an event which describes the equivalent of a "page view" on the web. This event is sent when the Track Screen API is called. ```javascript ea:4 // int - event action - defined above st:"title", // String - screen title sl:34543 // int - (load time) screen load time (diff between last action and this event) ``` ### Tap Single Finger gesture event, when the user is interacting with a loaded screen. This is an event which describes the equivalent of a "click" in the web. This event is defined by the following sequence of touch events: * Touch Down -> N x Touch Move -> Touch Up ```javascript ea:6 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ur: true, // boolean - was this a "responsive" touch event (the target view had a handler) ``` ### Long press Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Duration: > 500ms * Distance: < 24 dp ```javascript ea:8 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ``` ### Drag (Slow Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity < 100 dp/s ```javascript ea:9 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance dragged tvv:100 // int - target view velocity while dragging dp/s ``` ### Flick (Fast Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity > 100 dp/s ```javascript ea:10 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view graph path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance scrolled tvv:100 // int - target view velocity while scrolling dp/s ``` ### Transaction To track transactions we provide a public API which can send a transaction object (see section [Track Transactions](https://docs.contentsquare.com/en/android/track-transactions/)). This object must contain the following parameters: ```javascript ea:16, // int - event action - defined above tr:{ // a json object with different properties defining the transaction made vl: 20.0, // mandatory - float - the value of the transaction cu: 978, // mandatory - int - the ISO 4217 code of the currency of the transaction id: "32akjkljklJ575775" // optional - string - an id for the transaction } ``` ### Dynamic variables To track dynamic variables we provide a public API (see section [Dynamic variables](https://docs.contentsquare.com/en/android/track-dynamic-variables/)). ```javascript // Dynamic variable event with a string value ea:18, // int - event action - defined above k:"key", // String - Custom key assigned by client. v:"value" // String - Custom value assigned by client. ``` ```javascript // Dynamic variable event with a number value ea:19, // int - event action - defined above k:"key", // String - Custom key assigned by client. v: 2344 // Integer - Custom value assigned by client. ``` ## Exposure Metrics In the Zoning Analysis module, Exposure Metrics provide information on the size of the display zone in the application and data about exposure of content in scrolling elements. ### Behavior for scrollable elements Exposure Metrics data for scrolling is only calculated on the first scrollable element on the screen. Other scrolling elements in the view hierarchy are not taken into account. The event is defined by the following content: ```javascript ea:23, // int - event action dx:10, // int - normalized x content offset dy:10, // int - normalized y content offset du: 5, // int - duration of the movement (in milliseconds) ``` #### Exclude `ScrollView`, `HorizontalScrollView`, `NestedScrollView`, or `RecyclerView` type object from Exposure Metrics To exclude a scrollable container from Exposure Metrics, use the `Contentsquare.excludeFromExposureMetric(View)` API. Call it from the `onCreate` method of the activity or the `onCreateView` method of the fragment. * Java ```java import com.contentsquare.android.Contentsquare; @Override public void onResume() { super.onResume(); // ... ScrollView scrollView = findViewById(R.id.scrollView); // or HorizontalScrollView, NestedScrollView, or RecyclerView Contentsquare.excludeFromExposureMetric(scrollView); } ``` * Kotlin ```kotlin import com.contentsquare.android.Contentsquare public override fun onResume() { super.onResume() // ... val scrollView = findViewById(R.id.scrollView) // or HorizontalScrollView, NestedScrollView, or RecyclerView Contentsquare.excludeFromExposureMetric(scrollView) } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Collected data points","description":"Events and metadata collected by the Android SDK","url":"https://docs.contentsquare.com/en/android/collected-data-points/","inLanguage":"en","dateModified":"2026-06-05T17:39:25+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Disabling Automatic SDK Initialization - Android (classic) description: How to disable autostart in the Contentsquare SDK for Android lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/android/disable-autostart/ md: https://docs.contentsquare.com/en/android/disable-autostart/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). By default the SDK initializes automatically at startup; you can disable this behavior and call `start()` manually. ## How to disable autostart Set the `com.contentsquare.android.autostart` flag to false in your `AndroidManifest.xml` file. **AndroidManifest.xml** ```xml ... ... ``` Then, you can start the Contentsquare SDK by calling the `start()` method of the Contentsquare class. ```kotlin Contentsquare.start(context) ``` This initialize function is called automatically on app startup if the `com.contentsquare.android.autostart` flag is not listed in the AndroidManifest. This function should be called before the first activity is created. Call this function in the `onCreate()` method of a custom Application subclass: ```kotlin import android.app.Application import com.contentsquare.android.Contentsquare class MyApplication : Application() { override fun onCreate() { super.onCreate() // Start Contentsquare SDK Contentsquare.start(this) } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Disabling Automatic SDK Initialization","description":"How to disable autostart in the Contentsquare SDK for Android","url":"https://docs.contentsquare.com/en/android/disable-autostart/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Compatibility - Android (classic) description: Requirements and limitations to develop with the Contentsquare Android SDK lastUpdated: 06 August 2026 source_url: html: https://docs.contentsquare.com/en/android/compatibility/ md: https://docs.contentsquare.com/en/android/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). The Contentsquare Android SDK requires a minimum Android version and specific language and dependency configurations. * **Supported languages**: The Contentsquare SDK supports and tracks content written in Kotlin or Java. * **Minimum Android version**: Your app must be running Android 5.0 (Lollipop) or a later version (API Level 21+) to use the Contentsquare SDK. * **Compilation information**: The Contentsquare SDK is built and compiled using Android SDK version 34. Warning If your app supports Android devices running versions below 7.1, you must include the ISRG Root X1 certificate in your app to ensure Let's Encrypt certificates work correctly. For more details and guidance, check this link: [Let's Encrypt Cross-Sign Expiration ↗](https://letsencrypt.org/2023/07/10/cross-sign-expiration/). ## Java versions This version has been compiled on `Java 17` (Bytecode version 61). Note If you try to import the Contentsquare SDK while using a lower Java version in your project, you will get a `bad class file` error. Update your Java version to get rid of the error. ## Kotlin versions Contentsquare Android SDK is compiled with Kotlin version `1.8.22`. If you don't use the `1.8.22` Kotlin version and you have conflict issues; you must exclude the Kotlin `stdlib` from our SDK. ```groovy implementation("com.contentsquare.android:library:4.52.1") { exclude group: "org.jetbrains.kotlin", module: "kotlin-stdlib-jdk8" } ``` Compatibility modes We use [Kotlin Compatibility modes ↗](https://kotlinlang.org/docs/compatibility-modes.html) flags to be backward compatible with two previous Kotlin versions and one next version. For an in-depth understanding of compatibility modes, see this [quicksheet ↗](https://blog.mbonnin.net/kotlin-compatibility-quicksheet). ## Jetpack Compose versions Contentsquare Compose SDK `com.contentsquare.android:compose:4.52.1` is compiled using Jetpack Compose version `1.6.0` (`bom 2024.01.00`). | CSQ SDK Version | CS Compose version | Embedded Compose version | Minimum Compose version | Latest tested Compose version | | - | - | - | - | - | | | 4.52.1 | 1.6.0 | 1.6.0 | 1.11.0 | | | 4.52.0 | 1.6.0 | 1.6.0 | 1.11.0 | | | 4.51.2 | 1.6.0 | 1.6.0 | 1.11.0 | | | 4.51.1 | 1.6.0 | 1.6.0 | 1.11.0 | | | 4.51.0 | 1.6.0 | 1.6.0 | 1.11.0 | | | 4.50.0 | 1.6.0 | 1.6.0 | 1.10.0 | | | 4.44.2 | 1.6.0 | 1.6.0 | 1.10.0 | | 0.11.2 | 4.44.1 | 1.6.0 | 1.6.0 | 1.10.0 | | 0.11.1 | 4.44.1 | 1.6.0 | 1.6.0 | 1.10.0 | | 0.11.0 | 4.44.0 | 1.6.0 | 1.6.0 | 1.10.0 | | 0.10.1 | 4.43.2 | 1.6.0 | 1.6.0 | 1.10.0-beta02 | | 0.10.0 | 4.43.0 | 1.6.0 | 1.6.0 | 1.10.0-beta02 | | 0.9.0 | 4.41.0 | 1.6.0 | 1.6.0 | 1.9.0-beta02 | | 0.8.0 | 4.40.0 | 1.5.0 | 1.5.0 | 1.9.0-beta02 | | 0.7.2 | 4.39.3 | 1.5.0 | 1.5.0 | 1.8.0-rc02 | | 0.7.1 | 4.38.2 | 1.5.0 | 1.5.0 | 1.8.0-rc02 | | 0.7.0 | 4.38.1 | 1.5.0 | 1.5.0 | 1.8.0-rc02 | | | 4.38.0 | 1.5.0 | 1.5.0 | 1.8.0-rc02 | | 0.6.0 | 4.37.0 | 1.5.0 | 1.5.0 | 1.7.7 | | 0.5.1 | 4.36.1 | 1.5.0 | 1.5.0 | 1.7.7 | | 0.5.0 | 4.36.0 | 1.5.0 | 1.5.0 | 1.7.7 | | 0.4.0 | 4.35.0 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | 0.3.0 | 4.34.0 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | 0.2.0 | 4.33.2 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | | 4.33.1 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | | 4.33.0 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | 0.1.1 | 4.32.1 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | 0.1.0 | 4.32.0 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | | 4.31.0 | 1.5.4 | 1.5.0 | 1.7.0-beta06 | | | 4.30.0 | 1.5.4 | 1.5.0 | | | | 4.29.1 | 1.5.4 | 1.5.0 | | | | 4.28.0 | 1.5.4 | 1.5.0 | | | | 4.27.1 | 1.5.4 | 1.4.0 | | | | 4.26.0 | 1.5.4 | 1.4.0 | | | | 4.25.0 | 1.5.4 | 1.4.0 | | | | 4.24.1 | 1.5.4 | 1.4.0 | | | | 4.23.1 | 1.4.0 | 1.4.0 | | | | 4.22.0 | 1.4.0 | 1.4.0 | | | | 4.21.0 | 1.4.0 | 1.4.0 | | | | 4.20.0 | 1.4.0 | 1.4.0 | | Note If your project uses a lower Compose version than the one embedded in the Contentsquare Compose SDK, Gradle will automatically use the latter version. Update the Compose version to the one used by our SDK or later. ## Dependencies The Contentsquare SDK has a few dependencies. We try to be up-to-date as much as possible to avoid conflict issues. ### Handling conflicts We may sometimes have conflicts between your app dependencies VS SDK dependencies. In this case, you can exclude from our SDK any dependency we pull and use your version instead. #### Example with excluding `recyclerview` dependency If you have a version of the **`recyclerview`** in your app which is older than the one we use, you can use the following to exclude it in your Gradle file. ```groovy implementation("com.contentsquare.android:library:4.52.1") { exclude group: "androidx.recyclerview", module: "recyclerview" exclude group: "androidx.swiperefreshlayout", module: "swiperefreshlayout" } ``` By doing this, you skip the **`recyclerview`** and **`swiperefreshlayout`** dependencies provided by our SDK. ### Dependencies list The list of dependencies for each artifact is searchable on mvnrepository.com: * [`com.contentsquare.android:library` ↗](https://mvnrepository.com/artifact/com.contentsquare.android/library) ## Known limitations and recommendations ### Native UI Elements are not supported **Symptom:** 1. You capture screenshots but main elements of the screen are not appearing. 2. SDK does not log any gesture events when interacting with some native UI elements. **Explanation:** Native UI Elements such as Bottom Sheets, Dialogs, Menus are not supported by the SDK. ### Gestures not attached to the expected view (Layout visibility) **Symptom:** In some cases, we found that gestures tracked by the SDK are not attached to the right UI element of the screen. These gestures will be attached to an invisible view. **Explanation:** The reason for this is that when the SDK attaches the gesture to a UI element, it generates a path regarding the visibility of the view when traversing the view hierarchy. If a view is visible and it matches the coordinates on where the gesture was performed it will be taken into account. Most of the time, the issue is that a layout is still present on the screen even if there is no content. **Best Practice:** When designing your application UI, do not let any layout stray along if it is not used. If a layout contains widgets like progress bar, remember to set its visibility to `GONE` or `INVISIBLE` after its purpose is served. ### Taps will be assigned to the first clickable view **Symptom:** A tap is not assigned to the tapped view, but to a view higher in the view hierarchy. **Explanation:** When a tap is captured, the view hierarchy is traversed to find all views that match the tap coordinates. The tap is assigned to the first clickable view, starting at the tail of the view list, meaning the search starts at the lowest hierarchy level. If no clickable view is found, then the tap is assigned to the view at the tail of the list. Jetpack Compose example: ```kotlin Button( onClick = { ... } ) { Text(text = "Simple Button") } ``` A tap on the `Text` will be assigned to the `Button`, because the `Button` is clickable. **Best practice:** If the described behavior does not fit your needs, you may add click listeners to the corresponding views. In the example above, you may add an identical click listener to the `Text`. ### Heatmaps: Initial scroll position has to be 0 **Symptom:** The tap positions in the Tap Heatmap do not match the actual tap positions on the screen. **Explanation:** For lists with lazy item generation, we may be unable to determine the correct initial scroll position. This is because the top list items may not be generated yet. We expect the initial scroll position to always be 0. **Best practice:** Ensure that the initial scroll position is always 0 for RecyclerViews and Compose lazy lists and lazy grids. ### No gesture detection for WebViews embedded in scroll container **Symptom:** Swipe gestures are not detected for a WebView. **Explanation:** For WebViews, the gesture detection is completely covered by the CS Tag, not the native Android SDK. However, when a WebView is placed inside a scrollable container, for example a `ScrollView`, the WebView will expand to its full size and all scrolling will be done by the scrollable container. In this case, no swipe gestures will be detected. **Best practice:** Ensure that WebViews are not placed inside any scrollable containers. ### Long Screenshot: Large Capture Limitation **Symptom:** The Long Screenshot capture completes the creation process, but then fails at the very end without a clear error message. **Explanation:** Long Screenshots can produce a very large amount of data. For reliability and performance reasons, the server enforces a maximum payload size (\~75 MB). Very long or content-heavy screens may exceed this limit, causing the screenshot to be rejected. **Workaround:** Capture a shorter area (reduce the scroll length) and/or reduce the amount of on-screen content (for example fewer or lighter elements), then retry the Long Screenshot. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Contentsquare Android SDK","url":"https://docs.contentsquare.com/en/android/compatibility/","inLanguage":"en","dateModified":"2026-08-06T16:52:07+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: How the SDK works - Android (classic) description: Understand how the Android SDK loads, tracks, and send data lastUpdated: 28 April 2026 source_url: html: https://docs.contentsquare.com/en/android/how-the-sdk-works/ md: https://docs.contentsquare.com/en/android/how-the-sdk-works/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). The SDK auto-starts at application launch, attaches to the current process, and intercepts the events and gestures needed to capture analytics data. ## Configuration Once started, our SDK fetches its configuration from our servers. Then depending on the segmentation size (defined by our team when you sign a contract) and the user consent status, it will start collecting analytics data from system and user events it detects from the runtime. ## Data collection ### Analytics data collection The SDK monitors the application, lifecycle events, the view hierarchy, and generates data from the behavior of the app, the content of the screen and the user interactions. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. ### Session Replay data collection See [Session Replay Initialization](https://docs.contentsquare.com/en/android/session-replay/#data-collection) to learn how Session Replay data collection works. ## Sending data ### Sending analytics data Analytics data are sent in batches of maximum 50 events. Requests are triggered when network conditions allow for the server to be reached and: * The current batch of events has reached 50 * Or the app is put in background ### Sending Session Replay Data See [Session Replay Requests](https://docs.contentsquare.com/en/android/session-replay/#requests) to learn more about how Session Replay data is sent. ### Sending crash Data See [Send Crash data](https://docs.contentsquare.com/en/android/error-analysis/#sending-crash-data) to learn more about how crash data is sent. ## Session definition A session is one continuous period of user interaction. It starts upon app launch and persists through state changes, including putting the app in the background or terminating and restarting it. As long as users interact at least once every 30 minutes, it remains the same session. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"How the SDK works","description":"Understand how the Android SDK loads, tracks, and send data","url":"https://docs.contentsquare.com/en/android/how-the-sdk-works/","inLanguage":"en","dateModified":"2026-04-28T22:02:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Error Analysis - Android (classic) description: How to use Contentsquare Error Analysis in your Android apps lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/android/error-analysis/ md: https://docs.contentsquare.com/en/android/error-analysis/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. Error Analysis automatically captures API errors and network failures in your app and surfaces them in the Contentsquare platform. ## Prerequisites ### Screen tracking implemented Tracking will start at the 1st screenview event, it is required to have screen tracking implemented. Make sure to follow the [Android Track screens](https://docs.contentsquare.com/en/android/track-screens/) sections. ### Reminder about User consent If you are in the process of implementing the SDK for the 1st time (or choose to take this update as an opportunity to review your Privacy related implementation), make sure to follow the [Android Privacy](https://docs.contentsquare.com/en/android/privacy/) sections. ## API errors ### Automatic network inspection By using code instrumentation, network calls will be instrumented to collect network data. This way, two largely used network stacks are supported, and all the libraries that use them: * [OkHttp ↗](https://square.github.io/okhttp/), * [HttpURLConnection ↗](https://developer.android.com/reference/java/net/HttpURLConnection) #### Adding the Gradle plugin With the use of a Gradle plugin, an instrumentation of your code will be performed to collect the data about network errors. Add the Contentsquare Network Gradle plugin to the plugins block in both your root-level and app-level Gradle files: * Groovy **build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.network" version "1.9.0" apply false } ``` **app/build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.network" } ``` * Kotlin **build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.network") version "1.9.0" apply false } ``` **app/build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.network") } ``` #### Task added The plugin adds new tasks for network code instrumentation: `transformVariantClassesWithAsm` #### Configure Gradle plugin By default the plugin is enabled for each variant, there are three ways to disable the Gradle plugin: ##### Build type * Groovy **build.gradle** ```groovy android { buildTypes { debug { errorAnalysisNetwork { setInstrumentationEnabled(false) } } } } ``` * Kotlin **build.gradle.kts** ```kotlin android { buildTypes { debug { configure { setInstrumentationEnabled(false) } } } } ``` ##### By flavor * Groovy **build.gradle** ```groovy android { flavorDimensions "example" productFlavors { enable { dimension "example" } disable { dimension "example" errorAnalysisNetwork { setInstrumentationEnabled(false) } } } } ``` * Kotlin **build.gradle.kts** ```kotlin android { flavorDimensions += "example" productFlavors { create("enable") { dimension = "example" } create("disable") { dimension = "example" configure { setInstrumentationEnabled(false) } } } } ``` ##### With a Gradle properties **gradle.properties** ```properties errorAnalysisNetworkInstrumentationEnabled=false ``` Command line: ```shell ./gradlew :app:assembleDebug -PerrorAnalysisNetworkInstrumentationEnabled=false ``` ### Manual inspection Note Our recommendation is to use the Gradle plugin. #### OkHttp interceptor If your project is using OkHttp client, an interceptor (`ErrorAnalysisInterceptor`) can be added to collect all the network errors: * Java ```java import com.contentsquare.android.error.analysis.network.ErrorAnalysisInterceptor; new OkHttpClient().newBuilder() .addInterceptor(new ErrorAnalysisInterceptor()) .build(); ``` * Kotlin ```kotlin import com.contentsquare.android.error.analysis.network.ErrorAnalysisInterceptor OkHttpClient().newBuilder() .addInterceptor(ErrorAnalysisInterceptor()) .build() ``` #### Custom implementation If no other solution works, a custom implementation can be created via the `newNetworkMetric` method. Multiple data will need to be gathered: **URL** and **method** at the creation of the metric, and **status code** after the request is done. Also calling `start` (before the request) and `stop` (after all the rest) methods for time metrics to be collected and to send the event. * Java ```java import com.contentsquare.android.error.analysis.ErrorAnalysis; import com.contentsquare.android.error.analysis.NetworkMetric; NetworkMetric metric = ErrorAnalysis.getInstance().newNetworkMetric(url, ErrorAnalysis.HttpMethod.GET); metric.start(); // do your request metric.setStatusCode(code); metric.stop(); ``` * Kotlin ```kotlin import com.contentsquare.android.error.analysis.ErrorAnalysis import com.contentsquare.android.error.analysis.trace ErrorAnalysis.getInstance().newNetworkMetric(url, ErrorAnalysis.HttpMethod.GET).trace { // do your request setStatusCode(code) } ``` Note `start` and `stop` are automatically called by `trace` ### Removing Personal Data in request URL path By default, the API errors feature collects the URL path of the failed API requests. To prevent the collection of Personal Data in the URL path, you can rewrite the request URL path with the `ErrorAnalysis.setUrlMaskingPatterns` SDK API. Replace a step of the path - meaning between two slashes (/) - containing Personal Data with a variable: * `:user_id` becomes CS\_ANONYMIZED\_USER\_ID * `:address` becomes CS\_ANONYMIZED\_ADDRESS #### Example * Java ```java ErrorAnalysis.setUrlMaskingPatterns( List.of("https://www.contentsquare.com/users/:user_id/address/:address") ); ``` * Kotlin ```kotlin ErrorAnalysis.setUrlMaskingPatterns( listOf("https://www.contentsquare.com/users/:user_id/address/:address") ) ``` ##### Result | URL before masking | URL after masking | | - | - | | `https://www.contentsquare.com/users/123/address/castle+black` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS` | | `https://www.contentsquare.com/users/123/address/castle+black/reset-token/abcdef123456` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS/reset-token/abcdef123456` | ### Validate API error integration #### Validate API error collection is enabled If in-app features are enabled, an info log should appear when API Error collection has successfully been enabled (see [Android Debugging and Logging](https://docs.contentsquare.com/en/android/in-app-features/#debugging-and-logging) section).: ```plaintext CSLIB: Api Error collection is enabled ``` #### Validate API error collection If you have [logging enabled](https://docs.contentsquare.com/en/android/in-app-features/#debugging-and-logging), you will see API errors: * Displayed in [Contentsquare Log Visualizer](https://docs.contentsquare.com/en/android/in-app-features/#viewing-logs-in-the-contentsquare-platform). * As an Info log in Logcat: ```plaintext CSLIB: API Error - 401 GET https://api.client.com ``` ### How API errors works #### Initialization The way our SDK works is by auto-starting with the application launch and collecting the API errors through the instrumented code added by the Gradle plugin. #### Configuration Once started, our SDK fetches its config from our servers. It will start collecting data from network events if the API errors setting is enabled in the config (this is handled by the Contentsquare team). #### API errors collection The SDK monitors only the API errors with response code equal or above 400, and generates analytics data. These events are then locally stored, and eventually sent to our servers in batches. Warning For API errors to be tracked and processed, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. #### Sending API errors data For each network error, a new event will be sent in analytics and Session Replay data. Check the following sections to learn more about how data is processed and sent: * [Analytics requests](https://docs.contentsquare.com/en/android/how-the-sdk-works/#sending-data) * [Session Replay requests](https://docs.contentsquare.com/en/android/session-replay/#requests) ### API Troubleshooting Details API errors troubleshooting details enables you to collect more information about API errors so you can troubleshoot errors faster. With this feature you will be able to see three types of additional API error details in the Event Stream of Session Replay. * The HTTP headers of the request and the response. * The body (the data sent by the request or received in the response). * The query parameters of the request endpoint (of the URL of the information you request for). Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. See [API Troubleshooting Details ↗](https://support.contentsquare.com/hc/en-us/articles/37271885035537) for more details. ### Collected data points Only network calls in error (response code above 400) will be collected. Here the exhaustive list of data collected: * Response code * URL (without query strings) * HTTP method * Timestamp of the request * Timestamp of the response ### Known limitations and recommendations #### Conflict with Firebase Performance using code instrumentation Code instrumentation of requests made using HttpURLConnection does not work well with Firebase Performance plugin. Network events will not be logged when using Contentsquare Error Analysis network and Firebase performance plugin (only one of the two will log events). If you want to use both libraries, prefer using interceptors than code instrumentation. ## Crash Reporter ### Upload mapping file Android mapping files are generated during the process of obfuscating Android application code using tools like ProGuard. A mapping file for your app will be generated for all [obfuscated builds ↗](https://developer.android.com/build/shrink-code) at compile time. [Download the mapping file example](https://docs.contentsquare.com/ff-sample-mapping.txt) generated when building the [Contentsquare Android sample app ↗](https://github.com/ContentSquare/contentsquare-android-sample). To produce readable crash reports from builds that have been obfuscated, Contentsquare requires to upload the mapping file produced by your build to our servers. To simplify this process, we've provided a Gradle plugin that you can integrate into your build. It adds a distinct Gradle task that will be executed immediately after the build is done. This new task will be automatically triggered on assemble task for any minified build. Warning In versions before **1.4.0** of Error Analysis Crash Plugin, it was necessary to manually trigger the upload task for the mapping file. Since it's now automatically triggered, you need to remove any manual call to the `uploadContentsquareMappingFile` task. #### Adding the Gradle plugin Add the Contentsquare Crash Gradle plugin to the plugins block in both your root-level and app-level Gradle files: * Groovy **build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.crash" version "1.10.0" apply false } ``` **app/build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.crash" } ``` * Kotlin **build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.crash") version "1.10.0" apply false } ``` **app/build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.crash") } ``` #### Configuring the Gradle Plugin To use the plugin, you must provide it with the relevant credentials to be able to upload the mapping file. ##### Get project ID 1. Login to the Contentsquare platform on [https://app.contentsquare.com ↗](https://app.contentsquare.com) 2. Make sure to be on the right project 3. The project ID can be found in the URL query parameter `project`: `https://app.contentsquare.com/#/{MODULE_NAME}?project={PROJECT_ID}&hash={HASH}` ##### Get project credentials Follow the dedicated documentation from the Help Center to get the **client ID** and **client Secret**: [How to create API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/9292880837660). ##### Use credentials You can do this by setting the `uploadCredentials` property of the errorAnalysisCrash extension in your app-level `build.gradle` or `build.gradle.kts` file, as shown below. The errorAnalysisCrash extension is available on all build types and product flavours. * Groovy **build.gradle** ```groovy android { buildTypes { release { errorAnalysisCrash { uploadCredentials { projectId = clientId = "" clientSecret = "" } } } } } ``` * Kotlin **build.gradle.kts** ```kotlin android { buildTypes { release { configure { uploadCredentials { projectId = clientId = "" clientSecret = "" } } } } } ``` #### Disable Upload By default, the mapping file will be uploaded automatically. If you need to disable the upload, you can do it by adding a specific flag `mappingFileUploadEnabled` to the plugin configuration: * Groovy **build.gradle** ```groovy android { buildTypes { release { errorAnalysisCrash { mappingFileUploadEnabled = false uploadCredentials { ... } } } } } ``` * Kotlin **build.gradle.kts** ```kotlin android { buildTypes { release { configure { mappingFileUploadEnabled = false uploadCredentials { ... } } } } } ``` It is also possible to disable the upload using the command line when the assemble task is triggered by using the flag `errorAnalysisCrashMappingFileUploadEnabled` as follow: ```plaintext ./gradlew app:assembleRelease -PerrorAnalysisCrashMappingFileUploadEnabled=false ``` Doing that, the upload task will be disabled and you will see the following log: ```plaintext [ErrorAnalysisCrashPlugin] uploadContentsquareMappingFileRelease disabled for release ``` #### ProGuard Configuration To ensure that we can provide line numbers and file names in the crash reports, add the following configuration to your ProGuard file: ```plaintext -keepattributes SourceFile,LineNumberTable # Keep file names and line numbers ``` #### Custom mapping file If you obfuscate your app with a tool other than R8/ProGuard, or need to control exactly which mapping file is uploaded, you can point the plugin at a specific file with `customMappingFile`. When set, it takes precedence over the auto-detected R8 mapping. * Kotlin **build.gradle.kts** ```kotlin android { buildTypes { release { configure { customMappingFile = file("path/to/mapping.txt") uploadCredentials { ... } } } } } ``` * Groovy **build.gradle** ```groovy android { buildTypes { release { errorAnalysisCrash { customMappingFile = file("path/to/mapping.txt") uploadCredentials { ... } } } } } ``` #### DexGuard support The plugin is compatible with [DexGuard ↗](https://www.guardsquare.com/dexguard). It auto-detects DexGuard and uploads the **DexGuard** mapping instead of the R8 one. The mapping upload is wired as a finalizer of the DexGuard protect task, so running `./gradlew guardsquareProtectApk` (or `guardsquareProtectBundle` for app bundles) obfuscates the app and uploads the correct mapping automatically. ### Validate Crash reporter integration #### Validate crash collection is activated If in-app features are enabled, an info log should appear when the Crash reporter has successfully been initialized (see [Android Debugging and Logging](https://docs.contentsquare.com/en/android/in-app-features/#debugging-and-logging) section).: ```plaintext CSLIB: Crash reporter is enabled ``` #### Validate crash reporting To test that the Crash Reporter is working properly, you can force a crash in your application. The next time you start your application, the crash will be sent to our servers. If you have [logging enabled](https://docs.contentsquare.com/en/android/in-app-features/#debugging-and-logging), you will see the upload reflected in the log: ```plaintext CSLIB: Crash event detected and sent for userID: , session: on screen: crashID: ``` ### How Crash Reporter works #### Initialization Crash Reporter is started automatically and begins to report basic information for crashes in your application when it is launched. #### Configuration Once started, our SDK fetches its configuration from our servers. It will start reporting crashes if the Crash Reporter setting is enabled (this is handled by the Contentsquare team). #### Reporting When a crash occurs, a report is created and stored locally in the device. Once the app is launched again, the report is sent to our servers and then removed from the local storage. Warning For crashes to be reported and processed, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. #### Sending crash data For each crash, a new event will be sent to Analytics and Session Replay data when the app is launched again after the crash occurred and the network conditions allow for the server to be reached. ### Collected data points The Crash Reporter will capture any crashes caused by an unhandled exception in applications written in Java or Kotlin. It will collect information about the application, system, process, threads, stack traces and some other event metadata you can find in [collected data points](https://docs.contentsquare.com/en/android/collected-data-points/) ### Known limitations and recommendations Native crashes from applications written using C or C++ are not supported. #### Compatibility with other crash reporters It is possible that the Crash Reporter will work with other SDKs, but we cannot guarantee it. Android has a global error handling class and therefore we rely on other SDKs forwarding the error on to us in the event of a crash, should they have been registered first. If the Contentsquare Crash Reporter is registered first, it will forward on errors to any other registered handlers. Based on our tests, we can confirm it is compatible with Firebase Crashlytics. ## WebView errors Errors occurring in web pages loaded in WebViews can be collected if Webview tracking is set up in your app. See 📚 [Webview Tracking implementation](https://docs.contentsquare.com/en/webview-tracking-tag/). Once WebView tracking is implemented, errors collection can be set up. See 📚 [Errors (in WebView)](https://docs.contentsquare.com/en/webview-tracking-tag/error-analysis/) ## Compatibility ### Dependencies list | Package | Name | Version | | - | - | - | | androidx.annotation | annotation | 1.5.0 | ## Impact on Performance We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. The following performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | Pixel 5 | | Android version | 13 | We used [Android Microbenchmark ↗](https://developer.android.com/topic/performance/benchmarking/microbenchmark-overview) to measure the time added by our implementation. Note The numbers provided below will vary depending on the user's device, Android version, SDK version. The instrumented code added is running in *less than 1ms* per request: our benchmarks show less 400µs. About CPU and memory, the overhead of adding the collection of network error is negligible. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Error Analysis","description":"How to use Contentsquare Error Analysis in your Android apps","url":"https://docs.contentsquare.com/en/android/error-analysis/","inLanguage":"en","dateModified":"2026-08-03T10:30:43+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Impact on performance - Android (classic) description: Metrics to evaluate the impact on performance of the SDK on your apps lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/android/impact-on-performance/ md: https://docs.contentsquare.com/en/android/impact-on-performance/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). Contentsquare strives to be non-intrusive and transparent to client app developers. The following metrics help you evaluate the performance impact of the Contentsquare SDK on your apps. ## Performance impact The following are the technical specifics we can share on performance. The performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | Pixel 5 | | Android version | 34 (Android 14) | Note The numbers provided below will vary depending on the user's device and Android version. | Property | Value | | - | - | | SDK size | 1567 KB | | Nbr. of methods | 5753 | | Nbr. of fields | 3701 | | SDK CPU peak on event | <15 % | | Data transmitted over network for a default batch size of 50 events. The size of the batch can be customized if needed. | \~25kb | ## Performance test procedure | CPU Usage Test | RAM Usage Test | Memory Leak Test | | - | - | - | | We are profiling our Demo app with and without the SDK dependency by following the same use case. | We are profiling our Demo app with and without the SDK dependency by following the same use case. | We are profiling our demo app and we are using the ADB Monkey tool to create random user input events | | We are measuring the CPU peak for both versions of the app and we are computing the difference | We are measuring the RAM usage peak for both versions of the app and we are computing the difference | During this time we are monitoring the RAM behavior for any anomaly. We are using the Memory Profiler to track/fix the issue | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Impact on performance","description":"Metrics to evaluate the impact on performance of the SDK on your apps","url":"https://docs.contentsquare.com/en/android/impact-on-performance/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: In-app features - Android (classic) description: Implement in-app features with the Contentsquare Android SDK lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/android/in-app-features/ md: https://docs.contentsquare.com/en/android/in-app-features/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). Alongside its tracking capabilities, the SDK embeds some features aimed at Contentsquare users such as [Screenshot Capture](#screenshot-capture) and [SDK Logs](#debugging-and-logging). ## Enable in-app features To enable in-app features within your app, you have to **first make sure your app is launched in the background**. To do so, start it and press the Android home button. Then, follow the appropriate method described as follows. If access is blocked by the Android OS, you may need to allow the restricted settings first. To do this, go to your device settings, navigate to **Apps**, tap on your app, open the **More** menu (three dots), and then tap on **Allow restricted settings**. ### On a device: scan the QR code If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code with your phone.  Note On Android, some devices have a built-in QR code reader feature in the default camera app. If that is not the case for you, use [QR & Barcode Reader by TeaCapps ↗](https://play.google.com/store/apps/details?id=com.teacapps.barcodescanner\&hl=en\&gl=US). ### On an emulator: use the ADB command If you are using an emulator, you can use the ADB command to enable in-app features. If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and select "Copy this ADB command".  It will look like this: ```shell adb shell am start -W -a android.intent.action.VIEW -d "cs-{{packageName}}://contentsquare.com?activationKey={{uniqueActivationKey}}\&userId={{userId}}" ``` If you don't have access to the Contentsquare platform, you can ask the Contentsquare team to share the link with you. ## Debugging and Logging Contentsquare provides Logging capabilities that allow you to see the raw event data logged by your app in Android Studio or in the Contentsquare platform. Check logs for validation purposes during the instrumentation phase of development and can help you discover errors and mistakes in your analytics implementation and confirm that all events are being logged correctly. ### Viewing logs in Android Studio By default, almost all logs are disabled. There is only one log that is always visible to notify that the SDK has started: ```text CSLIB: Contentsquare SDK 4.52.1 starting in app: your.application.package ``` To enable all logs, activate [in-app features](#enable-in-app-features). Logging is directly linked to in-app features state: it starts when in-app features are enabled and stops when you disable in-app features. To view logs: 1. Plug your Android Phone to your Computer (or use emulator) 2. Start the Android Studio app 3. Open the Logcat view and select your phone or emulator 4. Filter logs on `CSLIB`  ### Viewing logs in the Contentsquare platform To view logs directly on the platform, you can use Log visualizer. Log visualizer is a helper tool to see SDK logs without logging tools. It requires having platform access for your project and enabling in-app features. See the [SDK Log Visualizer Help Center Article ↗](https://support.contentsquare.com/hc/en-us/articles/37271699876625) for more information. ## Screenshot capture To unlock the full data-visualization capabilities of Contentsquare, the SDK provides a way to capture screenshots of your app screens. These screenshots can only be taken by Contentsquare's users on their device. They are not captured from your end-users device. It means your Personal Data is safe, as long as you use a test user account. Warning For screenshot capture to work, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. Note The screenshot capture is only supported from Android API 26 (Android Oreo). Note To maintain accurate statistics in the Zoning Analysis module, the SDK prevents R8/ProGuard from obfuscating the names of all [View ↗](https://developer.android.com/reference/android/view/View) subclasses. However, class methods and fields can still undergo obfuscation and optimization.  Screenshots are used in the **Zoning Analysis** module to look at zone-level metrics (Tap rate, Swipe rate...):  ### Jetpack Compose support To enable Jetpack Compose support for Zoning, it is necessary to add a new Gradle dependency to your Gradle build file. Make sure to follow the [Track screens](https://docs.contentsquare.com/en/android/track-screens/#jetpack-compose-support) section. ### Invisible overlays covering other elements of a Compose screen Invisible overlays are transparent information overlays that do not display any information most of the time. These overlays may lead to issues in the Zoning editor. The screen elements covered by the overlay will display 0 taps. On the Contentsquare SDK side, the gesture recognition assigns the taps to the overlay, that is the target view path (TVP) of the tap differs from the TVP of the covered element in the Zoning editor. To avoid this issue, you may change the layout of the screen so that the overlay is no longer present. Another option is to mark the overlay using the extension function `Modifier.excludeFromGestureRecognition()`. ```kotlin /** * [Modifier] extension function that provides the facility to exclude a Composable from the gesture recognition. */ fun Modifier.excludeFromGestureRecognition(): Modifier ``` The marked Composable and all of its children will be excluded from gesture recognition, so no gestures will be assigned to this part of the Composable hierarchy. Additionally, this Composable subtree will not be included in the screenshot generated by the SDK and will therefore not appear in the Zoning editor. For example: ```kotlin @Composable private fun InfoOverlay() { Box( modifier = Modifier .fillMaxSize() .excludeFromGestureRecognition() ) { // some content that is displayed occasionally } } ``` ### Lists with Slowly Rendering Items When creating a Long Screenshot of a RecyclerView or a lazy Compose list, the contents of the list are scrolled automatically. If individual elements of the list are missing in the resulting screenshot, that is they are invisible, this may be because the elements take too long to render. In such a case, automatic scrolling can be delayed. You must have enabled in-app features: 1. Long press on the screenshot button to open the Contentsquare settings. 2. Move the slider to set the delay for scrolling. The value is displayed in milliseconds. 3. Tap on the arrow back to close the Contentsquare settings. You can now repeat the screenshot and then check it in the zoning editor.  ## Known limitations ### Screenshot capture * The screenshot capture is only supported from Android API 26 (Android Oreo). * The combination of `CoordinatorLayout`, `AppBarLayout`, and `RecyclerView` is not supported. * `ConcatAdapter` is not supported. * Lists with different item layouts are not supported. * Two or more scrollable containers are not supported. Furthermore, horizontal scrollable containers are not supported. * Screenshots of screens in edge-to-edge / fullscreen mode may contain visual artifacts in Zoning Analysis module, for example from the status and navigation button bar. Although some zoning elements will be visually altered by system bars, creating zones and displaying statistics will still work correctly. * Taps and other gestures are assigned to UI elements so the Zoning editor can display metrics. The SDK favors clickable elements. For instance, a tap on a button that is part of an overlay is assigned to the button. A tap on a non-clickable element results in the assignment of a background element. * Some lifecycle events are not handled, for example app in background, device rotation, fragment change. * Dark mode is not supported. ### Additional limitations for Compose Screens * The screenshot for Jetpack Compose is not fully supported yet. This also applies to the combination of Compose and WebViews. * The visual information may not be consistent for screenshots of Jetpack Compose screens. This applies in particular to transparency and visibility. * Scrollable elements with spacings and paddings may not yet be fully supported. While all elements can be selected as zones in the Zoning editor and statistics will be accurate, visual presentation might be affected by artifacts. * Screens containing transparent overlays are not supported in the Zoning module. Any transparent Composables covering the main content of the screen need to be fully removed when unused. * Android views embedded within scrollable Compose containers are not fully supported. These views can be selected as zones in the Zoning editor, and the statistics will be accurate. However, they will not scroll properly with the rest of the content. * Sometimes, `LazyColumn` items may contain more than one direct composable, or no composables at all. This can result in an error during screenshot creation or an invalid screenshot in the Zoning editor. To avoid this, wrap the `LazyColumn` items with an additional Column wrapper, like this: ```kotlin LazyColumn(modifier = Modifier.fillMaxSize()) { items(20) { itemIndex -> // Wrapping every item with additional Column avoids issues if some // items have multiple direct composables, or no composables at all. Column { when (itemIndex % 3) { 0 -> { // Item with 1 direct composable (Row). Row { Text(text = "Sample") } } 1 -> { // Item with multiple direct composables (Text, Row). Text(text = "Sample") Row { Text(text = "Sample") } } // No else statement: some items will have no composables at all. } } } } ``` * Material `ModalBottomSheetLayout` contains an internal `Scrim` composable that may prevent the SDK from tracking content wrapped by `ModalBottomSheetLayout`. Explicit tagging of `ModalBottomSheetLayout` using the `CsqTag()` API is required for Zoning and Heatmaps to work correctly. For example: ```kotlin CsqTag(CsqTag.ModalBottomSheetLayout) { ModalBottomSheetLayout(..) { .. } } ``` * When modifying the semantics of a clickable element, the order of the modifiers is important. For example, when clearing the semantics with the `clearAndSetSemantics` modifier, the clickable modifier should be placed before the `clearAndSetSemantics` modifier. ```kotlin Column( modifier = modifier .clickable(..) .clearAndSetSemantics { contentDescription = .. } ) ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"In-app features","description":"Implement in-app features with the Contentsquare Android SDK","url":"https://docs.contentsquare.com/en/android/in-app-features/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Privacy - Android (classic) description: Learn how Contentsquare deals with Personal Data and related APIs lastUpdated: 07 August 2026 source_url: html: https://docs.contentsquare.com/en/android/privacy/ md: https://docs.contentsquare.com/en/android/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). Customers ("Customer(s)", "you," or "your"), as app developers and/or publishers, shall ensure compliance with applicable data privacy laws and regulatory guidelines while using Contentsquare SDK for your app. This section explains the data processing involved in the use of Contentsquare SDK and provides information to help you comply with data protection laws, including the GDPR, e-privacy directive, and the [French Data Protection authority (CNIL) guidelines on mobile applications ↗](https://www.cnil.fr/sites/cnil/files/2025-05/recommendation-mobiles-app.pdf). This section is for informational purposes only and is not legal advice. If you are not sure of how to comply with data protection laws that apply to you, refer to legal counsel. To learn about Contentsquare privacy practices, see our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Purpose of processing and categories of personal data processed ### Purpose of processing The Contentsquare SDK is designed to collect personal data from end-users interacting with your app to analyze their digital behavior, visualize their journey, and improve digital user experience and your app performance. ### Categories of personal data collected By default, the SDK processes the following categories of personal data: * **Online identifier**: Contentsquare user ID * **Behavioral data**: touch gestures (taps, swipes), user journey (pages visited), time of engagement, and transactions. * **Technical data**: device information (such as operating system, resolution, time zone, or language), API error messages and crashes Additional types of personal data may be processed (such as username, email address, customer ID, account number), depending on your configuration of the SDK and the applicable order form you signed with Contentsquare. Note Contentsquare is not designed to collect sensitive personal data (such as health, financial, or racial data). It is your responsibility to prevent any sensitive data from being sent to Contentsquare. If you accidentally send sensitive data, contact your customer success manager to immediately delete them from Contentsquare servers. ## User Identifiers ### Contentsquare User ID The SDK generates a randomized hash unique user ID (UUID) that is specific to each end-user on a given device. Contentsquare cannot identify an end-user across devices with this UUID. This UUID is not persisted when the app is deleted and re-installed. The SDK generates a new UUID after install or re-install. ### Usage of App Set ID Contentsquare does not use App Set ID. ## Data retention and storage location ### Data retention By default, end-users personal data are kept for 13 months. The retention of end-users personal data collected via the Session Replay is customizable by customers, from 3 to 24 months. ### Storage location End-users personal data are stored in Europe or in the US, depending on your location. For more details on applicable hosting locations, refer to our [subprocessors list ↗](https://contentsquare.com/privacy-center/subprocessors/). ## Informing your end-user The Contentsquare SDK collects end-user's personal data on your app. As a data controller, app developers, or app publishers, it is your responsibility to provide appropriate information to your end-users on how their personal data is handled when using the CSQ SDK, for example via a privacy policy or cookie banner. Contentsquare provides a sample [description of the services ↗](https://contentsquare.com/privacy-center/sample-cookie-description/) (including Experience Analytics and Product Analytics) to help customers meet their transparency obligations. This description is for information only and is not legal advice. ## Handling User Consent Contentsquare collects usage data on your app. **By default, the SDK will consider every new user to be opted-out.** To start tracking, the SDK [Opt-in API](#opt-in) must be called. You are responsible for handling the UI asking end-users for their consent and allowing them to manage their privacy settings. Use the following APIs to pass the user decision to the Contentsquare SDK. Note If data protection laws that apply to you do not require end-user consent for your app, discuss it during implementation with your Contentsquare contact. ### Opt-in Use the Opt-in API to get user consent. Calling this API will generate a user ID and initiate tracking. ```kotlin import com.contentsquare.android.Contentsquare // To opt in to CS Tracking Contentsquare.optIn() ``` ### Opt-Out When this API is called, tracking stops immediately, all settings are reset (session number, page number) and all files and directory including personal data collected via the SDK created by Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track and collect any data from the user's phone unless the Opt-in API is called again. ```kotlin import com.contentsquare.android.Contentsquare // To opt out of CS Tracking Contentsquare.optOut() ``` ### Handling your end-user's data subject requests In case Contentsquare receives a request from an individual that identifies as an end-user of your app, Contentsquare will promptly refer such individual directly to you, as the data controller and will support you with any means available to resolve such request. Contentsquare has launched a portal for managing data subject requests to its customers respond to data subjects within the legal deadlines. Therefore, you can forward any data subject request (such as data deletion or data access request) you receive to Contentsquare via this Data Subject Portal at [https://contentsquare.com/privacy-center/data-subject-request-portal/ ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ### Get your end-user's Contentsquare User ID Since Contentsquare SDK does not collect by default any directly identifiable personal data about your end-user, we cannot help you respond to an end-user's data subject request without their Contentsquare User ID. Use this API to get the Contentsquare User ID of your end-user and forward the end-user's data subject request (such as data deletion or data access request) via Contentsquare's [portal ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ```kotlin import com.contentsquare.android.Contentsquare // Get CS User ID Contentsquare.getUserId() ``` Note This API can return `null` if the SDK has not been started or is under initialization. You can use `Contentsquare.wasInitialized()` to check if the SDK has been successfully initialized. ### Stop / Resume Tracking Use stop and resume tracking APIs to completely pause data collection of your end-users on your app. When stop is called, the Contentsquare SDK pauses all tracking (Analytics, Session Replay, Errors) of your end-users. When resume is called, the Contentsquare SDK resumes all tracking (Analytics, Session Replay, Errors) and starts collecting your end-users personal data again with the same Contentsquare user ID. ```kotlin import com.contentsquare.android.Contentsquare // Stop tracking Contentsquare.stopTracking() // Resume tracking Contentsquare.resumeTracking() ``` Note As this mechanism pauses the tracking, make sure that you call resume once your user exits the sensitive screen. Best practice would be to link these method calls to lifecycle events on activities/fragments. ### Stop automatic gesture tracking End-users' personal data, including behavioral data (such as taps, scrolls, swipes) are collected automatically by the Contentsquare SDK. In specific cases, you might want to stop this data collection momentarily for some Activities (as defined by Android). To do so, use our public API: ```kotlin Contentsquare.doNotTrack(@NonNull Class... activitiesClasses) // filters the activities according to their classes ``` Also, you can stop the collection of end-users' personal data, including behavioral data (such as taps, scrolls, swipes) on specific UI components using the following public API: ```kotlin Contentsquare.doNotTrack(@NonNull View view, boolean includeSubtree) // filters a single view instance ``` In case you still need to track these Activities or Views but the automatic gesture tracking does not work, we offer the possibility to do this manually by capturing and sending end-users' personal data via our public API method: ```kotlin class MainActivity : AppCompatActivity() { .......... override fun dispatchTouchEvent(ev: MotionEvent): Boolean { Contentsquare.consumeEvent(ev) return super.dispatchTouchEvent(ev) } } ``` ### Forget me **Permanently breaking the link between the collected data and actual end-user.** This resets all settings and deletes all files and directories, including personal data collected via the Contentsquare SDK from the end-user's device (that is Contentsquare User ID and all related personal data is deleted). If the end-user is opted in to be tracked by the Contentsquare SDK, next time the end-user starts the app, the SDK will re-start its collection mechanisms as if this was the first ever run for a new end-user, under a new Contentsquare User ID. Configurations will be fetched from the server and application tracking will be on. Note "Forget me" only works when user is opted in. Deprecated This API is deprecated. To achieve the same effect use [Opt-out API](#opt-out) to delete all files and settings including end-users personal data collected via the Contentsquare SDK, and call [Opt-in API](#opt-in) on next app launch if tracking needs to resume. ```kotlin import com.contentsquare.android.Contentsquare Contentsquare.forgetMe() ``` ### Disable end-user tracking across sessions If you don't want to link the different sessions of an end-user to the same Contentsquare User ID, you can follow these instructions to reset the Contentsquare User ID at each app start: 1. Disable [SDK auto-start](https://docs.contentsquare.com/en/android/disable-autostart/) 2. Implement the following: ```kotlin class MyApplication : Application() { override fun onCreate() { super.onCreate() // Start Contentsquare SDK Contentsquare.start(this) Contentsquare.optOut() Contentsquare.optIn() } } ``` Starting the SDK manually using `start()` will ensure that opt-out is called right after the start of the SDK (no event tracked in between). Calling `optOut()` will delete the previous userID. Calling `optIn()` will set a new one. Note If you are monitoring the network requests, you may see event requests being sent at app start. This is expected as there may be events from the previous session that haven't been sent yet. The opt-out API makes sure to send all data stored locally before stopping the tracking and wiping all data. ### Session Replay personal data masking mechanisms As part of Session Replay, Contentsquare provides masking mechanisms to prevent unwanted end-user's personal data from the Session Replay module from being transmitted to Contentsquare. See [Session Replay Personal data masking](https://docs.contentsquare.com/en/android/session-replay/#personal-data-masking) for more information. ## Permissions The Contentsquare SDK requires technical permissions to operate properly. Some of these permissions involve read and write operations within the meaning of the e-privacy directive and article 82 of the French Data Protection Act, which may require the end-user's specific consent. See [App permissions](https://docs.contentsquare.com/en/android/security/#app-permissions) for more information. ## Play Store Privacy Guidelines Compliance As customer app developers, it is your responsibility to comply with the [Play Store Privacy guidelines ↗](https://support.google.com/googleplay/android-developer/answer/10144311?visit_id=637574546075634450-3505282410\&rd=1). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Learn how Contentsquare deals with Personal Data and related APIs","url":"https://docs.contentsquare.com/en/android/privacy/","inLanguage":"en","dateModified":"2026-08-07T08:07:46+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Security - Android (classic) description: Data transfer and security information lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/android/security/ md: https://docs.contentsquare.com/en/android/security/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). The Android SDK requires a set of permissions to operate properly and transmits all data securely over HTTPS. ## App permissions The SDK includes the following permissions, which are mandatory for the SDK to operate properly: **AndroidManifest.xml** ```xml ``` | Permission | Required to | Associated with read/write operations under e-privacy directive | | - | - | - | | `android.permission.INTERNET` | Send collected data to Contentsquare servers | Yes. The end-user's data is collected for analytics purposes. | | `android.permission.READ_BASIC_PHONE_STATE` | Retrieve non-sensitive device information such as carrier name for analytics purposes | Yes. The end-user's data is collected for analytics purposes. | | `android.permission.SYSTEM_ALERT_WINDOW` | Use Contentsquare in-app features | No. This permission is solely used to display Contentsquare UI elements in our customers' apps. | | `android.permission.ACCESS_NETWORK_STATE` | Check network availability before sending data | No. This permission is solely used to check the network status check. | Note Some of these permissions involve read and write operations within the meaning of the e-privacy directive and article 82 of the French Data Protection Act, which may require the end-user's specific consent as specified above. This requirement applies in particular to customers based in the EU or targeting end-users in the EU. For more information on how to combine technical permission and legal consent, refer to the [CNIL (French data protection authority) recommendations ↗](https://www.cnil.fr/fr/permissions-applications-mobiles-recommandations-de-la-cnil-pour-respecter-la-vie-privee). ## Deep links usage in Contentsquare SDK As outlined in the [Android Security Guidelines ↗](https://developer.android.com/privacy-and-security/risks/unsafe-use-of-deeplinks), there are security risks associated with using deep links. To address these concerns, the Contentsquare SDK implements robust data validation for deep links and safeguards to prevent deep link hijacking, following these guidelines. If you have specific security concerns and prefer to remove the Contentsquare SDK deep link declaration from your application, add the following code snippet to your `AndroidManifest.xml` file inside the `` tag: ```xml ``` Removing the deep link will disable the In-app feature within your application. ## Transmission and hosting All data is encrypted in transport over HTTPS. Our hosting solution is a PCI DSS Level 1 Service Provider. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Security","description":"Data transfer and security information","url":"https://docs.contentsquare.com/en/android/security/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Session Replay - Android (classic) description: How to implement Session Replay with the Contentsquare Android SDK lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/android/session-replay/ md: https://docs.contentsquare.com/en/android/session-replay/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). Session Replay enables replaying real sessions to observe how users interact with your product, by capturing screen content - including text and images - as users navigate your mobile app. For more details, see [Introduction to Session Replay for Apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) in the Help Center. ## Starter guide ### Prerequisites #### Update to latest SDK version To enable Session Replay in your app and get the most stable version, it is required to [upgrade the SDK](https://docs.contentsquare.com/en/android/#install-the-sdk) to its latest version. #### Implement screen tracking Ensure screen tracking is implemented, since Session Replay collection starts at the first screenview event. See [Track screens](https://docs.contentsquare.com/en/android/track-screens/). #### Handle User consent Ensure user consent is handled for Contentsquare data collection, especially if you're implementing the SDK for the first time. See [Privacy](https://docs.contentsquare.com/en/android/privacy/) section. Moreover if you need to obtain a specific end-user's consent for Session Replay or to start Session Replay data collection only under certain conditions (in specific geolocations for instance), see [Define when Session Replay starts](#define-when-session-replay-starts) #### Add Gradle dependency for Jetpack Compose To enable Jetpack Compose support in Session Replay, it is necessary to add a new Gradle dependency to your Gradle build file. Make sure to follow the [Track screens](https://docs.contentsquare.com/en/android/track-screens/#jetpack-compose-support) section. Note Mandatory data collection settings are configured by Contentsquare in your project parameters. [Learn more about Data collection configurations ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) on the Help Center. ### Configure Session Replay masking #### Masking behavior By default, the Contentsquare SDK is configured to mask all content displayed on the user interface (UI) to prevent unnecessary data collection. For more details, see what a fully masked screen looks like in [Masking mechanisms](#masking-mechanisms). **For testing purposes**, use this setup: * Either unmasking all the content by setting the [default masking](#default-masking) status to false. * Or unmasking most content with the [Text and Image unmasking configuration ↗](https://support.contentsquare.com/hc/en-us/articles/37271682878353-Data-masking-in-Session-Replay-Mobile-Apps) in your Console parameters. **For more granular control in deployment mode**, you can use the [SDK public masking APIs](#public-masking-apis) to fine-tune exactly which elements remain masked. Warning Always keep sensitive data masked to ensure compliance with privacy regulations and to protect users' personal data. ### Configure Event-Triggered Replays (optional) If Event-Triggered Replays is included in your contract, you can set up ETR events to enable specific screen and session collection in Session Replay. See [Event-Triggered Replays (ETR)](#event-triggered-replays-etr). ### Configure Webviews (optional) If your mobile app includes Webviews, specific implementation steps are required to ensure they are properly reflected in Session Replay: * Implement [Webview tracking](https://docs.contentsquare.com/en/webview-tracking-tag/) * Handle [personal data within WebViews](https://docs.contentsquare.com/en/webview-tracking-tag/session-replay/#personal-data-handling) ### Test your setup #### Enable Session Replay on your device If the Session Replay sampling rate is less than 100%, only a portion of sessions are collected. To ensure data collection on your device for testing and debugging purposes, you can force it from the In-app Features settings by following these steps: 1. [Enable In-app Features](https://docs.contentsquare.com/en/android/in-app-features/#enable-in-app-features) 2. Open In-app Features settings with a long press on the screenshot button 3. Under "Session Replay", toggle "Enable Session Replay" on 4. Kill the app 5. Start app, a new session is starting with Session Replay enabled  #### How do I know if Session Replay is enabled? There are 2 places where you can check if Session Replay is enabled: **In the logs:** The log `CSLIB|SessionReplay: Session Replay is starting.` will confirm that Session Replay is enabled. **In in-app features settings:** Below the "Enable Session Replay" *(see below [Access the replay](#access-the-replay))*, you will either see: * `No replay link available`, which means Session Replay is not running for the current session * `Get Replay link`, which means Session Replay is running for the current session #### Access the Replay The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay your session up to the previous screenview if the session is still running. Since 4.6.0, the Session can be accessed by tapping on the `Get replay link` button from the in-app features settings:  ## Define when Session Replay starts If you need to ensure that Session Replay data is collected only under certain conditions — for example, only after receiving explicit user consent for Session Replay or in specific geolocations — follow these instructions: ### Disable Automatic Session Replay Initialization 1. Deactivate SDK autostart as explained in [Disabling Automatic SDK Initialization](https://docs.contentsquare.com/en/android/disable-autostart/) 2. Call `Contentsquare.configure(ContentsquareOptions(isSessionReplayAutoStartEnabled = false))` **before** `start()`. The initialization of the SDK should look like this: ```kotlin Contentsquare.configure(ContentsquareOptions(isSessionReplayAutoStartEnabled = false)) Contentsquare.start(context) ``` Warning `configure` must be called before `start` ### Start Session Replay Once your app has determined that Session Replay can start — for example, via a reverse geocoding service or after receiving specific user consent for Session Replay — you can call `Contentsquare.startSessionReplay()` to start Session Replay. Note Calling `startSessionReplay()` does not force Session Replay data collection. It enables the Session Replay module, allowing it to begin checking whether the global Replay sampling rate or Event Triggered Replay conditions are met. Session Replay data collection will only start if these conditions are satisfied. For more information, see [Data collection for Session Replay (Apps) ↗](https://support.contentsquare.com/hc/en-us/articles/37271951720721) on the Help Center. The following log confirms Session Replay data collection has started: ```plaintext CSLIB: Session Replay is starting ``` ## Personal Data Masking The Session Replay feature replays every interaction of your users with your app. to respect the user's right to privacy, the Contentsquare SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our [Masking rules](#masking-rules) Warning If you decide to use unmask elements leading to the collection of new data or use already collected data but for a different purpose, it is up to you to update your Google Play Data Safety declaration accordingly. Examples of data potentially collected via un-masked session Replay include: search history, purchase history, advertising data, etc. See [Types of data and purpose](../privacy/). Contentsquare is not intended nor designed to collect sensitive personal data (such as health, financial, or racial data). It is the customer's responsibility not to send any sensitive personal data to Contentsquare. ### Masking mechanisms Every single UI element is converted into a highly pixelated image to reach a very low resolution. Text and images will appear very blurry so that the content cannot be identified. #### Original vs Replay fully masked Masking depends on the type of element: * **Images**: A blurred representation is sent in place of the original content. * **Text**: Replaced by \* (asterisk) characters, matching the original character count. Whitespace characters (spaces, tabs, line breaks) are preserved. For instance, `the lazy fox` is collected as `*** **** ***`. All other visual properties (text color, background color, alignment, etc.) are collected. * **TextFields**: Same as Text * **TextField with `obscureText`**: Both the obscured text and the briefly revealed character are replaced by • (bullet). * **Containers**: Plain backgrounds, drawables, and colors are send as-is. Other background elements follow the rules above. * **Other types**: A blurred representation is sent in place of the original content.  ### Masking rules Masking rules can be applied in two ways: 1. **Through remote masking configuration in the CSQ Console (for admin users):** These configurations are managed directly in the Console and take effect for all sessions as soon as the app is restarted or brought to the foreground See [How to customize masking rules from the Data Masking tab ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) in the Help Center. 2. **Using public masking APIs in the SDK (for mobile application developers):** These configurations require developer implementation and will be applied only after the mobile app has gone through its release cycle. Masking rules set via the CSQ Console or the public APIs are applied according to different priorities, as described below. The SDK determines whether a view is masked by evaluating the rules in the order specified below. Once a rule is triggered, the state is set, and subsequent rules are not applied: #### General case | Rule | Configured via | | - | - | | 1. The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text or Image masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. An [instance](#maskingun-masking-by-instance) is specifically masked or unmasked | API | | 4. A [type](#maskingun-masking-by-type) is masked or unmasked | API | | 5. A [parent](#masking-and-unmasking-behaviors-on-a-parent-view) is specifically masked or unmasked | API | | 6. A parent [type](#maskingun-masking-by-type) is masked or unmasked | API | | 7. Remote Text or Image unmasking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 8. Otherwise the [default masking state](#default-masking) is applied | API | #### Exception: Text input fields Special consideration is needed for text inputs, as the risk of leaking personal data is higher with these elements. As a result, the SDK applies slightly different rules to `EditText` and Jetpack Compose `TextField`: | Rule | Configured via | | - | - | | 1. The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text input masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. An `EditText` [instance](#maskingun-masking-by-instance) is specifically unmasked | API | | 4. The `EditText` [type](#maskingun-masking-by-type) is unmasked | API | | 5. Otherwise a text input field remains masked | default | Specifically, default masking and parent masking won't change the masking state of text inputs. ### Public masking APIs #### Default masking Warning You should not perform any call on Contentsquare API before the first visible Activity to be sure our SDK is initialized. If you perform a call too soon, it will be discarded and you will see the following log: ```plaintext CSLIB Contentsquare SDK: Unable to call the public API, make sure you are not opted out of the Contentsquare tracker and SDK was correctly initialized. ``` All Android View elements, their subclasses and Jetpack Compose components are fully masked by default. The SDK provides an API to change the default masking state: ```kotlin /** * Set the default masking of all the views. * @param masked true mask all views by default. * false unmask all views by default. * The default value is true. */ setDefaultMasking(boolean masked) ``` Note If you change the default masking state to `false`, `EditText` will stay masked by default. This does not apply to Jetpack Compose composables, meaning `TextField` components will also be unmasked. #### Masking/Un-masking by instance Warning Animations are not supported when masking by instance. To know more, see [Animations are not supported when masking by instance or type](#animations-are-unsupported-when-masking-by-instance-or-type). * Views Use `mask(View view)` and `unmask(View view)` methods to mask or unmask a specific view instance. ```kotlin /** * Masks a specific {@link View} during data collection for Session Replay. * * @param view an instance of {@link View} to be masked. */ public static void mask(@NonNull View view) ``` ```kotlin /** * Unmasks a specific {@link View} during data collection for Session Replay. * * @param view an instance of {@link View} to be unmasked. */ public static void unMask(@NonNull View view) ``` Following the previous example, we have the views hierarchy in which all instances of TextView type are unmasked with the default masking state of all the views are masked by default.  In this example you may want to mask a specific text view TextView1, call `mask(textView1)` then this instance of TextView1 will be masked. As you can see in this example the view instance rule overrides the type rule and the default rule. * Jetpack Compose Use the `Modifier.sessionReplayMask(enableMasking: Boolean)` extension function to mask or unmask a composable. ```kotlin /** * [Modifier] extension function that provides the facility to mask or unmask a composable in * Session Replay. * * @param enableMasking `true` when the target composable has to be masked; `false` otherwise. */ fun Modifier.sessionReplayMask(enableMasking: Boolean): Modifier ``` For example: ```kotlin Text( text = "Text", modifier = Modifier.sessionReplayMask(true) // mask this `Text` composable ) ``` #### Masking/Un-masking by type Although the SDK allows masking elements by type for convenience but it isn't the recommended masking mechanism because it impacts all screens of your application. Use this when you have a specific class for presenting user information or for displaying the user profile picture to make sure it always stays masked, for instance. Warning Animations are not supported when masking by type. To know more, see [Animations are not supported when masking by instance or type](#animations-are-unsupported-when-masking-by-instance-or-type). * Views Use `mask(Class type)` and `unmask(Class type)` methods to mask or unmask a specific type. ```kotlin /* * Masks all instances of a specific {@link Class} * and subclass of a view during data collection for Session Replay. * * @param type {@link Class} to be masked. */ public static void mask(@NonNull Class type) ``` ```kotlin /** * Unmasks all instances of a specific {@link Class} * and subclass of a view during data collection for Session Replay. * * @param type {@link Class} to be unmasked. */ public static void unMask(@NonNull Class type) ``` For example, given the views hierarchy:  The default masking state of all the views is masked by default and for example, you may want to unmask all **TextView** types, you can call `unMask(TextView.class)` then all instances of **TextView** type will be unmasked. In this example, the button is also impacted by the unmask API because the button is also a **TextView** type (a subclass of **TextView**). You can also notice that the **EditText** is also a **TextView** type but it is not impacted by `unMask(TextView.class)` call because the **EditText** type is masked by default [see Masking rules priority](#masking-rules). * Jetpack Compose As of now, it is not possible to mask or unmask composables by type. Alternatively, you can mask or unmask a group of composables by wrapping multiple composables within the same parent, then applying the `Modifier.sessionReplayMask(enableMasking: Boolean)` modifier on the parent. ##### Masking and Unmasking behaviors on a parent view * Views The masking of the ViewGroup (RelativeLayout, LinearLayout, ConstraintLayout, etc..) is supported. If a parent view is masked all of its children will inherit the masking state from the parent. The children's view masking state can be overridden by using a specific API to mask or unmask by instance or by type.  For example, given the view hierarchy with the default masking state. All the views are masked by default in the initial state and in this case, you may want to unmask all children's views of the parent view **LinearLayout1**, you can call `unMask(linearLayout1)` then all children views of the parent view **LinearLayout1** will be unmasked. As noticed here the **EditText** is not impacted from the parent call because the **EditText** type is masked by default [Masking rules priority](#masking-rules). * Jetpack Compose The masking of a parent layout (for example `Column`, `Row`, or `Box`) is supported. If a parent composable is masked, then all of its children will inherit the masking state from the parent. The children's masking state can be overridden by using the dedicated `Modifier.sessionReplayMask(enableMasking: Boolean)` function. For example: ```kotlin Column( modifier = Modifier.sessionReplayMask(true) // mask every children ) { Row { Text( text = "Text", modifier = Modifier.sessionReplayMask(false) // unmask this `Text` composable ) } Row { Text( text = "Text 2", // this `Text` composable will be masked, as it inherits the masking state from the parent ) } } ``` #### Masking and Unmasking of Bottom Sheets, Dialogs, and Menus If you were using Contentsquare Android SDK versions before 4.39.0 in your mobile app, then masking is automatically enforced on all bottom sheets, dialogs, and menus, as these elements were not supported in earlier versions. To unmask any of these elements, contact your CSM to disable the forced masking and use the APIs described below. **Bottoms Sheets** Bottom sheets can be masked or unmasked using the same APIs available for any other view, whether you're working with Android Views or Jetpack Compose. To apply the masking behavior, ensure that you call the appropriate API after the bottom sheet has been created. **AlertDialogs** * Views Dialogs, such as AlertDialog, TimePickerDialog, and DatePickerDialog, can be masked or unmasked using the APIs provided below. Also, the masking behavior of individual components within these dialogs can be customized using the provided Kotlin extension functions. For instance, if an AlertDialog is fully masked by default, you can selectively unmask specific elements—such as the title or action buttons—using the extension functions provided below for more granular control. For example, given an AlertDialog with the default masking state, all views in the dialog are masked by default in the initial state. In this case, you may want to unmask the title and buttons of the dialog. To do that, we provide Kotlin extension functions to the Dialog API to make it easy. ```kotlin /** * Masks the entire [AlertDialog]. */ fun AlertDialog.csqMask() /** * Masks the title of the [AlertDialog]. */ fun AlertDialog.csqMaskTitle() /** * Masks the message of the [AlertDialog]. */ fun AlertDialog.csqMaskMessage() /** * Masks the positive button of the [AlertDialog]. */ fun AlertDialog.csqMaskPositiveButton() /** * Masks the negative button of the [AlertDialog]. */ fun AlertDialog.csqMaskNegativeButton() /** * Unmasks the entire [AlertDialog]. */ fun AlertDialog.csqUnMask() /** * Unmasks the title of the [AlertDialog]. */ fun AlertDialog.csqUnMaskTitle() /** * Unmasks the message of the [AlertDialog]. */ fun AlertDialog.csqUnMaskMessage() /** * Unmasks the positive button of the [AlertDialog]. */ fun AlertDialog.csqUnMaskPositiveButton() /** * Unmasks the negative button of the [AlertDialog]. */ fun AlertDialog.csqUnMaskNegativeButton() ``` Note The mask API for dialogs should be called immediately after the `show` method in the main thread. Example: ```kotlin val builder: AlertDialog.Builder = AlertDialog.Builder(context) builder.setMessage("This is a dialog. This text should be masked") builder.setTitle("Dialog Title") builder.setCancelable(true) builder.setPositiveButton("Close") { ... } builder.setNegativeButton("Idle") { ... } val alertDialog: AlertDialog = builder.create() alertDialog.show() alertDialog.csqUnMaskTitle() alertDialog.csqUnMaskPositiveButton() alertDialog.csqUnMaskNegativeButton() ``` * Jetpack Compose The AlertDialog composable in Jetpack Compose can be masked or unmasked using the same APIs applied to other composables. Simply add the appropriate modifier to the elements you want to mask or unmask within the dialog. Example: ```kotlin AlertDialog( icon = { Icon(icon, contentDescription = "Example Icon") }, title = { Text(text = dialogTitle) }, text = { Text( text = dialogText modifier = Modifier.sessionReplayMask(true) ) }, onDismissRequest = { onDismissRequest() }, confirmButton = { TextButton( onClick = { onConfirmation() } ) { Text( "Confirm", modifier = Modifier.sessionReplayMask(false) ) } } ) ``` **TimePickerDialog and DatePickerDialog** * Views Time and date pickers function similarly to AlertDialogs but contain their own distinct UI components. These sections can be selectively masked or unmasked using the APIs provided below. To support masking on this dialogs we added the following APIs: ```kotlin /** * Masks the entire [DatePickerDialog]. */ fun DatePickerDialog.csqMask() /** * Masks the header of the DatePicker, which typically displays the selected date. * This affects the [DatePickerDialog]. */ fun DatePickerDialog.csqMaskHeader() /** * Masks the calendar view (day picker) of the [DatePickerDialog]. */ fun DatePickerDialog.csqMaskCalendar() /** * Masks the button panel of the [DatePickerDialog], typically containing "OK" and "Cancel" buttons. */ fun DatePickerDialog.csqMaskButtonPanel() /** * Unmasks the entire [DatePickerDialog]. */ fun DatePickerDialog.csqUnMask() /** * Unmasks the header of the DatePicker. * This affects the [DatePickerDialog]. */ fun DatePickerDialog.csqUnMaskHeader() /** * Unmasks the calendar view (day picker) of the DatePicker. * This affects the [DatePickerDialog]. */ fun DatePickerDialog.csqUnMaskCalendar() /** * Unmasks the button panel of the [DatePickerDialog]. */ fun DatePickerDialog.csqUnMaskButtonPanel() /** * Masks the entire TimePicker view within the [TimePickerDialog]. */ fun TimePickerDialog.csqMask() /** * Masks the header of the TimePicker, including the time display and input mode header. * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqMaskHeader() /** * Masks the radial picker (clock face) of the TimePicker. * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqMaskRadialPicker() /** * Masks the input mode view of the TimePicker (keyboard input for time). * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqMaskInputMode() /** * Masks the button panel of the [TimePickerDialog], including positive, negative, and toggle mode buttons. */ fun TimePickerDialog.csqMaskButtonPanel() /** * Unmasks the entire TimePicker view within the [TimePickerDialog]. */ fun TimePickerDialog.csqUnMask() /** * Unmasks the header of the TimePicker, including the time display and input mode header. * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqUnMaskHeader() /** * Unmasks the radial picker (clock face) of the TimePicker. * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqUnMaskRadialPicker() /** * Unmasks the input mode view of the TimePicker (keyboard input for time). * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqUnMaskInputMode() /** * Unmasks the button panel of the [TimePickerDialog], including positive, negative, and toggle mode buttons. */ fun TimePickerDialog.csqUnMaskButtonPanel() ``` * Jetpack Compose The Time and Picker composables in Jetpack Compose can be masked or unmasked using the same APIs applied to other composables. Simply add the appropriate modifier to the elements you want to mask or unmask within the dialog. **Custom Dialogs** * Views If you're creating a custom dialog by extending the Dialog base class and inflating a layout using the setContentView method, you can mask or unmask individual views within your custom view hierarchy, using the masking APIs. * Jetpack Compose The custom dialogs in Jetpack Compose can be masked or unmasked using the same APIs applied to other composables. Simply add the appropriate modifier to the elements you want to mask or unmask within the dialog. **Menu Items** * Views Menu items captured by Session Replay can be selectively masked or unmasked. For example, consider a context menu, including an action item and another item displaying the user's name (see XML example below). If masking is disabled by default, you may want to mask sensitive menu items to prevent personal data from appearing in session replays. Conversely, if masking is enabled by default, you may choose to unmask certain non-sensitive items to keep them visible. To achieve this, simply apply masking or unmasking to individual menu items as needed. ```xml ``` Note This API does not need to be called strictly after menu inflation; it can be invoked earlier if necessary. However, as a best practice, apply it during or after menu inflation when you have clear context about what is being masked and where. ```kotlin override fun onCreateOptionsMenu(menu: Menu): Boolean { // Inflate the menu; this adds items to the action bar if it is present. menuInflater.inflate(R.menu.activity_main, menu) val item = menu.findItem(R.id.profile_settings) item.title = current_user.fullName // Unmask action menu item Contentsquare.unMaskMenuItem(R.id.action_settings) // Mask profile menu item that contains user's name Contentsquare.maskMenuItem(R.id.profile_settings) return true } ``` * Jetpack Compose The Menu components in Jetpack Compose can be masked or unmasked using the same APIs applied to other composables. Add the appropriate modifier to the elements you want to mask or unmask within the menu. #### Handling Transparent Views The SDK processes masked views first (using the [Masking rules priority](#masking-rules)), ensuring that if a view has transparency and is not masked, it will not expose any personal data since masked views have already been processed. This approach ensures the protection of sensitive information, even in UIs with transparent views. Warning Keep in mind that if the view below the transparent view is a **WebView**, and you unmask the view on top of it (for example a dialog progress bar) it will leak the content of the WebView. This is a known limitation. On the left, a possible implementation of a payment screen in a WebView. On the right, the result in Session Replay.  ### Implementation recommendations #### Where to perform masking operations Masking operation should be performed before the first draw of the view and it should always be called on the UI thread. At the **Activity** level, call the masking API methods on the `onCreate` lifecycle method. At the **Fragment** level, call the masking API methods on the `onViewCreated` lifecycle method. Note The masking API stores the view element to be masked or unmasked inside a WeakHashMap, repeating the masking operation multiple times on the same element will override the old value that is already stored in the map. #### Keeping track of what is masked The SDK doesn't provide a list of what is currently masked, if you need to keep track, you probably will have to write your specific wrapper. #### Masking operations performance impact You can call `unmask(View view)` multiple times without impacting the SDK performance or your app. ### Masking limitations #### Maps You can mask or unmask a Map, that will then be captured as an image in the replay. However, you won't be able to mask or unmask specific elements within the Map. #### Navigate between fragments using animations Masking rules don't apply on Fragments using animations. So to mask this type of Fragment, mask the container view where the Fragment is inserted, rather than masking its content. This ensures that the Fragment content remains masked during transitions. Additionally, you can unmask some specific views within the Fragment content, by using `Contentsquare.unmask(View)` or `Modifier.sessionReplayMask(false)`. #### Rotated or Scaled Views The masking solution relies on the bounding box reported by a view to determine the area that should be masked. In most cases, this approach is sufficient, as the bounding box accurately reflects the view's position and dimensions on the screen. However, when a view is rotated or scaled, the bounding box no longer represents the view's actual position or size after the transformation. To prevent any personal data from being leaked, we advise adopting one of the following approaches: * **Mask the Parent View**: Apply masking to the parent container of the transformed view. This ensures that the entire area encompassing the rotated or scaled view is covered, regardless of transformations. * **Mask the Entire Window**: In case of complex layouts, transformations, or critical scenarios where absolute certainty is required, mask the entire window to guarantee that no personal data is exposed. These approaches provide the highest level of confidence in preventing personal data leakage while working within the constraints of the current implementation. ## Event-Triggered Replays (ETR) Event-Triggered Replays (ETR) is an add-on feature that allows you to selectively collect specific screens or sessions for Session Replay, based on predefined custom events. Once configured, ETR events can be used to filter specific replays, or view these events as they happen in the player event stream. To enable ETR, contact your CSM or Implementation Manager. For more information, see [Event-Triggered Replays ↗](https://support.contentsquare.com/hc/en-us/articles/4412027865874) in the Help Center. Note When ETR is enabled, the SDK collects data for the entire session even if none of the ETR methods described below are called. After collection, only the sessions or screens that match the global replay sampling rate or are associated with ETR events are retained. As a result, you may notice a network activity during all sessions, regardless of whether ETR has been triggered or not. Warning To protect end-user personal data, ensure that appropriate masking configurations are applied to all screens even the ones that are not associated with ETR events. ### Trigger Replay for the Session Use the following function to trigger Session Replay for the entire current session, with the parameter `name` as "ETR event". ```kotlin Contentsquare.triggerReplayForCurrentSession(name: name) ``` ### Trigger Replay for the Screen Use the following function to trigger Session Replay for the entire current screen, with the parameter `name` as "ETR event". ```kotlin Contentsquare.triggerReplayForCurrentScreen(name: name) ``` ## Advanced features for Experience Monitoring Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. ### Send user identifier Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier: email, phone number, customer ID… As these values are typically personal data, from the moment the SDK is collecting the User Identifier, we immediately encode the value using a hashing algorithm so that the information is hidden and can never be accessed. Use the following code to send a user identifier: ```kotlin Contentsquare.sendUserIdentifier("any_identifier") ``` When called, the SDK will log: ```plaintext CSLIB: User identifier hashed sent {value} ``` #### Sending a user identifier for each session You may want to send the user identifier for each session. While triggering the user identifier at app launch will cover most cases, it will not be enough. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See Session definition section for more information. That is why we also recommend sending the user identifier every time the app enters foreground. You can use the [`ProcessLifecycleOwner` Class ↗](https://developer.android.com/reference/androidx/lifecycle/ProcessLifecycleOwner) to detect foreground and trigger a `sendUserIdentifier()`. #### Limitations * User identifier max length is 100 characters (if the limit is exceeded, the user identifier will not be handled and you will see an error message in the Console/Logcat) * Only the first 15 user identifiers per view will be processed on server side * The SDK will trim and lowercase user identifier * User identifier event are not visible in Log visualizer ## Integrations Contentsquare provides the ability to retrieve the link of the replay to be attached to other vendors such as Voice of Customer or Crash reporting tools. ### Get current replay Link Generate a link to the replay of the current session. This link can be pushed to any internal or 3rd-party tool as a custom property/variable. For instance, you can add the replay link to: * Each user request sent to your customer service tool * Each user voting in your Voice of Customer tool * Each user session in your App Performance, Observability tool * ... Note The replay link can also be accessed from the in-app features settings. See [Access the Replay](#access-the-replay)/ Warning For the API to return a valid replay link, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before it's called, since Session Replay only starts after the first screenview event. Use the following code to retrieve a Session Replay link each time it changes: ```kotlin Contentsquare.onSessionReplayLinkChange { link -> // Send link to your customer service tool } ``` To unregister the current callback, pass `null` as the argument: ```kotlin Contentsquare.onSessionReplayLinkChange(null) ``` To avoid memory leaks, you can use the [`ProcessLifecycleOwner` Class ↗](https://developer.android.com/reference/androidx/lifecycle/ProcessLifecycleOwner) to detect foreground and background events and register or unregister the callback. When a new link is available, the SDK will also log: ```plaintext CSLIB: SessionReplay link: https://app.contentsquare.com/quick-playback/index.html?pid={projectId}&uu={userId}&sn={sessionNumber}&recordingType=cs ``` Warning You can only have one callback at a time. Calling this API twice will override the previous callback. The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay the session up to the previous screenview if the session is still running. ## How Session Replay works ### Initialization Sessions can be collected for Session Replay if the Session Replay feature has been enabled for your project and the session matches the collection criteria. The following conditions will have an impact on which sessions will be collected: * **User consent**: The users have given their **consent** (if required) * **Collection rate**: The session is being **drawn for collection** (see Collection rate below) * **Compatibility**: The **OS version** is supported. * **App version**: The **app version** is not part of the block list (see App version block list below) When Session Replay is turned off, no content specific to Session Replay is collected whatsoever. The standard Contentsquare analytics tracking remains unaffected by this. #### Collection rate Data collection for Session Replay is based on a percentage of the total sessions. By default data collection for Session Replay is disabled. During the early access phase, the percentage or collected sessions will be set to 1% at the beginning. It will then be adjusted according to: * The traffic on your app * The volume of collected sessions set in the contract #### Compatibility See [compatibility](https://docs.contentsquare.com/en/android/compatibility/). #### App version block list Contentsquare team can add versions of your app in the block list to make sure Session Replay does not start on these versions. This is done when a problem is discovered on a specific version of your app, such as a Personal Data for which the masking was forgotten. This allows to keep Session Replay to work on the other app versions (especially the new ones with the fix). ### Data collection The SDK monitors the application lifecycle events and the view hierarchy, and generates Session Replay data from the behavior of the app, the content of the screen and the interaction of the user. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. Tip Data collection for Session Replay will start at the 1st screenview event. ### Quality levels Session Replay has three quality levels available: High, Medium, Low. Quality level is defined by the frame rate and the image quality. The quality level is defined independently for **Wi-Fi** and **Cellular Network**. The default level for both is **Medium**. For more information on network data consumption see: [Performance Impact section](#performance-impact). Note If you require a particular setting, reach out to your Contentsquare contact that will make the adjustment in the project configuration. #### Quality-level examples Select the image to open it in full size and GIF format. [](https://docs.contentsquare.com/_astro/android-quality-levelgrand.Djk7sO10.gif) ### Network and Storage By default, Session Replay data can be sent over **cellular network**. If the particular context of your app or users requires a very limited impact on cellular data consumption, **sending data over cellular network can be completely disabled**. Once disabled, data will be sent when the device is using Wi-Fi. Reach out to your Contentsquare contact that will make the adjustment in the project configuration. #### Storage Before being sent, data is stored in local files on disk up to 20MB on Android. When the limit is reached, all collected data is dropped, and data collection continues. Then, every time the limit is reached again, the same process is applied. ### Requests The maximum request size is 1Mbyte. Requests are sent: * On screen change * When [Replay Link API](#get-current-replay-link) is called ## Performance impact ### Performance impact mitigation Most operations related to Session Replay are performed on dedicated background threads, for a minimal impact on the main thread. If CPU usage is too high for background tasks, some expensive calculations will be discarded. To make sure of this, we run performance tests on testing applications, along with the Android profiler. If too much time is spent on the main thread, the [quality level](#quality-levels) will decrease automatically: from high to medium to low to a complete stop if required. Once conditions are back to normal, quality level will be changed back to the default value set in the configuration. We defined our network strategy to have the lesser impact on CPU, memory, and data consumption of the users devices. We measure these impacts, using the Android profiler and dedicated logging system, for each release of our SDK. You can reduce the quality level if you want to favor performance impact over quality. ### Performance test results We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. The performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | Pixel 5 | | Android version | 34 (Android 14) | | Quality level | High | | Default Masking State | Disabled | Note That the numbers provided below will vary depending on the user's device and Android version. | Property | Value | | - | - | | Total % on main thread (CPU Profiling) | <15 % | | Memory overhead | 15 MB | | Session Replay data transmitted over network during 1 minute of use: | | | - with "High quality" level | <838 KB | | - with "Medium quality" level | <545 KB | | - with "Low quality" level | <369 KB | #### Additional info on performance test procedure **CPU Usage Test** We are profiling our Demo app with and without the SDK dependency by following the same use case. We are measuring the CPU peak for both versions of the app and we are computing the difference. **RAM Usage Test** We are profiling our Demo app with and without the SDK dependency by following the same use case. We are measuring the RAM usage peak for both versions of the app and we are computing the difference. **Memory Leak Test** We are profiling our demo app and we are using the ADB Monkey tool to create random user input events. During this time we are monitoring the RAM behavior for any anomaly. We are using the Memory Profiler to identify leaks. **Data consumption** We replay a predefined, repeatable, and automated user scenario on our demo app and all data sent is measured in kB/min. **JankStats** If you use the alpha library from Google to monitor the jank frames and you already have some jank frames in your application (main thread overwhelmed), you can expect an increase of 1% or 2% with data collection for Session Replay activated. Data collection for Session Replay requires to perform tasks on the main thread (screen capture and view hierarchy inspection). ## Known limitations ### SurfaceView [SurfaceView ↗](https://developer.android.com/reference/android/view/SurfaceView) are not supported for now. They will be displayed as white views. This includes views used for video streaming and camera previews, ensuring that no such content is captured. ### Animations are unsupported when masking by instance or type When views are masked by instance or type, personal data may leak during animations in the collected session. To prevent this, there are two possible options: masking the entire screen or masking around the animation. **Mask the entire Screen** Apply default masking to the entire screen with `setDefaultMasking(true)`, without using any [instance-based](#maskingun-masking-by-instance) or [type-based](#maskingun-masking-by-type) masking/unmasking. After the user navigates to another screen, you can deactivate the default masking with `setDefaultMasking(false)` and use any view masking APIs. **Mask around the animation** Mask the entire screen just before the animation, following the [Masking rules priority](#masking-rules). This involves reversing any [instance-based](#maskingun-masking-by-instance) or [type-based](#maskingun-masking-by-type) masking/unmasking for views and then calling `setDefaultMasking(true)`. After the animation, you can restore the previous masking settings by instance or type. ## Troubleshooting ### Requests are not sent from an Android emulator If you struggle to watch a replay created on an emulator/simulator, it may be due to some network constraints applied on your computer (VPN, company network restrictions, etc.). Check your configuration or use a real device. See [Requests are failing](https://docs.contentsquare.com/en/android/troubleshooting/#requests-are-failing) for more information about our endpoints and requests. #### Very long session on an Android emulator It is important to remember that **an app kill does not end a session**. See [Session definition](https://docs.contentsquare.com/en/android/how-the-sdk-works/#session-definition) for more information. If you leave the simulator/emulator running with the app in foreground, the session will not end, even if you are inactive. To better reflect actual end user behavior and avoid unusually long sessions (last hours), put the app in background or kill it. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Session Replay","description":"How to implement Session Replay with the Contentsquare Android SDK","url":"https://docs.contentsquare.com/en/android/session-replay/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Surveys - Android (classic) description: How to implement Surveys in your Android app lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/android/surveys/ md: https://docs.contentsquare.com/en/android/surveys/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). Note Surveys are in Beta. If you are interested, reach out to your Contentsquare contact. Learn how to integrate, configure, and validate surveys using the Contentsquare SDK. Contentsquare mobile surveys enable collection of user feedback through configurable surveys displayed in mobile applications. These surveys capture the voice of your customers, providing valuable insights into how users perceive your app. By analyzing survey responses, you can make informed decisions for site improvements or identify issues you may not have been aware of. ## Before you begin To enable Surveys in your app and get the most stable version, [install](https://docs.contentsquare.com/en/android/), or [upgrade](https://docs.contentsquare.com/en/android/changelog/) the SDK to its latest version. If you install the SDK for the first time, these steps are required: * [Install the SDK](https://docs.contentsquare.com/en/android/#install-the-sdk) * [Check the logs](https://docs.contentsquare.com/en/android/#check-the-logs) * [Get user consent](https://docs.contentsquare.com/en/android/#get-user-consent) ## Trigger surveys Triggering surveys allows for a clear separation between survey management and app development: * Marketing and Product Teams use the Contentsquare platform to create surveys and decide when they should appear by assigning them to a specific trigger (for example, `purchase-complete`). * Developers place these triggers in the application's code at key moments in the user journey. This allows your business teams to launch, update, and manage survey campaigns independently, without requiring a new app release. ### Step 1: Define and implement triggers Your mobile app can trigger a survey by referencing a predefined trigger name tied to a specific event or behavior. ```kotlin Contentsquare.triggerSurvey(triggerName: String) ``` Triggers act as flexible placeholders and are not bound to individual surveys—allowing your business team to assign or update surveys later without requiring code changes. For example, if you want to collect Net Promoter Score (NPS) feedback after a user completes a purchase: 1. Determine the precise moments in the user journey where you want to collect feedback and define the trigger name, for example `purchase-complete`. 2. Implement this trigger right after the purchase completes: ```kotlin Contentsquare.triggerSurvey("purchase-complete") ``` When this code is executed, it signals that the `purchase-complete` event has occurred, which in turn displays the corresponding survey to the user. Define triggers early Implement as many relevant survey triggers as possible during the initial setup. This reduces the need for future app updates if new surveys are added later. Triggers can safely exist in the code even if no survey is currently linked to them—these events will be ignored until a matching survey is configured. ### Step 2: Set up your first test survey To validate the integration, start by creating a test survey in the test environment of your application. * Create and activate a test survey on the Surveys platform by following [these steps ↗](https://support.contentsquare.com/hc/en-us/articles/37271718906513-How-to-create-a-survey). * When creating the survey, assign a test survey trigger — this is the trigger you'll implement in your application. ### Step 3: Validate the integration Validate the integration on the test environment of your application. 1. Implement the test survey trigger in your application code. 2. Launch the app and navigate as an end user to simulate the behavior or event associated with the trigger. 3. Confirm that the survey UI appears as expected. 4. Check SDK logs to ensure the trigger is recognized. Look for a log entry like: `CSLIB: Will attempt triggering survey`. 5. After successful validation, deactivate the test survey. ## Key considerations * Surveys can only be triggered and displayed when the device has an active internet connection * Only one survey can be displayed for a given trigger. If multiple surveys are configured for the same trigger, the SDK will display the one with the most specific matching criteria. If the criteria are identical, the most recently created survey will be shown ## Collected data The SDK collects the following data related to surveys: * Survey interaction events (for example, impressions, completion, or close actions) * Targeting parameters used for displaying surveys, such as the targeting percentage * Survey responses ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Surveys","description":"How to implement Surveys in your Android app","url":"https://docs.contentsquare.com/en/android/surveys/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Third-party libraries license - Android (classic) description: Contentsquare includes several third-party libraries, which are licensed under their own respective licenses lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/android/third-party-libraries-license/ md: https://docs.contentsquare.com/en/android/third-party-libraries-license/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). The Android SDK includes third-party libraries; the table below lists each library, its license, and copyright notice. | Libraries | License | Copyright | | - | - | - | | AndroidX | Apache-2.0 license | Copyright 2024 The Android Open Source Project Licensed under the Apache License, Version 2.0 (the "License"); | | KotlinX | Apache-2.0 license | Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors. | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Third-party libraries license","description":"Contentsquare includes several third-party libraries, which are licensed under their own respective licenses","url":"https://docs.contentsquare.com/en/android/third-party-libraries-license/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Track custom variables - Android (classic) description: Track custom variables with the Contentsquare Android SDK lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/android/track-custom-variables/ md: https://docs.contentsquare.com/en/android/track-custom-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). Custom variables attach additional information about the screen, user, or session to screenview events. For example, they can include information on the current layout of a screen, like dark or light mode. ## Defining custom variables To define and send custom variables, follow this: * Java ```java CustomVar customVar1 = new CustomVar(1, "CustomVarName1", "CustomVarValue1"); CustomVar customVar2 = new CustomVar(2, "CustomVarName2", "CustomVarValue2"); CustomVar[] customVars = new CustomVar[] {customVar1, customVar2}; Contentsquare.send("ScreenName", customVars); ``` Warning For consistent analytics, use the same index/name pair values across your application: **Screen A** ```java CustomVar customVar4 = new CustomVar(4, "hero_banner_type", "carousel"); CustomVar[] customVars = new CustomVar[] {customVar4}; Contentsquare.send("ScreenA", customVars); ``` **Screen B** ```java CustomVar customVar4 = new CustomVar(4, "hero_banner_type", "slider"); CustomVar[] customVars = new CustomVar[] {customVar4}; Contentsquare.send("ScreenB", customVars); ``` * Kotlin ```kotlin val customVar1 = CustomVar(1, "CustomVarName1", "CustomVarValue1") val customVar2 = CustomVar(2, "CustomVarName2", "CustomVarValue2") Contentsquare.send("ScreenName", arrayOf(customVar1, customVar2)) ``` Warning For consistent analytics, use the same index/name pair values across your application: **Screen A** ```kotlin val customVar4 = CustomVar(4, "hero_banner_type", "carousel") Contentsquare.send("ScreenA", arrayOf(customVar4)) ``` **Screen A** ```kotlin val customVar4 = CustomVar(4, "hero_banner_type", "slider") Contentsquare.send("ScreenB", arrayOf(customVar4)) ``` ## Limits ### On the server side * It is possible to save up to 20 distinct custom variables per screenview. If more are received, only the first 20 custom variables, based on their `index` value, will be kept. * The `index` value of custom variable is used to determine which custom variable to be kept. Only `index` value between 1 and 20 will be taken into account. ### On the SDK side * Every custom variable is composed of `index`, `name` and `value`. * If you are using the same `index` twice in a single screen only the first (`name`, `value`) pair associated with the `index` will be kept. * In case `name` (max. 512 characters) or `value` (max. 255 characters) maximum characters length is reached, the SDK will automatically trim the exceeding characters. * If `name` or `value` are empty, the SDK will instead send the literal string `"cs-empty"`. * Use a consistent `index` for a given variable within an application - for instance, if the "screen layout" is collected with an `index` of 3, use the slot 3 for this information on every screen of the application. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track custom variables","description":"Track custom variables with the Contentsquare Android SDK","url":"https://docs.contentsquare.com/en/android/track-custom-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Track dynamic variables - Android (classic) description: Track dynamic variables with the Contentsquare Android SDK lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/android/track-dynamic-variables/ md: https://docs.contentsquare.com/en/android/track-dynamic-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). Dynamic variables are additional information on the session that can be used to segment sessions. For example, they can include information on the A/B Test variations displayed to the current user. ## Defining dynamic variables To define and send a dynamic variable, directly use the key and String/Long value: ```kotlin Contentsquare.send("my key 1", "my value") Contentsquare.send("my key 2", 10) ``` **Type of the value** — The value can be either a **whole number** or a **string**. For each case, available features won't be the same in the Contentsquare app: * For **whole numbers**, you will be able to do some algebra. Example: *sessions with dynamic variable key = "numberOfFriends" and value >= 10* * For **strings**, auto-completion and Regular Expression will be available. Example: *sessions with dynamic variable key = "accountType" and value = "Premium"* ## Sending a dynamic variable for each session You may want to send a dynamic variable for each session (like the user's country or store). While **triggering the dynamic variable at app launch will cover most cases, it will not be enough**. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See [Session definition](https://docs.contentsquare.com/en/android/how-the-sdk-works/#session-definition) section for more information. That is why we also recommend **sending such dynamic variable every time the app enters foreground**. You can use the [`ProcessLifecycleOwner` Class ↗](https://developer.android.com/reference/androidx/lifecycle/ProcessLifecycleOwner) to detect foreground and trigger a dynamic variable. ## Limits ### On the server side * It is possible to save up to 40 distinct *dynamic variable keys* per screenview. If more are received, only the first 40 keys will be kept. * If you are using the same key twice on the same screenview, the last value associated with the key will be collected. ### On the SDK side * Every dynamic variable is composed of a pair of key (max. 512 characters) and value (max. 255 characters string or number of type `Long` between 0 and 232 - 1). In case these maximums length are reached, the SDK will automatically trim the exceeding characters. * If key or value are empty, the SDK will instead send the literal string "cs-empty". ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track dynamic variables","description":"Track dynamic variables with the Contentsquare Android SDK","url":"https://docs.contentsquare.com/en/android/track-dynamic-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Track transactions - Android (classic) description: Track transactions with the Contentsquare Android SDK lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/android/track-transactions/ md: https://docs.contentsquare.com/en/android/track-transactions/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). To associate a user's session with their potential purchases (and corresponding revenue), you must send the transaction via a dedicated API. For each transaction, we send: * Price (mandatory) * Currency (mandatory) * Transaction ID (optional) - Java ```java import com.contentsquare.android.api.Currencies; import com.contentsquare.android.api.model.Transaction; // Sends Transaction float price = 430.00f; String id = "id"; // Currency Currencies currency = Currencies.EUR; // or currency = "USD" Contentsquare.send(Transaction.builder(price, currency).id(id).build()); ``` - Kotlin ```kotlin import com.contentsquare.android.api.Currencies import com.contentsquare.android.api.model.Transaction // Sends Transaction val price = 430.00f val id = "id" // Currency val currency = Currencies.EUR // or currency = "USD" Contentsquare.send(Transaction.builder(price, currency).id(id).build()) ``` Warning **Each transaction must only be sent once**. A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ## Currency The currency is conforming to the [ISO 4217 ↗](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) standard. The currency can be passed either as "alphanumeric code" or "numeric code". If the currency passed doesn't match the supported currencies, the SDK will send a currency value of `-1`. It will be processed as the default currency of the project. ## Float precision The `Transaction` API uses a `Float` to represent the transaction value, which means very large numbers may be **rounded** when stored or serialized. For example, `1234567890f` becomes `1234567936f`. This behavior is normal for floating-point values and does not affect regular currency amounts (`0.99`, `430.00`, `100000.00`). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track transactions","description":"Track transactions with the Contentsquare Android SDK","url":"https://docs.contentsquare.com/en/android/track-transactions/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Track screens - Android (classic) description: Track screens with the Contentsquare Android SDK lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/android/track-screens/ md: https://docs.contentsquare.com/en/android/track-screens/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). Contentsquare aggregates user behavior and engagement at the screen level. To achieve this, it is necessary to provide a name for each screen by calling a dedicated screenview API. Warning Sessions without at least one screenview will be discarded. ```kotlin import com.contentsquare.android.Contentsquare // Sends Screenview Contentsquare.send("screen_name") ``` ## Jetpack Compose support To enable Jetpack Compose support, it is necessary to add a new dependency to your Gradle build file. * Groovy **build.gradle** ```groovy implementation 'com.contentsquare.android:compose:4.52.1' ``` * Kotlin **build.gradle** ```kotlin implementation("com.contentsquare.android:compose:4.52.1") ``` Attention must be paid to recompositions. The call should be wrapped using `TriggeredOnResume` to ensure only one screenview is triggered when a given screen is presented to the user. ```kotlin import com.contentsquare.android.Contentsquare import com.contentsquare.android.compose.analytics.TriggeredOnResume @Composable fun MyComposable(data: Data) { TriggeredOnResume { Contentsquare.send("screen_name") } // ... } ``` ## Screen name handling The screen name is limited to 2083 characters. However, this limit is not enforced by the SDK, but rather by the Contentsquare servers. ## Implementation recommendations ### General rules From a functional standpoint, we expect a screenview to be sent: * When the screen appears on the device * When a modal or pop-up is displayed * When a modal or pop-up is closed, returning the user to the screen * When the app is brought back to the foreground (after being minimized) ### When to send your first screenview Most events collected by the SDK require a screenview event to be sent first so they can be associated with that screen; otherwise, they will be discarded. If you need to collect events from the moment the app launches, you should trigger a screenview event immediately after the SDK has started. #### Automatic start If the SDK is started automatically, you should send your first screenview when your app's life cycle begins. For instance, you can send it in your Application `onCreate()` method: * Java ```java import android.app.Application; import com.contentsquare.android.Contentsquare; public class MyApplication extends Application { @Override public void onCreate() { super.onCreate(); // Send screenView Contentsquare.send("Launch screen"); } } ``` * Kotlin ```kotlin import android.app.Application import com.contentsquare.android.Contentsquare class MyApplication : Application() { override fun onCreate() { super.onCreate() // Send screenView Contentsquare.send("Launch screen") } } ``` #### Manual start If the SDK is started manually, you should send your first screenview right after calling `start()`: * Java ```java Contentsquare.start(); Contentsquare.send("Launch screen"); ``` * Kotlin ```kotlin Contentsquare.start() Contentsquare.send("Launch screen") ``` ### Activities To trigger a custom screenview each time the activity becomes visible, place the call in the `onResume` method (XML layouts only). ### ViewPagers To avoid double tagging on Fragments, make sure to include the call in each ViewPager's `onPageChangeListener` callback. ### Popups When tracking a popup as an isolated screen, use the API to send a screenview event in `onShow`. To re-trigger a screenview of the current activity when the popup is dismissed, make sure to trigger a screenview event with the original activity screenName on the popup `DismissListener`. ### Bottom sheets When tracking a bottom sheet as an isolated screen, use the API to send a screenview event on view displayed. On its dismiss, make sure to trigger a screenview event with the original screen name on `BottomSheetBehaviorCallback` state change (Usually when STATE\_HIDDEN) to track the complete cycle. ### Back navigation and navigation between screens Make sure that screenview events will be triggered when a user will go to the previous screen (example: Home → Profile → Home), it is expected to have a screenview event for the Home screen that might be reached with the back navigation button. Trigger screenview event in a [**custom callback** ↗](https://developer.android.com/guide/navigation/navigation-custom-back) to catch the back events. ### Redirecting the user to another screen (authentication, home) when closing the app/re-opening the app For some apps, you might want to redirect users whenever they hide your app, for example for security purposes (bank apps, password managers, etc...). If that is the case, pay specific attention to the way `screen_view` events are sent, in order not to track a screen which is not actually shown users. ## How to name screens As a general rule, keep the number of distinct screen names under 100. Since these names are used to map your app in Contentsquare, choose names that are clear and comprehensive. ### Separate words with spaces, dashes, or underscores When generating screen names with multiple words, separate them using spaces, dashes, or underscores. For instance, use `Home & Living - Home Furnishings` instead of ~~`homeLivingHomeFurnishings`~~ for a sub-category in a retail app. ### Screen name limitations Casing sensitivity Screen names are not case sensitive and will appear in lowercase on the Contentsquare platform. ```kotlin Contentsquare.send("ScreenName") // screenname Contentsquare.send("Screen Name") // screen name Contentsquare.send("screen_name") // screen_name Contentsquare.send("screenname") // screenname ``` ### Use screen template/layout names As a general recommendation, use names referring to the screen template/layout rather than referring to the specific content (data). This will help: * To keep the number of distinct screen names low and therefore make Contentsquare easier to use * Remove the risk of sending Personal Data to Contentsquare List of screen types falling into that category: Product detail, Event detail, Conversation/Chat, and User profile. ### Screens with multiple states/layouts Screens can have different layouts or states depending on the user context. In this case, append its value to the screen name. **Home screen** | State | Screen name | | - | - | | App landing layout | `Home` | | Women products layout | `Home - Women` | | Men products layout | `Home - Men` | | Sales layout | `Home - Sales` | **Product Detail screen (PDP)** | State | Screen name | | - | - | | Users on a Top for Women PDP | `PDP - Clothing - Women - Tops` | | Users on a Microwave PDP | `PDP - Kitchenware - Electrics - Microwave` | | Users on a Hotel details screen | `PDP - Holiday type - Season - Board` | **User account screen** | State | Screen name | | - | - | | Overview | `My Account - Dashboard` | | Order history | `My Account - Order history` | | Returns | `My Account - Returns` | **Search screen** | State | Screen name | | - | - | | Search | `Search` | | Search results for "Skincare" products | `Search - Skincare` | | Search results error screen | `Search - Error` | **Cart screen** | State | Screen name | | - | - | | Empty cart | `Cart - Empty` | | Items have been added to the cart | `Cart - Populated` | | Issues with availability or pricing | `Cart - Error` | **Checkout screen** | State | Screen name | | - | - | | User provides name, surname, and date of birth | `Checkout - User Details` | | User provides shipping address | `Checkout - Shipping Details` | | User inputs their credit card information | `Checkout - Payment` | ## How to track sessions and screen metadata **Custom Variables** Custom variables are designed to provide additional details about the screenview or user information during end-user engagement. These variables can encompass various aspects, including screen-specific attributes or user-related information, and serve to enhance data collection and analysis. Example: * Product name: "Acme Widget" * Product color: "red" * Product price: "$19.99" [Learn how to setup Custom Variables](https://docs.contentsquare.com/en/android/track-custom-variables/) **Dynamic Variables** Dynamic variables are used to provide additional information on the session, such as the name of a campaign or the version of a variation for an A/B test integration. They can be sent at any time during a session and do not require sending a screenview. dynamic variables should be used only in segments. Example: * Campaign name: "Summer Sale 2023" * Variation version: "Version A" [Learn how to setup Dynamic Variables](https://docs.contentsquare.com/en/android/track-dynamic-variables/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track screens","description":"Track screens with the Contentsquare Android SDK","url":"https://docs.contentsquare.com/en/android/track-screens/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Track WebViews - Android (classic) description: Track webviews with the Contentsquare Android SDK lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/android/track-webviews/ md: https://docs.contentsquare.com/en/android/track-webviews/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). WebView tracking links the Contentsquare SDK to the JavaScript tag running inside your WebViews to support analytics and Session Replay for web content displayed within your app. Android compatibility Contentsquare **only** allows to track instances of `android.webkit.WebView`. `androidx.browser.customtabs` is **not** supported: The Contentsquare SDK **cannot** track what is happening within its context, and its content will **not** be visible in replays. ## Enable tracking in WebViews ### Where to inject your WebViews? It is **essential** that the following steps are done before an URL is loaded in your WebView. With that in mind, you should inject your webviews in `onCreate()` in Activity and `onCreateView()` in Fragment. No matter where you decide to add the following injection code, keep in mind that it will not take effect until the next WebView content reload. ### WebView registration Use the following API: ```kotlin CsWebViewManager.injectEventTrackingInterface(@NonNull WebView webView) // to start tracking the specific WebView ``` ### Tag setup To complete the implementation, inject the **CS Tag in WebView mode** on your pages. See 📚 [Mobile Apps WebView Tracking Documentation](https://docs.contentsquare.com/en/webview-tracking-tag/#manual-injection). ## Let's sum it up Let's illustrate our implementation with an Activity. In your `onCreate()` method, you will add the following: ```kotlin override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_web_view) val webView = findViewById(R.id.webview) webView.settings.javaScriptEnabled = true webView.webViewClient = object : WebViewClient() {} // Inject the Bridge between the CS Tag in WebView mode and the SDK CsWebViewManager.injectEventTrackingInterface(webview) webView.loadUrl(DEFAULT_WEB_VIEW_CONTENT_URL) webView.reload() } ``` If you are using Fragments, the approach is similar, but should be done in the `onCreateView()` method, as stated previously. ## Validate your implementation of WebView tracking *There is no way of validating the implementation on the native side only.* ### Validating the implementation on the web side Once you arrive on the screen with the tracked WebView, you should see the following logs in sequence: 1. **JS interface injected:** ```plaintext [WebView] Js interface added to the webView ``` 2. **WebView registered:** ```plaintext [WebView] Registering WebView on native side ``` 3. **Tag configuration received — confirms successful tag to SDK communication:** ```plaintext [WebView JS log] (TAG_CONFIGURATION) [Config] ``` 4. **Tracking active:** ```plaintext [WebView] onWebViewTrackingReady ``` Specific logs are then emitted for: * Page views fired by the WebView Tracking Tag in the same format as for screen views: `Screenview - Screen name: {{page name given}} - Screen number: 11` * Taps and swipes detected by the WebView Tracking Tag in the same format as for defaults taps and swipe but with the target matching an HTML DOM element value: `Tap - Target: {Last view info: div:eq(0)} - Unresponsive: false` ***Going further:*** If you still have doubt, you can look for logs by filtering on `WebViewEventProcessor`. Their presence will confirm that it is well implemented on both web and native sides. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track WebViews","description":"Track webviews with the Contentsquare Android SDK","url":"https://docs.contentsquare.com/en/android/track-webviews/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Troubleshooting - Android (classic) description: Need help? We share probable causes and recommended fixes lastUpdated: 29 July 2026 source_url: html: https://docs.contentsquare.com/en/android/troubleshooting/ md: https://docs.contentsquare.com/en/android/troubleshooting/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). When the SDK is not sending data as expected, use this page to identify probable causes and apply recommended fixes. ## Requests are failing In order for Contentsquare to work, you need to make sure the following endpoints are not blocked by your network (VPN): | Request | Endpoint | Detail | | - | - | - | | Config file | `https://mobile-production.content-square.net` | See [Configuration](../how-the-sdk-works/#configuration) | | Analytics data (EU) | `https://m.csqtrk.net` `https://m.ba.contentsquare.net` `https://m.aa.contentsquare.net` | See [Sending data](../how-the-sdk-works/#sending-data) | | Analytics data (US) | `https://m-aus1.contentsquare.net` `https://m.bf.contentsquare.net` `https://m.af.contentsquare.net` | See [Sending data](../how-the-sdk-works/#sending-data) | | Monitoring | `https://l.contentsquare.net` | Used by the SDK to send SDK monitoring analysis in JSON format over HTTPS. | | Session Replay data (EU) | `https://ka-aeu1.contentsquare.net` `https://ka.ba.contentsquare.net` `https://ka.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Session Replay data (US) | `https://ka-aus1.contentsquare.net` `https://ka.bf.contentsquare.net` `https://ka.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Screenshot (EU) | `https://s.contentsquare.net` `https://b.ba.contentsquare.net` `https://b.aa.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Screenshot (US) | `https://s-aus1.contentsquare.net` `https://b.bf.contentsquare.net` `https://b.af.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Resources manager (EU) | `https://srm.ba.contentsquare.net` `https://srm.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Resources manager (US) | `https://srm.bf.contentsquare.net` `https://srm.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | ## Wrong tag loaded in WebView When using Manual tag injection for dual context (WebView and Browser tracking on the same webpage), the SDK injects a script that may load after the page, causing the wrong tag to load in the WebView. Use the following solution: Add a query parameter to the URL of the page you are loading in the WebView: ```kotlin webView.loadUrl("https://www.example.com/?isWebView=1") ``` Then add it to the conditions in the page script itself: ```javascript function isWebView() { return navigator.userAgent.indexOf('CS_WebView') !== -1 || typeof CSJavascriptBridge != 'undefined' || !!window.CS_isWebView || new URLSearchParams(window.location.search).get('isWebView') === '1'; } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Troubleshooting","description":"Need help? We share probable causes and recommended fixes","url":"https://docs.contentsquare.com/en/android/troubleshooting/","inLanguage":"en","dateModified":"2026-07-29T20:54:18+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Use Adobe Analytics - Android (classic) description: Leverage our native integration to use Adobe Analytics segments in Contentsquare lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/android/use-adobe-analytics/ md: https://docs.contentsquare.com/en/android/use-adobe-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). Analyze your data from anywhere in the customer journey using your Adobe Analytics segments. Contentsquare allows you to use your Adobe Analytics segments in every Contentsquare feature (Journey Analysis, Page Comparator, Session Replay). Warning Sessions without at least one screenview will be discarded. You should implement your screen tracking plan first, to have your Adobe Analytics integration work. See [Track screens](../track-screens/). ## Prerequisites **Adobe SDK code requirements** Make sure you register at least `Identity.EXTENSION` and `Analytics.EXTENSION` extensions before starting `MobileCore`. Check the [Getting Started with Adobe Analytics Android Extension ↗](https://github.com/adobe/aepsdk-analytics-android/blob/main/Documentation/getting-started.md) repository for that. 1. Follow the instructions from [Adobe Analytics for mobile apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271665881745) 2. Add the [AEP Android SDK ↗](https://github.com/adobe/aepsdk-analytics-android) to your project ## Code implementation Add the CSAppLifecycleObserver to the [ProcessLifecycleOwner ↗](https://developer.android.com/reference/androidx/lifecycle/ProcessLifecycleOwner) Note **Why 30 minutes before sending a new csMatchingKey** * 30 minutes is Contentsquare default session duration. * Setting a value **higher** than 30 minutes would cause overlapping on our sessions, and would impact negatively the data import from Adobe. * Setting a value **lower** than 30 minutes would make you to send more data to Adobe. This could cause the variable to reach Adobe's threshold, causing Adobe to filter values, and potentially impact your billing. See [Low-traffic value in Adobe Analytics ↗](https://experienceleague.adobe.com/docs/analytics/technotes/low-traffic.html) - Java ```java public class CSAppLifecycleObserver implements DefaultLifecycleObserver { private final SharedPreferences sharedPreferences; private final Random random = new Random(); public CSAppLifecycleObserver(@NonNull Context appContext) { sharedPreferences = appContext.getSharedPreferences( "CSAppLifecycleObserver", MODE_PRIVATE ); } @Override public void onResume(@NonNull LifecycleOwner owner) { DefaultLifecycleObserver.super.onResume(owner); sendCSMatchingKeyIfNeeded(); } public void sendCSMatchingKeyIfNeeded() { String csMatchingKeyTimestampKey = "csMatchingKey_ts"; int csMatchingKeyValidityMs = 1800000; // 30 minutes long currentTimestamp = new Date().getTime(); long csMatchingKeyIsPreviousTimestamp = sharedPreferences.getLong(csMatchingKeyTimestampKey, 0); if ((currentTimestamp - csMatchingKeyIsPreviousTimestamp) <= csMatchingKeyValidityMs) { return; } sharedPreferences.edit().putLong(csMatchingKeyTimestampKey, currentTimestamp).apply(); String csMatchingKey = "csMatchingKey"; String csMatchingKeyValue = random.nextDouble() + "_" + currentTimestamp; Contentsquare.send(csMatchingKey, csMatchingKeyValue); MobileCore.trackState(csMatchingKey + "_state", Collections.singletonMap(csMatchingKey, csMatchingKeyValue)); } } ``` - Kotlin ```kotlin class CSAppLifecycleObserver(appContext: Context) : DefaultLifecycleObserver { private val sharedPreferences = appContext.getSharedPreferences( "CSAppLifecycleObserver", Context.MODE_PRIVATE ) private val random = Random() override fun onResume(owner: LifecycleOwner) { super.onResume(owner) sendCSMatchingKeyIfNeeded() } private fun sendCSMatchingKeyIfNeeded() { val csMatchingKeyTimestampKey = "csMatchingKey_ts" val csMatchingKeyValidityMs = 1800000 // 30 minutes val currentTimestamp = Date().time val csMatchingKeyIsPreviousTimestamp = sharedPreferences.getLong(csMatchingKeyTimestampKey, 0) if (currentTimestamp - csMatchingKeyIsPreviousTimestamp <= csMatchingKeyValidityMs) { return } sharedPreferences.edit().putLong(csMatchingKeyTimestampKey, currentTimestamp).apply() val csMatchingKey = "csMatchingKey" val csMatchingKeyValue = random.nextDouble().toString() + "_" + currentTimestamp Contentsquare.send(csMatchingKey, csMatchingKeyValue) MobileCore.trackState("${csMatchingKey}_state", Collections.singletonMap(csMatchingKey, csMatchingKeyValue)) } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Use Adobe Analytics","description":"Leverage our native integration to use Adobe Analytics segments in Contentsquare","url":"https://docs.contentsquare.com/en/android/use-adobe-analytics/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Use Google Tag Manager - Android (classic) description: Leverage our native integration to send Google Tag Manager events to Contentsquare lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/android/use-google-tag-manager/ md: https://docs.contentsquare.com/en/android/use-google-tag-manager/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). If you are using Firebase to track events such as screenviews or transactions, you can trigger these events for Contentsquare with minimal effort, thanks to Google Tag Manager. ## Prerequisites If you are following this Google Tag Manager integration process, you should already have followed the Google Tag Manager + Firebase setup as described in [Google's Tag Manager + Firebase: Getting Started ↗](https://developers.google.com/tag-manager/android/) You also need to [integrate the Contentsquare SDK](https://docs.contentsquare.com/en/android/). ## Screenview events This section covers how to trigger a Contentsquare screenview event for every Firebase screenview event. Firebase allows you to [log screenviews automatically or manually ↗](https://firebase.google.com/docs/analytics/screenviews) for an exhaustive coverage of your app screens. ### Variables Contentsquare screenview events require a `name` parameter. Firebase has 2 ways to track screens: #### 1. Variable for automatically tracked screens Firebase's `screen_view` events have an `_sc` parameter (for screen class) which we can use as parameter for screens that are **automatically tracked**. We will create a variable called **Auto Screenview** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `_sc`  #### 2. Variable for manually tracked screens Firebase's `screen_view` events have a `_sn` parameter (for screen name) which we can use as parameter for screens that are **manually tracked**. We will create a variable called **Manual Screenview** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `_sn`  We can also create variables for our own custom parameters, for example, we can send a `screen_view` event like this: ```kotlin firebaseAnalytics.logEvent(FirebaseAnalytics.Event.SCREEN_VIEW) { param(FirebaseAnalytics.Param.SCREEN_NAME, "MyScreenName") param("is_user_logged_in", "true") } ``` and create a variable called **Is User Logged In** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `is_user_logged_in` Check out [Configure variables in Tag Manager ↗](https://developers.google.com/tag-platform/tag-manager/android/v5#configure_variables_in_tag_manager) for more information. ### Screenview trigger We will need to tell Google Tag Manager when to send a Contentsquare screenview, and for that we need to create a **Trigger**. Firebase sends screenviews as events of name `screen_view`, so we need to create a trigger for that event. * Name your trigger `Screenview Trigger` * **Trigger Type** should be set to **Custom** * Trigger should fire on **Some Events** * For the Event, the **Event Name** should be **equal** to `screen_view`  ### Create the custom function Tag In Google Tag Manager, a **Tag** is what configures what happens when some trigger is activated. It will be automatically linked to a custom class which we will create in a later step. The **Tag Type** should be a **Function Call**. You will also need to fill in the **Class Path** field with a class name of your liking, typically related to what the tag is about (here we chose `com.myapp.ContentsquareScreenviewTag`), which you will re-use later.  ### Adding the trigger and the variables to the Tag Edit the `ContentsquareScreenviewTag` Tag: * Add an argument with the key `auto_screen_name` and the variable `{{Automatic Screenview Name}}` as the value * Add an argument with the key `manual_screen_name` and the variables `{{Manual Screenview Name | Is User Logged In}}` or `{{Manual Screenview Name}}` as the value * Add **Contentsquare Screenview Trigger** as the Tag's trigger It should look like this now:  ### Create the custom function Tag class In your app code, create a class of the same name as the `Class Path` you configured in the GTM interface, for example `ContentsquareScreenviewTag`. This is how GTM connects the configuration and the actual class to trigger. This class is used to call the Contentsquare screenview tracking function as follows: ```kotlin @Keep class ContentsquareScreenviewTag : com.google.android.gms.tagmanager.CustomTagProvider { override fun execute(map: MutableMap?) { val autoScreenName = map?.get("auto_screen_name") as String? val manualScreenName = map?.get("manual_screen_name") as String? if (autoScreenName != null) { Contentsquare.send(autoScreenName) Log.w("GTM", "-------> $autoScreenName") } if (manualScreenName != null) { Contentsquare.send(manualScreenName) Log.w("GTM", "-------> $manualScreenName") } } } ``` Now, every time Firebase sends a screenview event, Contentsquare will send one as well. ## Screenview events with Custom Variables Custom Variables Custom variables are additional information on the page, the user or the session, sent within screenviews. For more information about custom variables, see [Track Custom Variables](https://docs.contentsquare.com/en/android/track-custom-variables/). It is possible to send custom variables along with the screenview events. To do so: 1. Follow **Use Google Tag Manager** > [Screenview events](#screenview-events) 2. Add extra arguments to the `ContentsquareScreenviewTag` Tag as follows: * *Key:* the index of the custom variable * *Value:* a string that will contain the custom variable name and value such as `CVAR_NAME : {{Event Name}}` Note The value of the custom variable is composed of a name and a value: `NAME : VALUE` concatenated into a single string and separated by `:`. It should look like this:  For Custom Variables You are free to implement your own logic for filling key and value in GTM, but the application side must be able to receive and extract for each custom variable: 1. An index 2. A name 3. A value In the code of your application, edit the code of your class to handle the added custom variables: ```kotlin @Keep class ContentsquareScreenviewTag : com.google.android.gms.tagmanager.CustomTagProvider { override fun execute(map: Map) { val autoScreenName = map["auto_screen_name"] as String? val manualScreenName = map["manual_screen_name"] as String? val screenName = manualScreenName ?: autoScreenName ?: "No screen name!" val cvars = mutableListOf() for ((tagKey, tagValue) in map) { val varIndex = tagKey.toIntOrNull() ?: continue val tagValueString = tagValue as? String ?: continue val splitTagValues = tagValueString.split(':') if (splitTagValues.size == 2) { val varName = splitTagValues[0].trim() val varValue = splitTagValues[1].trim() cvars.add(CustomVar(varIndex, varName, varValue)) } } Contentsquare.send(screenName, cvars.toTypedArray()) Log.d("GTM", "-------> $screenName") } } ``` With this code, the custom variables will be sent by Contentsquare automatically along with the screenview. ## Transaction events A Contentsquare transaction event can also be triggered for every Firebase `purchase` event ([See Firebase documentation ↗](https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics.Event#public-static-final-string-purchase)). To do so, you will need to follow the setup described below. ### Variables We have to create at least two variables to be able to build a transaction event: Value and Currency. Optionally, it is also possible to pass a transaction identifier, meaning you would need to create an additional variable to be able to use it. #### Value (mandatory)  #### Currency (mandatory)  #### Transaction ID (optional)  ### Trigger Create the following custom trigger.  ### Tag Create a **Function call** Tag called `ContentsquareTransactionTag`. You will also need to fill in the **Class Path** field with a class path of your liking, typically related to what the tag is about (here we chose `com.myapp.ContentsquareTransactionTag`), which you will re-use later. Pass the two to three variables created earlier as arguments (skip the `id` line if you do not want to use it) and set its trigger to the one you just created.  ### Implementing the function call We need to create a `ContentsquareTransactionTag` class, and have it adhere to the `CustomTagProvider` interface to link it to the Google Tag Manager custom Tag of the same name. Take good to be able to create and send a Contentsquare Transaction successfully, when you create a Firebase purchase event you will **have to** at least pass values for `VALUE` and `CURRENCY`, and can optionally pass a value for `TRANSACTION_ID` [see Firebase reference docs ↗](https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics.Event#PURCHASE) ```kotlin @Keep class ContentsquareTransactionTag : com.google.android.gms.tagmanager.CustomTagProvider { override fun execute(map: MutableMap?) { val value = map?.get("value") as String? val currency = map?.get("currency") as String? if (value != null && currency != null) { val transactionBuilder = Transaction.builder(value.toFloat(), currency) val id = map?.get("id") as String? if (id != null) { transactionBuilder.id(id) } Contentsquare.send(transactionBuilder.build()) } } } ``` Now, every time Firebase sends an `ecommerce_purchase` event, Contentsquare will send one as well. ## Dynamic variable events We can send values from any Firebase event as a Contentsquare dynamic variable: ```kotlin firebaseAnalytics.logEvent("addToCart") { param("product_count", 12) param("product_name", "ProductA") } ``` ### Variables The `addToCart` event has parameters `product_count`, `product_name`, we will create variables called **Product Count** and **Product Name** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `product_count`/`product_name` Check out [Configure variables in Tag Manager ↗](https://developers.google.com/tag-platform/tag-manager/android/v5#configure_variables_in_tag_manager) for more information. ### Triggers We need to create a **Trigger** to tell Google Tag Manager when to send a Contentsquare dynamic variable, so we will create one for the event `addToCart`. * Name your trigger `AddToCartTrigger` * **Trigger Type** should be set to **Custom** * Trigger should fire on **Some Events** * For the Event, the **Event Name** should be **equal** to `addToCart` ### Create the custom function Tag We need to create a function tag **AddToCartDynamicVar** * The **Tag Type** set to **Function Call** * The **Class Name** set to **DynamicVarTag** (we'll create this class later) * Add two arguments * Key: `cs_dynamic_var_key`, Value: `Product` * Key: `cs_dynamic_var_value`, Value: `{{Product Name}}: {{Product Count}}` * The **Triggering** set to **AddToCartTrigger** It should look like this now:  ### Create the custom function Tag class In your app code, create a class of the same name as the `Class Name` you configured in the GTM interface, for example `DynamicVarTag`. This is how GTM connects the configuration and the actual class to trigger. This class is used to call the Contentsquare dynamic variable function as follows: ```kotlin @Keep class DynamicVarTag : com.google.android.gms.tagmanager.CustomTagProvider { override fun execute(parameters: MutableMap) { val dynamicVarKey = parameters["cs_dynamic_var_key"] as? String ?: return when (val dynamicVarValue = parameters["cs_dynamic_var_value"]) { is String -> Contentsquare.send(dynamicVarKey, dynamicVarValue) is Long -> Contentsquare.send(dynamicVarKey, dynamicVarValue) } } } ``` Now, every time Firebase sends an `addToCart` event, Contentsquare will send a dynamic variable `key: "Product", value: "ProductA: 12"`. Note To create another tag for a dynamic variable, you can use the `DynamicVarTag` class again. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Use Google Tag Manager","description":"Leverage our native integration to send Google Tag Manager events to Contentsquare","url":"https://docs.contentsquare.com/en/android/use-google-tag-manager/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Enrichment API - APIs description: Getting started with the Enrichment API lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/api/enrichment/ md: https://docs.contentsquare.com/en/api/enrichment/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare Enrichment API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. Not a developer? Contact your CSM. They will direct you to the best solution to meet your data needs. * **Base URL of the API:** `https://enrichment-api.{cloud}.contentsquare.com/` * **Current Version of the API:** 1.0 Note The `{cloud}` part in the base URL depends on which cloud the target project you want to query resources from is installed. The base URL that you should use will be returned dynamically by our authentication server. See an explanation and a detailed example in [Authentication](authentication/). ## What is Contentsquare? Contentsquare is a next-gen Analytics tool that helps you understand how and why your users are interacting with your app, mobile, and website. ## What this API is about Contentsquare relies on a web tracking tag or mobile SDK to track session-based data. By session we mean a user's visit on a website or app. This API allows for enriching the behavioural data tracked by Contentsquare client-side, with other session-based data that can be sent server-side. For example, you can start reconciling offline and online journeys by enriching web sessions data with phoning data for calls that were triggered from those sessions. As Contentsquare cannot access phone call data during a web session via its tag or SDK, the related data must be sent to Contentsquare server-side, once the calls are ended and processed. In Contentsquare, you can then create user segments based on this phoning data and start answering questions like: "how does a specific journey on my website impact my conversion on the phone?", or "How do users who end up making a qualitative call behave on my website?" Note As of today, the Enrichment API does not support Transactions. ## Enrichment Flow overview Making an integration based on the Enrichment API up and running goes through the following steps: 1. As a starting point, the [Provider](definitions/#provider) provides an integration schema to Contentsquare and gets listed in the Contentsquare integrations catalog 2. Customers install the integration and provides the [Provider](definitions/#provider) with the generated Contentsquare OAuth credentials (client\_id/client\_secret) 3. During web sessions, the [Provider](definitions/#provider) pulls Contentsquare session information (project ID, session ID) that will be used by Contentsquare to match the data received server-side 4. The [Provider](definitions/#provider) can then send enrichment data batches: 1. The [Provider](definitions/#provider) authenticates with the OAuth credentials provided by the customer, and receives both a JWT access token valid for 1 hour and the dynamic base URL of the enrichment endpoint (that depends on the cloud the target project is installed on) 2. The [Provider](definitions/#provider) sends the data to the enrichment endpoint with a valid JWT access token And here is a diagram summarizing the detailed interactions involved in the authentication flow for an integration based on the integration API: ``` sequenceDiagram accTitle: User authentication flow accDescr: This diagram shows the steps a user takes to authenticate with OAuth participant Customer participant Provider participant CS_UI as CS console (UI) participant Auth as Authentication endpoint participant Enrichment as Enrichment endpoint Note over CS_UI, Enrichment: Contentsquare Customer->>CS_UI: Install integration
and create OAuth credentials (client_id/client_secret) CS_UI->>Customer: OAuth credentials (client_id/client_secret)
and integration_id generated Customer->>Provider: Provide OAuth credentials
and integration_id
(e.g. in a config UI) Provider->>Auth: Authenticate with OAuth credentials
POST https://api.contentsquare.com/v1/oauth/token Auth->>Provider: JWT access token
and base URL of the enrichment endpoint Provider->>Enrichment: Send enrichment data with JWT access token
POST https://enrichment-api.{cloud}.contentsquare.com/v1/enrichments ``` We will detail each step in the following sections. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Enrichment API","description":"Getting started with the Enrichment API","url":"https://docs.contentsquare.com/en/api/enrichment/","inLanguage":"en","dateModified":"2026-03-11T15:17:40+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Getting Started - APIs description: Getting Started with the Metrics API lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/api/metrics/ md: https://docs.contentsquare.com/en/api/metrics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare Metrics API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. All API requests must be made over HTTPS. Not a developer? Contact your CSM. They will direct you to the best solution to meet your data needs, whether it's connectors (such as Google Data Studio or Reeport) or the help of the Professional Services team at Contentsquare. * **Base URL of the API:** `https://api.contentsquare.com/` * **Current Version of the API:** 1.0 ## What is Contentsquare? Contentsquare is a next-gen Analytics tool that helps you understand how and why your users are interacting with your app, mobile, and websites. To understand the metrics exposed by the API Metrics you should understand some very important concepts of Contentsquare. The metrics are obtained based on elements created and managed within the Contentsquare interface. ## Mappings Defined by a name and set of pages, a mapping helps model your site by grouping together your site's URLs into page groups. Thanks to multiple mappings of varying granularity, you can analyze your site at a macro and micro level. Contentsquare's Mappings are organized into URLs which are sorted in different "page groups" and the "page groups" are grouped under different categories. [More information here ↗](https://support.contentsquare.com/hc/en-us/articles/37271862920465) ## Page Groups Contentsquare page groups allow you to gather and group one or several URLs of the same type: a set of pages from your website sharing the same template and function, such as Product pages or List pages. Gathering URLs into "buckets" is the easiest way to analyze your website according to different levels of granularity. [More information here ↗](https://support.contentsquare.com/hc/en-us/articles/37271862920465) ## Zonings The Zoning Analysis module allows you to analyze visitors' in-page navigation. You can differentiate clickable areas on the page, called "zones". Zoning Analysis has a large range of metrics so as to provide the most accurate and deepest in-page analysis. This way, you can determine what zones bring navigation anomalies and should be changed or moved. You can perform your analysis with segment or goal. Zonings split your page groups into zones. The definition of zones is based on the div of your HTML code. You can create multiple zonings for the same page group. See [Zonings](https://docs.contentsquare.com/en/api/metrics/objects-endpoints/#zonings), [Zones](https://docs.contentsquare.com/en/api/metrics/objects-endpoints/#zones), [Zone Metrics for Web Endpoints](https://docs.contentsquare.com/en/api/metrics/zone-metrics-endpoints-web/) and [Zone Metrics for Apps Endpoints](https://docs.contentsquare.com/en/api/metrics/zone-metrics-endpoints-apps/). [Learn more about the Zoning feature on the Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271709566609). ## Goals A Goal is a navigation event collected by the tag. A goal can be one of three types: * A page view * A select a zone * A hover over a zone [More information here ↗](https://support.contentsquare.com/hc/en-us/articles/37271667397905) ## Segments Segments help you to divide visitors into homogeneous population groups based on behaviors. A segment can be composed of: * Conditions tied to visitors' context (location, technology used, language, etc.) * Conditions tied to visitors' intention (behaviors, visit time, page viewed, etc.) [More information here ↗](https://support.contentsquare.com/hc/en-us/articles/37271731077521) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started","description":"Getting Started with the Metrics API","url":"https://docs.contentsquare.com/en/api/metrics/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Getting Started - APIs description: Getting Started with the Data Export API lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/api/export/ md: https://docs.contentsquare.com/en/api/export/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare Data Export API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. All API requests must be made over HTTPS. Not a developer? Contact your CSM. They will direct you to the best solution to meet your data needs. * **Base URL of the API:** `https://api.contentsquare.com/` * **Current Version of the API:** 1.0 ## What is Contentsquare? Contentsquare is a next-gen Analytics tool that helps you understand how and why your users are interacting with your app, mobile, and websites. Contentsquare allows its clients to create and manage export jobs to extract raw data that we rely on for our analytics. For a complete documentation of how to create jobs in the Contentsquare platform, refer to the documentation included in the help center or provided by your CSM. By extracting raw data in downloadable files, clients can perform their own analyses for business intelligence or data science use cases, for example. And they can store this data in their own infrastructure, allowing to go beyond the contractual data retention period provided by Contentsquare. ## What this API is about Use this API to programmatically create export jobs and retrieve the exported files. You can't use the API to update an existing export job. Edit export jobs for your project in the Contentsquare console (**Data Export** tab). This API allows for extracting raw data, as opposed to aggregated data. To retrieve the aggregated data of your Contentsquare analyses modules, use the [Metrics API](https://docs.contentsquare.com/en/api/metrics/). You can extract raw data at the pageview or session level. To understand how the export API works, you should understand the basic objects that you will manipulate via the provided endpoints. ## Jobs A job is the abstract definition of an extraction task. A job definition includes: * A **name** for the job * A file **format** ("CSV" or "JSONL") * A **scope** ("sessions" or "views") * A **frequency** ("daily", "hourly", or "once"): a daily job will run every day to extract the last day of data (the job is triggered every day at midnight **UTC** + 4 hours); a "once" job is triggered immediately after creation or is queued if another once job is running. * A **date range**: only required for a "once" job, and not to exceed 7 days; not required for daily jobs (extraction is automatically run for the last day everyday) * The **fields** to extract (example: `session_id`): extractable fields will depend on the scope * The **filters** (example: "deviceId") ## Job runs A job run is a specific instance of a job. For example, if a daily job has been defined, a job run represents the execution of this job on a specific day. ## Job run parts Job runs will generate several files to be downloaded. A job run part corresponds to a specific file. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started","description":"Getting Started with the Data Export API","url":"https://docs.contentsquare.com/en/api/export/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Getting Started - APIs description: Getting Started with the Speed Analysis Lab API lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/api/speed-analysis-lab/ md: https://docs.contentsquare.com/en/api/speed-analysis-lab/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare Speed Analysis Lab API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. All API requests must be made over HTTPS. Not a developer? Contact your CSM. They will direct you to the best solution to meet your data needs. * **Base URL of the API:** `https://api.contentsquare.com/` * **Current Version of the API:** 1.0 ## What is Contentsquare? Contentsquare is a next-gen Analytics tool that helps you understand how and why your users are interacting with your app, mobile, and websites. Speed Analysis is a web pages testing and monitoring capability which enables you to monitor your website, spot slowdowns, discover optimization opportunities, and benchmark against your competitors. Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. ## Analysis Speed Analysis Lab allows you to analyze the performance on demand and generate reports for any web page. [See how to analyze a website ↗](https://support.contentsquare.com/hc/en-us/articles/37271703673233-How-to-run-a-basic-web-performance-test) ## Monitorings Leverage the Speed Analysis Lab's synthetic monitoring to keep a close eye on your main pages: * Be notified when a page experiences slowness or downtime * Analyze performance trends over time and detect regression * Benchmark your pages against your competitors * Monitor lower environments to fix performance issues before reaching production [See how to create monitorings ↗](https://support.contentsquare.com/hc/en-us/articles/37271888634385-How-to-use-web-page-monitoring) ## Scenarios Create scenarios to closely monitor your main funnels and user journeys. With scenarios, you can: * Be alerted when a funnel breaks or slows down * Analyze performance trends over time and detect regression * Leverage scenarios on lower environments to fix performance issues before reaching production [See how to create scenarios ↗](https://support.contentsquare.com/hc/en-us/articles/37271664181009-How-to-record-and-import-scenarios-via-your-web-browser) ## Events Events in Speed Analysis Lab are user-defined markers that allow you to track and document significant events (for example website updates, releases, failures). These events are then shown on your performance graphs, helping you correlate changes in website performance with specific actions or incidents. [See how to add events ↗](https://support.contentsquare.com/hc/en-us/articles/37271875285521-How-to-create-events-on-Monitorings-and-Scenarios) [Learn more about the Speed Analysis Lab ↗](https://support.contentsquare.com/hc/en-us/articles/37271683925905-Introduction-to-Speed-Analysis-Lab). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started","description":"Getting Started with the Speed Analysis Lab API","url":"https://docs.contentsquare.com/en/api/speed-analysis-lab/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Changelog - Capacitor description: The Contentsquare Capacitor plugin changelog lastUpdated: 21 July 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/changelog/ md: https://docs.contentsquare.com/en/capacitor/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. ## 7.1.1 - 2026.07.21 * **Native SDKs:** iOS 4.46.4, Android 4.43.3 ## 7.1.0 - 2025.12.19 * **Native SDKs:** iOS 4.45.4, Android 4.43.3 ## 7.0.0 - 2025.07.28 * **Native SDKs:** iOS 4.42.4, Android 4.39.4 🚨 Minimum Capacitor Version Change Announcement: We officially support Capacitor 7. ## 6.4.1 - 2026.07.21 * **Native SDKs:** iOS 4.46.4, Android 4.43.3 ## 6.4.0 - 2025.12.19 * **Native SDKs:** iOS 4.45.4, Android 4.43.3 ## 6.3.0 - 2025.07.04 * **Native SDKs:** iOS 4.42.3, Android 4.39.3 * **Android:** Fixed a race condition that could prevent Tag from being injected. * **Android:** Fixed a race condition that could lead to Session Replay not starting. * **Session Replay:** Improved Session Replay screen change consistency. 🚨 Minimum Capacitor Version Change Announcement: Starting next version of our SDK we will drop support for any Capacitor versions below 6.0 ## 6.2.0 - 2025.05.05 * **Native SDKs:** iOS 4.41.1, Android 4.38.1 * **Zoning:** Fixed issue on Android when using local assets. ## 6.1.0 - 2025.03.24 * **Native SDKs:** iOS 4.40.2, Android 4.36.1 * Native SDKs perform tracking tag injection ## 6.0.0 - 2024.08.27 * **Capacitor 6** is now supported * **Native SDKs:** iOS 4.34.0, Android 4.30.0 ## 5.0.0 - 2024.03.11 * **Capacitor 5** is now supported * **Session Replay:** is now supported. * **Screenshot Capture:** is now supported. * **Native SDKs:** iOS 4.28.0, Android 4.24.0 ## 4.1.0 - 2024.08.05 * **Native SDKs:** iOS 4.34.0, Android 4.30.0 ## 4.0.0 - 2024.01.11 * **Session Replay:** is now supported. * **Screenshot Capture:** is now supported. * **Native SDKs:** iOS 4.28.0, Android 4.24.0 ## 0.3.1 - 2023.05.10 **Gesture tracking:** Fixed issue on Android related to webview injection at startup. ## 0.3.0 - 2023.03.06 * **Gesture tracking:** is now supported. * **Native SDKs:** iOS 4.20.0 ## 0.2.0 - 2022.09.28 * **Dynamic Variables:** The API is now available. * **Track Transactions:** The API is now available. ## 0.1.1 - 2022.09.07 * First beta version. * Opt-in is supported. * Opt-out is supported. * Screenview event is supported. * The Plugin uses **[Android native SDK 4.12.0](https://docs.contentsquare.com/en/android/changelog/#4120---20220810)** and **[iOS native SDK 4.15.1](https://docs.contentsquare.com/en/ios/changelog/#4151---20220726)** ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare Capacitor plugin changelog","url":"https://docs.contentsquare.com/en/capacitor/changelog/","inLanguage":"en","dateModified":"2026-07-21T15:56:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Error analysis - Capacitor description: How to use Contentsquare Error Analysis in your Capacitor apps lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/error-analysis/ md: https://docs.contentsquare.com/en/capacitor/error-analysis/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. Error Analysis automatically captures API errors and network failures in your Capacitor app and surfaces them in the Contentsquare platform. ## Get Started ### Start the SDK You do not need to do anything to start the errors collection, it will start itself with Contentsquare SDK. ## Sample App For best implementation practices of our library, explore the [Contentsquare for Capacitor sample app ↗](https://github.com/ContentSquare/capacitor-sample-app). ## JS Errors Similar to web context, JS errors are collected out of the box if the collection is enabled in the web project associated to the Capacitor project. Find more information on how Contentsquare handles JS errors in our [JavaScript errors Help Center article ↗](https://support.contentsquare.com/hc/en-us/articles/37271807561873). ## API Errors ### Automatic network inspection API Errors automatically collects failed network requests. ### Debugging and Logging If in-app features are enabled, a info log should appear with the details of the event (see [Capacitor Debugging and Logging](https://docs.contentsquare.com/en/capacitor/#check-the-logs) section): ```plaintext CSLIB ℹ️ Info: API Error (from Webview) - GET 401 https://api.client.com ``` ### How API Errors works #### Initialization The way our SDK works is by auto-starting with the application launch and automatically collects failed network requests. #### Configuration Once started, our SDK fetches its config from our servers. It will start collecting data from network events if the API Errors setting is enabled in the config (this is handled by the Contentsquare team). #### Tracking The SDK monitors only the API Errors with response code above 400, and generates analytics data. These events are then locally stored, and eventually sent to our servers in batches. Warning To make sure API Errors occurring at app launch are correctly tracked, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. #### Sending data For each network error, a new event will be sent in analytics and Session Replay data. ### API Troubleshooting Details API Errors troubleshooting details enables you to collect more information about API errors so you can troubleshoot errors faster. With this feature you will be able to see three types of additional API error details in the Event Stream of Session Replay. * The HTTP headers of the request and the response. * The body (the data sent by the request or received in the response). * The query parameters of the request endpoint (of the URL of the information you request for). Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. See [API Troubleshooting Details ↗](https://support.contentsquare.com/hc/en-us/articles/37271885035537) for more details. ### Collected data points Only network calls in error (response code above 400) will be collected. Here the exhaustive list of data collected: * URL (without query strings) * HTTP method * Response code * Timestamp of the request * Timestamp of the response * HTTP headers of the request * HTTP headers of the response * HTTP body of the request * HTTP body of the response * Query parameters of the request endpoint ### Known limitations and recommendations #### Conflict with Firebase Performance Monitoring * Android Contentsquare Error Analysis is not compatible with Firebase Performance Monitoring auto-collection. Only one of the two will log events, and usually, the events will be automatically logged by the Contentsquare Error Analysis. To log events to Firebase Performance Monitoring, we suggest [logging it manually ↗](https://rnfirebase.io/perf/usage#http-request-tracing). * iOS Contentsquare Error Analysis is compatible with Firebase Performance auto-collection, but the HTTP body from the response won't be collected by the Error Analysis SDK. Contentsquare Error Analysis may not be compatible with other network auto-collection tools. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Error analysis","description":"How to use Contentsquare Error Analysis in your Capacitor apps","url":"https://docs.contentsquare.com/en/capacitor/error-analysis/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Collected data points - Capacitor description: Events and metadata collected by the Contentsquare SDKs lastUpdated: 05 June 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/collected-data-points/ md: https://docs.contentsquare.com/en/capacitor/collected-data-points/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Capacitor SDK collects request metadata, gesture events, lifecycle events, transactions, and dynamic variables, all serialized as JSON and sent to the server in batches. * The events are in JSON format, which lists the properties and their description in comment. * Events are sent to the server in batches. * A batch is a subset of events originating from one session. A session can send events in more than one batch. * The batch size is defined in a run configuration file specific to each app (50 events by default). ## Requests meta data Each batch has a common header, a set of device specific, and repeatable information and an array of events, which is immutable. The header is composed at the moment of sending, so it has to be constant info ONLY. The array in the payload is data stored at the moment of collection. The structure of the batches of events will have the following format: ```javascript { pid:8, // int - ProjectId - represented in the mobile config format uid:"ac1529a7-59f6-49d9-b254-6f0a22f57284", // String - uuid Unique user ID dt:4, // int - device type (loosely enforced enum - [SDK-phone : 4, SDK-tablet :5]) dma:"Samsung", // String - device manufacturer. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. dmo:"SG", // String - device model. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. os:"7.0", // String - os version (Android version name 6.0, 7.0, 8.0) l:"en_US", // String - Language in iso-639 format https://www.ibabbleon.com/iOS-Language-Codes-ISO-639.html tz:"Europe/Paris", // String - timezone https://en.wikipedia.org/wiki/List_of_tz_database_time_zones now:1522159618000, // long - timestamp when the batch was sent to:{ // object - type origin of the event an:"appname" // String - application name st:"SDK-android", // String - type of SDK sf:"release", // string - SDK flavor/variant [release/debug/god] }, r:{ // Device - resolution. w:1080, // int - width h:1920 // int - height d: 1.5 // The device density as float. Its values can vary between (0.75 and 10) }, pl:[] // JSON array payload - list of event objects, see below } ``` ## Events ### Events meta data All events have a common first part (don't confuse it with the header explained above). This common section is data which is common for all events by type but is gathered at the moment the event occurred. This common section is a part of the actual event payload. ```javascript { upt:1522, // long - system update in milliseconds euid:"euid", // String - event UUID url:"app-and://identifier/mainPath/secondaryPath?title=screeName", // String - screenName is passed in the title query Parameter scn:4, // int - the number of screens already shown in the session c:3, // int - connectivity type [-1 - offline, 0 - error, 1 - wifi, 2 - 2g, 3 - 3g, 4 - 4g] ci:"verizon", // String - carrier_id when user is on mobile network o:1, // int - orientation [0 = portrait, 1 = landscape] vo:{ // object - version origin of the event sv:"2.1", // string version of the SDK sb:4, // int - SDK build number av:"appVersion", // String - application version af:"appFlavor" // String - application string - [release/debug/god] ab:1 // int - application build number }, sn:1, // int - session id (positive int) t:12894726459435 // long - timestamp of the event (in milliseconds) } ``` All event specific properties are appended to this JSON object. ### App Start This event describes the absolute start of the app. The trigger for this event is the absolute start of the app. This is the first event sent when the SDK is invoked. ```javascript ea: 0; // int - event action - defined above ``` ### App Show This event is sent when the user brings the app in the foreground (switching from another app, exiting lock screen, etc.). This event means the app is focused. ```javascript ea: 1; // int - event action - defined above ``` ### App Hide This event is sent when the user exits (minimizes) the app, or switches to something else. This event means the app is not focused and the session might end, but we have not completely ended the session yet, as the user might return. ```javascript ea: 2; // int - event action - defined above ``` ### Screenview Everything starts with a View event. This is an event which describes the equivalent of a "page view" on the web. This event is sent when the Track Screen API is called. ```javascript ea:4 // int - event action - defined above st:"title", // String - screen title sl:34543 // int - (load time) screen load time (diff between last action and this event) ``` ### Transaction To track transactions, we provide a public API which can send a transaction object (see section [Track Transactions](https://docs.contentsquare.com/en/capacitor/track-transactions/)). This object must contain the following parameters: ```javascript ea: 16, // int - event action - defined above tr: { // a json object with different properties defining the transaction made vl: 20.0, // mandatory - float - the value of the transaction cu: 978, // mandatory - int - the ISO 4217 code of the currency of the transaction id: "32akjkljklJ575775" // optional - string - an id for the transaction } ``` ### Dynamic variables To track dynamic variables we provide a public API which can send a custom event object (see section [Dynamic variables](https://docs.contentsquare.com/en/capacitor/track-dynamic-variables/)). ```javascript // Dynamic variable event with a string value ea:18, // int - event action - defined above k:"key", // String - Custom key assigned by client. v:"value" // String - Custom value assigned by client. ``` ```javascript // Dynamic variable event with a number value ea:19, // int - event action - defined above k:"key", // String - Custom key assigned by client. v: 2344 // Integer - Custom value assigned by client. ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Collected data points","description":"Events and metadata collected by the Contentsquare SDKs","url":"https://docs.contentsquare.com/en/capacitor/collected-data-points/","inLanguage":"en","dateModified":"2026-06-05T17:39:25+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: How the SDK works - Capacitor description: Understand how the Contentsquare SDKs load, track, and send data lastUpdated: 28 April 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/how-the-sdk-works/ md: https://docs.contentsquare.com/en/capacitor/how-the-sdk-works/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The SDK auto-starts at application launch, attaches to the current process, and intercepts the events and gestures needed to capture analytics data. ## Configuration Once started, our SDK fetches its config from our servers, and then depending on the segmentation size (defined by our team when you sign a contract) it will start collecting data from system and user events it detects from the runtime. ## Tracking The SDK monitors the application lifecycle events and the view hierarchy, and generates analytics data from the behavior of the app, the content of the screen and the interaction of the user. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. ## Sending data 📚 [Native Android SDK documentation for Sending data](https://docs.contentsquare.com/en/android/how-the-sdk-works/#sending-data) 📚 [Native iOS SDK documentation for Sending data](https://docs.contentsquare.com/en/ios/how-the-sdk-works/#sending-data) ## Session definition A session is one continuous period of user interaction. It starts upon app launch and persists through state changes, including putting the app in the background or terminating and restarting it. As long as users interact at least once every 30 minutes, it remains the same session. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"How the SDK works","description":"Understand how the Contentsquare SDKs load, track, and send data","url":"https://docs.contentsquare.com/en/capacitor/how-the-sdk-works/","inLanguage":"en","dateModified":"2026-04-28T22:02:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Compatibility - Capacitor description: Requirements and limitations to develop with the Contentsquare SDKs lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/compatibility/ md: https://docs.contentsquare.com/en/capacitor/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Each version of the Contentsquare plugin will be linked to specific, fixed versions of each native SDK. to make that clear, here is a compatibility table to consider when choosing your version of the plugin (refer to the [Capacitor Plugin Changelog](https://docs.contentsquare.com/en/capacitor/changelog/)) to know what the changes are for each version. | Plugin Version | iOS SDK Version | Android SDK Version | Min Capacitor Version | Max Capacitor Version | | - | - | - | - | - | | 7.0.0 | 4.42.4 | 4.39.4 | 7.0.0 | 7.4.x | | 6.3.0 | 4.42.3 | 4.39.3 | 6.0.0 | 6.2.x | | 6.2.0 | 4.41.1 | 4.38.1 | 6.0.0 | 6.2.x | | 6.1.0 | 4.40.2 | 4.36.1 | 6.0.0 | 6.2.x | | 6.0.0 | 4.34.0 | 4.30.0 | 6.0.0 | 6.1.x | | 5.1.0 | 4.34.0 | 4.30.0 | 5.0.0 | 5.7.x | | 5.0.0 | 4.28.0 | 4.24.0 | 5.0.0 | 5.7.x | | 4.1.0 | 4.34.0 | 4.30.0 | 4.0.0 | 4.7.x | | 4.0.0 | 4.28.0 | 4.24.0 | 4.0.0 | 4.7.x | | 0.3.1 | 4.20.0 | 4.15.0 | 3.0.0 | 4.7.x | | 0.3.0 | 4.20.0 | 4.15.0 | 3.0.0 | 4.7.x | | 0.2.0 | 4.18.0 | 4.15.0 | 3.0.0 | 4.1.x | | 0.1.0 | 4.15.1 | 4.12.0 | 3.0.0 | 4.1.x | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Contentsquare SDKs","url":"https://docs.contentsquare.com/en/capacitor/compatibility/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Impact on performance - Capacitor description: Metrics to evaluate the impact on performance of the SDKs on your apps lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/impact-on-performance/ md: https://docs.contentsquare.com/en/capacitor/impact-on-performance/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare strives to be non-intrusive and transparent to client app developers. The following are the technical specifics we can share on performance. *  ### [Android](https://docs.contentsquare.com/en/android/impact-on-performance/) *  ### [iOS](https://docs.contentsquare.com/en/ios/impact-on-performance/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Impact on performance","description":"Metrics to evaluate the impact on performance of the SDKs on your apps","url":"https://docs.contentsquare.com/en/capacitor/impact-on-performance/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: In-app features - Capacitor description: Implement in-app features with the Contentsquare SDKs lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/in-app-features/ md: https://docs.contentsquare.com/en/capacitor/in-app-features/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Alongside its tracking capabilities, the SDKs embed some features aimed at Contentsquare users such as [SDK Logs](#debugging-and-logging). ## Implement in-app features Note This step only applies to iOS. To allow Contentsquare users to enable in-app features, perform these tasks: 1. [Add the custom URL scheme in your app Info](#1-add-the-custom-url-scheme-in-your-app-info) 2. [Call the SDK when the app is launched via a deeplink](#2-call-the-sdk-when-the-app-is-launched-via-a-deeplink) ### 1. Add the custom URL scheme in your app Info You have to allow your app to be opened via a custom URL scheme which can be done using one of the following methods: ### Xcode 1. Open your project settings 2. Select the app target 3. Select the `Info` settings 4. Scroll to `URL Types` 5. Set the URL scheme to `cs-$(PRODUCT_BUNDLE_IDENTIFIER)` #### Text editor 1. Open the `Info.plist` of your project 2. Add the following snippet: **Info.plist** ```xml CFBundleURLTypes CFBundleURLSchemes cs-$(PRODUCT_BUNDLE_IDENTIFIER) ``` ### 2. Call the SDK when the app is launched via a deeplink Depending on the project, there are multiple ways to handle the deeplink opening. Choose the method matching your project structure: * AppDelegate In your `AppDelegate` class, complete or implement the function `application(app, open url:, options:)` with: `Contentsquare.handle(url: url)` * SceneDelegate In your `WindowSceneDelegate` class, you need to: 1. Update `func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions)` with: ```swift if let url = connectionOptions.urlContexts.first?.url { Contentsquare.handle(url: url) } ``` 2. Complete or implement `func scene(_ scene: UIScene, openURLContexts URLContexts: Set)` with: ```swift if let url = URLContexts.first?.url { Contentsquare.handle(url: url) } ``` * SwiftUI In the `body` of your main App struct, add the `onOpenURL` modifier and call the `Contentsquare` SDK to handle the URL: ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { MyView() .onOpenURL { url in Contentsquare.handle(url: url) } } } } ``` ## Enable in-app features In-app features can be enabled in different ways: ### Scan the QR Code If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code displayed with your phone. Take a look at the native documentation for further information. ### Alternative methods We provide alternative methods to enable in-app features especially for iOS Simulator and Android Emulator. 📚 [Native Android SDK documentation for Enable in-app features](https://docs.contentsquare.com/en/android/in-app-features/) 📚 [Native iOS SDK documentation for Enable in-app features](https://docs.contentsquare.com/en/ios/in-app-features/) ## Debugging and Logging Contentsquare provides Logging capabilities that allow you to see the raw event data logged by your app. Use this for validation purposes during the instrumentation phase of development and can help you discover errors and mistakes in your analytics implementation and confirm that all events are being logged correctly. 📚 [Native Android SDK documentation for Debugging and Logging](https://docs.contentsquare.com/en/android/in-app-features/#debugging-and-logging) 📚 [Native iOS SDK documentation for Debugging and Logging](https://docs.contentsquare.com/en/ios/in-app-features/#debugging-and-logging) ## Screenshot capture To unlock the full data-visualization capabilities of Contentsquare, the SDK provides a way to capture screenshots of your app screens. These screenshots can only be taken by Contentsquare's users on their device. They are not captured from your end-users device. It means your Personal Data is safe, as long as you use a test user account. Warning For screenshot capture to work, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. * Android Follow the [Native Android SDK documentation for Screenshot Capture](https://docs.contentsquare.com/en/android/in-app-features/#screenshot-capture) * iOS Follow the [Native iOS SDK documentation for Screenshot Capture](https://docs.contentsquare.com/en/ios/in-app-features/#screenshot-capture) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"In-app features","description":"Implement in-app features with the Contentsquare SDKs","url":"https://docs.contentsquare.com/en/capacitor/in-app-features/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Privacy - Capacitor description: Learn how Contentsquare deals with Personal Data and related APIs lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/privacy/ md: https://docs.contentsquare.com/en/capacitor/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare Capacitor Plugin and SDKs are compliant with the **Play Store and App Store Privacy guidelines** and with the **EU General Data Protection Regulation (GDPR)**. Consult our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Handling User Consent Even though Contentsquare only collects usage data on your app, we will consider every new user to be opted-out. To start tracking, the `optIn()` API must be called. Note If for some reason you think that securing user consent is not required for your app, discuss it during the Implementation process with your main contact. ## Opt-in Use the `optIn()` API to get user consent. Calling this API will generate a user ID and initiate tracking. ```javascript import { ContentsquarePlugin } from "@contentsquare/capacitor-plugin"; ContentsquarePlugin.optIn(); ``` ## Opt-Out **Permanently breaking the link and stopping all data collection.** When this API is called, tracking stops immediately, all settings are reset (session number, page number, user ID...) and all files related to Contentsquare tracking are deleted. Contentsquare will never track and collect any data from the user's phone unless the Opt-in API is called again. ```javascript import { ContentsquarePlugin } from "@contentsquare/capacitor-plugin"; ContentsquarePlugin.optOut(); ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Learn how Contentsquare deals with Personal Data and related APIs","url":"https://docs.contentsquare.com/en/capacitor/privacy/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Security - Capacitor description: Data transfer and security information lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/security/ md: https://docs.contentsquare.com/en/capacitor/security/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Capacitor SDK is designed with security and privacy in mind. ## Transmission and hosting All data is encrypted in transport over HTTPS. Our hosting solution is a PCI DSS Level 1 Service Provider. ## What is not collected * Passwords from password fields * Geo location information * Information from contacts, emails, or any other user identifiable information. * Text from labels, buttons, and any other widget which contains text * Accessibility information from any widget which the user interacts with * Labels printed on the screen of any kind ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Security","description":"Data transfer and security information","url":"https://docs.contentsquare.com/en/capacitor/security/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` --- title: Session Replay - Capacitor description: Session Replay implementation and Personal Data masking lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/session-replay/ md: https://docs.contentsquare.com/en/capacitor/session-replay/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Session Replay enables replaying real sessions to observe how users interact with your product, by capturing screen content - including text and images - as users navigate your mobile app. For more details, see [Introduction to Session Replay for Apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) in the Help Center. ## Starter guide ### Prerequisites #### Update to latest SDK version To enable Session Replay in your app and get the most stable version, it is required to [upgrade the SDK](https://docs.contentsquare.com/en/capacitor/#install-the-sdk) to its latest version. #### Implement screen tracking Ensure screen tracking is implemented, since Session Replay collection starts at the first screenview event. See [Track screens](https://docs.contentsquare.com/en/capacitor/track-screens/). #### Handle User consent Ensure user consent is handled, especially if you're implementing the SDK for the first time. See [Privacy](https://docs.contentsquare.com/en/capacitor/privacy/) section. #### Session Replay data collection Data collection settings - such as sampling rate - should be configured in your project parameters, as explained in this [Help Center article ↗](https://support.contentsquare.com/hc/en-us/articles/37271951720721-Data-collection-for-Session-Replay-Apps) ### Configure Session Replay masking See [Personal Data Masking](#personal-data-masking) Warning Always keep sensitive data masked to ensure compliance with privacy regulations and to protect users' personal data. ### Test your setup #### Enable Session Replay on your device Since not all sessions are collected (depending on the percentage set in the Contentsquare back office), we have implemented an option to force replay collection on your device for testing and debugging purposes. This option can be enabled from the in-app features settings: 1. [Enable in-app features](https://docs.contentsquare.com/en/capacitor/in-app-features/) 2. Open in-app features settings with a long press on the screenshot button 3. Under "Session Replay", toggle "Enable Session Replay" on 4. Kill the app 5. Start app, a new session is starting with Session Replay enabled ##### Android  #### How do I know if Session Replay is enabled? There are 2 places where you can check if Session Replay is enabled: **In the logs:** The log `Session Replay is starting` (Android) or `Enable Session Replay for Capacitor succeeded` (iOS) will confirm that Session Replay is enabled. **In in-app features settings:** Below the "Enable "will start at next app start" *(see below [Access the replay](#access-the-replay))*, you will either see: * `No replay link available` which means Session Replay is not running for the current session * `Get Replay link` which means Session Replay is running for the current session #### Access the replay The replay can be accessed by tapping on `Get replay link` button from the in-app features settings: The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay your session up to the previous screenview if the session is still running. ##### Android  ##### iOS  ## Personal Data Masking The Session Replay feature collects every user interaction within your app. to respect the user's right to privacy, the Contentsquare SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our masking and un-masking component. ### Masking mechanisms Warning If your application contains native screens, see the [iOS](https://docs.contentsquare.com/en/ios/session-replay/#personal-data-masking) and the [Android](https://docs.contentsquare.com/en/android/session-replay/#personal-data-masking) Masking documentation. Contentsquare never collects the actual text typed into any `` or `` field. Sessions will be collected for Session Replay if: * The `Session Replay` feature has been enabled for your account * The threshold set by the `Session Replay Collection Rate` is not exceeded. For the HTML content to be sent, all these conditions must be true: * The user hasn't opted out. * The session is being tracked. Warning If Session Replay is turned off, the HTML text/content of the page **is not** collected during the session. ### Session Replay data collection options If Session Replay is turned on and data collection is active for the session, the HTML content of the page is sent **after every pageview** (both natural and artificial) and **every DOM change** (only the updated elements are sent). Depending on the Session Replay option chosen, the resulting replay will differ and additional masking tasks will have to be carried out. Note Always contact your Implementation Manager to check your approach to masking. #### Clear content with masked Personal Data With this option enabled, the Tracking Tag performs the following tasks: * The content of `<input>` elements with type `text`, `email`, `password`, `search`, `tel`, `url` or `<input>` elements without a `type` attribute are replaced with bullets before the HTML is sent, * Every figure of `<input>` elements with type `number` are replaced by 0, * The content `<textarea>` elements is replaced with bullets before the HTML is sent, * The content of `<script>` elements is emptied, * Except for the above, all the HTML content is sent, including `<head>`, * The content of every element marked with the data attribute `data-cs-mask` is removed (see below). Note Dropdowns are usually coded with the `<select>` element, which is collected by default by Contentsquare. If you show any Personal Data in these elements, you would have to make sure to apply the `data-cs-mask` data attribute. #### Auto-masked content with AAA masking With this option enabled, the Tracking Tag performs the following tasks: * The content of `<input>` elements with type `text`, `email`, `password`, `search`, `tel`, `url` or `<input>` elements without a type are replaced with bullets before the HTML is sent, * Every figure of `<input>` elements with type `number` are replaced by 0, * The content `<textarea>` elements is replaced with bullets before the HTML is sent, * The content of `<script>` elements is emptied, * The content of every element marked with the data attribute `data-cs-mask` is removed (see below). * The content of every element marked with the data attribute `data-cs-capture` is collected and shown unless it falls under the excluded elements listed above (`<input>`, `<textarea>`) * **Every character of the text content included in the elements sent is replaced by "A"**. * Attributes unrelated to layout are Only `id`, `class`, `style`, `src`, `srcset`, `href`, `rel`, and `type` are kept. #### Selectively mask pages by URL In case your site displays Personal Data only on a specific set of pages, **you can decide to run the Auto-Masking process only on a pre-defined set of pages**, so that you won't have to apply the masking across the whole site. We have two available options: * **Mask all pages except**: All pages will be masked except the ones defined by a Regex Pattern agreed with your dedicated Implementation Manager. * **Unmask all pages except**: All pages will be collected with clear content except from the ones defined by a Regex pattern agreed with your dedicated Implementation Manager. These can only be configured by your dedicated Implementation Manager. ### Block data collection for specific pages (Session Replay) Use the `excludeURLforReplay` command to block data collection on pages based on their URL. You might want to use this command for the following reasons: * Some page replays for Session Replay cause performance issues (when the page contains many images or videos, for instance) — you can block these pages until the problem is fixed, * Personal data has been exposed, * You want to exclude whole parts of your website from being collected for Session Replay. ```javascript import { ContentsquarePlugin } from "@contentsquare/capacitor-plugin"; ContentsquarePlugin.excludeURLForReplay(URL_REGEX); ``` Using this command does not block page views for the given pages — it only blocks data collection for Session Replay. ### Remove content/Personal Data from the collected HTML There are two methods to remove content from the collected HTML: * Using the Contentsquare Personal Data Selector * Tagging DOM Elements #### Personal Data Selector Each DOM element to be masked is identified thanks to its CSS selector and those selectors are pushed to the API via a JavaScript object. The content of the identified element will be thus removed from the replay. Note In case of CSS selectors being changed or removed, the masking will be removed as well. The following object that contains CSS selectors for text and for attributes should be pushed to the API as follows, **before firing the main tag**: ```javascript import { ContentsquarePlugin } from '@contentsquare/capacitor-plugin'; ContentsquarePlugin.setPIISelectors({PII Object}); ``` The structure of the `PII` Object is as follows: * `PIISelectors`: CSS selectors defined here will allow the **matching DOM element to be masked by the tag.** * `Attributes`: Using this key, one can **remove the defined attributes of the DOM elements from the elements matching the CSS selectors.** it is possible to use an array of attribute names as shown in the example above. Keep in mind that using both `PII Selectors` and `Attributes` is optional, meaning you can use either full element selectors, specific attribute selectors or both in the same object: ```javascript { PIISelectors: [".css-selector, ss-selector"], // DOM elements to be sked Attributes: [ { selector: "select#month option, select#year option", // CSS selectors attrName: 'id' // Attribute name you want to mask }, { selector: ".link-page-7", // CSS selectors attrName: ['href','name'] // Array attribute names you want to mask } ] }; ``` #### Tagging DOM elements To exclude content from being collected, use the `data-cs-mask` attribute on selected elements: ```html Content before <p data-cs-mask>emailaddress@sentitivedata.com</p> Content after ``` Their content is removed in the browser before it is sent to Contentsquare: ```html Content before <p data-cs-mask>emailaddress@sentitivedata.com</p> Content after ``` You can also add the `data-cs-mask` attribute with JavaScript provided you do it before any pageview is sent. **Events on removed HTML** — [Events](https://docs.contentsquare.com/en/web/events-handling/) (click, hover, etc.) will still be collected and sent to our servers even if they are targeting removed HTML elements. They will be visible in the application using Live Resources (as named in the platform). Warning Using comments within the HTML is not supported (`<!-- MousetestSensitiveStart -->...<!-- MousetestSensitiveEnd -->`). ### Display content in a fully masked HTML page There are two methods to display content in a masked HTML page: * Using the Contentsquare Personal Data Selector * Tagging DOM Elements #### Personal Data Selector Each DOM element to be displayed is identified thanks to its CSS selector and those selectors are pushed to the API via a JavaScript object. The content of the identified element will be thus displayed in Session Replay. Note In case of CSS selectors being changed or removed, the element will be masked by default. The string which contains comma-separated CSS selectors for text and for attributes must be pushed to the Contentsquare API, **before firing the main tag**, as follows: ```javascript import { ContentsquarePlugin } from "@contentsquare/capacitor-plugin"; ContentsquarePlugin.setCapturedElementsSelector("#capture-me, .show-me"); ``` #### Tagging DOM elements To display an HTML element in a masked page, add the `data-cs-capture` attribute to the HTML element: ```html Sensitive Content before <p data-cs-capture>some piece of text that is not sensitive</p> Sensitive Content after ``` Content that is part of the tagged element is displayed as is: ```html AAAA AAAA AA <p data-cs-capture>some piece of text that is not sensitive</p> AAA AAA AA ``` It can also be added with JavaScript but, be careful, as attributes must be added before any pageview is sent. ## Known limitations * Some fonts are not loaded * SVG assets are not supported * Zoom is not properly handled ### Android specific * Some screen titles don't correspond to the screen currently shown in the player * Ratio of the screen is not correct while the gesture positions are correct on the player * "Loading webviews" and "Webview not tracked" messages sometimes appear in the player * The CSS is sometimes not immediately loaded on a new page ## Troubleshooting ### Requests are not sent from an Android emulator / iOS simulator If you struggle to watch a replay collected on an emulator/simulator, it may be due to some network constraints applied on your computer (VPN, company network restrictions, etc.). Check your configuration or use a real device. See following sections for more information about our endpoints and requests: * [Android - Requests are failing](https://docs.contentsquare.com/en/android/troubleshooting/#requests-are-failing) * [iOS - Requests are failing](https://docs.contentsquare.com/en/ios/troubleshooting/#requests-are-failing) ### Very long session on an Android emulator / iOS simulator It is important to remember that **an app kill does not end a session**. See [Session definition](https://docs.contentsquare.com/en/ios/how-the-sdk-works/#session-definition) for more information. If you leave the simulator/emulator running with the app in foreground, the session will not end, even if you are inactive. To better reflect actual end user behavior and avoid unusually long sessions (last hours), put the app in background or kill it. ### SR has weird timestamps when using Android / iOS simulator Some bugs with the timestamps only appear when testing with a simulator/emulator. Test out the Session Replay feature when implementing it with a device in order not to trigger it. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Session Replay","description":"Session Replay implementation and Personal Data masking","url":"https://docs.contentsquare.com/en/capacitor/session-replay/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track dynamic variables - Capacitor description: Track dynamic variables with the Contentsquare SDKs and Capacitor lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/track-dynamic-variables/ md: https://docs.contentsquare.com/en/capacitor/track-dynamic-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Dynamic variables are additional information on the session that can be used to segment sessions. For example, they can include information on the A/B Test variations displayed to the current user. ## Defining dynamic variables To define and send a dynamic variable, use the API below. For each dynamic variable, we send: * Key (`string`, mandatory) * Value (`string` or `integer`, mandatory) if you send an integer as a value, it has indeed to be an integer. A null or a float will not be accepted as a valid parameter, and will result in an error. ```javascript import { ContentsquarePlugin, DynamicVarItem } from '@contentsquare/capacitor-plugin'; const myDynamicVar: DynamicVarItem = { dynVarKey: 'myKey', dynVarValue: 32, } ContentsquarePlugin.sendDynamicVar(myDynamicVar) .catch(err => { // Handle Error }); ``` ## Sending a dynamic variable for each session You may want to send a dynamic variable for each session (like the user's country or store). While **triggering the dynamic variable at app launch will cover most cases, it will not be enough**. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See [Session definition](https://docs.contentsquare.com/en/capacitor/how-the-sdk-works/#session-definition) for more information. That is why we also recommend **sending such dynamic variable every time the app enters foreground**. You can use the [`appStateChange` event ↗](https://capacitorjs.com/docs/apis/app) triggered by Capacitor to detect foreground and trigger a dynamic variable. ## Limits ### On the server side * It is possible to save up to 40 distinct dynamic variable keys per screen view. If more are received, only the first 40 keys will be kept. * If you are using the same key twice, the last value associated with the key will be collected. ### On the SDK side * Every dynamic variable is composed of a pair of key (max. 512 characters) and value (max. 255 characters string or a whole number between 0 and 232 - 1 ). The SDK will trim the exceeding characters. * If key or value is empty, the SDK will send the string "cs-empty". ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track dynamic variables","description":"Track dynamic variables with the Contentsquare SDKs and Capacitor","url":"https://docs.contentsquare.com/en/capacitor/track-dynamic-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track screens - Capacitor description: Track screens with the Contentsquare SDKs and Capacitor lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/track-screens/ md: https://docs.contentsquare.com/en/capacitor/track-screens/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare aggregates user behavior and engagement at the screen level. To achieve this, it is necessary to provide a name for each screen by calling a dedicated screenview API. Warning Sessions without at least one screenview will be discarded. ```javascript import { ContentsquarePlugin } from "@contentsquare/capacitor-plugin"; ContentsquarePlugin.sendScreenName(screenName).catch((err) => { // Handle error }); ``` ## Screen name handling The screen name is limited to 2083 characters. However, this limit is not enforced by the SDK, but rather by the Contentsquare servers. ## Screenview after app in background The SDK triggers a screenview automatically after the app is put in background and foreground, as long as a screenview with a screen name has been triggered previously. It will use the last screen name set. ## Implementation recommendations From a functional standpoint, we expect a screenview to be sent: * When the screen appears * When a modal/pop-up is closed and the user is back on the screen * When the app is put in the foreground (after an app hide) ## How to name screens As a general rule, keep the number of distinct screen names under 100. Since these names are used to map your app in Contentsquare, choose names that are clear and comprehensive. ### Separate words with space, dash, or underscore characters If you want to generate screen names including more than one word, it is best to separate them and to do so using space, dash, or underscore characters. Contentsquare handles automatically the formatting for them. **Example:** For a sub-category list of a retail app, use `Home and Living - Home Furnishings` instead of `homeLivingHomeFurnishings`. ### Use screen template/layout names As a general recommendation, use names referring to the screen template/layout rather than referring to the specific content (data). This will help: * To keep the number of distinct screen names low and therefore make Contentsquare easier to use * Remove the risk of sending Personal Data to Contentsquare List of screen types falling into that category: *Product detail, Event detail, Conversation/Chat, User profile...* ### Screens with multiple states/layouts Screens can have different layouts or states depending on the user context. In this case, append its value to the screen name. **Home screen** | State | Screen name | | - | - | | App landing layout | `Home` | | Women products layout | `Home - Women` | | Men products layout | `Home - Men` | | Sales layout | `Home - Sales` | **Product Detail screen (PDP)** | State | Screen name | | - | - | | Users on a Top for Women PDP | `PDP - Clothing - Women - Tops` | | Users on a Microwave PDP | `PDP - Kitchenware - Electrics - Microwave` | | Users on a Hotel details screen | `PDP - Holiday type - Season - Board` | **User account screen** | State | Screen name | | - | - | | Overview | `My Account - Dashboard` | | Order history | `My Account - Order history` | | Returns | `My Account - Returns` | **Search screen** | State | Screen name | | - | - | | Search | `Search` | | Search results for "Skincare" products | `Search - Skincare` | | Search results error screen | `Search - Error` | **Cart screen** | State | Screen name | | - | - | | Empty cart | `Cart - Empty` | | Items have been added to the cart | `Cart - Populated` | | Issues with availability or pricing | `Cart - Error` | **Checkout screen** | State | Screen name | | - | - | | User provides name, surname, and date of birth | `Checkout - User Details` | | User provides shipping address | `Checkout - Shipping Details` | | User inputs their credit card information | `Checkout - Payment` | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track screens","description":"Track screens with the Contentsquare SDKs and Capacitor","url":"https://docs.contentsquare.com/en/capacitor/track-screens/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Amazon S3 - Data Connect description: Instructions for setting up and using Connect with Amazon S3 lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/connect/amazon-s3/ md: https://docs.contentsquare.com/en/connect/amazon-s3/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Amazon S3 (Simple Storage Service) is an object storage service that offers industry-leading scalability, data availability, security, and performance. The Data Connect integration with S3 allows you to export your Contentsquare data to S3 for flexible storage and analysis options. Unlike the other warehouse integrations (BigQuery, Redshift, Snowflake), the S3 integration provides raw data files that you can process with your preferred analytics tools, such as Athena, EMR, or third-party data processing services. ## Prerequisites Before setting up the S3 integration, ensure you have: * **An AWS account** with S3 access * **An S3 bucket** to store Contentsquare data * **AWS credentials** with appropriate permissions for the S3 bucket ## Set up AWS S3 1. Create an S3 bucket to store Contentsquare data (if you don't already have one) 2. Create an IAM user or role with appropriate permissions. The IAM policy should include: * `s3:PutObject` * `s3:GetObject` * `s3:ListBucket` * `s3:DeleteObject` * `s3:PutObjectAcl` 1) Apply the appropriate bucket policy for your region: * US ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1441164338000", "Effect": "Allow", "Action": [ "s3:*" ], "Resource": [ "arn:aws:s3:::", "arn:aws:s3:::/*" ], "Principal": { "AWS": [ "arn:aws:iam::085120003701:root" ] } } ] } ``` * EU ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "ConnectEU", "Effect": "Allow", "Action": [ "s3:*" ], "Resource": [ "arn:aws:s3:::", "arn:aws:s3:::/*" ], "Principal": { "AWS": [ "arn:aws:iam::556519846140:root" ] } } ] } ``` 2) Generate AWS access keys for the IAM user (if using user-based authentication). ## Configure Contentsquare Connect Admin only Configuration of this destination is only available to admin users in Contentsquare. 1. Log in to Contentsquare. 2. Navigate to **Analysis setup** > **Data Connect**. 3. Create the S3 bucket `csq-rs3-<bucket_name>` to sync Data Connect data with. 4. Select **Next**. 5. Add the displayed policy to your CSQ bucket on S3. 6. Input your S3 credentials to connect to your bucket. 7. Select **Connect**. Once setup is complete, you'll see a sync within 24 hours with the following built-in tables. ## Understand your data delivery ### Data organization in S3 When Data Connect syncs data to S3, it creates the following structure: ```plaintext s3://your-bucket/ ├── sync_[sync_id]/ │ ├── _heap_table_name=users/ │ │ ├── part-00000-[uuid].avro │ │ ├── part-00001-[uuid].avro │ │ └── ... │ ├── _heap_table_name=sessions/ │ │ ├── part-00000-[uuid].avro │ │ ├── part-00001-[uuid].avro │ │ └── ... │ ├── _heap_table_name=pageviews/ │ │ └── ... │ ├── _heap_table_name=[custom_event_name]/ │ │ └── ... │ └── ... ├── manifests/ │ └── ... └── sync_reports/ └── ... ``` Each sync folder follows the pattern `sync_[sync_id]/_heap_table_name=[table_name]/part-[part_number]-[uuid].avro`. For example: `sync_1010103140/_heap_table_name=sessions/part-00061-45d3eb01-f863-460b-a4ec-c6ab45d.avro` The data is organized by: * Sync ID (a unique identifier for each sync operation) * Table name (users, sessions, pageviews, custom events), prefixed with `_heap_table_name=` * Part files (data is split into multiple Avro-encoded files) ### Manifest metadata Each periodic data delivery will be accompanied by a manifest metadata file, which will describe the target schema and provide a full list of relevant data files for each table. ```json { "dump_id": 1234, "tables": [ { "name": "users", "files": [ "s3://customer/sync_1234/_heap_table_name=users/part-00000-a97432cba49732.avro", "s3://customer/sync_1234/_heap_table_name=users/part-00001-584cdba3973c32.avro", "s3://customer/sync_1234/_heap_table_name=users/part-00002-32917bc3297a3c.avro" ], "columns": [ "user_id", "last_modified", // ... ], "incremental": true }, { "name": "user_migrations", "files": [ "s3://customer/sync_1234/_heap_table_name=user_migrations/part-00000-2a345bc452456c.avro", "s3://customer/sync_1234/_heap_table_name=user_migrations/part-00001-4382abc432862c.avro" ], "columns": [ "from_user_id", "to_user_id", // ... ], "incremental": false // always false for migrations }, { "name": "defined_event", "files": [ "s3://customer/sync_1234/_heap_table_name=defined_event/part-00000-2fa2dbe2456c.avro" ], "columns": [ "user_id", "event_id", "time", "session_id", // ... ], "incremental": true } ], "property_definitions": "s3://customer/sync_1234/property_definitions.json" } ``` It includes the following information: * `dump_id`: A monotonically increasing sequence number for dumps. * `tables`: For each table synced: * `name`: The name of the table. * `columns`: An array consisting of the columns contained in the table. This can be used to determine which columns need to be added or removed downstream. * `files`: An array of full s3 paths to the Avro-encoded files for the relevant table. * `incremental`: A boolean denoting whether the data for the table is incremental on top of previous dumps. A value of false means it is a full/fresh resync of this table, and all previous data is invalid. * `property_definitions`: The s3 path to the defined property definition file. Ignore any files in the data delivery that aren't listed in the manifest metadata file. ### Sync reporting Each sync will be accompanied by a sync log file that reports on delivery status. These log files will be placed in the `sync_reports` directory. Each report will be in a JSON format as follows: ```json { "start_time":1566968405225, "finish_time":1566968649169, "status":"succeeded", "next_sync_at":1567054800000, "error":null } ``` `start_time`, `finish_time`, and `next_sync_at` are represented as epoch timestamps. See [Data Syncing](https://docs.contentsquare.com/en/connect/data-syncing/) to learn how the data will be structured upon sync. ### Data types and formats The `user_id`, `event_id`, and `session_id` are the only columns that are long types. All other columns should be inferred as string types. ## Process your S3 data When working with Contentsquare data in S3, you need to perform several processing steps to ensure data accuracy and completeness. The following sections outline the key considerations for building your ETL pipeline. ### Identity resolution Contentsquare's identify API allows you to create a single, cohesive view of a user across devices, browsers, and domains. When a user is identified via the identify API, their anonymous `user_id` is updated to a new `user_id`, which is a hash of the identity. Once this is set up, when this user is identified on another device or browser, this tells us that these users are the same, and that we should join their data together. Internally, we call this a "user migration" because we are migrating user and event data from one record to another. In other words, we are resolving data from two users into one identity. This is identity resolution, at a high-level. In the Contentsquare app, we handle this for you. In Redshift exports, we handle this on write. In Snowflake and BigQuery exports, we handle this on write and in a view. However, in S3 exports, we do not resolve identities for you. To merge this user activity correctly, you must resolve their identity using the `user_migrations` table. How do I apply this identity resolution mapping in my data warehouse? The `user_migrations` table contains a mapping of `from_user_id` to `to_user_id`, and should be joined against the `users` table and all pertinent event tables. You should create a view based on these joins that will refresh on a regular cadence. Below is an example of the view you should create to resolve identity on the users table - join `user_migrations.from_user_id` on `users.user_id`, and then coalesce `to_user_id` and `user_id` to obtain the user's final state: ```sql CREATE VIEW users_view AS SELECT user_id, MIN("joindate") AS "joindate", MAX("last_modified") AS "last_modified", MAX("identity") AS "identity", MAX("handle") AS "handle", MAX("email") AS "email", FROM ( SELECT COALESCE("to_user_id", "user_id") AS "user_id", "joindate","last_modified","identity","handle","email" FROM users u LEFT JOIN user_migrations m ON u.user_id = m.from_user_id ) x GROUP BY user_id; ``` The following example illustrates the view you should create to resolve identity on each of your synced event tables. Make sure to select all unique columns from each event table to replicate the desired table with migrations applied. Each time you toggle on a new event table to sync in the Contentsquare UI, create this migrated view for that table: ```sql CREATE VIEW example_event_migrated_view AS SELECT COALESCE("to_user_id", "user_id") AS "user_id", "event_column_1","event_column_2","event_id","session_id","time","session_time","type","library","platform","device_type","country","region","city","ip","referrer","landing_page","browser","search_keyword","utm_source","utm_campaign","utm_medium","utm_term","utm_content","domain","query","path","hash","title","href","target_text" FROM example_event_to_be_migrated e LEFT JOIN user_migrations m ON e.user_id = m.from_user_id ; ``` ### Deduplication Data across dumps/files are not guaranteed to be disjointed. As a result, downstream consumers are responsible for de-duplication. De-duplication must happen after applying user migrations. Here's a strategy you can adopt: | Table | De-duplication Columns | | - | - | | Sessions | `session_id`, `user_id` | | Users | `user_id` | | Event tables | `event_id`, `user_id` | ### Handle user updates Updated users (users with properties that have changed since the last sync) will re-appear in the sync files, and thus every repeated occurrence of a user (check on `user_id`) should replace the old one to ensure that the corresponding property updates are picked up. ### Apply user migrations `user_migrations` is a fully materialized mapping of `from_user_ids` to `to_user_ids`. Downstream consumers are responsible for joining this with events/users tables downstream to resolve identity retroactively. ### Process property definitions For v2, we only sync defined property definitions rather than the actual defined property values. Downstream consumers are responsible for applying these definitions to generate the defined property values for each row. ### Manage schema evolution Schemas are expected to evolve over time: properties can be added to the user and events tables. ## S3-Specific Considerations Working with Data Connect in S3 requires understanding several S3-specific behaviors and best practices. ### Full Sync Triggers The following actions will trigger a full resync of individual tables: * **Adding new events**: When you define and enable a new event in Contentsquare * **Toggling events on/off**: Turning an event sync on or off in the Contentsquare UI * **Configuration changes**: Modifying sync settings or warehouse configuration The `user_migrations` table **always** performs a full sync, regardless of changes. To minimize disruption: * Plan event definition changes during low-traffic periods * Test new events in a development environment first * Monitor sync reports after making changes ### Encryption Setup Data Connect supports server-side encryption for S3 buckets. **Supported Encryption:** * **SSE-S3** (Amazon S3-Managed Keys): Fully supported, no additional configuration required * Set default bucket encryption in your S3 bucket settings **Not Supported:** * **SSE-KMS** (AWS Key Management Service Keys): Not supported To enable SSE-S3 encryption: 1. Navigate to your S3 bucket in the AWS Console 2. Go to **Properties** > **Default encryption** 3. Select **AES-256 (SSE-S3)** 4. Save changes No additional IAM roles or permissions are required for SSE-S3. See [AWS documentation ↗](https://docs.aws.amazon.com/AmazonS3/latest/userguide/default-bucket-encryption.html) for detailed instructions. ### Schema Change Handling Schema changes in S3 behave differently than in other warehouses: **Adding Properties:** * New columns appear in subsequent syncs automatically * Historical data will not include the new property (no backfill) * The property will be present in new data files going forward **Removing Properties:** * Archived properties stop syncing immediately * The column/field stops appearing in new data files * Historical files still contain the property data **Property Type Changes:** * Not automatically handled - you must manage in your ETL process * Consider versioning your data schema * Use manifest files to track schema evolution Unlike warehouse integrations, S3 does not automatically update table schemas. You are responsible for: * Detecting schema changes via manifest files * Updating your ETL process to handle new/removed columns * Managing schema versioning in your data lake ### Sync Failure Recovery If a sync fails, Data Connect will automatically retry: 1. **Automatic Retries**: Most failures are transient and resolve automatically 2. **Monitoring**: Check sync reports in the `sync_reports` directory for status 3. **Manual Intervention**: In rare cases, you may need to contact support To monitor sync health: ```shell # Check latest sync report aws s3 cp s3://your-bucket/sync_reports/latest.json - # Monitor for failed syncs aws s3 ls s3://your-bucket/sync_reports/ | grep -i "failed" ``` Common failure causes: * Insufficient S3 permissions * Bucket policy misconfigurations * S3 service disruptions * Network connectivity issues ### Sync Completion Status To determine if a sync has completed: 1. **Monitor manifest files**: A new manifest signals sync completion ```shell # List recent manifests aws s3 ls s3://your-bucket/manifests/ --recursive | tail -5 ``` 2. **Check sync reports**: Look for `"status": "succeeded"` in sync reports ```shell # Get latest sync report aws s3 cp s3://your-bucket/sync_reports/$(aws s3 ls s3://your-bucket/sync_reports/ | tail -1 | awk '{print $4}') - ``` 3. **Validate data files**: Confirm all expected tables have new data files ```shell # List recent syncs aws s3 ls s3://your-bucket/ | grep sync_ ``` 4. **Schedule ETL jobs**: Trigger your ETL pipeline after manifest delivery ### Numeric Folder Values Each S3 sync creates folders with numeric identifiers: **Sync ID (`sync_[number]`):** * Incremental identifier for each sync operation * Example: `sync_1234567890/` * Used to organize data by sync batch * Corresponds to `dump_id` in manifest files **Dump ID:** * Monotonically increasing sequence number * Found in manifest metadata files * Links manifest files to their corresponding data folders * Example: `"dump_id": 1234567890` matches `sync_1234567890/` **Table Name Prefix:** * Each table is stored under `_heap_table_name=[table_name]/` * Example: `sync_1234/_heap_table_name=sessions/` * This format enables Hive-style partitioning in tools like Athena Use these identifiers to: * Track which sync batch each file belongs to * Build incremental ETL processes * Audit data lineage and sync history * Partition data in your data lake ## Limitations Contentsquare does not perform deduplication or identity resolution in S3 exports: your organization needs to manage the ETL process. **Data Deduplication:** * Not performed automatically - you must deduplicate in your ETL * Use the deduplication columns specified in the [Amazon S3 setup guide](#deduplication) * Apply deduplication after identity resolution for accurate results **Timestamp Formats:** * All timestamp columns use UNIX timestamp format (milliseconds since epoch) * Warehouses use native timestamp types (such as `TIMESTAMP`, `DATETIME`) * You must convert timestamps during ETL: ```sql -- Example conversion in Athena FROM_UNIXTIME(joindate / 1000) AS joindate_timestamp ``` **Schema Enforcement:** * No automatic schema validation or enforcement * Your ETL process must handle schema mismatches * Monitor manifest files for schema changes **Partitioning and Performance:** * Data is not pre-partitioned by date * You should repartition data during ETL for optimal query performance * Consider using Parquet or ORC formats with date-based partitioning * Example partitioning strategy: partition by year, month, and day ## FAQs ### Why don't I see initial user properties in Data Connect? Initial User properties (such as Initial Marketing Channel or Initial Browser) are not synced downstream in Data Connect. See [Creating An Enhanced Users Table](https://docs.contentsquare.com/en/connect/common-queries/#creating-an-enhanced-users-table) for an example of how to recreate those properties in your warehouse. ### What triggers a full sync for tables in S3? The addition of new events, and toggling an event on or off within the Contentsquare UI, will result in the full sync of an individual table. the `user_migrations` table always does a full sync. ### How do I set up encryption with S3? In terms of server-side encryption, Contentsquare supports only the Amazon S3-managed keys (SSE-S3) encryption key type. Buckets using the AWS Key Management Service key (SSE-KMS) encryption key type are **not** supported. No additional user/role in S3 is required. For instructions on how to edit your bucket's default encryption, see [AWS documentation ↗](https://docs.aws.amazon.com/AmazonS3/latest/userguide/default-bucket-encryption.html). ### Does an S3 schema change initiate a full sync? Schema changes should not initiate a full sync. In cases where a property is synced/unsynced from within the Contentsquare app, the property (column) will either be added or stop being included going forward. However, if you need to populate the column retroactively, a full resync of a given table is needed. ### How often is the schema of each table expected to change? For the users, pageviews, sessions, and `user_migrations` tables and their respective built-in properties, the schema typically stays the same. However, it is common for properties to be added/removed (archived/unsynced) from the Contentsquare app. when a new property is captured, it is automatically included in Data Connect. ### What happens after an S3 sync fails? The majority of sync failures will re-attempt and resolve themselves. In rare cases, manual intervention may be required. ### How can I tell if an S3 sync is completed for today? Completion of a sync is signaled by the delivery of a new manifest file. You should poll `s3://<BUCKET>/manifests/*` for new manifests. Once a manifest is delivered, you can process it via your ETL pipeline. ### What is the numeric value appended to each sync folder? This value is the `dump_id` which is appended to each sync and is used to associate the folder to the respective manifest located in `s3://<BUCKET>/manifests/*`. For example, the folder name may look like `sync_123456789/`. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Amazon S3","description":"Instructions for setting up and using Connect with Amazon S3","url":"https://docs.contentsquare.com/en/connect/amazon-s3/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track transactions - Capacitor description: Track transactions with the Contentsquare SDKs and Capacitor lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/capacitor/track-transactions/ md: https://docs.contentsquare.com/en/capacitor/track-transactions/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To associate a user's session with their potential purchases (and corresponding revenue), you must send the transaction via a dedicated API. For each transaction, we send: * Price (`number`, mandatory) * Currency (`CurrencyCode` or `string`, mandatory) * Transaction ID (`string`, optional) The plugin defines a `TransactionItem` type to prevent potential typing errors. ```javascript import { ContentsquarePlugin, CurrencyCode, TransactionItem } from '@contentsquare/capacitor-plugin'; const myTransaction: TransactionItem = { transactionValue: 10, transactionCurrency: CurrencyCode.USD, transactionId: 'my_transaction_id', }; ContentsquarePlugin.sendTransaction(myTransaction) .catch(err => { // Handle Error }); ``` Warning **Each transaction must only be sent once**. A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ## Currency The currency is conforming to the [ISO 4217 ↗](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) standard. Although the currency can be passed as "alphanumeric code", you should always prefer using the plugin's CurrencyCode object values. If you have to pass the ISO code as a string, capitalization is not a factor (`"USD"`, `"Usd"` or `"usd"` will all be treated as the US Dollar). If the currency passed doesn't match our supported currencies, the SDK will send a currency value of "-1". It will be processed as the default currency of the project. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track transactions","description":"Track transactions with the Contentsquare SDKs and Capacitor","url":"https://docs.contentsquare.com/en/capacitor/track-transactions/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: BigQuery - Data Connect description: Instructions for setting up and using Data Connect with Google BigQuery lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/connect/bigquery/ md: https://docs.contentsquare.com/en/connect/bigquery/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Google BigQuery is a fully managed, serverless data warehouse that enables scalable analysis over petabytes of data. The Data Connect integration with BigQuery allows you to automatically sync your Contentsquare data to BigQuery for advanced analysis and joining with other business data. Tip As part of this integration, Contentsquare creates the dataset in BigQuery for you during the initial sync. You do not need to create it manually. ## Prerequisites Before setting up the BigQuery integration, ensure you: 1. [Have a Google Cloud Platform (GCP) project ↗](https://support.google.com/cloud/answer/6251787?hl=en\&ref_topic=6158848). 2. [Enable billing in the GCP project ↗](https://cloud.google.com/billing/docs/how-to/modify-project). 3. [Enable the BigQuery API ↗](https://console.cloud.google.com/flows/enableapi?apiid=bigquery) 4. Know the region you want to use among `us`, `eu`, `europe-west1`, `europe-west2`, `europe-west4`, `europe-west6`, `us-central1`, `us-west1`, `us-west2`, `us-east4`, or `australia-southeast1`. 5. (Optional) Decide on a name for your dataset (default is `project_environment`). These prerequisites are also outlined in Google Cloud Platform [quick-start guide ↗](https://cloud.google.com/bigquery/docs/quickstarts/quickstart-web-ui) ## BigQuery setup Within the [GCP dashboard ↗](https://console.cloud.google.com/home/dashboard) for your selected project, visit `IAM & admin` settings and click **+ Add**. In the subsequent view, add `heap-sql@heap-204122.iam.gserviceaccount.com` with the `BigQuery User` role and save the new permission. We would prefer to be added as a BigQuery user per the steps above. At minimum, we need to be assigned to a `dataEditor` role, and we need the following [permissions ↗](https://cloud.google.com/bigquery/docs/access-control): **Project Permissions** * `bigquery.datasets.get` * `bigquery.jobs.create` **Dataset Permissions** * `bigquery.routines.create` * `bigquery.routines.delete` * `bigquery.routines.get` * `bigquery.routines.list` * `bigquery.routines.update` * `bigquery.tables.create` * `bigquery.tables.delete` * `bigquery.tables.get` * `bigquery.tables.getData` * `bigquery.tables.list` * `bigquery.tables.update` * `bigquery.tables.updateData` See how to grant individual permissions to create a [custom IAM role ↗](https://console.cloud.google.com/projectselector2/iam-admin/iam) for Contentsquare. ### External service account If you must, you can use your own GCP service account and have Data Connect write to a bucket in your Cloud Storage. Contentsquare will authenticate as your service account to deliver files into your bucket and if configured load them into BigQuery. In this case, provide Contentsquare teams with the: * Email associated with your GCP service account * Private key for this service account * Bucket name ### Virtual Private Cloud (VPC) If you have a Virtual Private Cloud: * Create a GCS staging bucket that allows ingress from outside the perimeter and share the bucket name with Contentsquare * Setup a perimeter bridge including this staging bucket and the target BigQuery dataset ## Configure Data Connect Admin only Configuration of this destination is only available to admin users in Contentsquare. 1. Log in to Contentsquare. 2. Navigate to **Analysis setup** > **Data Connect**. 3. Select **Connect** next to BigQuery. 4. Enter your BigQuery hostname and select **Next**. 5. Supply the required information: * Your **Project ID**, which you can find in the `Project info` section of your GCP project dashboard (make sure you're in the correct project). * Your **region**: `us`, `eu`, `europe-west1`, `europe-west2`, `us-central1`, `us-west1`, `us-west2`, `australia-southeast1`, `europe-west6`, or `us-east4`. * The **dataset name override** if you don't want the default. The default dataset name is `project_environment`. For example, the Main Production environment will default to a dataset name of `main_production`. 6. Select **Connect**. ## Advanced Features ### Partitioning Data Connect automatically partitions BigQuery tables by date to optimize query performance and reduce costs. Understanding how partitioning works helps you write more efficient queries. **How Data Connect Partitions Tables:** * Event tables are partitioned by the `time` column * Partitions are created daily based on event timestamps * Each partition contains all events for that specific date **Benefits of Partitioning:** * **Reduced query costs**: Queries that filter by date only scan relevant partitions * **Improved performance**: Less data to scan means faster query execution * **Automatic pruning**: BigQuery automatically eliminates unnecessary partitions **Writing Partition-Aware Queries:** ```sql -- Good: Uses partition filter on time column SELECT user_id, event_id, time FROM `your-project.main_production.page_viewed` WHERE DATE(time) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY) -- Bad: Scans all partitions (expensive) SELECT user_id, event_id, time FROM `your-project.main_production.page_viewed` WHERE user_id = 12345 ``` **Partition Pruning Tips:** * Always include a `WHERE` clause on the `time` column when possible * Use `DATE(time)` for date-based filters * Combine date filters with other conditions for optimal performance **Check Partition Details:** ```sql -- View partition information SELECT partition_id, total_rows, total_logical_bytes FROM `your-project.main_production.INFORMATION_SCHEMA.PARTITIONS` WHERE table_name = 'page_viewed' ORDER BY partition_id DESC LIMIT 10 ``` ### External Service Account Setup In some cases, you may need to use your own Google Cloud Platform (GCP) service account for Data Connect instead of Contentsquare's default service account. **When to Use a Custom Service Account:** * Your organization requires all data access to use internal service accounts * You need granular control over permissions and access logs * You have VPC Service Controls that restrict external service accounts * You want to route data through your own Cloud Storage bucket **Step-by-Step Configuration:** 1. **Create a Service Account** in your GCP project: ```shell gcloud iam service-accounts create contentsquare-connect \ --display-name="Contentsquare Data Connect" \ --project=your-project-id ``` 2. **Grant Required Permissions** to the service account: ```shell # BigQuery permissions gcloud projects add-iam-policy-binding your-project-id \ --member="serviceAccount:contentsquare-connect@your-project-id.iam.gserviceaccount.com" \ --role="roles/bigquery.dataEditor" gcloud projects add-iam-policy-binding your-project-id \ --member="serviceAccount:contentsquare-connect@your-project-id.iam.gserviceaccount.com" \ --role="roles/bigquery.jobUser" ``` 3. **Create a Cloud Storage Staging Bucket** (if needed): ```shell gsutil mb -p your-project-id -l us gs://your-csq-staging-bucket # Grant service account access gsutil iam ch serviceAccount:contentsquare-connect@your-project-id.iam.gserviceaccount.com:objectAdmin \ gs://your-csq-staging-bucket ``` 4. **Generate Service Account Key**: ```shell gcloud iam service-accounts keys create contentsquare-key.json \ --iam-account=contentsquare-connect@your-project-id.iam.gserviceaccount.com ``` 5. **Provide Credentials to Contentsquare**: * Service account email: `contentsquare-connect@your-project-id.iam.gserviceaccount.com` * Private key (from `contentsquare-key.json`) * Bucket name (if using staging bucket) **Security Considerations:** * **Rotate keys regularly**: Generate new service account keys periodically * **Limit permissions**: Only grant the minimum required permissions * **Monitor access**: Enable audit logging for the service account * **Secure key storage**: Never commit service account keys to version control * **Use IAM conditions**: Apply conditional access policies where appropriate **Required Permissions:** The service account needs these specific BigQuery permissions: * `bigquery.datasets.get` * `bigquery.jobs.create` * `bigquery.routines.*` (`create`, `delete`, `get`, `list`, `update`) * `bigquery.tables.*` (`create`, `delete`, `get`, `getData`, `list`, `update`, `updateData`) If using a staging bucket, also grant: * `storage.objects.create` * `storage.objects.delete` * `storage.objects.get` * `storage.objects.list` ### VPC Service Controls VPC Service Controls create security perimeters around GCP resources to prevent data exfiltration and unauthorized access. If your organization uses VPC Service Controls to secure GCP resources, you need to implement the following steps for Data Connect to work: 1. Create a GCS Staging Bucket outside the perimeter: ```shell # Create bucket in the same region as your BigQuery dataset gsutil mb -p your-project-id -l us gs://csq-staging-bucket # Grant Contentsquare's service account access gsutil iam ch serviceAccount:heap-sql@heap-204122.iam.gserviceaccount.com:objectAdmin \ gs://csq-staging-bucket ``` The staging bucket must be accessible from both Contentsquare (outside your perimeter) and your BigQuery dataset (inside your perimeter). 2. Create a perimeter bridge to allow data flow from the staging bucket to BigQuery: ```shell # Get your perimeter name gcloud access-context-manager perimeters list --policy=YOUR_POLICY_ID # Create bridge configuration gcloud access-context-manager perimeters update YOUR_PERIMETER_NAME \ --set-egress-policies=egress-policy.yaml \ --policy=YOUR_POLICY_ID ``` Example `egress-policy.yaml`: ```yaml - egressFrom: identities: - serviceAccount:heap-sql@heap-204122.iam.gserviceaccount.com egressTo: resources: - projects/YOUR_PROJECT_NUMBER operations: - serviceName: storage.googleapis.com methodSelectors: - method: "*" ``` 3. During Data Connect setup, provide Contentsquare with: * Project ID * BigQuery dataset name * Staging bucket name: `gs://csq-staging-bucket` * Region * VPC perimeter name (for support reference) 4. Once the setup is complete, verify data is flowing correctly: ```sql -- Check recent sync activity SELECT table_name, TIMESTAMP_MILLIS(creation_time) as created FROM `your-project.main_production.__TABLES__` ORDER BY creation_time DESC LIMIT 10 ``` If syncs fail with VPC-related errors, follow these steps to troubleshoot: 1. Verify the staging bucket is **not** inside the VPC perimeter 2. Check that the perimeter bridge includes the staging bucket 3. Confirm egress policies allow Contentsquare's service account 4. Review VPC Service Controls audit logs for denied requests 5. Ensure the staging bucket and BigQuery dataset are in the same region Common error messages include: * `"Request violates VPC Service Controls"`: Perimeter bridge not configured correctly * `"Bucket is inside VPC perimeter"`: Staging bucket must be outside the perimeter * `"Permission denied"`: Service account lacks necessary IAM permissions ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"BigQuery","description":"Instructions for setting up and using Data Connect with Google BigQuery","url":"https://docs.contentsquare.com/en/connect/bigquery/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Common Queries - Data Connect description: Common queries for analyzing Contentsquare data in your BI tool or directly on your cluster lastUpdated: 20 April 2026 source_url: html: https://docs.contentsquare.com/en/connect/common-queries/ md: https://docs.contentsquare.com/en/connect/common-queries/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Here's a collection of common queries you can use with Data Connect. Copy and paste these queries into your BI tool or run them directly on your cluster. Some queries may require you to update property names, event names, or date ranges to fit your specific needs. ## Basic Queries ### Event Counts ```sql SELECT device_type ,plan ,COUNT(session_id) FROM main_production.sessions AS sessions INNER JOIN main_production.users AS users ON sessions.user_id = users.user_id GROUP BY 1, 2 ``` ### Average Property Value ```sql SELECT [Property_to_Group_By], AVG([Numeric_Property]) FROM main_production.[event_name] GROUP BY 1 ORDER BY 1 ``` ## Aggregate Metrics In this section, you'll find various queries to measure aggregate metrics for your site, including average time, top events, and more. The value of these queries increases as you segment them by user personas, and the same logic can also be applied to calculate more specific statistics. ### Top 10 Events The top 10 events shed light on how users are interacting with your app. Looking at this list generates a lot of questions: Why are users selecting this button? Why are users viewing this page? Are these two actions correlated? Does the high event count come from users' success within the product, or is this caused by confusion? You can modify the `WHERE` statement to adjust the date range. You can include the date in the `SELECT` statement and `GROUP BY` clause to measure how the most frequently performed actions change over time. You can also adjust the number of events you are looking at by modifying the `LIMIT`. ```sql SELECT all_events.event_table_name AS "Event" ,COUNT(*) AS "Event Count" FROM main_production.all_events AS all_events WHERE time >= DATEADD(day, -30, getdate()) GROUP BY 1 ORDER BY 2 DESC LIMIT 10 ``` ### Average Time on Site This query is primarily beneficial to you if you have a content site, and there aren't a lot of user interactions to capture while reading, and avid readers don't always comment or share. Although this is a proxy for engagement, drastic changes in time on site can cue you in to investigate how users are engaging with your product. You can tweak this query to analyze average time between events, or break it down into different segments of users to get a better understanding of your site's usage. ```sql SELECT ROUND(AVG(duration)::FLOAT, 4) "Average Session time in Minutes" FROM ( SELECT session_id || '-' || user_id AS "unique" ,MIN(time) AS "start" ,MAX(time) AS "last" ,((DATEDIFF('milliseconds', MIN(time), MAX(time))::FLOAT / 1000) / 60) AS "duration" FROM main_production.all_events -- modify your date range here WHERE time >= DATEADD('month', -2, getDate()) GROUP BY 1 ) ``` ### Average Time on Page ```sql WITH ordered_pageviews AS ( SELECT * ,row_number() OVER (PARTITION BY user_id, session_id ORDER BY TIME ASC) AS rn FROM main_production.pageviews WHERE TIME >= DATEADD('month', -1, getDate()) ) SELECT a.path ,avg(pageview_time) / 60 as avg ,round(percentile_cont(0.25) within group (order by pageview_time) / 60, 2) as p25 ,round(percentile_cont(0.5) within group (order by pageview_time) / 60, 2) as median ,round(percentile_cont(0.75) within group (order by pageview_time) / 60, 2) as p75 ,round(percentile_cont(0.9) within group (order by pageview_time) / 60, 2) as p90 FROM ( SELECT p1.session_id ,p1.user_id ,p1.path ,datediff('seconds', p1.time, p2.time) AS pageview_time FROM ordered_pageviews p1 JOIN ordered_pageviews p2 ON p1.session_id = p2.session_id AND p1.user_id = p2.user_id AND p1.rn + 1 = p2.rn -- optional filter to limit paths you're analyzing -- WHERE p1.path !~ '/app' GROUP BY p1.session_id, p1.user_id, p1.path, p1.time, p2.time ) a GROUP BY 1 ORDER BY 2 DESC; ``` ### Average Events per Session The average events per session metric can give you insight into aggregate behavior. This query can also be modified to analyze behavior across segments and over time, allowing you to answer questions such as: Does this number change with a product launch or tweaks to the onboarding flow? Do different types of users interact differently? Changes in the average can prompt investigation into what is really happening within your app. ```sql SELECT Round(Count(DISTINCT event_id)::DECIMAL / Count(DISTINCT session_id), 2) AS "average" FROM main_production.all_events -- modify your date range here WHERE TIME >= Dateadd('day', -30, Getdate()) ``` ### Average Events per Session Over Time To modify this query to calculate the average number of events per session over the past year or past six months, update the `WHERE` statement to include the time range and add a `GROUP BY` clause to address the granularity. ```sql SELECT TO_CHAR(main_production.all_events.time, 'YYYY-MM') as month ,ROUND(COUNT(DISTINCT event_id)::DECIMAL / COUNT(DISTINCT session_id), 2) AS "average" FROM main_production.all_events -- modify your date range here WHERE time >= DATEADD('month', -6, getdate()) GROUP BY 1 ``` ### Average Events per Session by User Property To calculate this, join the all events table on the user table and add a `GROUP BY` clause based on the user properties you want to use for segmentation. ```sql SELECT user_property ,ROUND(COUNT(DISTINCT event_id)::DECIMAL / COUNT(DISTINCT session_id), 2) AS "average" FROM main_production.all_events JOIN main_production.users ON main_production.all_events.user_id = main_production.users.user_id -- modify your date range here WHERE time >= DATEADD('day', -30, getdate()) GROUP BY 1 ``` ### Average Sessions per User The average number of sessions per user can be used in the same way as average events per session and can be modified in the same manner. To find the average number of sessions per user, divide the number of unique sessions by the number of unique users across the time period. ```sql SELECT ROUND(COUNT(DISTINCT session_id)::DECIMAL / COUNT(DISTINCT user_id), 2) FROM main_production.sessions -- modify the date range here WHERE time >= DATEADD('day', -30, GETDATE()) ``` ### Average Sessions Before Signup (or any other event) ```sql WITH first_signup AS ( SELECT user_id, min(time) AS first_time FROM main_production.sign_up GROUP BY 1 ), sessions_pre_signup AS ( SELECT sessions.user_id, count(distinct session_id) AS total_sessions FROM main_production.sessions JOIN first_signup ON first_signup.user_id = sessions.user_id AND sessions.time <= first_signup.first_time GROUP BY 1 ) SELECT avg(total_sessions) FROM sessions_pre_signup ``` ### Bounce Rate ```sql WITH data AS ( SELECT time::date AS day, session_id, count(*) AS pageviews FROM heap_production.pageviews GROUP BY 1, 2 ) SELECT day, count(CASE WHEN pageviews = 1 THEN 1 ELSE NULL END) / count(*) AS bounce_rate FROM data GROUP BY 1 ORDER BY 1 ``` ### Month-to-Month Retention ```sql -- get a cohort based on join date WITH new_user_activity AS ( SELECT activity.user_id ,activity.TIME AS DATE FROM main_production.sessions AS activity INNER JOIN users ON users.user_id = activity.user_id AND users.joindate = activity.TIME WHERE date_part('year', joindate) >= 2014 ), -- number of users in cohort cohort_active_user_count AS ( SELECT to_char(DATE, 'YYYY-MM') AS DATE ,count(DISTINCT user_id) AS count FROM new_user_activity GROUP BY 1 ) -- change format to change granularity SELECT joindate ,period ,new_users ,retained_users ,retention FROM ( SELECT to_char(new_user_activity.DATE, 'YYYY-MM') AS "joindate" ,'Month ' || -- change month to change granularity datediff('month', new_user_activity.DATE, future_activity.TIME) AS period ,max(cohort_size.count) AS new_users ,-- all equal in group count(DISTINCT future_activity.user_id) AS retained_users ,round(count(DISTINCT future_activity.user_id) / max(cohort_size.count)::DECIMAL, 2) AS retention FROM new_user_activity LEFT JOIN main_production.sessions AS future_activity ON new_user_activity.user_id = future_activity.user_id AND new_user_activity.DATE <= future_activity.TIME LEFT JOIN cohort_active_user_count AS cohort_size ON to_char(new_user_activity.DATE, 'YYYY-MM') = cohort_size.DATE GROUP BY 1, 2 ) t WHERE period IS NOT NULL ORDER BY 1, 2 ``` ## Error Analysis ### Excluded Errors Excluded errors show up in the downstream data. To exclude errors from the data downstream, navigate to **Error Analysis > Search Errors**. Filter the list for excluded errors, then click into the excluded errors and note the `Group Error ID`. Exclude these error IDs from the error queries downstream: ```sql SELECT COUNT(*) FROM main_production.error_events_console_message WHERE error_group_id NOT IN ('<excluded_error_id>') ``` ### Custom Errors In the UI, custom errors include console messages. Downstream, these types of errors are broken out into their own tables. If you would like to mirror the data shown in the UI, you can union the tables. ```sql WITH combined_errors AS ( SELECT * FROM main_production.error_events_console_message UNION ALL SELECT * FROM main_production.error_events_custom_error ) SELECT * FROM combined_errors -- Optional: filter out specific error group(s) WHERE error_group_id NOT IN ('<excluded_error_id>') ``` ## Funnels This section covers Data Connect queries that enable you to conduct funnel analysis by measuring all types of funnels. Funnels are fundamental to understanding any flow through your site, from onboarding to filling out forms, to virtually any step users are expected to take within your product. ### The Basic Funnel The funnel below can be used to mirror the funnel in Contentsquare's dashboard. It calculates the number of users who have completed Step 1 within the time frame, the number of users who have completed Step 2, and then Step 3. It's both sequential and time-constrained, though there are many modifications you may wish to make, as shown below. ```sql WITH e1 AS ( SELECT DISTINCT user_id ,1 AS step_1 ,MIN(time) AS step_1_time -- change to table name of event 1 in your funnel FROM main_production.step_1 AS e1 WHERE time BETWEEN '2016-04-13' AND '2016-04-21' GROUP BY 1 ), e2 AS ( SELECT e1.user_id ,1 AS step_2 ,MIN(time) AS step_2_time -- change to table name of event 2 in your funnel FROM main_production.step_2 AS e2 INNER JOIN e1 ON e1.user_id = e2.user_id WHERE time BETWEEN step_1_time AND '2016-04-21' GROUP BY 1 ), e3 AS ( SELECT e3.user_id ,1 AS step_3 ,MIN(time) AS step_3_time -- change to table name of event 3 in your funnel FROM main_production.step_3 AS e3 INNER JOIN e2 ON e2.user_id = e3.user_id WHERE TIME BETWEEN step_2_time AND '2016-04-21' GROUP BY 1 ) SELECT SUM(step_1) AS "Step 1" ,SUM(step_2) AS "Step 2" ,SUM(step_3) AS "Step 3" ,ROUND(SUM(step_2)/SUM(step_1)::DECIMAL, 2) as step_1to2_conversion ,ROUND(SUM(step_3)/SUM(step_2)::DECIMAL, 2) as step_2to3_conversion ,ROUND(SUM(step_3)/SUM(step_1)::DECIMAL, 2) as overall_conversion FROM ( SELECT e1.user_id ,step_1 ,step_1_time ,step_2 ,step_2_time ,step_3 ,step_3_time FROM e1 LEFT JOIN e2 ON e1.user_id = e2.user_id LEFT JOIN e3 ON e2.user_id = e3.user_id ) ``` ### Funnels Grouped by an Event-Level Property Each event has a set of properties ranging from attributes Contentsquare captures automatically, like referrer, UTM parameters, and device type, and any properties you set using snapshots, `heap.addEventProperties`, or `heap.track`. To view a breakdown of the conversion rate based on these event-level properties, only a couple of modifications need to be made. In the funnel, include the event-level property in the `SELECT` statement and `GROUP BY` clause. You can also join this on the users table (`JOIN main_production.users on main_production.users.user_id=e1.user_id`) to analyze your conversion rates based on user-level properties as well. ```sql WITH e1 AS ( SELECT DISTINCT e1.user_id ,1 AS step_1 ,min(TIME) AS step_1_time ,utm_source FROM main_production.define_event AS e1 INNER JOIN ( SELECT user_id ,min(TIME) AS mintime FROM main_production.define_event WHERE DATE(TIME) BETWEEN '2016-04-13' AND '2016-04-20' GROUP BY 1 ) AS min_value ON e1.user_id = min_value.user_id AND e1.TIME = min_value.mintime WHERE DATE(TIME) BETWEEN '2016-04-13' AND '2016-04-20' GROUP BY 1, 4 ), e2 AS ( SELECT e1.user_id ,1 AS step_2 ,MIN(time) AS step_2_time -- change to table name of event 2 in your funnel FROM main_production.step_2 AS e2 INNER JOIN e1 ON e1.user_id = e2.user_id WHERE time BETWEEN step_1_time AND '2016-04-21' GROUP BY 1 ), e3 AS ( SELECT e3.user_id ,1 AS step_3 ,MIN(time) AS step_3_time -- change to table name of event 3 in your funnel FROM main_production.step_3 AS e3 INNER JOIN e2 ON e2.user_id = e3.user_id WHERE TIME BETWEEN step_2_time AND '2016-04-21' GROUP BY 1 ) SELECT utm_source ,sum(step_1) AS "Step 1" ,sum(step_2) AS "Step 2" ,sum(step_3) AS "Step 3" FROM ( SELECT e1.user_id ,step_1 ,step_1_time ,step_2 ,step_2_time ,step_3 ,step_3_time ,utm_source FROM e1 LEFT JOIN e2 ON e1.user_id = e2.user_id LEFT JOIN e3 ON e2.user_id = e3.user_id ) GROUP BY 1 ``` ### Restricting Funnels to One Session In this funnel, user ID and session ID are aligned to make sure that funnel spans across one session. There are a couple of tweaks needed in each step of the query. ```sql WITH e1 AS ( SELECT DISTINCT user_id ,session_id ,Min(time) AS step_1_time -- change to table name of event 1 in your funnel FROM main_production.step_1 AS e1 WHERE time BETWEEN '2016-04-13' AND '2016-04-21' GROUP BY 1, 2 ), e2 AS ( SELECT e1.user_id ,e1.session_id ,Min(time) AS step_2_time -- change to table name of event 2 in your funnel FROM main_production.step_2 AS e2 INNER JOIN e1 ON e1.user_id = e2.user_id AND e1.session_id = e2.session_id WHERE time BETWEEN step_1_time AND '2016-04-21' GROUP BY 1, 2 ), e3 AS ( SELECT e3.user_id ,e3.session_id ,Min(time) AS step_3_time -- change to table name of event 3 in your funnel FROM main_production.step_3 AS e3 INNER JOIN e2 ON e2.user_id = e3.user_id AND e2.session_id = e3.session_id WHERE time BETWEEN step_2_time AND '2016-04-21' GROUP BY 1, 2 ) SELECT count(DISTINCT step_1) as step_one ,count(DISTINCT step_2) AS step_two ,count(DISTINCT step_3) AS step_three ,round(count(DISTINCT step_3)/count(DISTINCT step_1)::decimal, 2) AS conversion_rate -- calculate additional percentages here FROM ( SELECT e1.user_id AS step_1 ,e1.session_id ,step_1_time ,e2.user_id AS step_2 ,step_2_time ,e3.user_id AS step_3 ,step_3_time FROM e1 LEFT JOIN e2 ON e1.user_id = e2.user_id AND e1.session_id = e2.session_id LEFT JOIN e3 ON e2.user_id = e3.user_id AND e2.session_id = e3.session_id ORDER BY 1 ) ``` ### Conversion Rate Over Time This report gives the user a window to complete the funnel and tracks how your conversion changes over time. ```sql WITH e1 AS ( SELECT DISTINCT user_id ,1 AS step_1 ,MIN(time) AS step_1_time ,TO_CHAR(e1.time, 'YYYY-MM') as "month" FROM main_production.[event_1] AS e1 WHERE TIME BETWEEN '2015-04-01' AND '2016-04-01' GROUP BY 1, 4 ), e2 as ( SELECT e1.user_id, 1 AS step_2, MIN(e2.time) AS step_2_time, e1.step_1_time FROM main_production.[event_2] AS e2 JOIN e1 ON e1.user_id=e2.user_id AND e1.step_1_time <= DATEADD('day', -30, e2.time) WHERE time BETWEEN step_1_time AND '2016-04-01' GROUP BY 1, 4 ), e3 as ( SELECT e3.user_id, 1 AS step_3, MIN(time) AS step_3_time, e2.step_1_time FROM main_production.[event-3] AS e3 JOIN e2 ON e2.user_id=e3.user_id AND e2.step_1_time <= DATEADD('day', -30, e3.time) WHERE time BETWEEN step_2_time AND '2016-04-01' GROUP BY 1, 4 ) SELECT MONTH, ROUND(SUM(step_3)/SUM(step_1)::DECIMAL, 2) AS "Conversion Rate" FROM ( SELECT e1.user_id, step_1, e1.step_1_time, step_3, step_3_time, e1.month FROM e1 LEFT JOIN e2 ON e1.user_id = e2.user_id AND e1.step_1_time=e2.step_1_time LEFT JOIN e3 ON e2.user_id= e3.user_id AND e2.step_1_time=e3.step_1_time ) GROUP BY 1 ORDER BY 1 ``` ### Time to Conversion Time can be an interesting metric to analyze. The time it takes for a user to make their first purchase from the date first seen, or the time it takes a user to fill out a form from the first field to submit, or the time between two purchases can be measured and optimized. You can analyze which behaviors, user properties, or first touch properties are associated with faster conversion rates. This example measures the time it takes users to purchase an item but can be adapted to measure a slew of different events, and segmented by a variety of user and event-level properties. ```sql SELECT avg(duration) AS "Average hours until Purchase" FROM ( SELECT user_id ,datediff('milliseconds', start_time, end_time)::DECIMAL / 1000 / 60 / 60 AS "duration" FROM ( SELECT main_production.users.user_id ,min(joindate) AS start_time ,min(main_production.purchase.time) AS end_time FROM main_production.sign_up JOIN main_production.users ON main_production.purchase.user_id = main_production.users.user_id GROUP BY 1 ) ) ``` ## Path Analysis This query allows you to track the most common flows or 'paths' into and out of your product via Data Connect. As is, the SQL selects the first 5 events of every session consisting of at least five events. It then aggregates the number of users who have completed each flow and displays the top 20 most common paths. ```sql WITH event_count AS ( SELECT event_table_name ,count(*) AS cardinality FROM main_production.all_events WHERE TIME >= dateadd('day', -30, getDate()) GROUP BY 1 ), all_events AS ( SELECT DISTINCT event_id ,main_production.all_events.user_id AS user_id ,main_production.all_events.event_table_name AS event_name ,main_production.all_events.TIME AS occurred_at ,cardinality AS number FROM main_production.all_events LEFT JOIN event_count ON main_production.all_events.event_table_name = event_count.event_table_name ORDER BY 1, 2 ), events AS ( SELECT all_events.user_id ,all_events.event_id ,event_name ,occurred_at ,cardinality FROM all_events INNER JOIN ( SELECT event_id ,user_id ,min(number) AS cardinality FROM all_events GROUP BY 1, 2 ) AS event ON all_events.number = event.cardinality AND all_events.event_id = event.event_id AND all_events.user_id = event.user_id ORDER BY 1, 2, 4 ) SELECT e1, e2, e3, e4, e5 ,COUNT(*) AS occurrences FROM ( -- Pivot out first five events in each session SELECT user_id ,session ,MAX(CASE WHEN event_number = 1 THEN event_name ELSE NULL END) AS e1 ,MAX(CASE WHEN event_number = 2 THEN event_name ELSE NULL END) AS e2 ,MAX(CASE WHEN event_number = 3 THEN event_name ELSE NULL END) AS e3 ,MAX(CASE WHEN event_number = 4 THEN event_name ELSE NULL END) AS e4 ,MAX(CASE WHEN event_number = 5 THEN event_name ELSE NULL END) AS e5 FROM ( -- Find event number in session SELECT z.* ,ROW_NUMBER() OVER (PARTITION BY user_id, session ORDER BY occurred_at) AS event_number FROM ( -- Sum breaks to find sessions SELECT y.* ,SUM(BREAK) OVER (ORDER BY user_id, occurred_at ROWS UNBOUNDED PRECEDING) AS session FROM ( -- Add flag if last event was more than 10 minutes ago SELECT x.* ,CASE WHEN last_event IS NULL OR occurred_at >= last_event + INTERVAL '10 MINUTE' THEN 1 ELSE 0 END AS BREAK FROM ( -- Find last event SELECT * ,LAG(occurred_at, 1) OVER (PARTITION BY user_id ORDER BY occurred_at) AS last_event FROM events ) x ) y ) z ) a WHERE event_number <= 5 GROUP BY 1, 2 ) final WHERE e1 IS NOT NULL AND e2 IS NOT NULL AND e3 IS NOT NULL AND e4 IS NOT NULL AND e5 IS NOT NULL GROUP BY 1, 2, 3, 4, 5 ORDER BY 6 DESC LIMIT 20 ``` ## Attribution This section covers Data Connect queries that enable you to measure attribution to better understand where your users are coming from. ### Top Referrers This query returns the top N referrers and the number of sessions they generate. ```sql SELECT referrer ,COUNT(*) AS sessions FROM main_production.sessions WHERE referrer IS NOT NULL GROUP BY 1 ORDER BY 2 DESC LIMIT 10 ``` ### First Touch Properties This query generates a table that matches Contentsquare's Users view. You can export and select all the user-level properties and all the first touch properties. #### How it works This query starts by calculating the first session for each user and joins the first sessions data with the users table based on the unique user ID. From here, each user-level property and session-level property can be selected. ```sql SELECT all_sessions.user_id ,first_session.first_time AS first_seen ,referrer ,utm_source ,utm_campaign ,utm_medium ,utm_content FROM main_production.sessions AS all_sessions INNER JOIN ( SELECT user_id ,MIN(time) AS first_time FROM main_production.sessions GROUP BY user_id ) AS first_session ON all_sessions.user_id = first_session.user_id AND all_sessions.time = first_session.first_time INNER JOIN main_production.users AS users ON all_sessions.user_id = users.user_id -- [optional] insert where clause here ORDER BY 3 DESC ``` ### First Touch Property by User Count This query returns the number of users that fall into each category. In this case, the number of users who have come in via each UTM source will be displayed. This can be adapted and broken down by any first touch or user-level properties. ```sql SELECT utm_source, COUNT(distinct user_id) FROM main_production.sessions AS all_sessions INNER JOIN ( SELECT user_id ,MIN(time) AS first_time FROM main_production.sessions GROUP BY user_id ) AS first_session ON all_sessions.user_id = first_session.user_id AND all_sessions.time = first_session.first_time INNER JOIN main_production.users AS users ON all_sessions.user_id = users.user_id GROUP BY 1 ``` ### Multi-Touch Attribution Users come in via many channels, and the campaign that drives the first touch doesn't always match with the campaign on the conversion event. Because Contentsquare automatically captures the referrer and UTM parameters for each session, you can build a query that compares the channel for each session a user has. This query compares the UTM source of the first touch with the UTM source on the session with the conversion event, and calculates the number of users who fall into each category. ```sql SELECT initial.utm_campaign AS "INITIAL" ,CASE WHEN event_2.utm_campaign IS NULL THEN 'None' ELSE event_2.utm_campaign END AS "LAST TOUCH" ,count(DISTINCT initial.user_id) AS "Number of Users" FROM ( SELECT all_sessions.user_id ,CASE WHEN all_sessions.utm_campaign IS NULL THEN 'None' ELSE all_sessions.utm_campaign END FROM main_production.sessions AS all_sessions INNER JOIN ( SELECT user_id ,MIN(time) AS first_time FROM main_production.sessions GROUP BY user_id ) AS first_session ON all_sessions.user_id = first_session.user_id AND all_sessions.time = first_session.first_time ) AS initial JOIN main_production.conversion_event AS event_2 ON initial.user_id = event_2.user_id GROUP BY 1, 2 ORDER BY 3 DESC ``` ## Revenue Analysis One of the most powerful aspects of Data Connect is the ability to join a complete set of user interactions with other data sources to see revenue data, such as a user's order history. ### ARPU per UTM Source This query combines Contentsquare's attribution data with order history data, allowing you to compare how each source is correlated with a user's downstream behavior. ```sql WITH first_touch AS ( SELECT all_sessions.user_id ,identity ,first_session.first_time AS first_seen ,utm_source -- add any user level properties or session level properties here FROM main_production.sessions AS all_sessions inner join ( SELECT user_id ,Min(TIME) AS first_time FROM main_production.sessions GROUP BY user_id ) AS first_session ON all_sessions.user_id = first_session.user_id AND all_sessions.TIME = first_session.first_time inner join main_production.users AS users ON all_sessions.user_id = users.user_id ) SELECT CASE WHEN utm_source IS NULL THEN 'none' ELSE utm_source END ,Round(SUM(order_total)::DECIMAL, 2) AS total_revenue ,Round(SUM(order_total)::DECIMAL / Count(DISTINCT customer_id)::DECIMAL, 2) AS avg_per_customer FROM heap.TRANSACTION join first_touch ON customer_id = identity GROUP BY 1 ``` ### Monthly ARPU per UTM Source With a slight tweak to your query, you can see how the UTM source is correlated with the ARPU on a month-to-month basis. ```sql WITH first_touch AS ( SELECT all_sessions.user_id ,identity ,first_session.first_time AS first_seen ,utm_source -- add any user level properties or session level properties here FROM main_production.sessions AS all_sessions inner join ( SELECT user_id ,Min(TIME) AS first_time FROM main_production.sessions GROUP BY user_id ) AS first_session ON all_sessions.user_id = first_session.user_id AND all_sessions.TIME = first_session.first_time inner join main_production.users AS users ON all_sessions.user_id = users.user_id ) SELECT utm_source ,CASE WHEN Length(Substring(order_date, 0, Position('/' IN order_date))) = 2 THEN '20' || Right(order_date, 2) || '-' || Substring(order_date, 0, Position('/' IN order_date)) ELSE '20' || Right(order_date, 2) || '-0' || Substring(order_date, 0, Position('/' IN order_date)) END AS order_month ,Count(DISTINCT customer_id) ,Round(SUM(order_total)::DECIMAL, 2) AS total_revenue ,Round(SUM(order_total)::DECIMAL / Count(DISTINCT customer_id)::DECIMAL, 2) AS avg_per_customer FROM heap.TRANSACTION join first_touch ON customer_id = identity WHERE utm_source IS NOT NULL GROUP BY 1, 2 ORDER BY 2 ``` ### ARPU by Behavior You can also combine Contentsquare data with revenue data to determine if certain actions or if the number of times an action is performed is correlated with higher returns. This report segments users into two categories: users who have uploaded files, and users who haven't uploaded files. It then calculates the ARPU for each segment. ```sql WITH user_info AS ( SELECT identity ,users.user_id ,SUM(order_total) AS total_revenue ,Count(event_id) AS event_count FROM main_production.users AS users join heap.TRANSACTION ON identity = customer_id left join main_production.dashboard_galleries_click_add_new_files AS event ON users.user_id = event.user_id GROUP BY 1, 2 ) SELECT CASE WHEN event_count = 0 THEN 'has not uploaded files' ELSE 'has uploaded files' END ,Round(SUM(total_revenue)::DECIMAL / Count(DISTINCT user_id), 2) AS avg_revenue_per_user FROM user_info GROUP BY 1 ``` ### Churned Customer Revenue Data Connect allows you to get a better understanding of your churned customers as well. You can answer questions like "Where did they come from?", "What did they do in my product?", and "How much revenue did a customer bring in before churning?". The table below combines Contentsquare session data, server-side events, and revenue data to enhance your understanding of churned customers. ```sql WITH first_touch AS ( SELECT all_sessions.user_id ,identity ,first_session.first_time AS first_seen ,utm_source -- add any user level properties or session level properties here FROM main_production.sessions AS all_sessions inner join ( SELECT user_id ,Min(TIME) AS first_time FROM main_production.sessions GROUP BY user_id ) AS first_session ON all_sessions.user_id = first_session.user_id AND all_sessions.TIME = first_session.first_time inner join main_production.users AS users ON all_sessions.user_id = users.user_id ) SELECT utm_source ,Round(SUM(order_total)::DECIMAL, 2) AS churned_customer_total_value ,Round(Count(DISTINCT order_id)::DECIMAL / Count(DISTINCT user_id), 2) AS avg_orders_per_user ,Round(SUM(order_total)::DECIMAL / Count(DISTINCT first_touch.identity), 2) AS avg_ltv FROM first_touch join heap.TRANSACTION ON customer_id = first_touch.identity join main_production.account_modification ON first_touch.identity = main_production.account_modification.identity WHERE account_change = 'cancel' AND utm_source IS NOT NULL GROUP BY 1 ``` ## Modeling Your Data ### Creating an Enhanced Users Table This query provides an example of how to recreate the users table, adding the Initial User Properties (ex: Initial Referrer, Initial Browser, etc.) that are displayed in your Contentsquare account. ```sql BEGIN; DROP TABLE IF EXISTS enhanced_users; CREATE TABLE enhanced_users AS SELECT u.* ,s.time AS date_first_seen ,s.referrer AS initial_referrer ,s.utm_source AS initial_utm_source ,s.utm_medium AS initial_utm_medium ,s.utm_campaign AS initial_utm_campaign ,s.city AS initial_city ,s.region AS initial_region ,s.country AS initial_country ,s.landing_page AS initial_landing_page ,s.browser AS initial_browser ,s.device_type AS initial_device_type ,s.platform AS initial_platform ,s.ip AS initial_ip FROM main_production.sessions s JOIN main_production.users u ON s.user_id = u.user_id JOIN ( SELECT user_id, min(TIME) AS first_session_time FROM main_production.sessions GROUP BY user_id ) AS first_session ON s.user_id = first_session.user_id AND first_session_time = s.time; END; ``` ### Sessionizing Client-Side and Server-Side Events ```sql BEGIN; -- Prepending a table with # makes a temp table. Change this if you want a table to persist. DROP TABLE IF EXISTS #sessions; CREATE TABLE #sessions AS SELECT user_id ,min(time) over (partition by calc_session_id) as session_time ,time as event_time ,calc_session_id ,split_part(calc_session_id, '_', 2) as visit_number_in_range ,event_table_name ,first_value(path) over (partition by calc_session_id) as landing_page ,first_value(utm_source) over (partition by calc_session_id) as utm_source ,first_value(utm_medium) over (partition by calc_session_id) as utm_medium ,first_value(utm_campaign) over (partition by calc_session_id) as utm_campaign ,path ,total_price ,subtotal_price FROM ( SELECT * ,user_id || '_' || sum(new_session) over (partition by user_id order by time rows unbounded preceding) AS calc_session_id FROM ( SELECT e.* ,p.path ,p.utm_source ,p.utm_medium ,p.utm_campaign ,o.total_price ,o.subtotal_price -- Change your session definition here i.e. 30 * 60 = 30 minutes so 60 * 60 = 1 hour. ,case when extract(epoch from e.time) - lag(extract(epoch from e.time)) over (partition by e.user_id order by e.time) >= 30 * 60 then 1 else 0 end as new_session FROM heap_production.all_events e LEFT JOIN heap_production.pageviews p ON p.user_id = e.user_id AND p.event_id = e.event_id AND p.session_id = e.session_id LEFT JOIN heap_production.confirmed_order o ON o.user_id = e.user_id AND o.event_id = e.event_id AND o.session_id = e.session_id -- This example focuses on pageviews and a conversion event called `confirmed_order` from Contentsquare's Shopify integration. -- If you extend this model to include other tables and want properties from their tables, follow the left join pattern above and add the event_table_name to filter below. WHERE (event_table_name = 'pageviews' or event_table_name = 'confirmed_order') -- Change your date range here. -- AND e.time >= current_date - interval '1 week' ORDER BY time ) s ) ORDER BY time; END; ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Common Queries","description":"Common queries for analyzing Contentsquare data in your BI tool or directly on your cluster","url":"https://docs.contentsquare.com/en/connect/common-queries/","inLanguage":"en","dateModified":"2026-04-20T11:18:03+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Data Model - Data Connect description: Learn how accounts, users, sessions, pageviews, and events connect in the Contentsquare data hierarchy, plus property types and user identification. lastUpdated: 09 March 2026 source_url: html: https://docs.contentsquare.com/en/connect/data-model/ md: https://docs.contentsquare.com/en/connect/data-model/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To effectively analyze your data, it's important to understand how users, sessions, and events are connected in our data model. The summary version is this: Multiple users can belong to an **account**. When users visit your app, they conduct sessions during which they do pageviews and events. This results in a hierarchy of **account** > **users** > **sessions** > **pageviews** and **events** within Contentsquare. ``` flowchart TD accTitle: Contentsquare data model hierarchy accDescr: Shows the relationships between Account, User, Session, Pageview, and Event entities in the Contentsquare data model Acc((Account)):::xxl --- U1((User)):::xl Acc --- U2((User)):::xl U1 --- S1((Session)):::lg U1 --- S2((Session)):::lg U2 --- S3((Session)):::lg U2 --- S4((Session)):::lg S1 --- P1((Pageview)):::md S1 --- P2((Pageview)):::md S2 --- P3((Pageview)):::md S2 --- P4((Pageview)):::md S3 --- P5((Pageview)):::md S3 --- P6((Pageview)):::md S4 --- P7((Pageview)):::md S4 --- P8((Pageview)):::md P1 --- E1((Events)):::sm P2 --- E2((Events)):::sm P3 --- E3((Events)):::sm P4 --- E4((Events)):::sm P5 --- E5((Events)):::sm P6 --- E6((Events)):::sm P7 --- E7((Events)):::sm P8 --- E8((Events)):::sm P1 --- E9((Events)):::sm P2 --- E9 P3 --- E10((Events)):::sm P4 --- E10 P5 --- E11((Events)):::sm P6 --- E11 P7 --- E12((Events)):::sm P8 --- E12 classDef xxl font-size:20px classDef xl font-size:19px,padding:3.5em classDef lg font-size:18px,padding:3.5em classDef md font-size:16px classDef sm font-size:16px ``` ## Table hierarchy Each table contains: * **users**: One row per unique user with user-level properties * **sessions**: One row per session with session-level properties (linked to users) * **pageviews**: One row per pageview with page-level properties (linked to sessions) * **events**: One row per event with event-level properties (linked to pageviews/sessions) These tables are connected by the following primary keys: ``` flowchart LR accTitle: Data Connect table relationships accDescr: Shows how users, sessions, pageviews, and events tables are connected through join keys U["<b>users</b><br/>user_id (PK)<br/>identity<br/>handle"] -->|user_id| S["<b>sessions</b><br/>session_id (PK)<br/>user_id (FK)"] S -->|session_id| P["<b>pageviews</b><br/>event_id (PK)<br/>user_id (FK)<br/>session_id (FK)"] P -->|event_id| E["<b>events</b><br/>user_id (FK)<br/>session_id (FK)<br/>event_id (FK)"] ``` Use `identity` and `handle` from the users table to join Contentsquare data with external sources such as CRMs or email marketing platforms. See [Data Schema](https://docs.contentsquare.com/en/connect/data-schema/) for detailed column definitions and [Common Queries](https://docs.contentsquare.com/en/connect/common-queries/) for joining examples. ## Properties In Contentsquare, bits of metadata from user interactions are known as **properties**. Properties are classified into the following types based on their place in the data model. ### User-level properties User-level properties are all attributes associated with a user, including touch properties, account information, business logic, and more. Since they are at the top of the hierarchy and thus carry through each session and event, user-level properties apply across the entire hierarchy. You can group your analysis by user-level properties in any analysis view, which allows you to compare conversion rates based on plan type, Industry, LTV, region, and A/B experiment, just to name a few. ### Session-level properties Session-level properties include all attributes captured at the session level, such as the landing page, browser, referrer, and more. Since they are in the middle of the hierarchy, session properties also trickle down and exist at the event level. ### Pageview-level properties **Session-level properties** include all attributes captured at the session level, such as the landing page, browser, referrer, and more. Since they are in the middle of the hierarchy, session properties also trickle down and exist at the event level. **Pageview-level properties** include all attributes associated with a particular pageview (or screenview on native mobile SDKs) such as path, title, and domain. Snapshots created on pageview events will result in pageview-level properties, and these properties will trickle down to all events that occur on that page. **Event-level properties** are all attributes associated with events, including last touch properties, target text, or context captured by snapshots, such as price or quantity. You can also create custom events, aka events sent in via our track APIs, to have additional metadata (SKU, Email Subject, Successful Charge, etc.) associated with your user interactions. Because events are at the bottom of the hierarchy, event-level properties only apply to those specific events. When grouping by event-level properties, you have to select the event with the properties you'd like to group by. ### First vs. Last Touch Properties Contentsquare also distinguishes between first touch and last touch properties based on when the interaction occurred in relation to the history of the user. Whether a property is first touch, last touch, or somewhere in between plays a role in how it fits into the data model. A **first touch property** represents the very first time a user had that specific interaction within Contentsquare, such as the first time they ever signed in. A **last touch property** is the opposite - they represent the most recent interaction. Contentsquare tracks all first touch properties as user-level properties. You can use these properties to group first-time users together into a segment, then analyze that segment to better understand your app's new user experience. Contentsquare also attaches relevant session-level properties to each event, which you can use in analysis to spot trends during sessions. ## Identifying Your Users Contentsquare captures all of this information about user interactions and organizes it into a user-based data model. But how do you distinguish between different types of users? Our [`identify`](https://docs.contentsquare.com/en/web/command-reference/#identify) API allows you to pass along all the information about a user that you've collected, such as their email address or a unique ID you may have assigned in your app's backend, to Contentsquare so that it can be a part of your analysis. This can be any information that you want to be associated with your users, such as email address, account type, A/B experiment variation, business logic (number of users on the account, LTV, etc.) and more. Implementing our [`addUserProperties`](https://docs.contentsquare.com/en/web/command-reference/#adduserproperties) API allows you to pass along any information you have about the users, including demographic information, plan type, company information, industry information, and more that will help you filter by this data in your analysis. The more information you pass, the more you can narrow the definition for and understand a particular subset or segment of users. This enables you to complete a richer analysis of your users' interactions with your product. ### Managing Anonymous Users Even if a user hasn't logged in, your site or app might still have valuable information that you might want to attach to a user as a user-level property. Contentsquare attaches a unique identifier to anonymous users, so you can still attach this information as a user-level property using the [`addUserProperties`](https://docs.contentsquare.com/en/web/command-reference/#adduserproperties) API. A great example of when to attach user-level properties to anonymous users is A/B testing. See the Using Identify guide for more details and use cases for capturing anonymous user interactions. ## Custom events You can send custom events to Contentsquare via our [`trackEvent`](https://docs.contentsquare.com/en/web/command-reference/#trackevent) APIs. When track occurs on the client-side, the event will occur in the context of a session, complete with all of the metadata associated with our autocaptured events. Server-side events exist outside the context of a session, and only have the properties that you send via the API call. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Data Model","description":"Learn how accounts, users, sessions, pageviews, and events connect in the Contentsquare data hierarchy, plus property types and user identification.","url":"https://docs.contentsquare.com/en/connect/data-model/","inLanguage":"en","dateModified":"2026-03-09T14:31:47+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Data Schema - Data Connect description: Understanding the data schema and structure of Data Connect tables in your data warehouse lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/connect/data-schema/ md: https://docs.contentsquare.com/en/connect/data-schema/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Data Connect creates the following tables in your data warehouse, each representing a different aspect of user behavior data. Understanding this schema is essential for effective analysis and joining with other data sources. Data Connect adopts a hierarchical schema. By default, Data Connect will sync the following tables: * One users table (for all user information) * One sessions table (for all session information) * One pageviews table (for all pageview information) S3 format differences When syncing to S3, timestamp columns are stored in UNIX timestamp format (milliseconds since epoch) rather than native timestamp types. You'll need to convert these during your ETL process. See [Amazon S3](https://docs.contentsquare.com/en/connect/amazon-s3/) for more details. ## Time-related columns Several columns across tables track time in different ways. Understanding their differences is important for writing accurate queries. | Column | Table | Meaning | | - | - | - | | `time` | sessions | Timestamp when the session started. Use for session-level date filters. | | `time` | events | Timestamp when the event occurred. | | `session_time` | events | Seconds elapsed since the session started. Use for analyzing event timing within a session (for example, `WHERE session_time <= 60` to find events in the first minute). | | `joindate` | users | Timestamp when the user was first seen. Use for cohort analysis and user lifetime calculations. | S3 timestamp format In S3, `time` and `joindate` are stored as UNIX timestamps in milliseconds. Divide by 1000 before converting to a timestamp type. See [Amazon S3](https://docs.contentsquare.com/en/connect/amazon-s3/#data-types-and-formats) for details. ```sql -- Find users and their first action within 30 seconds of session start SELECT u.user_id, u.joindate, e.event_table_name, e.session_time FROM users u JOIN all_events e ON u.user_id = e.user_id WHERE e.session_time <= 30 ORDER BY u.joindate DESC; ``` ## Core tables ### users The `users` table contains a row for each unique user that has visited your site. | Column Name | Type | Description | | - | - | - | | `user_id` | BIGINT | Unique ID of user, randomly generated by Contentsquare (CSQ). | | `identity` | TEXT | User's username or other unique token, passed [identify](https://docs.contentsquare.com/en/web/command-reference/#identify). Must be unique. | | `handle` | TEXT | User's username or other unique token, passed [identify](https://docs.contentsquare.com/en/web/command-reference/#identify). | | `email` | TEXT | User's email address, passed in via [addUserProperties](https://docs.contentsquare.com/en/web/command-reference/#adduserproperties) API. | | `joindate` | TIMESTAMP | Timestamp without time zone of when the user was first seen. In S3, this is in UNIX timestamp format. | | `last_modified` | TIMESTAMP | Timestamp without time zone of when the user's data was last modified. In S3, this is in UNIX timestamp format. | | user properties | TEXT | There will be one column for every unique user property you've sent via the [addUserProperties](https://docs.contentsquare.com/en/web/command-reference/#adduserproperties) API (name, gender, account status, etc). The column type is automatically inferred from the underlying property values. | ### sessions The `sessions` table represents individual user sessions. | Column Name | Type | Description | | - | - | - | | `event_id` | BIGINT | ID of associated session event, randomly generated by CSQ. | | `user_id` | BIGINT | ID of associated user, randomly generated by CSQ. | | `session_id` | BIGINT | ID of associated session, randomly generated by CSQ. | | `time` | TIMESTAMP | Timestamp without time zone of when session started. | | `library` | TEXT | Version of Contentsquare library which began the session. Can be one of "web" or "iOS". | | `platform` | TEXT | User's operating system. | | `device_type` | TEXT | Device type. Can be one of: Mobile, Desktop, or Tablet. | | `country` | TEXT | Country in which user session occurred, based on IP. | | `region` | TEXT | Region in which user session occurred, based on IP. | | `city` | TEXT | City in which user session occurred, based on IP. | | `referrer` | TEXT | URL that linked to your site and initiated the session. If the user navigated directly to your site, or referral headers were stripped, then this value will appear as NULL downstream and as `direct` in the UI. | | `landing_page` | TEXT | URL of the first pageview of the session. | | `browser` | TEXT | User's browser. | | `utm_source` | TEXT | GA-based `utm_source` tag associated with the session's initial pageview. | | `utm_campaign` | TEXT | GA-based `utm_campaign` tag associated with the session's initial pageview. | | `utm_medium` | TEXT | GA-based `utm_medium` tag associated with the session's initial pageview. | | `utm_term` | TEXT | GA-based `utm_term` tag associated with the session's initial pageview. | | `utm_content` | TEXT | GA-based `utm_content` tag associated with the session's initial pageview. | | Custom variables | TEXT | One column is created for every unique custom variable key you've attached. The column type is automatically inferred from the underlying property values. | | `session_replay_link` | TEXT | Contentsquare Platform URL link of the Session Replay. | | `session_duration` | TEXT | Total duration of the session. | | `session_language` | TEXT | Language displayed during the session. | | `session_number_of_views` | TEXT | The number of page views in the session. | | `frustration_score` | TEXT | Measure of user frustration during the session. | | `looping_Index` | TEXT | The proportion of same URLs visited during the session (meaning the user is doing back and forth). | | `page_consumption` | TEXT | Proportion of pages where the user spent less than 2s and did less than 2 clicks. | | `filtered_APV` | TEXT | Number of views in which APVs (Artificial Pageviews) are not counted / a boolean determining whether a given page view is an Artificial Page view. | ### pageviews The `pageviews` table contains detailed information about each pageview. | Column Name | Type | Description | | - | - | - | | `event_id` | BIGINT | ID of associated pageview event. | | `user_id` | BIGINT | Unique ID of associated user, randomly generated by CSQ. | | `session_id` | BIGINT | Unique ID of associated session, randomly generated by CSQ. | | `time` | TIMESTAMP | Timestamp without time zone of when the pageview occurred. | | `library` | TEXT | Version of Contentsquare library which started the session. Can be one of "web" or "iOS". | | `platform` | TEXT | User's operating system. | | `device_type` | TEXT | Device type. Can be one of: Mobile, Desktop, or Tablet. | | `country` | TEXT | Country in which user session occurred, based on IP. | | `region` | TEXT | Region in which user session occurred, based on IP. | | `city` | TEXT | City in which user session occurred, based on IP. | | `referrer` | TEXT | URL that linked to your site and started the session. If the user navigated directly to your site, or referral headers were stripped, then this value will appear as NULL downstream and as `direct` in the UI. | | `landing_page` | TEXT | URL of the first pageview of the session. | | `browser` | TEXT | User's browser. | | `utm_source` | TEXT | GA-based `utm_source` tag associated with the session's initial pageview. | | `utm_campaign` | TEXT | GA-based `utm_campaign` tag associated with the session's initial pageview. | | `utm_medium` | TEXT | GA-based `utm_medium` tag associated with the session's initial pageview. | | `utm_term` | TEXT | GA-based `utm_term` tag associated with the session's initial pageview. | | `utm_content` | TEXT | GA-based `utm_content` tag associated with the session's initial pageview. | | `path` | TEXT | The path of the pageview. | | `query` | TEXT | The query parameters associated with the pageview. | | `hash` | TEXT | The hash parameters associated with the pageview. | | `title` | TEXT | Title of the current page. | | Custom variables | TEXT | One column is created for every unique custom variable key you've attached. The column type is automatically inferred from the underlying property values. | | Dynamic variables | TEXT | One column is created for every unique dynamic variable key you've attached. The column type is automatically inferred from the underlying property values. | | `view_number` | TEXT | The pageview number in the session. | | `is_first` | TEXT | If the page is the entry page then value is 1 otherwise value is 0. | | `is_last` | TEXT | If the page is the exit page then value is 1, otherwise value is 0. | | `scroll_rate` | TEXT | The portion of the page which was displayed (in percentage points). | | `view_duration_msec` | TEXT | Duration between the page view event time (`view_time`) and the timestamp of the last interaction event (in milliseconds). | | `first_input_delay` | TEXT | Delay (in milliseconds) between the first user interaction and when the web browser can handle it (part of Core Web Vitals). | | `interaction_to_next_paint` | TEXT | Longest visual delay (in milliseconds) experienced by a user when interacting with the page (clicks or keystrokes). | | `time_to_first_byte` | TEXT | Delay (in milliseconds) between the request for the web page and when the web browser received the first piece of data. | | `largest_contentful_paint` | TEXT | Delay (in milliseconds) to render the largest piece of content (part of Core Web Vitals). | | `cumulative_layout_shift` | TEXT | Score about the layout stability of the page rendering (part of Core Web Vitals). | | `dom_interactive_after_msec` | TEXT | The time in milliseconds required before the user is able to interact with the page (although all resources may not be fully loaded yet). | | `fully_loaded` | TEXT | The time in milliseconds required to fully load all the resources of the page, from initiation of the pageview to load completion in the browser. | | `first_contentful_paint` | TEXT | Delay (in milliseconds) to render the first piece of content. | | `start_render` | TEXT | Timestamp sent by tag when the rendering of the page started. | | `window_height` | TEXT | Height of the window in which the page is opened. | | `window_width` | TEXT | Width of the window in which the page is opened. | | `session_replay_link` | TEXT | Contentsquare Platform URL link of the Session Replay. | ## Event tables ### events Contentsquare will create one table for every labeled event you've created within Contentsquare and synced downstream. See how to [create, manage, and sync Events ↗](https://support.contentsquare.com/hc/en-us/articles/39322036577553-How-to-create-manage-and-sync-Events-in-Data-Connect). | Column Name | Type | Description | | - | - | - | | `event_id` | BIGINT | ID of the associated event, randomly generated by CSQ. | | `user_id` | BIGINT | Unique ID of the associated user, randomly generated by CSQ. | | `session_id` | BIGINT | Unique ID of the associated session, randomly generated by CSQ. | | `pageview_id` | BIGINT | Unique ID of the associated page, randomly generated by CSQ. | | `time` | TIMESTAMP | Timestamp without time zone of when the event happened. | | `type` | TEXT | For web autocaptured events, can be any of view page, click, submit, change, with push state events registered as view page events. For custom events, this will be the custom event name. | | `library` | TEXT | Version of Contentsquare library on which event occurred. Can be one of "web", "iOS", or "server". | | `platform` | TEXT | User's operating system. | | `device_type` | TEXT | Device type. Can be one of: Mobile, Desktop, or Tablet. | | `country` | TEXT | Country in which user session occurred, based on IP. | | `region` | TEXT | Region in which user session occurred, based on IP. | | `city` | TEXT | City in which user session occurred, based on IP. | | `referrer` | TEXT | URL that linked to your site and started the session. If the user navigated directly to your site, or referral headers were stripped, then this value will appear as NULL downstream and as `direct` in the UI. | | `landing_page` | TEXT | URL of the first pageview of the session. | | `landing_page_query` | TEXT | The query parameters of the first page of the user's session. | | `landing_page_hash` | TEXT | The hash route of the first page of the user's session. | | `browser` | TEXT | User's browser. | | `utm_source` | TEXT | GA-based `utm_source` tag associated with the session's initial pageview. | | `utm_campaign` | TEXT | GA-based `utm_campaign` tag associated with the session's initial pageview. | | `utm_medium` | TEXT | GA-based `utm_medium` tag associated with the session's initial pageview. | | `utm_term` | TEXT | GA-based `utm_term` tag associated with the session's initial pageview. | | `utm_content` | TEXT | GA-based `utm_content` tag associated with the session's initial pageview. | | `domain` | TEXT | Domain including subdomain, for example, blog.company.io. | | `path` | TEXT | Portion of the current URL following your domain, for example, `/docs` for `company.io/docs`. | | `hash` | TEXT | Portion of the current URL following the hash sign, for example, `#install` for `company.io/docs#install`. | | `query` | TEXT | Query parameters of the page's current URL, for example, `?utm_id=1234` for `company.io?utm_id=1234`. | | `title` | TEXT | Title of the current page. | | `href` | TEXT | `href` property of the link element (used for clicks on anchor tags). | | `target_text` | TEXT | Button text of the event target. | ### `all_events` Table Does Not Sync For S3. The `all_events` table does not sync for S3. You can create an `all_events` view of all synced tables after the data synced to S3 has gone through ETL processing. | Column Name | Type | Description | | - | - | - | | `event_id` | BIGINT | ID of associated event, randomly generated by Contentsquare. | | `user_id` | BIGINT | Unique ID of associated user, randomly generated by Contentsquare. | | `session_id` | BIGINT | Unique ID of associated session, randomly generated by Contentsquare. | | `time` | TIMESTAMP | Timestamp without time zone of when event happened. | | `event_table_name` | TEXT | Name of the table where similar events can be found. | #### Primary Key Considerations The `all_events` table is a **UNION** of all individual event tables. Because a single event can qualify for multiple event definitions, the same `event_id` may appear multiple times in this table with different `event_table_name` values. **For data warehouses (Redshift, BigQuery, Snowflake):** * The composite primary key for `all_events` should be: `(user_id, event_id, event_table_name)` * Individual event tables can use: `(user_id, event_id)` **For S3:** * You must handle deduplication in your ETL process after identity resolution * Use the same composite key pattern when creating views See [Troubleshooting](https://docs.contentsquare.com/en/connect/troubleshooting/#why-are-there-duplicate-event-ids-in-the-all-events-view-in-my-data-warehouse) for more information about duplicate event IDs. BigQuery Limitations In most cases, the schema for the `all_events` view will consist of the union of all columns from all event tables, with nulls filled in where applicable. However, if you are syncing many tables to your project, this can run into BigQuery query length limits, in which case we'll fall back to one of the following reduced column sets: * All built-in Contentsquare columns that is `event_view_name` and columns contained in the pageviews/sessions tables * Basic columns - `event_view_name`, `user_id`, `event_id`, `session_id`, time If your `all_events` view is created with a reduced column set, you can join it with the underlying event views to access any property columns that are not available in the view. ### `ecommerce_transactions` The `ecommerce_transactions` table contains information about e-commerce transactions. | Column Name | Type | Description | | - | - | - | | `event_id` | BIGINT | ID of associated session event, randomly generated. | | `user_id` | BIGINT | ID of associated user, randomly generated. | | `session_id` | BIGINT | ID of associated session, randomly generated. | | `time` | TIMESTAMP | Timestamp without time zone of when the pageview occurred. | | `library` | TEXT | Version of Contentsquare library which began the session. "web" or "iOS". | | `platform` | TEXT | User's operating system. | | `country` | TEXT | Country in which user session occurred, based on IP. | | `region` | TEXT | Region in which user session occurred, based on IP. | | `city` | TEXT | City in which user session occurred, based on IP. | | `referrer` | TEXT | URL that linked to your site and initiated the session. If the user navigated directly to your site, or referral headers were stripped, then this value will appear as NULL downstream and as `direct` in the UI. | | `type` | TEXT | E-commerce transaction. | | `device_type` | TEXT | Device type. Can be one of: Mobile, Desktop, or Tablet. | | `transaction_amount` | TEXT | The total monetary value of a purchase or payment made by a user during a session. | | `transaction_currency` | TEXT | The currency in which the transaction amount was processed. | ## Error tables ### `api_errors` Experience Monitoring The `api_errors` table contains information about API errors detected during user sessions. | Column Name | Type | Description | | - | - | - | | `event_id` | BIGINT | ID of associated event, randomly generated. | | `user_id` | BIGINT | ID of associated user, randomly generated. | | `session_id` | BIGINT | ID of associated session, randomly generated. | | `pageview_id` | BIGINT | Unique ID of the associated page, randomly generated by CSQ. | | `time` | TIMESTAMP | Timestamp without time zone of when the event happened. | | `library` | TEXT | Version of Contentsquare library which began the session. "web" or "iOS". | | `platform` | TEXT | User's operating system. | | `device_type` | TEXT | Device type. Can be one of: Mobile, Desktop, or Tablet. | | `country` | TEXT | Country in which user session occurred, based on IP. | | `region` | TEXT | Region in which user session occurred, based on IP. | | `city` | TEXT | City in which user session occurred, based on IP. | | `landing_page` | TEXT | URL of the first pageview of the session. | | `api_error_duration` | TEXT | Time taken to resolve API error. | | `api_error_endpoint` | TEXT | URL where API errors are reported. | | `api_error_method` | TEXT | Standardized communication of API error responses. | | `api_error_status_code` | TEXT | Numerical code identifying API error. | | `errors_after_clicks` | TEXT | Issue occurring post-user interaction (boolean). | | `error_group_id` | TEXT | Identifier for categorizing related errors. | | `error_source` | TEXT | Origin point of the reported error. | | `type` | TEXT | API error. | | `referrer` | TEXT | URL that linked to your site and initiated the session. If the user navigated directly to your site, or referral headers were stripped, then this value will appear as NULL downstream and as `direct` in the UI. | ### `js_errors` Experience Monitoring The `js_errors` table contains information about JavaScript errors detected during user sessions. | Column Name | Type | Description | | - | - | - | | `event_id` | BIGINT | ID of associated session event, randomly generated. | | `user_id` | BIGINT | ID of associated user, randomly generated. | | `session_id` | BIGINT | ID of associated session, randomly generated. | | `pageview_id` | BIGINT | Unique ID of the associated page, randomly generated by CSQ. | | `time` | TIMESTAMP | Timestamp without time zone of when the event happened. | | `library` | TEXT | Version of Contentsquare library which began the session. "web" or "iOS". | | `platform` | TEXT | User's operating system. | | `device_type` | TEXT | Device type. Can be one of: Mobile, Desktop, or Tablet. | | `country` | TEXT | Country in which user session occurred, based on IP. | | `region` | TEXT | Region in which user session occurred, based on IP. | | `city` | TEXT | City in which user session occurred, based on IP. | | `landing_page` | TEXT | URL of the first pageview of the session. | | `error_message` | TEXT | Description of the encountered error. | | `error_line_number` | TEXT | Line in the code where the error occurred. | | `js_error_file_name` | TEXT | File name containing the JavaScript error. | | `js_error_column_number` | TEXT | Column in the file where the error occurred. | | `errors_after_clicks` | TEXT | Issue occurring post-user interaction (boolean). | | `error_group_id` | TEXT | Identifier for categorizing related errors. | | `error_source` | TEXT | Origin point of the reported error. | | `type` | TEXT | JS error. | | `referrer` | TEXT | URL that linked to your site and initiated the session. If the user navigated directly to your site, or referral headers were stripped, then this value will appear as NULL downstream and as `direct` in the UI. | ### `custom_errors` Experience Monitoring The `custom_errors` table contains information about custom errors detected during user sessions. | Column Name | Type | Description | | - | - | - | | `event_id` | BIGINT | ID of associated session event, randomly generated. | | `user_id` | BIGINT | ID of associated user, randomly generated. | | `session_id` | BIGINT | ID of associated session, randomly generated. | | `pageview_id` | BIGINT | Unique ID of the associated page, randomly generated by CSQ. | | `time` | TIMESTAMP | Timestamp without time zone of when the event happened. | | `library` | TEXT | Version of Contentsquare library which began the session. "web" or "iOS". | | `platform` | TEXT | User's operating system. | | `device_type` | TEXT | Device type. Can be one of: Mobile, Desktop, or Tablet. | | `country` | TEXT | Country in which user session occurred, based on IP. | | `region` | TEXT | Region in which user session occurred, based on IP. | | `city` | TEXT | City in which user session occurred, based on IP. | | `landing_page` | TEXT | URL of the first pageview of the session. | | `error_message` | TEXT | Description of the encountered error. | | `errors_after_clicks` | TEXT | Issue occurring post-user interaction (boolean). | | `error_group_id` | TEXT | Identifier for categorizing related errors. | | `error_source` | TEXT | Origin point of the reported error. | | `type` | TEXT | Custom Error. | | `referrer` | TEXT | URL that linked to your site and initiated the session. If the user navigated directly to your site, or referral headers were stripped, then this value will appear as NULL downstream and as `direct` in the UI. | ### `console_message` Experience Monitoring The `console_message` table contains information about console messages detected during user sessions. | Column Name | Type | Description | | - | - | - | | `event_id` | BIGINT | ID of associated session event, randomly generated. | | `user_id` | BIGINT | ID of associated user, randomly generated. | | `session_id` | BIGINT | ID of associated session, randomly generated. | | `pageview_id` | BIGINT | Unique ID of the associated page, randomly generated by CSQ. | | `time` | TIMESTAMP | Timestamp without time zone of when the event happened. | | `library` | TEXT | Version of Contentsquare library which began the session. "web" or "iOS". | | `platform` | TEXT | User's operating system. | | `device_type` | TEXT | Device type. Can be one of: Mobile, Desktop, or Tablet. | | `country` | TEXT | Country in which user session occurred, based on IP. | | `region` | TEXT | Region in which user session occurred, based on IP. | | `city` | TEXT | City in which user session occurred, based on IP. | | `landing_page` | TEXT | URL of the first pageview of the session. | | `error_message` | TEXT | Description of the encountered error. | | `errors_after_clicks` | TEXT | Issue occurring post-user interaction (boolean). | | `error_group_id` | TEXT | Identifier for categorizing related errors. | | `error_source` | TEXT | Origin point of the reported error. | | `type` | TEXT | Console Message. | | `referrer` | TEXT | URL that linked to your site and initiated the session. If the user navigated directly to your site, or referral headers were stripped, then this value will appear as NULL downstream and as `direct` in the UI. | ## Frustration tables Data Connect creates one table per frustration signal type, each prefixed with `frustration_events_`. All frustration tables share a common set of columns, with a few table-specific columns listed under each table. ### Common columns (all `frustration_events_*` tables) | Column Name | Type | Description | | - | - | - | | `event_id` | BIGINT | ID of the associated event, randomly generated by Contentsquare. | | `user_id` | BIGINT | Unique ID of the associated user, randomly generated by Contentsquare. | | `session_id` | BIGINT | Unique ID of the associated session, randomly generated by Contentsquare. | | `pageview_id` | BIGINT | Unique ID of the associated page, randomly generated by Contentsquare. | | `time` | TIMESTAMP | Timestamp without time zone of when the event happened. | | `library` | TEXT | Always `frustration`. | | `platform` | TEXT | User's operating system. | | `device_type` | TEXT | Device type. Can be one of: Mobile, Desktop, or Tablet. | | `country` | TEXT | Country in which user session occurred, based on IP. | | `region` | TEXT | Region in which user session occurred, based on IP. | | `city` | TEXT | City in which user session occurred, based on IP. | | `landing_page` | TEXT | URL of the first pageview of the session. | | `landing_page_query` | TEXT | Query parameters of the landing page URL. | | `landing_page_hash` | TEXT | Hash fragment of the landing page URL. | | `type` | TEXT | Frustration signal type (for example, `Rage Click`, `Multiple Button Interactions`). | | `referrer` | TEXT | URL that linked to your site and initiated the session. If the user navigated directly to your site, or referral headers were stripped, then this value will appear as NULL downstream and as `direct` in the UI. | | `domain` | TEXT | Domain including subdomain, for example, blog.company.io. | | `path` | TEXT | Portion of the current URL following your domain, for example, `/docs` for `company.io/docs`. | | `hash` | TEXT | Portion of the current URL following the hash sign, for example, `#install` for `company.io/docs#install`. | | `query` | TEXT | Query parameters of the page's current URL, for example, `?utm_id=1234` for `company.io?utm_id=1234`. | | `title` | TEXT | Title of the current page. | | `href` | TEXT | `href` attribute of the link element, if the frustration event occurred on an anchor tag. | | `target_text` | TEXT | The text displayed on the element where the event occurred. | | `frustration_score` | TEXT | Frustration score of the pageview. | ### `frustration_events_rage_click` A rage click occurs when a user clicks on the same element multiple times in quick succession, indicating frustration. | Column Name | Type | Description | | - | - | - | | `target_path` | TEXT | Target path of the HTML component where the event happened. | | `relative_time` | INT | Time offset in milliseconds from the start of the pageview. | | `value` | INT | Number of clicks recorded. | ### `frustration_events_multiple_button_interactions` A multiple button interaction occurs when a user clicks the same button multiple times, suggesting the button may not be responding as expected. | Column Name | Type | Description | | - | - | - | | `target_path` | TEXT | Target path of the HTML component where the event happened. | | `relative_time` | INT | Time offset in milliseconds from the start of the pageview. | | `value` | INT | Number of clicks recorded. | ### `frustration_events_multiple_field_interactions` A multiple field interaction occurs when a user interacts with the same form field multiple times, which may indicate confusion or an error in the form. | Column Name | Type | Description | | - | - | - | | `target_path` | TEXT | Target path of the HTML component where the event happened. | | `relative_time` | INT | Time offset in milliseconds from the start of the pageview. | | `value` | INT | Number of interactions recorded. | ### `frustration_events_multiple_use_target` A multiple use target event occurs when a user clicks the same element multiple times across the page. | Column Name | Type | Description | | - | - | - | | `target_path` | TEXT | Target path of the HTML component where the event happened. | | `relative_time` | INT | Time offset in milliseconds from the start of the pageview. | | `value` | INT | Number of clicks recorded. | | `count` | INT | Number of times the target was used. | ### `frustration_events_excessive_hover` An excessive hover event occurs when a user hovers over an element for an unusually long time, which may indicate hesitation or confusion. | Column Name | Type | Description | | - | - | - | | `target_path` | TEXT | Target path of the HTML component where the event happened. | | `relative_time` | INT | Time offset in milliseconds from the start of the pageview. | | `value` | INT | Duration of the hover in milliseconds. | | `count` | INT | Number of hover events recorded. | ### `frustration_events_loading_time` A loading time event is recorded when a page or resource takes longer than expected to load, which can negatively impact user experience. | Column Name | Type | Description | | - | - | - | | `target_path` | TEXT | Target path of the HTML component associated with the loading event. | | `relative_time` | INT | Time offset in milliseconds from the start of the pageview. | | `value` | INT | Loading time duration in milliseconds. | | `count` | INT | Number of loading time events recorded. | ### `frustration_events_low_activity` A low activity event is recorded when a user shows very little interaction with a page (fewer than 2 clicks and less than 2 seconds of engagement), suggesting disengagement. | Column Name | Type | Description | | - | - | - | | `target_path` | TEXT | Target path of the HTML component where the low activity was detected. | | `relative_time` | INT | Time offset in milliseconds from the start of the pageview. | | `value` | INT | Activity metric value. | | `count` | INT | Number of low activity events recorded. | ### `frustration_scores` The `frustration_scores` view is automatically created when a customer syncs at least one frustration table. It aggregates frustration signals at the pageview level by joining the `pageviews` table with all active `frustration_events_*` tables. Each row corresponds to one pageview and includes all [pageview columns](#pageviews) plus one count column per synced frustration table. The count columns are dynamically named `number_of_<table_name>` based on which frustration tables are enabled. For example: | Column Name | Type | Description | | - | - | - | | `number_of_frustration_events_rage_click` | INT | Number of rage click events for this pageview. `NULL` if none occurred. | | `number_of_frustration_events_excessive_hover` | INT | Number of excessive hover events for this pageview. `NULL` if none occurred. | | `number_of_frustration_events_loading_time` | INT | Number of loading time events for this pageview. `NULL` if none occurred. | | `number_of_frustration_events_multiple_button_interactions` | INT | Number of multiple button interaction events. `NULL` if none occurred. | | `number_of_frustration_events_multiple_field_interactions` | INT | Number of multiple field interaction events. `NULL` if none occurred. | | `number_of_frustration_events_multiple_use_target` | INT | Number of multiple use target events for this pageview. `NULL` if none occurred. | | `number_of_frustration_events_low_activity` | INT | Number of low activity events for this pageview. `NULL` if none occurred. | Only columns for frustration tables actively synced by the customer will appear in the view. ## System tables ### `_sync_history` Contentsquare creates a table called `_sync_history` that contains a record for every attempted sync. This table is helpful for monitoring sync performance and scheduling dependent jobs. All timestamps are in UTC for Redshift and BigQuery and in local time for Snowflake. | Column Name | Type | Description | | - | - | - | | `status` | STRING | Takes value running/succeeded/failed based on the outcome of the sync attempt. | | `start_time` | TIMESTAMP | Start time of the sync attempt. | | `finish_time` | TIMESTAMP | Finish time of the sync attempt. | | `error` | STRING | Error message if sync fails. | | `next_scheduled_sync_at` | TIMESTAMP | Time of the next scheduled sync (estimated at the time of sync based on sync frequency settings). | ### `_sync_info` Contentsquare creates a table called `_sync_info` that contains metadata around the sync process and last updated times. | Column Name | Type | Description | | - | - | - | | `event_table_name` | TEXT | The event name. | | `sync_started` | TIMESTAMP | A timestamp for when that table began syncing. | | `sync_ended` | TIMESTAMP | A timestamp for when that table completed syncing. | | `synced_to_time` | TIMESTAMP | A timestamp that reflects the most recent occurrence of the event. | | `inserted_row_count` | BIGINT | The number of rows inserted during the most recent sync. | ### `user_migrations` When a user is identified, a migration occurs to aggregate the data under the new identity. These migrations are recorded in this table. Time is a column for Redshift and S3 destinations only. Snowflake and BigQuery do not have a column for time. | Column Name | Type | Description | | - | - | - | | `from_user_id` | BIGINT | The migrating user's ID. | | `to_user_id` | BIGINT | The destination user's ID. | | `time` | TIMESTAMP | A timestamp for when the migration occurred. | ### `event_metadata` This table contains metadata about the names of events, which allows you to build automated jobs that use this metadata. This table is re-created on each sync to stay updated with the latest event metadata. | Column Name | Type | Description | | - | - | - | | `table_name` | TEXT | For each event, this row contains the sanitized name of the table containing the event's data synced to your warehouse. | | `ui_name` | TEXT | For each event, this row contains the name of the event in Contentsquare. | | `last_updated_at` | TIMESTAMP | Time event label was last updated. | | `last_updated_by` | TEXT | User who last updated event label. | | `notes` | TEXT | Notes attached to the event. | | `source` | TEXT | Data capture source (ex: web, iOS, android). | | `verified_at` | TIMESTAMP | Time event was verified. | | `verified_by` | TEXT | User who verified the event. | The `event_metadata` table shows up differently for S3. You can query it as follows: ```json { "ui_name": "Stripe charge", "table_name": "stripe_charge", "source": "stripe", "last_updated_at": "1609459200000", "last_updated_by": "sales@company.com", "notes": "This is a note", "verified_at": "1640995200000", "verified_by": "admin@company.com" } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Data Schema","description":"Understanding the data schema and structure of Data Connect tables in your data warehouse","url":"https://docs.contentsquare.com/en/connect/data-schema/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Data Syncing - Data Connect description: Data Connect uses an ETL (Extract, Transform, Load) process to move data from Contentsquare to your data warehouse, and syncs data once per day. lastUpdated: 09 March 2026 source_url: html: https://docs.contentsquare.com/en/connect/data-syncing/ md: https://docs.contentsquare.com/en/connect/data-syncing/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Data Connect uses an ETL (Extract, Transform, Load) process to move data from Contentsquare to your data warehouse once per day. ## Initial vs. Incremental syncs When you first set up Data Connect or add a new table, an **initial sync** copies all historical data from Contentsquare to your warehouse. This process: * Creates the necessary tables and views * Copies all historical data (which can take several hours or days depending on data volume) * Runs only once per table, unless a full resync is needed Initial syncs run separately When you enable a new table, Data Connect performs the initial sync in the background, separate from daily syncs. This prevents the backfill process from delaying your existing table updates. The new table won't appear in your warehouse until the initial sync completes. You can monitor the progress in the Data Connect dashboard - hover over the toggle next to the table name to see "pending initial sync" status. Once finished, the table is synced daily along with the rest of the data. After the initial sync, Data Connect performs **incremental updates** during each sync window. These updates: * Only transfer new or changed data since the last sync * Are much faster than initial syncs * Maintain data consistency while minimizing warehouse load * Run daily ## Configure event tables syncs As a project or account admin, use **Analysis setup** > **Data Connect** > \[Select your warehouse destination] > **Details** to define which event tables Data Connect syncs to your warehouse. Toggle syncing of Contentsquare event tables or custom events that you created individually or in bulk. Data Connect always syncs the following pre-built tables: `users`, `sessions`, and `pageviews`. When you toggle off an event table that's in sync, the existing table remains in your warehouse but will no longer receive updates. Tables that are not synced appear greyed out.  ## Monitoring sync status Monitor the status of your Data Connect syncs through: * The Data Connect dashboard in the Contentsquare UI * Email notifications for failed syncs (if configured) * Warehouse query logs showing Data Connect activity ### Sync failures When a Data Connect sync fails, Contentsquare automatically retries the sync several times. If multiple retries fail, you'll receive a notification. Work through these steps to identify the cause: 1. Check for error messages in the Data Connect dashboard 2. Verify warehouse permissions and quotas 3. Look for schema conflicts 4. Review recent changes to your Contentsquare implementation 5. Contact Contentsquare support with specific error messages and timestamps Once resolved, syncs will resume from where they left off. ## Managing schema changes As your Contentsquare implementation evolves (adding new events or properties), Data Connect handles schema evolution automatically: | Change | Result | | - | - | | New event defined | A new table is created for the event | | New property added | A new column is added to the appropriate table (event table for event properties, `users` table for user properties) | | User property values updated | Corresponding rows in the `users` table are updated | | Anonymous user identified | The user is migrated: the `users` table and all event tables referencing the anonymous `user_id` are updated | | Property type update | Handled according to warehouse-specific rules | Changes requiring manual intervention * **Column name conflicts**: Renaming a property in Contentsquare to match an existing column name * **Type incompatibilities**: Property values that change in ways that conflict with existing column types * **Reserved words**: New properties whose names are reserved in your warehouse ### Renaming events When you modify an event name in the Contentsquare interface, the behavior differs by destination. **For warehouses (BigQuery, Redshift, Snowflake, Databricks):** 1. The existing table is dropped 2. A new table is created with the updated name 3. Historical data is backfilled into the new table 4. The `all_events` view is automatically updated 5. Queries using the old table name will fail **For S3:** 1. New syncs use the updated folder name: `_heap_table_name=new_event_name` 2. Historical data remains under the old folder name 3. You must update your ETL process to handle the name change After renaming an event: * Update downstream queries, dashboards, and ETL jobs * Rename events during low-traffic periods to minimize disruption * Document event name changes for your team * Use the [`event_metadata`](https://docs.contentsquare.com/en/connect/data-schema/#event_metadata) table to track naming history ## Data retention and historical data Data Connect syncs all data available based on your account's retention settings. If data is deleted in Contentsquare, it is not automatically removed from your warehouse — you need to delete it manually. ## Best practices To ensure smooth operation of your Data Connect pipeline: 1. **Monitor sync status regularly**: Check that syncs are completing successfully 2. **Plan for schema changes**: Consider potential impacts when adding new properties 3. **Test new warehouse queries**: Verify queries after schema changes 4. **Manage warehouse resources**: Schedule heavy queries outside of the daily sync window 5. **Document custom tables**: Maintain documentation for any views or derived tables you create 6. **Set up alerting**: Configure monitoring for sync failures 7. **Manage data volume**: Archive or partition historical data as needed ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Data Syncing","description":"Data Connect uses an ETL (Extract, Transform, Load) process to move data from Contentsquare to your data warehouse, and syncs data once per day.","url":"https://docs.contentsquare.com/en/connect/data-syncing/","inLanguage":"en","dateModified":"2026-03-09T14:31:47+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Data Warehouses - Data Connect description: Overview of supported data warehouse platforms for Data Connect lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/connect/data-warehouses-overview/ md: https://docs.contentsquare.com/en/connect/data-warehouses-overview/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Data Connect supports integration with several data warehouse platforms, allowing you to export your behavioral data for advanced analytics and joining with other business data. ### Supported destinations *  ### [Amazon S3](https://docs.contentsquare.com/en/connect/amazon-s3/) *  ### [BigQuery](https://docs.contentsquare.com/en/connect/bigquery/) *  ### [Databricks](https://docs.contentsquare.com/en/connect/databricks/) *  ### [Redshift](https://docs.contentsquare.com/en/connect/redshift/) *  ### [Snowflake](https://docs.contentsquare.com/en/connect/snowflake/) ## Start frequency and start time | Feature | Amazon S3 (Retroactive) | BigQuery | Databricks | Redshift | Snowflake | | - | - | - | - | - | - | | Supported Sync Frequency | Once every 24 hours | Once every 24 hours | Once every 24 hours | Once every 24 hours | Once every 24 hours | | Segment Syncing | Not Supported | Not Supported | Not Supported | Not Supported | Not Supported | | Defined Properties Syncing | Supported | Supported[1](#user-content-fn-1) | Not Supported | Supported | Supported | | User Migration Syncing | Supported | Supported | Supported | Supported | Supported | | User Migrations Applied on Tables | Manually Applied[2](#user-content-fn-2) | Automatic | Automatic | Automatic | Automatic | ## Syncing to multiple destinations You can sync Contentsquare data to multiple destinations simultaneously. Use cases include: * Different teams use different data platforms * You need a backup data warehouse * You are migrating between warehouses * Development, staging, and production environments need separate data Each destination operates independently with its own sync schedule and table selection. Contact your Contentsquare account team to enable multi-destination syncing. ## Footnotes 1. Defined properties on the built-in pageviews or sessions tables are not included. [↩](#user-content-fnref-1) 2. Requires manual application of identity resolution queries. [↩](#user-content-fnref-2) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Data Warehouses","description":"Overview of supported data warehouse platforms for Data Connect","url":"https://docs.contentsquare.com/en/connect/data-warehouses-overview/","inLanguage":"en","dateModified":"2026-03-11T15:17:40+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Redshift - Data Connect description: Instructions for setting up and using Data Connect with Amazon Redshift lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/connect/redshift/ md: https://docs.contentsquare.com/en/connect/redshift/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Amazon Redshift is a fully managed, petabyte-scale data warehouse service in the cloud. The Data Connect integration with Redshift allows you to automatically sync your Contentsquare data to Redshift for advanced analysis and joining with other business data. ## Prerequisites Before setting up the Redshift integration, ensure you have: * **An Amazon Redshift cluster** that is provisioned and accessible * **Sufficient permissions** to create schemas and tables in Redshift * **Database credentials** with appropriate permissions ## Redshift Setup 1. Ensure your Redshift cluster is running and accessible 2. [Create a dedicated schema for Contentsquare data ↗](https://docs.aws.amazon.com/redshift/latest/gsg/t_creating_schema.html): ```sql CREATE SCHEMA heap_data; ``` 3. [Create a dedicated user for Data Connect ↗](https://docs.aws.amazon.com/redshift/latest/gsg/t_adding_redshift_user_cmd.html): ```sql CREATE USER heap_connect_user WITH PASSWORD 'your-secure-password'; GRANT USAGE ON SCHEMA heap_data TO heap_connect_user; GRANT CREATE ON SCHEMA heap_data TO heap_connect_user; GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA heap_data TO heap_connect_user; ALTER DEFAULT PRIVILEGES IN SCHEMA heap_data GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO heap_connect_user; ``` 4. Ensure your Redshift cluster is accessible from Contentsquare's servers: * If your cluster is public, ensure the security group allows access * If your cluster is private, you may need to set up VPC peering or a VPN connection ## Configure Data Connect Admin only Configuration of this destination is only available to admin users in Contentsquare. 1. Log in to Contentsquare. 2. Navigate to **Analysis setup** > **Data Connect**. 3. Select **Connect** next to Redshift. 4. Enter the required information: * Host (endpoint) * Port (typically 5439) * Database name * Username * Password * Schema (the schema you created for Contentsquare data) 5. Select **Connect**. ## SSH Tunneling Setup If your Redshift cluster is in a private subnet and not publicly accessible, you can use SSH tunneling to allow Data Connect to connect securely. **When SSH Tunneling is Required:** * Your Redshift cluster is in a private VPC subnet * Security policies prohibit public Redshift endpoints * You need additional network security layer * Direct VPC peering is not available **Configuration Steps:** 1. **Set up a bastion host** (jump server) in a public subnet with access to your Redshift cluster 2. **Generate SSH key pair** on the bastion host: ```shell ssh-keygen -t rsa -b 4096 -f ~/.ssh/contentsquare_rsa ``` 3. **Add Contentsquare's public key** to `authorized_keys`: ```shell # Contentsquare will provide their public key echo "ssh-rsa AAAAB3NzaC1yc2E..." >> ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys ``` 4. **Configure SSH daemon** on bastion host: ```shell # Edit /etc/ssh/sshd_config PermitRootLogin no PubkeyAuthentication yes PasswordAuthentication no ``` 5. **Provide connection details** to Contentsquare: * Bastion host IP address * SSH username * SSH port (typically 22) * Redshift cluster endpoint (internal IP/hostname) * Redshift port (typically 5439) **Connection String Format:** The connection will be established as: ```plaintext User → Contentsquare → SSH Tunnel → Bastion Host → Redshift Cluster ``` **Security Best Practices:** * Use key-based authentication only (no passwords) * Restrict bastion host security group to only necessary IPs * Enable AWS CloudTrail logging on bastion host * Regularly rotate SSH keys * Use non-standard SSH port if required by security policy **Troubleshooting SSH Connectivity:** * Verify bastion host security group allows SSH from Contentsquare IPs * Check Redshift security group allows bastion host IP * Test SSH connection manually from bastion to Redshift * Review SSH daemon logs: `sudo tail -f /var/log/auth.log` ## Performance Optimization Optimizing Redshift performance for Data Connect tables ensures fast queries and cost-effective operations. ### Distribution Keys Distribution keys determine how data is distributed across nodes in your Redshift cluster. **Recommended Distribution Keys:** ```sql -- Users table: distribute by user_id ALTER TABLE main_production.users ALTER DISTSTYLE KEY DISTKEY user_id; -- Sessions table: distribute by user_id for joins with users ALTER TABLE main_production.sessions ALTER DISTSTYLE KEY DISTKEY user_id; -- Event tables: distribute by user_id ALTER TABLE main_production.page_viewed ALTER DISTSTYLE KEY DISTKEY user_id; ``` **Why user\_id?** * Most queries join tables on `user_id` * Co-locates related data on same nodes * Reduces network traffic during joins * Improves query performance ### Sort Keys Sort keys determine the physical order of data on disk, enabling efficient range queries. **Recommended Sort Keys:** ```sql -- Sort by time for date-range queries ALTER TABLE main_production.sessions COMPOUND SORTKEY (time); ALTER TABLE main_production.page_viewed COMPOUND SORTKEY (time); ALTER TABLE main_production.all_events COMPOUND SORTKEY (time, event_table_name); ``` **Compound vs. Interleaved:** * **Compound**: Use when queries filter primarily on `time` * **Interleaved**: Use when queries filter on multiple columns equally ### VACUUM and ANALYZE Regular maintenance ensures optimal performance: ```sql -- Reclaim space and re-sort rows VACUUM FULL main_production.users; VACUUM FULL main_production.sessions; VACUUM FULL main_production.page_viewed; -- Update table statistics for query planner ANALYZE main_production.users; ANALYZE main_production.sessions; ANALYZE main_production.page_viewed; ``` **Maintenance Schedule:** * Run VACUUM weekly or after large data loads * Run ANALYZE after VACUUM and after schema changes * Consider AUTO VACUUM for regular maintenance * Schedule during low-usage periods ### Query Performance Tuning **Use EXPLAIN to analyze queries:** ```sql EXPLAIN SELECT u.user_id, COUNT(s.session_id) FROM users u JOIN sessions s ON u.user_id = s.user_id WHERE s.time >= DATEADD('day', -30, GETDATE()) GROUP BY u.user_id; ``` **Optimization Techniques:** 1. **Filter early**: Apply WHERE clauses before joins 2. **Use appropriate joins**: INNER vs LEFT based on need 3. **Limit columns**: Select only needed columns 4. **Use temp tables**: For complex multi-step queries 5. **Leverage sort keys**: Filter on sort key columns when possible **Example Optimized Query:** ```sql -- Create temp table with filtered data CREATE TEMP TABLE recent_sessions AS SELECT user_id, session_id, time FROM sessions WHERE time >= DATEADD('day', -30, GETDATE()); -- Analyze temp table ANALYZE recent_sessions; -- Join with optimized temp table SELECT u.user_id, u.identity, COUNT(rs.session_id) as session_count FROM users u INNER JOIN recent_sessions rs ON u.user_id = rs.user_id GROUP BY u.user_id, u.identity; ``` ## Advanced Troubleshooting ### Permission Issues Deep-Dive **Common Permission Errors:** ```sql -- Error: "permission denied for schema" -- Solution: Grant schema usage GRANT USAGE ON SCHEMA main_production TO heap_connect_user; -- Error: "permission denied for table" -- Solution: Grant table permissions GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA main_production TO heap_connect_user; -- Ensure future tables are accessible ALTER DEFAULT PRIVILEGES IN SCHEMA main_production GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO heap_connect_user; ``` **Verify Permissions:** ```sql -- Check user permissions SELECT schemaname, tablename, usename, HAS_TABLE_PRIVILEGE(usename, schemaname||'.'||tablename, 'SELECT') as can_select, HAS_TABLE_PRIVILEGE(usename, schemaname||'.'||tablename, 'INSERT') as can_insert FROM pg_tables CROSS JOIN pg_user WHERE schemaname = 'main_production' AND usename = 'heap_connect_user' ORDER BY tablename; ``` ### Connection Timeout Resolution **Symptoms:** * Sync fails with timeout errors * Connection drops during large syncs * Intermittent connectivity issues **Solutions:** 1. **Increase cluster connection limit:** ```sql -- Check current connections SELECT COUNT(*) FROM stv_sessions; -- Modify parameter group if needed -- max_connections parameter in AWS Console ``` 2. **Check network connectivity:** ```shell # Test from Contentsquare IPs (if self-testing) telnet your-cluster.region.redshift.amazonaws.com 5439 ``` 3. **Review VPC and security groups:** * Ensure Contentsquare IPs are allowed * Check Network ACLs in VPC * Verify route tables 4. **Enable enhanced VPC routing** (if using S3): * Improves reliability for data loads * Configure in Redshift cluster settings ### Schema Access Problems **Issue: Cannot see tables after sync** ```sql -- Check if schema exists SELECT nspname FROM pg_namespace WHERE nspname = 'main_production'; -- Check if user has access SELECT n.nspname as schema_name, HAS_SCHEMA_PRIVILEGE(u.usename, n.nspname, 'USAGE') as has_usage FROM pg_namespace n CROSS JOIN pg_user u WHERE u.usename = 'heap_connect_user' AND n.nspname = 'main_production'; -- Grant access if needed GRANT USAGE ON SCHEMA main_production TO heap_connect_user; ``` ## FAQs ### Why are constraints not applied to the tables? Primary and foreign key constraints are not applied to the Data Connect tables because Amazon Redshift does not enforce constraints. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Redshift","description":"Instructions for setting up and using Data Connect with Amazon Redshift","url":"https://docs.contentsquare.com/en/connect/redshift/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Snowflake - Data Connect description: Instructions for setting up and using Data Connect with Snowflake lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/connect/snowflake/ md: https://docs.contentsquare.com/en/connect/snowflake/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Snowflake is a cloud-based data platform that provides data warehouse-as-a-service designed for the cloud. The Data Connect integration with Snowflake allows you to automatically sync your Contentsquare data to Snowflake for advanced analysis and joining with other business data. ## Prerequisites Before setting up the Snowflake integration, ensure you have: * **A Snowflake account** with appropriate access * **Snowflake user credentials** with a role that has the following privileges: * `USAGE` on database and schema * `CREATE TABLE` on schema * `SELECT`, `INSERT`, `UPDATE`, `DELETE` on tables * `CREATE VIEW` on schema (for `all_events` and other views) ## Snowflake setup To get started, you need to have the following information about your Snowflake account: * **Your Snowflake account name**: Your account name can be found in the URL used to access Snowflake: `<account_name>.snowflakecomputing.com`. * **Your account region**: We support the following regions: **AWS**: * `us-west-2` (Oregon): region not included in snowflake URLs for this region only * `us-east-1` (N. Virginia) * `us-east-2` (Ohio) * `eu-west-1` (Ireland) * `eu-central-1` (Frankfurt) * `ap-southeast-2` (Sydney) * `ca-central-1` (Canada Central) **Azure**: * `east-us-2` (Virginia) * `west-us-2` (Washington) * `canada-central` (Toronto) * `west-europe` (Netherlands) * `australia-east` (New South Wales) * `north-europe` (Ireland) * `centralus` (Iowa) * `uksouth` (London) **GCP**: * `us-central1` (Iowa) * `europe-west4` (Netherlands) If you are outside of these regions, let us know and we will work to add support for you. To find this information in your Snowflake account, see the **Analysis Setup** > **Connect** > **Snowflake** page in Contentsquare. This page will only be available once Data Connect has been enabled for you by someone on our end. ## Configure Data Connect Admin only Configuration of this destination is only available to admin users in Contentsquare. 1. Log in to Contentsquare. 2. Navigate to **Analysis setup** > **Data Connect**. 3. Select **Connect** next to Snowflake. 4. Create a database in Snowflake by copying and running the generated snippet: ```sql CREATE DATABASE heap_<project_name>_<environment_name> FROM SHARE heap_uswest.share_<env_id> ``` 5. Select **Next**. 6. [Enter your Snowflake hostname ↗](https://docs.snowflake.com/en/user-guide/organizations-connect#connecting-with-a-url). 7. Select **Connect**. ## Performance Control Center The Performance Control Center is a Contentsquare Snowflake Native App available in the Snowflake Marketplace. It delivers a single-page e-commerce performance dashboard purpose-built for category managers and e-merchandisers who need a recurring health check across categories, brands, and SKUs directly inside their Snowflake account. The dashboard answers three core questions: * `What is underperforming or overperforming in my scope right now?` * `Which entities deserve attention this week?` * `How are my key merchandising funnel metrics evolving over time?` Limited availability The Performance Control Center is available as a demo app in the Snowflake Marketplace with mock data. Access to the full app with your data requires both Merchandising and Data Connect (Snowflake) to be enabled. The full app is available on request via the Snowflake Marketplace. ### Dashboard sections The app delivers four sections in a single dashboard: * **Performance overview**: A sortable table of categories, brands, or products with dynamic period-over-period comparisons (compared to last week, month, quarter, and more) * **Main metrics**: Eight KPI cards (Product Exposures, PDP Visited, Add-to-Cart Rate, Conversion Rate, Cart Abandonment Rate, Withdrawn Rate, Total Revenue, Average Order Value) with overall-site benchmarks * **Trend**: A multi-metric chart comparing the evolution of selected KPIs over a chosen time period * **Page analysis**: Top and bottom 10 non-PDP URLs where selected entities are most exposed in sessions where a key outcome occurred Data refreshes approximately every 2 hours. ### Access the app **Demo app (mock data):** Available directly from the Snowflake Marketplace. Search for "Performance Control Center" by Contentsquare. No Contentsquare account required. **Full app (your Merchandising data):** The following are required to access the full app: * Your organization must be an active Snowflake customer * Merchandising must be active on your Contentsquare account * Data Connect with the Snowflake destination must be enabled 1. Request access via the Snowflake Marketplace listing. 2. Contentsquare validates your eligibility (Merchandising + Data Connect). 3. Contentsquare provisions the app for your Snowflake account via a private listing. 4. Install the app and it connects automatically to your existing Data Connect data sharing. ## Advanced Features ### Data Sharing via Snowflake Shares Contentsquare uses Snowflake's Secure Data Sharing feature to provide you with access to your data without copying or moving it. **How Data Sharing Works:** * Contentsquare creates a share containing your data * You create a database from this share in your Snowflake account * Data stays in Contentsquare's Snowflake account (no data transfer) * You query the data as if it were in your account * No compute costs for data storage on your end **Benefits:** * **Instant access**: No wait time for data copying * **Always up-to-date**: See data as soon as syncs complete * **No storage costs**: Data lives in Contentsquare's account * **Secure**: Snowflake's secure sharing with access controls **Managing Shared Data:** ```sql -- View available shares SHOW SHARES; -- See databases created from shares SHOW DATABASES LIKE '%heap%'; -- Check when data was last updated SELECT table_name, last_altered FROM heap_<project_name>_<environment_name>.information_schema.tables WHERE table_schema = 'PUBLIC' ORDER BY last_altered DESC; ``` ### Query Optimization for Shared Data While Snowflake data shares are efficient, following these practices ensures optimal query speed: **1. Use appropriate warehouse sizes:** ```sql -- For light queries (< 10K rows) USE WAREHOUSE small_wh; -- For heavy analytics (millions of rows) USE WAREHOUSE large_wh; ``` **2. Filter early and often:** ```sql -- Good: Filter before joins WITH recent_sessions AS ( SELECT * FROM heap_<project_name>_<environment_name>.public.sessions WHERE time::date >= DATEADD('day', -30, CURRENT_DATE()) ) SELECT * FROM recent_sessions; ``` **3. Leverage clustering hints:** ```sql -- Add clustering information for query optimizer SELECT /*+ CLUSTER_BY(time) */ * FROM heap_<project_name>_<environment_name>.public.all_events WHERE time >= DATEADD('day', -7, CURRENT_DATE()); ``` **4. Create materialized views for frequent queries:** ```sql CREATE MATERIALIZED VIEW my_database.my_schema.daily_sessions AS SELECT time::date as session_date, device_type, COUNT(DISTINCT session_id) as session_count, COUNT(DISTINCT user_id) as user_count FROM heap_<project_name>_<environment_name>.public.sessions GROUP BY session_date, device_type; ``` ### Integration with BI Tools Snowflake's native integrations allow you to connect Data Connect data with popular BI tools: **Tableau:** * Use Snowflake connector * Point to shared database: `heap_<project_name>_<environment_name>` * Enable query pushdown for optimal performance **Looker:** * Configure Snowflake connection * Use `heap_<project_name>_<environment_name>` as database * Consider Looker Blocks (see below) **Power BI:** * Use Snowflake connector in Power BI Desktop * Import mode recommended for smaller datasets * DirectQuery for larger datasets **Metabase:** * Add Snowflake database connection * Select `heap_<project_name>_<environment_name>` database * Build dashboards directly on shared data ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Snowflake","description":"Instructions for setting up and using Data Connect with Snowflake","url":"https://docs.contentsquare.com/en/connect/snowflake/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Databricks - Data Connect description: Instructions for setting up and using Data Connect with Databricks lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/connect/databricks/ md: https://docs.contentsquare.com/en/connect/databricks/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Databricks is a unified analytics platform built on Apache Spark that combines data engineering, data science, and analytics workloads. The Data Connect integration allows you to automatically sync your Contentsquare data to Databricks for advanced analysis and machine learning. ## Prerequisites Before setting up the Databricks integration, ensure you have: * Access is required to a Databricks account hosted on either **AWS** or **Azure** that uses Unity Catalog. * A Personal Access Token (PAT) for a user with the following privileges: * `CREATE TABLE` on the target schema * `MODIFY` on tables * `SELECT` on tables ## Configure Data Connect Admin only Configuration of this destination is only available to admin users in Contentsquare. 1. Log in to Contentsquare. 2. Navigate to **Analysis setup** > **Data Connect**. 3. Select **Connect** next to Databricks. 4. Provide the following information: * **Hostname**: The ID of your Databricks account, which you can find in the account URL. * **Path**: The path of the warehouse you are connecting via this integration. * **Catalog**: The catalog that this data should sync to; if left blank, this integration will create a new catalog. * **Schema (optional)**: The schema that this data should sync to; if left blank, this integration will create a new schema. * **Token**: This is required to allow Data Connect to write to the schema. The token must be a Personal Access Token (PAT) rather than an OAuth Token. 5. Select **Next**. Once setup is complete, you'll see a sync within 24 hours with the following built-in tables: * Pageviews * Sessions * Users * `user_migrations` ## Limitations * Segment syncing is not supported. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Databricks","description":"Instructions for setting up and using Data Connect with Databricks","url":"https://docs.contentsquare.com/en/connect/databricks/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Troubleshooting - Data Connect description: Troubleshooting Data Connect lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/connect/troubleshooting/ md: https://docs.contentsquare.com/en/connect/troubleshooting/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Running into unexpected data or performance issues with Data Connect? Find answers to common data questions — from duplicate events and missing user properties to query optimization tips — so you can troubleshoot quickly and get back to your analysis. ## Why are there duplicate event IDs in the All Events view in my data warehouse? Some duplicate pairs (`user_id`, `event_id`) can be expected in the `all_events` table, as long as the `event_table_name` value is different for the rows that share an event ID. If you have two event definitions that overlap, it's possible for a single event with a unique event ID to qualify for multiple event definitions. Let's say you have two click event definitions: one that captures every click on your platform and one that captures clicks on a specific element. A click event that qualifies for the first event will automatically qualify for the second event because the first event captures any click. If both event definitions are synced to Data Connect, they will each have their own event table downstream and a single event that qualifies for both definitions will appear on both tables with the same event ID. An event will always have just one event ID, even if it qualifies for multiple event definitions (and by extension, is included on multiple event tables in your data warehouse). The `all_events` table is a **UNION** of every individual event table that has been synced to your data warehouse. If both individual event tables include the same event, then the `all_events` table will show duplicate event IDs. However, these two rows will have different `event_table_name` values. The primary key for `all_events` should be a composite of `user_id`, `event_id`, and `event_table_name`. In individual event tables, a composite of `user_id` and `event_id` should suffice. ## Why don't I see initial user properties in Data Connect? We don't sync Initial User properties downstream in Data Connect (such as Initial Marketing Channel, or Initial Browser). Refer to [how to recreate those properties in your warehouse](https://docs.contentsquare.com/en/connect/common-queries/#creating-an-enhanced-users-table). ## Why is a given `event_id` included more than once on the `all_events` table? This FAQ applies to using Data Connect for warehouses (Redshift, BigQuery, Snowflake) only. A given `event_id` across all tables corresponds with a unique event recorded by Contentsquare. That said, the same `event_id` may exist in multiple event tables, as Contentsquare provides the flexibility to create multiple event definitions that may correspond to the same raw event. For instance, you may define the following two events in the product: * **Click CTA** defined as Click on .cta * **Click CTA - Homepage** defined as Click on .cta with a filter where Path equals / If a user clicks the CTA on the homepage, a new event will be recorded on both event tables that correspond with both event definitions. As a result, two events with the same `event_id` will be included in the `all_events` table, as it contains every recorded instance of all defined and custom events. Additionally, pageviews can share an `event_id` with a *defined* event. The defined event with a given `event_id` will have a unique time, after excluding where `event_name = 'pageviews'`. ## Table constraints are not enforced Data Connect defines primary and foreign key constraints in the table schema, but no supported warehouse (Redshift, BigQuery, Snowflake) enforces them. Constraints exist for documentation and query optimization only — data integrity is your responsibility. To avoid duplicate records: * Use `DISTINCT` or window functions for deduplication in queries * Implement deduplication logic in your ETL pipelines * Consider creating views with built-in deduplication for commonly used datasets ## Query performance issues If you're experiencing slow query performance when working with Data Connect data, consider these optimization strategies: ### General optimization tips 1. **Filter early**: Apply date range filters and other conditions as early as possible in your queries ```sql -- Good: Filter before joining SELECT * FROM sessions WHERE time >= DATEADD('day', -30, GETDATE()) ``` 2. **Select specific columns**: Avoid `SELECT *` and only query the columns you need ```sql -- Good: Select only needed columns SELECT user_id, session_id, time, device_type FROM sessions ``` 3. **Use appropriate joins**: Choose the right join type (INNER, LEFT, RIGHT) based on your analysis needs 4. **Limit result sets**: Use `LIMIT` for exploratory queries ```sql SELECT * FROM all_events WHERE time >= DATEADD('day', -1, GETDATE()) LIMIT 1000 ``` 5. **Use `EXPLAIN` to understand query plans**: Before optimizing, review the execution plan to identify bottlenecks like full table scans or expensive joins 6. **Create materialized views for frequent queries**: Cache results of commonly-run analytical queries to avoid recomputation ```sql CREATE MATERIALIZED VIEW daily_metrics AS SELECT DATE(time) as day, COUNT(*) as event_count FROM all_events GROUP BY DATE(time); ``` ### Warehouse-specific optimization **Redshift:** * Use distribution keys and sort keys for frequently queried tables * Run `VACUUM` and `ANALYZE` regularly on Connect tables * Consider creating materialized views for complex, frequently-run queries **BigQuery:** * Take advantage of table partitioning (Data Connect tables are partitioned by date) * Use approximate aggregation functions like `APPROX_COUNT_DISTINCT()` for large datasets * Consider clustering keys for frequently filtered columns **Snowflake:** * Configure warehouse size appropriately for your workload * Use Snowflake's automatic clustering or define clustering keys * Set up automatic warehouse suspension to control costs * Create materialized views for frequently-run analytical queries **S3:** * Optimize your ETL process to create partitioned Parquet or ORC files * Use AWS Athena or EMR with proper partition pruning * Consider using AWS Glue for schema management and cataloging ### Common query patterns to optimize **Large table scans:** ```sql -- Instead of scanning all events SELECT COUNT(*) FROM all_events -- Filter to specific time range and event types SELECT COUNT(*) FROM all_events WHERE time >= DATEADD('month', -1, GETDATE()) AND event_table_name IN ('page_view', 'button_click') ``` **Expensive joins:** ```sql -- Instead of joining all sessions with all events SELECT * FROM sessions s INNER JOIN all_events e ON s.session_id = e.session_id -- Filter both tables first, then join WITH recent_sessions AS ( SELECT * FROM sessions WHERE time >= DATEADD('day', -7, GETDATE()) ), recent_events AS ( SELECT * FROM all_events WHERE time >= DATEADD('day', -7, GETDATE()) ) SELECT * FROM recent_sessions s INNER JOIN recent_events e ON s.session_id = e.session_id AND s.user_id = e.user_id ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Troubleshooting","description":"Troubleshooting Data Connect","url":"https://docs.contentsquare.com/en/connect/troubleshooting/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Getting Started with Experience Analytics - Android description: Integrate the Contentsquare SDK into your Android app in minutes (installation, user consent, screen tracking, and testing) lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This quick start guide shows you how to get Contentsquare Experience Analytics set up in an Android application. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-android/experience-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. After completing the setup process, you'll be able to take full advantage of the CSQ API to collect data from your app, within just a few minutes. ## Install the SDK 1. Add the CSQ SDK dependency to your Gradle build file: * Kotlin **build.gradle.kts** ```kotlin implementation("com.contentsquare.android:sdk:1.12.1") ``` * Groovy **build.gradle** ```groovy implementation "com.contentsquare.android:sdk:1.12.1" ``` 2. Synchronize your Gradle project to be able to use the CSQ API. ## Start the SDK 1. Add a call to [`CSQ.start(context)`](command-reference/#csqstart) within `onCreate()` of a custom Application subclass: * Experience Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this, StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")) } } ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 2. Start your application, and check logs for this output: ```text [INFO] CSQ 1.12.1 for Experience Analytics is attempting to start. ``` ## Get user consent The CSQ SDK treats users as opted-out by default. Implement the [`optIn()`](command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` Start your application, click the UI that triggers the opt-in, and check logs for this output: ```text User is drawn for tracking: true ``` ## Track your first screens Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel. Once tracking has started, you're able to take full advantage of the CSQ SDK API to track screen views, monitor user interactions, and capture app behavior data. Contentsquare Experience Analytics also comes with powerful Session Replay and Error Monitoring capabilities as paid options. ### Sending screenview events Screen tracking is achieved by sending a `screenview` event when: * The screen appears on the device * A modal or pop-up is displayed * A modal or pop-up is closed, returning the user to the screen * The app is brought back to the foreground (after being minimized) To trigger a screenview each time an activity becomes visible, place the call in the `onResume()` method (Android view system only): ```kotlin import com.contentsquare.CSQ class MyActivity : Activity() { override fun onResume() { super.onResume() // Send screenView CSQ.trackScreenview("screen_name") } } ``` For more information, see [Implementation recommendations](track-screens/#implementation-recommendations) #### Jetpack Compose support To enable Jetpack Compose support, add a new dependency to your Gradle build file. * Kotlin **build.gradle.kts** ```kotlin implementation("com.contentsquare.android:sdk-compose:1.12.1") ``` * Groovy **build.gradle** ```groovy implementation 'com.contentsquare.android:sdk-compose:1.12.1' ``` Attention must be paid to recompositions. The call should be wrapped using `TriggeredOnResume` to ensure only one screenview is triggered when a given screen is presented to the user. ```kotlin import com.contentsquare.CSQ import com.contentsquare.api.compose.TriggeredOnResume @Composable fun MyComposable(data: Data) { TriggeredOnResume { CSQ.trackScreenview("screen_name") } // ... } ``` #### Tracking app launch Most events collected by the SDK require a screenview event to be sent first so they can be associated with that screen; otherwise, they will be discarded. If you need to collect events from the moment the app launches, you should trigger a screenview event immediately after the SDK has started. Refer to [our guide](track-screens/#when-to-send-your-first-screenview) for implementation examples. #### Screen name handling It is necessary to provide a name for each screen when calling the screenview API. As a general rule, keep distinct screen names under 100. As they are used to map your app in Contentsquare, you will want something comprehensive. The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side. More on [screen name handling](track-screens/#how-to-name-screens). Tracking plan To get the most out of your data, it's best to follow a tracking plan. This way, you'll capture every step of the user's journey without missing important interactions, giving you a complete picture of how your app is used. ## Sample app To explore some of these features in context, check our Android sample app. ### [contentsquare-android-sample](https://github.com/ContentSquare/contentsquare-android-sample) [Kotlin](https://github.com/ContentSquare/contentsquare-android-sample) ## Next Steps While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior. Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking. Proceed with these how-to's to refine your implementation. [Custom Variables](track-custom-variables/)Collect additional details about the screen or the user. [Dynamic Variables](track-dynamic-variables/)Collect additional information about the session. [Transactions tracking](track-transactions/)Associate user's session with their potential purchases and corresponding revenue. [WebViews](track-webviews/)For native apps which embark web applications or pages. [Session Replay](session-replay/)Collect data for Session Replay in compliance personal data masking. [Error Analysis](error-analysis/)Track API errors and application crashes with automated collection and privacy-safe debugging tools. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started with Experience Analytics","description":"Integrate the Contentsquare SDK into your Android app in minutes (installation, user consent, screen tracking, and testing)","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - Cordova description: The Contentsquare Cordova plugin changelog lastUpdated: 09 October 2025 source_url: html: https://docs.contentsquare.com/en/cordova/changelog/ md: https://docs.contentsquare.com/en/cordova/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. ## 0.3.0 - 2023.04.04 * Gesture tracking: is now supported. * Native SDKs: iOS 4.20.0 ## 0.2.0 - 2022.09.19 * Dynamic Variables: The API is now available. * Track Transactions: The API is now available. ## 0.1.0 - 2022.08.12 * First beta version. * Opt-in is supported. * Opt-out is supported. * Screenview event is supported. * The Plugin uses Android native SDK 4.12.0 and iOS native SDK 4.15.1 ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare Cordova plugin changelog","url":"https://docs.contentsquare.com/en/cordova/changelog/","inLanguage":"en","dateModified":"2025-10-09T13:23:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Getting Started with Product Analytics - Android description: Integrate the CSQ SDK for Product Analytics into your Android app in minutes lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This quick start guide shows you how to get Contentsquare Product Analytics set up in an Android application. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-android/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. Once you've completed the setup process, the Contentsquare SDK will capture a wide variety of user interactions in your application with no additional code required. Upgrading See our guides to upgrade to the CSQ SDK from the [Heap Core SDK](../product-analytics/upgrade-from-heap-core-sdk/) or the [Heap Classic SDK](../product-analytics/upgrade-from-heap-classic-sdk/). ## Install the SDK 1. In your app-level `build.gradle` file, add the dependency for the CSQ SDK and the CSQ Compose SDK. * Kotlin **build.gradle.kts** ```kotlin dependencies { implementation("com.contentsquare.android:sdk:1.12.1") implementation("com.contentsquare.android:sdk-compose:1.12.1") } ``` * Groovy **build.gradle** ```groovy dependencies { implementation 'com.contentsquare.android:sdk:1.12.1' implementation 'com.contentsquare.android:sdk-compose:1.12.1' } ``` 2. Add the Android View Autocapture Plugin to instrument your app code: * Kotlin **build.gradle.kts** ```kotlin plugins { // ... id("io.heap.gradle") version "1.1.1" } ``` * Groovy **build.gradle** ```groovy plugins { // ... id 'io.heap.gradle' version "1.1.1" } ``` 3. Once the dependencies and plugins have been added, sync Gradle and rebuild your application. ## Start the SDK 1. Configure and start the SDK with `CSQ.start()`. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID" ) ) } } ``` Find your environment ID `YOUR_ENVIRONMENT_ID` is either provided to you by Contentsquare or you can find it in **Account** > **Manage** > **Projects** > \[Select your project] > **Environments** within the [Product Analytics web app ↗](https://heapanalytics.com/app/). * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID" ) ) } } ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 2. Enable autocapture by setting `enableViewAutocapture` to `true`. * Product Analytics **MyApplication.kt** ```kotlin CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true ) ) ) ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( enableViewAutocapture = true ) ) ) ``` 3. (Optional) For Jetpack Compose, register the Compose Autocapture SDK. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import io.heap.autocapture.compose.ComposeAutocaptureSDK class MyApplication : Application() { override fun onCreate() { super.onCreate() ComposeAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import io.heap.autocapture.compose.ComposeAutocaptureSDK class MyApplication : Application() { override fun onCreate() { super.onCreate() ComposeAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( enableViewAutocapture = true ) ) ) } } ``` 4. (Optional) If your Product Analytics environment is hosted in the EU, set the `baseUri` option to `https://mh.ba.contentsquare.net`. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true, baseUri = URI.create("https://mh.ba.contentsquare.net") ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( enableViewAutocapture = true, baseUri = URI.create("https://mh.ba.contentsquare.net") ) ) ) } } ``` 5. Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. * Product Analytics ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this, StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` * CSQ Experience Platform (Early Access) ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this, StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more. Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code. 6. Start your application, and check logs for this output: ```text [INFO] CSQ 1.12.1 for Product Analytics is attempting to start. ``` ## Next steps Our SDK offers a wide range of features to enhance your implementation, including extended tracking capabilities, and personal data masking. [Track identity](track-identity/)Link anonymous and identified user data across sessions and devices for comprehensive analytics [Track push notifications](track-push-notifications/)Track mobile notification interactions automatically [Track events manually](track-events-manually/)Learn how to track custom events [Hide sensitive data](hide-sensitive-data/)Protect sensitive data by disabling text capture, masking specific views, or ignoring interactions Session Replay and Error Monitoring are both available with the [Experience Analytics extension](dxae-setup/), which you can purchase separately. [Experience Analytics extension](dxae-setup/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started with Product Analytics","description":"Integrate the CSQ SDK for Product Analytics into your Android app in minutes","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Collected Data Points - Cordova description: Events and metadata collected by the Contentsquare SDKs lastUpdated: 05 June 2026 source_url: html: https://docs.contentsquare.com/en/cordova/collected-data-points/ md: https://docs.contentsquare.com/en/cordova/collected-data-points/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Cordova SDK collects request metadata, gesture events, lifecycle events, transactions, and dynamic variables, all serialized as JSON and sent to the server in batches. * The events are in JSON format, which lists the properties and their description in comment. * Events are sent to the server in batches. * A batch is a subset of events originating from one session. A session can send events in more than one batch. * The batch size is defined in a run configuration file specific to each app (50 events by default). ## Requests meta data Each batch has a common header, a set of device specific, and repeatable information and an array of events, which is immutable. The header is composed at the moment of sending, so it has to be constant info ONLY. The array in the payload is data stored at the moment of collection. The structure of the batches of events will have the following format: ```javascript { pid:8, // int - ProjectId - represented in the mobile config format uid:"ac1529a7-59f6-49d9-b254-6f0a22f57284", // String - uuid Unique user ID dt:4, // int - device type (loosely enforced enum - [SDK-phone : 4, SDK-tablet :5]) dma:"Samsung", // String - device manufacturer. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. dmo:"SG", // String - device model. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. os:"7.0", // String - os version (Android version name 6.0, 7.0, 8.0) l:"en_US", // String - Language in iso-639 format https://www.ibabbleon.com/iOS-Language-Codes-ISO-639.html tz:"Europe/Paris", // String - timezone https://en.wikipedia.org/wiki/List_of_tz_database_time_zones now:1522159618000, // long - timestamp when the batch was sent to:{ // object - type origin of the event an:"appname" // String - application name st:"SDK-android", // String - type of SDK sf:"release", // string - SDK flavor/variant [release/debug/god] }, r:{ // Device - resolution. w:1080, // int - width h:1920 // int - height d: 1.5 // The device density as float. Its values can vary between (0.75 and 10) }, pl:[] // JSON array payload - list of event objects, see below } ``` ## Events ### Events meta data All events have a common first part (don't confuse it with the header explained above). This common section is data which is common for all events by type but is gathered at the moment the event occurred. This common section is a part of the actual event payload. ```javascript { upt:1522, // long - system update in milliseconds euid:"euid", // String - event UUID url:"app-and://identifier/mainPath/secondaryPath?title=screeName", // String - screenName is passed in the title query Parameter scn:4, // int - the number of screens already shown in the session c:3, // int - connectivity type [-1 - offline, 0 - error, 1 - wifi, 2 - 2g, 3 - 3g, 4 - 4g] ci:"verizon", // String - carrier_id when user is on mobile network o:1, // int - orientation [0 = portrait, 1 = landscape] vo:{ // object - version origin of the event sv:"2.1", // string version of the SDK sb:4, // int - SDK build number av:"appVersion", // String - application version af:"appFlavor" // String - application string - [release/debug/god] ab:1 // int - application build number }, sn:1, // int - session id (positive int) t:12894726459435 // long - timestamp of the event (in milliseconds) } ``` All event-specific properties are appended to this JSON object. ### App Start This event describes the absolute start of the app. The trigger for this event is the absolute start of the app. This is the first event sent when the SDK is invoked. ```javascript ea: 0; // int - event action - defined above ``` ### App Show This event is sent when the user brings the app in the foreground (switching from another app, exiting lock screen, etc.). This event means the app is focused. ```javascript ea: 1; // int - event action - defined above ``` ### App Hide This event is sent when the user exits (minimizes) the app, or switches to something else. This event means the app is not focused and the session might end, but we have not completely ended the session yet, as the user might return. ```javascript ea: 2; // int - event action - defined above ``` ### Screenview Everything starts with a View event. This is an event which describes the equivalent of a "page view" on the web. This event is sent when the Track Screen API is called. ```javascript ea:4 // int - event action - defined above st:"title", // String - screen title sl:34543 // int - (load time) screen load time (diff between last action and this event) ``` ### Transaction To track transactions, we provide a public API which can send a transaction object (see section [Track Transactions](https://docs.contentsquare.com/en/cordova/track-transactions/)). This object must contain the following parameters: ```javascript ea: 16, // int - event action - defined above tr: { // a json object with different properties defining the transaction made vl: 20.0, // mandatory - float - the value of the transaction cu: 978, // mandatory - int - the ISO 4217 code of the currency of the transaction id: "32akjkljklJ575775" // optional - string - an id for the transaction } ``` ### Dynamic variables To track dynamic variables we provide a public API which can send a custom event object (see section [Dynamic variables](https://docs.contentsquare.com/en/cordova/track-dynamic-variables/)). ```javascript // Dynamic variable event with a string value ea:18, // int - event action - defined above k:"key", // String - Custom key assigned by client. v:"value" // String - Custom value assigned by client. ``` ```javascript // Dynamic variable event with a number value ea:19, // int - event action - defined above k:"key", // String - Custom key assigned by client. v: 2344 // Integer - Custom value assigned by client. ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Collected Data Points","description":"Events and metadata collected by the Contentsquare SDKs","url":"https://docs.contentsquare.com/en/cordova/collected-data-points/","inLanguage":"en","dateModified":"2026-06-05T17:39:25+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - Cordova description: Requirements and limitations to develop with the Contentsquare SDKs lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/cordova/compatibility/ md: https://docs.contentsquare.com/en/cordova/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Each version of the Contentsquare plugin will be linked to specific, fixed versions of each native SDK. to make that clear, here is a compatibility table to consider when choosing your version of the plugin (refer to the [Cordova Plugin Changelog](https://docs.contentsquare.com/en/cordova/changelog/)) to know what the changes are for each version. | Plugin Version | iOS SDK Version | Android SDK Version | Min Cordova Version | Max Cordova Version | | - | - | - | - | - | | 0.3.0 | 4.20.0 | 4.15.0 | 11.0.0 | 11.0.x | | 0.2.0 | 4.18.0 | 4.15.0 | 11.0.0 | 11.0.x | | 0.1.0 | 4.15.1 | 4.11.0 | 11.0.0 | 11.0.x | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Contentsquare SDKs","url":"https://docs.contentsquare.com/en/cordova/compatibility/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: How the SDK works - Cordova description: Understand how the Contentsquare SDKs load, track, and send data lastUpdated: 28 April 2026 source_url: html: https://docs.contentsquare.com/en/cordova/how-the-sdk-works/ md: https://docs.contentsquare.com/en/cordova/how-the-sdk-works/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The SDK auto-starts at application launch, attaches to the current process, and intercepts the events and gestures needed to capture analytics data. ## Configuration Once started, our SDK fetches its config from our servers, and then depending on the segmentation size (defined by our team when you sign a contract) it will start collecting data from system and user events it detects from the runtime. ## Tracking The SDK monitors the application lifecycle events and the view hierarchy, and generates analytics data from the behavior of the app, the content of the screen and the interaction of the user. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. ## Sending data 📚 [Native Android SDK documentation for Sending data](https://docs.contentsquare.com/en/android/how-the-sdk-works/#sending-data) 📚 [Native iOS SDK documentation for Sending data](https://docs.contentsquare.com/en/ios/how-the-sdk-works/#sending-data) ## Session definition A session is one continuous period of user interaction. It starts upon app launch and persists through state changes, including putting the app in the background or terminating and restarting it. As long as users interact at least once every 30 minutes, it remains the same session. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"How the SDK works","description":"Understand how the Contentsquare SDKs load, track, and send data","url":"https://docs.contentsquare.com/en/cordova/how-the-sdk-works/","inLanguage":"en","dateModified":"2026-04-28T22:02:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Impact on performance - Cordova description: Metrics to evaluate the impact on performance of the SDKs on your apps lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/cordova/impact-on-performance/ md: https://docs.contentsquare.com/en/cordova/impact-on-performance/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare strives to be non-intrusive and transparent to client app developers. The following are the technical specifics we can share on performance. *  ### [Android](https://docs.contentsquare.com/en/android/impact-on-performance/) *  ### [iOS](https://docs.contentsquare.com/en/ios/impact-on-performance/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Impact on performance","description":"Metrics to evaluate the impact on performance of the SDKs on your apps","url":"https://docs.contentsquare.com/en/cordova/impact-on-performance/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: In-app features - Cordova description: Implement in-app features with the Contentsquare SDKs lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/cordova/in-app-features/ md: https://docs.contentsquare.com/en/cordova/in-app-features/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Alongside its tracking capabilities, the SDKs embed some features aimed at Contentsquare users such as [SDK Logs](#debugging-and-logging). ## Implement in-app features ### 1. Install the Cordova plugin to handle URL schemes In order for your application to open when you scan the QR code or enter the URL we provide in a web browser, you have to install a Cordova plugin which will handle the URL scheme. ```javascript cordova plugin add cordova-plugin-customurlscheme --variable URL_SCHEME=cs-{package-id} // Example: // my package id is 'com.mycompany.myapp' // cordova plugin add cordova-plugin-customurlscheme --variable URL_SCHEME=cs-com.mycompany.myapp ``` ### 2. Call the SDK when your app is opened with the custom URL Then, you will need to link your app with our SDK. When your application is started via a deeplink, a specific global JavaScript function, handleOpenURL(), is automatically called in your App. You will have to define this function in the 'window' global scope and you will need to call a function of our API via the Contentsquare Cordova Plugin. ```javascript window.handleOpenURL = function (url) { console.log("received url: " + url); ContentsquarePlugin.handleURL(url); }; ``` ## Enable in-app features In-app features can be enabled in different ways: ### Scan the QR Code If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code displayed with your phone. Take a look at the native documentation for further information. ### Alternative methods We provide alternative methods to enable in-app features especially for iOS Simulator and Android Emulator. 📚 [Native Android SDK documentation for Enable in-app features](https://docs.contentsquare.com/en/android/in-app-features/) 📚 [Native iOS SDK documentation for Enable in-app features](https://docs.contentsquare.com/en/ios/in-app-features/) ## Debugging and Logging Contentsquare provides Logging capabilities that allow you to see the raw event data logged by your app. Use this for validation purposes during the instrumentation phase of development and can help you discover errors and mistakes in your analytics implementation and confirm that all events are being logged correctly. 📚 [Native Android SDK documentation for Debugging and Logging](https://docs.contentsquare.com/en/android/in-app-features/#debugging-and-logging) 📚 [Native iOS SDK documentation for Debugging and Logging](https://docs.contentsquare.com/en/ios/in-app-features/#debugging-and-logging) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"In-app features","description":"Implement in-app features with the Contentsquare SDKs","url":"https://docs.contentsquare.com/en/cordova/in-app-features/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - Cordova description: Learn how Contentsquare deals with Personal Data and related APIs lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/cordova/privacy/ md: https://docs.contentsquare.com/en/cordova/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare Cordova Plugin and SDKs are compliant with the **Play Store and App Store Privacy guidelines** and with the **EU General Data Protection Regulation (GDPR)**. Consult our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Handling User Consent Even though Contentsquare only collects usage data on your app, we will consider every new user to be opted-out. To start tracking, the Opt-in API must be called. Note If for some reason you think that securing user consent is not required for your app, discuss it during the Implementation process with your main contact. ## Opt-in Use the Opt-in API to get user consent. Calling this API will generate a user ID and initiate tracking. ```javascript import { ContentsquareCDVPlugin } from '@contentsquare/cordova-plugin-types'; declare var ContentsquarePlugin: ContentsquareCDVPlugin; ContentsquarePlugin.optIn((result)=>{ // Success }, (err)=>{ // Handle error }); ``` ## Opt-Out **Permanently breaking the link and stopping all data collection.** When this API is called, tracking stops immediately, all settings are reset (session number, page number, user ID...) and all files related to Contentsquare tracking are deleted. Contentsquare will never track and collect any data from the user's phone unless the Opt-in API is called again. ```javascript import { ContentsquareCDVPlugin } from '@contentsquare/cordova-plugin-types'; declare var ContentsquarePlugin: ContentsquareCDVPlugin; ContentsquarePlugin.optOut((result)=>{ // Success }, (err)=>{ // Handle error }); ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Learn how Contentsquare deals with Personal Data and related APIs","url":"https://docs.contentsquare.com/en/cordova/privacy/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Security - Cordova description: Data transfer and security information lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/cordova/security/ md: https://docs.contentsquare.com/en/cordova/security/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Cordova SDK is designed with security and privacy in mind. ## Transmission and hosting All data is encrypted in transport over HTTPS. Our hosting solution is a PCI DSS Level 1 Service Provider. ## What is not collected * Passwords from password fields * Geo location information * Information from contacts, emails, or any other user identifiable information. * Text from labels, buttons, and any other widget which contains text * Accessibility information from any widget which the user interacts with * Labels printed on the screen of any kind. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Security","description":"Data transfer and security information","url":"https://docs.contentsquare.com/en/cordova/security/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track Dynamic Variables - Cordova description: Track dynamic variables with the Contentsquare Cordova plugin lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/cordova/track-dynamic-variables/ md: https://docs.contentsquare.com/en/cordova/track-dynamic-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Dynamic variables are additional information on the session that can be used to segment sessions. For example, they can include information on the A/B Test variations displayed to the current user. ## Defining dynamic variables To define and send a dynamic variable, use the API below. For each dynamic variable, we send: * Key (`string`, mandatory) * Value (`string` or `integer`, mandatory) if you send an integer as a value, it has indeed to be an integer. A null or a float will not be accepted as a valid parameter, and will result in an error. ```javascript import { ContentsquareCDVPlugin, DynamicVarItem } from '@contentsquare/cordova-plugin-types'; declare var ContentsquarePlugin: ContentsquareCDVPlugin; const myDynamicVar: DynamicVarItem = { dynVarKey: 'myKey', dynVarValue: 32, } ContentsquarePlugin.sendDynamicVar(myDynamicVar, (result) => { // Success }, (err) => { // Handle Error }); ``` ## Sending a dynamic variable for each session You may want to send a dynamic variable for each session (like the user's country or store). While **triggering the dynamic variable at app launch will cover most cases, it will not be enough**. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See [Session definition](https://docs.contentsquare.com/en/cordova/how-the-sdk-works/#session-definition) for more information. That is why we also recommend **sending such dynamic variable every time the app enters foreground**. You can use the [`onResume` event ↗](https://cordova.apache.org/docs/en/latest/cordova/events/events.html) triggered by Cordova to detect foreground and trigger a dynamic variable. ## Limits ### On the server side * It is possible to save up to 40 distinct dynamic variable keys per screen view. If more are received, only the first 40 keys will be kept. * If you are using the same key twice, the last value associated with the key will be collected. ### On the SDK side * Every dynamic variable is composed of a pair of key (max. 512 characters) and value (max. 255 characters string or a whole number between 0 and 232 - 1 ). The SDK will trim the exceeding characters. * If key or value is empty, the SDK will send the string "cs-empty". ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track Dynamic Variables","description":"Track dynamic variables with the Contentsquare Cordova plugin","url":"https://docs.contentsquare.com/en/cordova/track-dynamic-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track screens - Cordova description: Track screens with the Contentsquare Cordova plugin lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/cordova/track-screens/ md: https://docs.contentsquare.com/en/cordova/track-screens/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare aggregates user behavior and engagement at the screen level. To achieve this, it is necessary to provide a name for each screen by calling a dedicated screenview API. Warning Sessions without at least one screenview will be discarded. ```javascript import { ContentsquareCDVPlugin } from '@contentsquare/cordova-plugin-types'; declare var ContentsquarePlugin: ContentsquareCDVPlugin; ContentsquarePlugin.sendScreenName("ScreenName", (result)=>{ // Success }, (err)=>{ // Handle error }); ``` ## Screen name handling The screen name is limited to 2083 characters. However, this limit is not enforced by the SDK, but rather by the Contentsquare servers. ## Screenview after app in background The SDK triggers a screenview automatically after the app is put in background and foreground, as long as a screenview with a screen name has been triggered previously. It will use the last screen name set. ## Implementation recommendations From a functional standpoint, we expect a screenview to be sent: * When the screen appears * When a modal/pop-up is closed and the user is back on the screen * When the app is put in the foreground (after an app hide) ## How to name screens As a general rule, keep the number of distinct screen names under 100. Since these names are used to map your app in Contentsquare, choose names that are clear and comprehensive. ### Separate words with space, dash, or underscore characters If you want to generate screen names including more than one word, it is best to separate them and to do so using space, dash, or underscore characters. Contentsquare handles automatically the formatting for them. **Example:** For a sub-category list of a retail app, use `Home and Living - Home Furnishings` instead of `homeLivingHomeFurnishings`. ### Use screen template/layout names As a general recommendation, use names referring to the screen template/layout rather than referring to the specific content (data). This will help: * To keep the number of distinct screen names low and therefore make Contentsquare easier to use * Remove the risk of sending Personal Data to Contentsquare List of screen types falling into that category: *Product detail, Event detail, Conversation/Chat, User profile...* ### Screens with multiple states/layouts Screens can have different layouts or states depending on the user context. In this case, append its value to the screen name. **Home screen** | State | Screen name | | - | - | | App landing layout | `Home` | | Women products layout | `Home - Women` | | Men products layout | `Home - Men` | | Sales layout | `Home - Sales` | **Product Detail screen (PDP)** | State | Screen name | | - | - | | Users on a Top for Women PDP | `PDP - Clothing - Women - Tops` | | Users on a Microwave PDP | `PDP - Kitchenware - Electrics - Microwave` | | Users on a Hotel details screen | `PDP - Holiday type - Season - Board` | **User account screen** | State | Screen name | | - | - | | Overview | `My Account - Dashboard` | | Order history | `My Account - Order history` | | Returns | `My Account - Returns` | **Search screen** | State | Screen name | | - | - | | Search | `Search` | | Search results for "Skincare" products | `Search - Skincare` | | Search results error screen | `Search - Error` | **Cart screen** | State | Screen name | | - | - | | Empty cart | `Cart - Empty` | | Items have been added to the cart | `Cart - Populated` | | Issues with availability or pricing | `Cart - Error` | **Checkout screen** | State | Screen name | | - | - | | User provides name, surname, and date of birth | `Checkout - User Details` | | User provides shipping address | `Checkout - Shipping Details` | | User inputs their credit card information | `Checkout - Payment` | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track screens","description":"Track screens with the Contentsquare Cordova plugin","url":"https://docs.contentsquare.com/en/cordova/track-screens/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track transactions - Cordova description: Track transactions with the Contentsquare Cordova plugin lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/cordova/track-transactions/ md: https://docs.contentsquare.com/en/cordova/track-transactions/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To associate a user's session with their potential purchases (and corresponding revenue), you must send the transaction via a dedicated API. For each transaction, we send: * Price (`number`, mandatory) * Currency (`CurrencyCode` or `string`, mandatory) * Transaction ID (`string`, optional) The plugin defines a `TransactionItem` type to prevent potential typing errors. ```javascript import { ContentsquareCDVPlugin, CurrencyCode, TransactionItem } from '@contentsquare/cordova-plugin-types'; declare var ContentsquarePlugin: ContentsquareCDVPlugin; const myTransaction: TransactionItem = { transactionValue: 10.99, transactionCurrency: CurrencyCode.USD, transactionId: 'my_transaction_id', }; ContentsquarePlugin.sendTransaction(myTransaction, (result) => { // Success }, (err) => { // Handle Error }); ``` Warning **Each transaction must only be sent once**. A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ## Currency The currency is conforming to the [ISO 4217 ↗](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) standard. Although the currency can be passed as "alphanumeric code", you should always prefer using the plugin's CurrencyCode object values. If you have to pass the ISO code as a string, capitalization is not a factor (`"USD"`, `"Usd"` or `"usd"` will all be treated as the US Dollar). If the currency passed doesn't match our supported currencies, the SDK will send a currency value of "-1". It will be processed as the default currency of the project. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track transactions","description":"Track transactions with the Contentsquare Cordova plugin","url":"https://docs.contentsquare.com/en/cordova/track-transactions/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Getting Started with Experience Analytics - Flutter description: Integrate the CSQ SDK for Experience Analytics into your Flutter app in minutes lastUpdated: 09 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This quick start guide shows you how to get Contentsquare Experience Analytics set up in a Flutter application. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-flutter/experience-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. After completing the setup process, you'll be able to take full advantage of the CSQ API to collect data from your app, within just a few minutes. ## Install the SDK With Flutter CLI: ```shell flutter pub add contentsquare ``` This will add a line like this to your package's `pubspec.yaml` (and run an implicit `flutter pub get`): **pubspec.yaml** ```yaml dependencies: flutter: sdk: flutter contentsquare: ^4.4.4 ``` ## Start the SDK 1. Import the SDK: ```dart import 'package:contentsquare/csq.dart'; ``` 2. Add a call to star SDK as soon as possible in your app, ideally in the `main()` function. **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start(); } ``` 3. Start your application, and check logs for this output: ```text ┌─────────────────────────────────────────────────────────────────────────────── │ 🔔 IMPORTANT 🔔 (CSLIB 4.4.4) ├─────────────────────────────────────────────────────────────────────────────── │ Contentsquare Flutter SDK 4.4.4 starting in app: │ com.example.testapp └─────────────────────────────────────────────────────────────────────────────── ``` ## Get user consent Implement the [`optIn()`](command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. The CSQ SDK treats users as opted-out by default. It can be done immediately after `start` is called: **main.dart** ```dart void main() async { // ... await CSQ().start(); await CSQ().optIn(); // ... } ``` Alternatively, you can call `optIn()` in response to a user action, such as tapping an "I agree" button: ```dart class UserConsentScreen extends StatelessWidget { @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: Text('User Consent'), ), body: Center( child: ElevatedButton( onPressed: () async { await CSQ().optIn(); }, child: Text('Agree with Terms and Conditions'), ), ), ); } } ``` ## Track your first screens Once SDK has started, you're able to take full advantage of the CSQ SDK API to track screen views, monitor user interactions, and capture app behavior data. CSQ Experience Analytics also comes with powerful Session Replay and Error Monitoring capabilities as paid options. ### Sending screenview events Screen tracking is achieved by sending a `screenview` event: * Right after the SDK has started * When the screen appears * When a modal/pop-up is closed and the user is back on the screen * When the app is put in the foreground (after an app hide) ```dart import 'package:contentsquare/csq.dart'; CSQ().trackScreenview(screenName: 'ScreenName'); ``` For more information see [Track screens](track-screens/). ## Next Steps While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior. Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking. Proceed with these how-to's to refine your implementation. [Custom Variables](track-custom-variables/)Collect additional details about the screen or the user. [Dynamic Variables](track-dynamic-variables/)Collect additional information about the session. [Transactions tracking](track-transactions/)Associate user's session with their potential purchases and corresponding revenue. [WebViews](track-webviews/)For native apps which embark web applications or pages. [Session Replay](session-replay/)Collect data for Session Replay in compliance personal data masking. [Error Analysis](error-analysis/)Track API errors and application crashes with automated collection and privacy-safe debugging tools. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started with Experience Analytics","description":"Integrate the CSQ SDK for Experience Analytics into your Flutter app in minutes","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/","inLanguage":"en","dateModified":"2026-06-09T16:28:37+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Getting Started with Product Analytics - Flutter description: Integrate the CSQ SDK for Product Analytics into your Flutter app with step-by-step instructions for installation and configuration lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use this quick start guide to set up the CSQ Product Analytics SDK in a Flutter application. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-flutter/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. Once you've completed the setup process, the CSQ SDK will capture a wide variety of user interactions in your application with no additional code required. Upgrading See our guides to upgrade to the CSQ SDK * [from the Heap Core SDK](../product-analytics/upgrade-from-heap-core-sdk/) * [from the Heap Core SDK + Contentsquare SDK](../product-analytics/upgrade-from-heap-and-cs-sdk/) ## Install the SDK With Flutter CLI: ```shell flutter pub add contentsquare ``` This will add a line like this to your package's `pubspec.yaml` (and run an implicit `flutter pub get`): **pubspec.yaml** ```yaml dependencies: flutter: sdk: flutter contentsquare: ^4.4.4 ``` ## Start the SDK 1. Import the CSQ SDK in your app: ```dart import 'package:contentsquare/csq.dart'; ``` 2. Configure and start the SDK as soon as possible in your app, ideally in the `main()` function. Find your environment ID `YOUR_ENVIRONMENT_ID` is either provided to you by Contentsquare or you can find it in **Account** > **Manage** > **Projects** > \[Select your project] > **Environments** within the [Product Analytics web app ↗](https://heapanalytics.com/app/). * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', ), ); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', ), ); } ``` 3. (**Optional**) Add `AnalyticsOptions`. For example if your Product Analytics environment is hosted in the EU, set the `baseUrl` option to `https://mh.ba.contentsquare.net` * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( baseUrl: Uri.parse('https://mh.ba.contentsquare.net'), ), ), ); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( baseUrl: Uri.parse('https://mh.ba.contentsquare.net'), ), ), ); } ``` 4. Start your application, and check logs for this output: ```text ┌─────────────────────────────────────────────────────────────────────────────── │ 🔔 IMPORTANT 🔔 (CSLIB 4.4.4) ├─────────────────────────────────────────────────────────────────────────────── │ Contentsquare Flutter SDK 4.4.4 starting in app: │ com.example.testapp └─────────────────────────────────────────────────────────────────────────────── ``` 5. Recommended To capture screen views automatically, add the `CSQNavigatorObserver` to your app's navigator observers: **main.dart** ```dart import 'package:contentsquare/csq.dart'; MaterialApp( navigatorObservers: [ CSQNavigatorObserver(), ], home: MyHomePage(), ) ``` More details in [Customize autocaptured screens](https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/customize-autocaptured-screens/). 6. Recommended To enable automatic capture of user interactions, add the option `enableInteractionsAutocapture: true` to your `AnalyticsOptions` configuration: * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( enableInteractionsAutocapture: true, ), ), ); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( enableInteractionsAutocapture: true, ), ), ); } ``` ## Get user consent Implement the [`optIn()`](command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. The CSQ SDK treats users as opted-out by default. It can be done immediately after `start` is called: **main.dart** ```dart void main() async { // ... await CSQ().start(); await CSQ().optIn(); // ... } ``` Alternatively, you can call `optIn()` in response to a user action, such as tapping an "I agree" button: ```dart class UserConsentScreen extends StatelessWidget { @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: Text('User Consent'), ), body: Center( child: ElevatedButton( onPressed: () async { await CSQ().optIn(); }, child: Text('Agree with Terms and Conditions'), ), ), ); } } ``` ## Next steps Our SDK offers a wide range of features to enhance your implementation, including extended tracking capabilities, and personal data masking. [Track identity](track-identity/) Link anonymous and identified user data across sessions and devices for comprehensive analytics [Track push notifications](track-push-notifications/)Track mobile notification interactions automatically [Track events manually](track-events-manually/)Learn how to track custom events [Hide sensitive data](privacy-and-sensitive-data/)Protect sensitive data by disabling text capture, masking specific views, or ignoring interactions Session Replay and Error Monitoring are both available with the [Experience Analytics extension](dxae-setup/), which you can purchase separately. [Experience Analytics extension](dxae-setup/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started with Product Analytics","description":"Integrate the CSQ SDK for Product Analytics into your Flutter app with step-by-step instructions for installation and configuration","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Getting Started with Experience Analytics - iOS description: Integrate the CSQ SDK for Experience Analytics into your iOS app in minutes lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This quick start guide shows you how to get Contentsquare Experience Analytics set up in an iOS application. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-ios/experience-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. After completing the setup process, you'll be able to take full advantage of the CSQ API to collect data from your app, within just a few minutes. ## Before you begin This guide assumes you are using Xcode with [Swift Package Manager ↗](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app) to manage external dependencies. ## Install the SDK CocoaPods support is ending CocoaPods trunk becomes read-only on December 2, 2026. After this date, Contentsquare will no longer publish new SDK versions via CocoaPods. [Migrate to Swift Package Manager (SPM)](https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/) to continue receiving updates. 1. In your Xcode project > `Package Dependencies`, add this repository location: ```plaintext https://github.com/ContentSquare/apple-sdk.git ``` 2. Set the Dependency Rule to `Exact Version` `1.12.2`. 3. Select `Add Package`. 4. To ensure the library can start properly, add `-ObjC` as a linker flag under `Build Settings` > `Linking - General` > `Other Linker Flags`. ## Start the SDK 1. Import the `ContentsquareSDK` module in `AppDelegate`: **AppDelegate.swift** ```swift import UIKit import ContentsquareSDK @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { ... } } ``` 2. Add a call to `CSQ.start()`: * Experience Analytics **AppDelegate.swift** ```swift import UIKit import ContentsquareSDK @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { CSQ.start() return true } } ``` * CSQ Experience Platform (Early Access) **AppDelegate.swift** ```swift import UIKit import ContentsquareSDK @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") return true } } ``` 3. Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. * Experience Analytics ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start() CSQ.optIn() // Continue with post-consent navigation or UI update } ``` * CSQ Experience Platform (Early Access) ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` 4. Start your application, and check logs for this output: ```text [INFO] CSQ 1.12.2 for Experience Analytics is attempting to start. ``` ## Track your first screens Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel. Once tracking has started, you're able to take full advantage of the CSQ SDK API to track screen views, monitor user interactions, and capture app behavior data. Contentsquare Experience Analytics also comes with powerful Session Replay and Error Monitoring capabilities as paid options. ### Sending screenview events Screen tracking is achieved by sending a `screenview` event: * Right after the SDK has started * When the screen appears * When a modal/pop-up is closed and the user is back on the screen * When the app is put in the foreground (after an app hide) As a general rule of thumb, you should send your screenviews in `viewWillAppear(_ animate: Bool)` when using UIKit, in `.onAppear()` when using SwiftUI. ```swift import ContentsquareSDK CSQ.trackScreenview(String, cvars: [CustomVar] = []) ``` For more information see [Implementation recommendations](track-screens/#implementation-recommendations) ## Next Steps While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior. Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking. Proceed with these how-to's to refine your implementation. [Custom Variables](track-custom-variables/)Collect additional details about the screen or the user. [Dynamic Variables](track-dynamic-variables/)Collect additional information about the session. [Transactions tracking](track-transactions/)Associate user's session with their potential purchases and corresponding revenue. [WebViews](track-webviews/)For native apps which embark web applications or pages. [Session Replay](session-replay/)Collect data for Session Replay in compliance personal data masking. [Error Analysis](error-analysis/)Track API errors and application crashes with automated collection and privacy-safe debugging tools. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started with Experience Analytics","description":"Integrate the CSQ SDK for Experience Analytics into your iOS app in minutes","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Migrate from CocoaPods to Swift Package Manager - iOS description: Step-by-step guide to migrate your Contentsquare iOS SDK integration from CocoaPods to Swift Package Manager lastUpdated: 01 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/ md: https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. CocoaPods is no longer supported for integrating the CSQ iOS SDK in your app. **If you stay on CocoaPods, you will stop receiving SDK updates. Migrate to Swift Package Manager to continue receiving new features and fixes.** ## Before you begin * Xcode 16.0 or later is required. * Make sure you have an up-to-date copy of your project in source control before starting. ## Migration steps ### 1. Remove the Contentsquare SDK from your Podfile Open your `Podfile` and remove the Contentsquare SDK pod reference: ```ruby pod 'ContentsquareSDK' ``` Then run `pod install` to update your project: ```shell pod install ``` Note This approach keeps CocoaPods in your project for other dependencies. You can continue using CocoaPods alongside Swift Package Manager. ### 2. Add the Contentsquare SDK via Swift Package Manager 1. In Xcode, go to `File > Add Packages…`. 2. Enter the following repository URL: ```plaintext https://github.com/ContentSquare/apple-sdk.git ``` 1) Set the Dependency Rule to `Exact Version` `1.12.2`. 1. Click `Add Package`. ### 3. Add the `-ObjC` linker flag To ensure the SDK starts correctly, add `-ObjC` as a linker flag: 1. In your target's `Build Settings`, search for `Other Linker Flags`. 2. Add `-ObjC`. ### 4. Remove leftover SwiftProtobuf dependency If you previously added `pod 'SwiftProtobuf'` to work around a known CocoaPods issue, remove that reference from your project. SwiftProtobuf is included automatically via SPM. Also remove `https://github.com/apple/swift-protobuf.git` from `Package Dependencies` if you had added it before SDK version 4.35.1. ### 5. Build and verify Build your project. If the build succeeds and the SDK initializes correctly, the migration is complete. Tip To verify the SDK is running, filter your Xcode or macOS Console logs by `CSLIB`. ## If you want to fully remove CocoaPods If you're not using CocoaPods for any other dependencies and want to completely remove it from your project: 1. Run `pod deintegrate` in your project directory. 2. Delete `Podfile` and `Podfile.lock`. 3. Open the `.xcodeproj` file directly instead of the `.xcworkspace`. Warning Only do this if you have no other CocoaPods dependencies in your project. ## Troubleshooting ### Symbol not found at runtime If you see an error like: ```text dyld: Symbol not found: _OBJC_CLASS_$_... ``` Make sure the `-ObjC` linker flag is present under `Build Settings` > `Linking` > `Other Linker Flags` for your app target. ### Module not found at build time If Xcode cannot find the `ContentsquareModule` import, check that the `ContentsquareSDK` package is listed under your target's `Frameworks, Libraries, and Embedded Content` in the General tab. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Migrate from CocoaPods to Swift Package Manager","description":"Step-by-step guide to migrate your Contentsquare iOS SDK integration from CocoaPods to Swift Package Manager","url":"https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/","inLanguage":"en","dateModified":"2026-07-01T21:01:22+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Getting Started with Product Analytics - iOS description: Integrate the CSQ SDK for Product Analytics into your iOS app with step-by-step instructions for installation and configuration lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use this quick start guide to set up a new instance of Contentsquare's Product Analytics SDK in an iOS application. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-ios/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. Once you've completed the setup process, the Contentsquare SDK will capture a wide variety of user interactions in your application with no additional code required. Upgrading See our guides to upgrade to the CSQ SDK from the [Heap Core SDK](../product-analytics/upgrade-from-heap-core-sdk/) or the [Heap Classic SDK](../product-analytics/upgrade-from-heap-classic-sdk/). ## Before you begin This guide assumes you are using Xcode with [Swift Package Manager ↗](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app) to manage external dependencies. ## Install the SDK CocoaPods support is ending CocoaPods trunk becomes read-only on December 2, 2026. After this date, Contentsquare will no longer publish new SDK versions via CocoaPods. [Migrate to Swift Package Manager (SPM)](https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/) to continue receiving updates. 1. In your Xcode project > `Package Dependencies`, add this repository location: ```plaintext https://github.com/ContentSquare/apple-sdk.git ``` 2. Set the Dependency Rule to `Exact Version` `1.12.2` 3. Select `Add Package` 4. To ensure the library can start properly, add `-ObjC` as a linker flag under `Build Settings` > `Linking - General` > `Other Linker Flags` ## Start the SDK 1. Configure and start the SDK with `CSQ.start()`. * Product Analytics **AppDelegate.swift** ```swift import UIKit import ContentsquareSDK @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { // ... CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID" ) } } ``` Find your environment ID `YOUR_ENVIRONMENT_ID` is either provided to you by Contentsquare or you can find it in **Account** > **Manage** > **Projects** > \[Select your project] > **Environments** within the [Product Analytics web app ↗](https://heapanalytics.com/app/). * CSQ Experience Platform (Early Access) **AppDelegate.swift** ```swift import UIKit import ContentsquareSDK @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { // ... CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID" ) } } ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 2. For UIKit and SwiftUI Enable screenviews and event autocapture. * Product Analytics ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .enableNativeAutocapture: true ] ) ``` * CSQ Experience Platform (Early Access) ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ .enableNativeAutocapture: true ] ) ``` Note [Customize screen names](../product-analytics/customize-autocaptured-screen-names/) to better match your analysis needs. 3. (Optional) If your Product Analytics environment is hosted in the EU, set the `baseURL` option to `"https://mh.ba.contentsquare.net"`. * Product Analytics ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .baseURL: "https://mh.ba.contentsquare.net" ] ) ``` * CSQ Experience Platform (Early Access) ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ .baseURL: "https://mh.ba.contentsquare.net" ] ) ``` 4. Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. * Product Analytics ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` * CSQ Experience Platform (Early Access) ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more. Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code. 5. Start your application, and check logs for this output: ```text [INFO] CSQ 1.12.2 for Product Analytics is attempting to start. ``` ## Next steps Our SDK offers a wide range of features to enhance your implementation, including extended tracking capabilities, and personal data masking. [Track identity](track-identity/) Link anonymous and identified user data across sessions and devices for comprehensive analytics [Track push notifications](track-push-notifications/)Track mobile notification interactions automatically [Track events manually](track-events-manually/)Learn how to track custom events [Hide sensitive data](hide-sensitive-data/)Protect sensitive data by disabling text capture, masking specific views, or ignoring interactions Session Replay and Error Monitoring are both available with the [Experience Analytics extension](dxae-setup/), which you can purchase separately. [Experience Analytics extension](dxae-setup/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started with Product Analytics","description":"Integrate the CSQ SDK for Product Analytics into your iOS app with step-by-step instructions for installation and configuration","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Getting Started with Experience Analytics - React Native description: Integrate the CSQ React Native SDK into your app in minutes (installation, user consent, screen tracking, and testing) lastUpdated: 09 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This quick start guide shows you how to get Contentsquare Experience Analytics set up in a React Native application. After completing the setup process, you'll be able to take full advantage of the CSQ API to collect data from your app, within just a few minutes. ## Install the SDK Compatibility The CSQ React Native SDK for React Native integrates the Contentsquare SDKs for both iOS and Android with your React Native JavaScript code. See [Compatibility](compatibility/) for more information. The CSQ React Native SDK is available as an [NPM package ↗](https://www.npmjs.com/package/@contentsquare/react-native-bridge), which includes the bridge and the necessary dependencies for specific versions of the SDKs. To install the CSQ React Native SDK, open a terminal and run the following commands from your application's root directory: * yarn ```shell yarn add @contentsquare/react-native-bridge cd ios && pod install ``` * npm ```shell npm install @contentsquare/react-native-bridge cd ios && pod install ``` iOS Specific Note Since React Native projects for iOS are in Objective-C and our SDK is in Swift, you need to embed the Swift standard libraries. In your project's target Build Settings, set **Embedded Content Contains Swift Code** to YES. Ensure CocoaPods version 1.10.0 or later is installed (`pod --version`). If not, update with `[sudo] gem install cocoapods`. This is required to link the SDK and bridge, as CocoaPods only added support for XCFrameworks in late 2020. ## Start the SDK Starting the SDK should happen as early as possible in your app's lifecycle, ideally in the main component or entry point of your React Native application. 1. Add a call to [`start()`](command-reference/#csqstart) within a `useEffect` hook in your main component, such as `App.js` or `index.js`: ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.dxa()); }, []); ``` 2. Start your application, and check logs for this output: ```text [INFO] CSQ 6.4.2 for Experience Analytics is attempting to start. ``` ## Get user consent The CSQ SDK treats users as opted-out by default. Implement the [`optIn()`](command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. ```javascript import React, { useState } from "react"; import { View, Text, Button } from "react-native"; import { CSQ } from "@contentsquare/react-native-bridge"; const PolicyConsentScreen = () => { const [isTrackingAccepted, setIsTrackingAccepted] = useState(false); const handleAcceptPolicy = () => { setIsTrackingAccepted(true); CSQ.optIn(); }; return ( <View> <Text>Please accept our privacy policy to proceed.</Text> <Button title="Accept Policy" onPress={handleAcceptPolicy} /> </View> ); }; export default PolicyConsentScreen; ``` Start your application, click the UI that triggers the opt-in, and check logs for this output: * Android ```shell User is drawn for tracking: true ``` * iOS ```shell Info: User consent status: Opted-in ``` ## Track your first screens Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel. Once tracking has started, you're able to take full advantage of the CSQ SDK API to track screen views, monitor user interactions, and capture app behavior data. Contentsquare Experience Analytics also comes with powerful Session Replay and Error Monitoring capabilities as paid options. ### Sending screenview events Screen tracking is achieved by sending a `screenview` event when: * The screen appears on the device * A modal or pop-up is displayed * A modal or pop-up is closed, returning the user to the screen * The app is brought back to the foreground (after being minimized) #### Sending Screenview Events using the React Navigation Library The sending of screenview events can be handled within the `NavigationContainer` in [React Navigation ↗](https://reactnavigation.org/docs/navigation-container/), which centralizes the logic and helps avoid unnecessary calls. ```javascript // This associates the screen name sent to Contentsquare to the screen name defined in the code const screenEventByScreenName: Record<string, string> = { Home: 'Home', ProductList: 'Product List', ProductDetails: 'Product #1', }; export const Navigation = () => { const navigationRef = useNavigationContainerRef<RootStackParamList>(); const routeNameRef = useRef<string>(); return ( <NavigationContainer ref={navigationRef} onReady={() => { // Getting initial route name from navigation and sending a screen view event with Contentsquare SDK const currentRouteName = navigationRef.getCurrentRoute()?.name; if (currentRouteName && screenEventByScreenName[currentRouteName]) { Contentsquare.send(screenEventByScreenName[currentRouteName]); } }} onStateChange={() => { // Getting route name from navigation and sending a screen view event with Contentsquare SDK const currentRouteName = navigationRef.getCurrentRoute()?.name; routeNameRef.current = currentRouteName; if (currentRouteName && screenEventByScreenName[currentRouteName]) { Contentsquare.send(screenEventByScreenName[currentRouteName]); } }} > <RootNavigator /> <PrivacyManager /> </NavigationContainer> ); }; ``` For more information, see [Implementation recommendations](track-screens/#implementation-recommendations) #### Tracking app launch Most events collected by the SDK require a screenview event to be sent first so they can be associated with that screen; otherwise, they will be discarded. If you need to collect events from the moment the app launches, you should trigger a screenview event immediately after the SDK has started. Refer to [our guide](track-screens/#when-to-send-your-first-screenview) for implementation examples. #### Screen name handling It is necessary to provide a name for each screen when calling the screenview API. As a general rule, keep distinct screen names under 100. As they are used to map your app in Contentsquare, you will want something comprehensive. The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side. More on [screen name handling](track-screens/#how-to-name-screens). Tracking plan To get the most out of your data, it's best to follow a tracking plan. This way, you'll capture every step of the user's journey without missing important interactions, giving you a complete picture of how your app is used. ## Sample app To explore some of these features in context, check our React Native sample app. ### [react-native-sample-app](https://github.com/ContentSquare/react-native-sample-app) [Sample apps illustrating how to use the Contentsquare Bridge for React Native in your app](https://github.com/ContentSquare/react-native-sample-app) [TypeScript](https://github.com/ContentSquare/react-native-sample-app) ## Next Steps While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior. Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking. Proceed with these how-to's to refine your implementation. [Custom Variables](track-custom-variables/)Collect additional details about the screen or the user. [Dynamic Variables](track-dynamic-variables/)Collect additional information about the session. [Transactions tracking](track-transactions/)Associate user's session with their potential purchases and corresponding revenue. [WebViews](track-webviews/)For native apps which embark web applications or pages. [Session Replay](session-replay/)Collect data for Session Replay in compliance personal data masking. [Error Analysis](error-analysis/)Track API errors and application crashes with automated collection and privacy-safe debugging tools. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started with Experience Analytics","description":"Integrate the CSQ React Native SDK into your app in minutes (installation, user consent, screen tracking, and testing)","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/","inLanguage":"en","dateModified":"2026-06-09T16:28:37+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Getting Started with Product Analytics - React Native description: Integrate the CSQ SDK for Product Analytics into your React Native app in minutes lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This quick start guide shows you how to get Contentsquare Product Analytics set up in a React Native application. Once you've completed the setup process, the Contentsquare SDK will capture a wide variety of user interactions in your application with no additional code required. Upgrading See our guides to upgrade to the CSQ SDK from the [Heap Core SDK](../product-analytics/upgrade-from-heap-core-sdk/) or the [Heap Classic SDK](../product-analytics/upgrade-from-heap-classic-sdk/). ## Install the SDK Compatibility The CSQ React Native SDK for React Native integrates the Contentsquare SDKs for both iOS and Android with your React Native JavaScript code. See [Compatibility](compatibility/) for more information. The CSQ React Native SDK is available as an [NPM package ↗](https://www.npmjs.com/package/@contentsquare/react-native-bridge), which includes the bridge and the necessary dependencies for specific versions of the SDKs. To install the CSQ React Native SDK, open a terminal and run the following commands from your application's root directory: * yarn ```shell yarn add @contentsquare/react-native-bridge cd ios && pod install ``` * npm ```shell npm install @contentsquare/react-native-bridge cd ios && pod install ``` iOS Specific Note Since React Native projects for iOS are in Objective-C and our SDK is in Swift, you need to embed the Swift standard libraries. In your project's target Build Settings, set **Embedded Content Contains Swift Code** to YES. Ensure CocoaPods version 1.10.0 or later is installed (`pod --version`). If not, update with `[sudo] gem install cocoapods`. This is required to link the SDK and bridge, as CocoaPods only added support for XCFrameworks in late 2020. Add the React Native Babel Autocapture Plugin to instrument your app code: In your `babel.config.js` file, add `@contentsquare/react-native-bridge/babel` to the plugins array: **babel.config.js** ```javascript module.exports = { presets: ['module:@react-native/babel-preset'], plugins: ['@contentsquare/react-native-bridge/babel'], }; ``` Make sure to add the plugin to all relevant `babel.config.js` files in your project, including those in any packages that contain React Native code. Autocapture Plugin Note Autocapture's babel plugin depends on the @babel/plugin-transform-react-display-name to include component names in interaction events. This is typically provided by module:metro-react-native-babel-preset, babel-preset-expo, or @react-native/babel-preset. If you aren't including any of these, you should include @babel/plugin-transform-react-display-name alongside @contentsquare/react-native-bridge/babel in your plugins section. Compatibility Notes Autocapture's Babel plugin instruments the built-in React Native components. Instrumentation of similarly named components exported by third-party libraries (for example, `react-native-gesture-handler`'s `Pressable` or `TouchableWithoutFeedback`) is not guaranteed and depends on the library's implementation. As a result, interactions with these components may not be captured automatically. ## Start the SDK 1. Configure and start the SDK with `start()`. * Product Analytics **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")); }, []); ``` Find your environment ID `YOUR_ENVIRONMENT_ID` is either provided to you by Contentsquare or you can find it in **Account** > **Manage** > **Projects** > \[Select your project] > **Environments** within the [Product Analytics web app ↗](https://heapanalytics.com/app/). * CSQ Experience Platform (Early Access) **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")); }, []); ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 2. To capture interactions and screenviews automatically, enable autocapture by setting `enableRNAutocapture` to `true`. Review supported navigation libraries in the [compatibility section](https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/compatibility/#autocapture-navigation-libraries-compatibility). * Product Analytics **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, })); }, []); ``` * CSQ Experience Platform (Early Access) **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true, })); }, []); ``` 3. (Optional) If your Product Analytics environment is hosted in the EU, set the `baseUrl` option to `https://mh.ba.contentsquare.net`. * Product Analytics **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, baseUrl: "https://mh.ba.contentsquare.net", })); }, []); ``` * CSQ Experience Platform (Early Access) **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true, baseUrl: "https://mh.ba.contentsquare.net", })); }, []); ``` 4. Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. ```javascript import React, { useState } from "react"; import { View, Text, Button } from "react-native"; import { CSQ } from "@contentsquare/react-native-bridge"; const PolicyConsentScreen = () => { const [isTrackingAccepted, setIsTrackingAccepted] = useState(false); const handleAcceptPolicy = () => { setIsTrackingAccepted(true); CSQ.optIn(); }; return ( <View> <Text>Please accept our privacy policy to proceed.</Text> <Button title="Accept Policy" onPress={handleAcceptPolicy} /> </View> ); }; export default PolicyConsentScreen; ``` Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more. Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code. 5. Start your application, and check logs for this output: ```text [INFO] CSQ 6.4.2 for Product Analytics is attempting to start. ``` ## Next steps Our SDK offers a wide range of features to enhance your implementation, including extended tracking capabilities, and personal data masking. [Track identity](track-identity/)Link anonymous and identified user data across sessions and devices for comprehensive analytics [Track push notifications](track-push-notifications/)Track mobile notification interactions automatically [Track events manually](track-events-manually/)Learn how to track custom events [Hide sensitive data](privacy-and-sensitive-data/)Protect sensitive data by disabling text capture, masking specific views, or ignoring interactions Session Replay and Error Monitoring are both available with the [Experience Analytics extension](dxae-setup/), which you can purchase separately. [Experience Analytics extension](dxae-setup/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started with Product Analytics","description":"Integrate the CSQ SDK for Product Analytics into your React Native app in minutes","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Adobe Analytics - Flutter (classic) description: Leverage our native integration to use Adobe Analytics segments in Contentsquare lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/flutter/adobe-analytics/ md: https://docs.contentsquare.com/en/flutter/adobe-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). Analyze your data from anywhere in the customer journey using your Adobe Analytics segments. Contentsquare allows you to use your Adobe Analytics segments in every Contentsquare feature (Journey Analysis, Page Comparator, Session Replay). Warning Sessions without at least one screenview will be discarded. You should implement your screen tracking plan first, to have your Adobe Analytics integration work. See [Track screens](../track-screens/). ## Prerequisites 1. Follow the instructions from [Adobe Analytics for mobile apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271665881745) 2. Add the [`flutter_aepedge` package ↗](https://pub.dev/packages/flutter_aepedge) to your project and follow its instructions. ## Code implementation Adobe SDK code requirements On the native Android and iOS parts of your Flutter project, make sure you have followed the instructions of [Usage of `flutter_aepedge` ↗](https://pub.dev/packages/flutter_aepedge#usage). **Why 30 minutes before sending a new csMatchingKey** * 30 minutes is Contentsquare default session duration. * Setting a value **higher** than 30 minutes would cause overlapping on our sessions, and would impact negatively the data import from Adobe. * Setting a value **lower** than 30 minutes would make you to send more data to Adobe. This could cause the variable to reach Adobe's threshold, causing Adobe to filter values, and potentially impact your billing. See [Low-traffic value in Adobe Analytics ↗](https://experienceleague.adobe.com/docs/analytics/technotes/low-traffic.html) Add the following code snippet in your application code. Add a call to the `sendCSMatchingKeyIfNeeded()` from within the `initState` of your application. Listen to `AppLifecycleState` change and call `sendCSMatchingKeyIfNeeded()` when the application resumed. ```dart import 'package:contentsquare/contentsquare.dart'; import 'package:flutter_aepedge/flutter_aepedge.dart'; // ... others imports // TODO: Use your local storage. A package you can use is: https://pub.dev/packages/shared_preferences final localStorage = LocalStorageFake(); @override void initState() { // ... your code sendCSMatchingKeyIfNeeded(); WidgetsBinding.instance.addObserver(this); // ... your code } @override void dispose() { // ... your code WidgetsBinding.instance.removeObserver(this); super.dispose(); // ... your code } @override void didChangeAppLifecycleState(AppLifecycleState state) { super.didChangeAppLifecycleState(state); // Check if the app is in the foreground if (state == AppLifecycleState.resumed) { sendCSMatchingKeyIfNeeded(); } } Future<void> sendCSMatchingKeyIfNeeded() async { // TODO: Implement your local storage. A package you can use is: https://pub.dev/packages/shared_preferences final csMatchingKeyTimestampMap = await localStorage.getMap( 'csMatchingKey_creation_ts', ); final csMatchingKeyIsNotGenerated = csMatchingKeyTimestampMap == null; if (csMatchingKeyIsNotGenerated) { await _submitNewCsMatchingKey(); return; } final timestamp = DateTime.fromMillisecondsSinceEpoch( csMatchingKeyTimestampMap['timestamp'], ); if (DateTime.now().difference(timestamp).inMinutes > 30) { // if the key is not valid anymore, submit a new one await _submitNewCsMatchingKey(); } // if the key is still valid, do nothing } Future<void> _submitNewCsMatchingKey() async { // Generate the matching key and store it in the local storage final millisecondsSinceEpoch = DateTime.now().millisecondsSinceEpoch; final csMatchingKeyValue = '${Random().nextDouble()}_$millisecondsSinceEpoch'; await localStorage.setMap('csMatchingKey_creation_ts', { 'csMatchingKey': csMatchingKeyValue, 'timestamp': millisecondsSinceEpoch, }); // Submit the matching key to Adobe final experienceEvent = ExperienceEvent({ 'xdmData': {'eventType': 'csMatchingKey_state'}, 'data': {'csMatchingKey': csMatchingKeyValue} }); await Edge.sendEvent(experienceEvent); // Submit the matching key to Contentsquare await Contentsquare().sendDynamicVar( 'csMatchingKey', stringValue: csMatchingKeyValue, ); } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Adobe Analytics","description":"Leverage our native integration to use Adobe Analytics segments in Contentsquare","url":"https://docs.contentsquare.com/en/flutter/adobe-analytics/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - Flutter (classic) description: The Contentsquare Flutter SDK changelog lastUpdated: 12 August 2026 source_url: html: https://docs.contentsquare.com/en/flutter/changelog/ md: https://docs.contentsquare.com/en/flutter/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). 📬 Stay updated! ## 4.4.4 - 2026.08.12 * **Improvements:** * Improved zoning analysis and autocapture interaction performance. ## 4.4.3 - 2026.08.6 * **Improvements:** * Improved zoning analysis and autocapture interaction performance. ## 4.4.2 - 2026.07.21 * **Native SDKs:** * iOS: 4.51.0 → 4.51.1 * Re-signed the release artefacts with a new valid certificate to resolve a code-signing validation failure (`CSSMERR_TP_CERT_REVOKED`). No functional changes. ## 4.4.1 - 2026.07.07 * **Bug fix:** * Fixed an error in interaction `autocapture` while keeping events captured correctly. * Improved interaction `autocapture` performance during scroll interactions. * Improved zoning and heatmap stability. ## 4.4.0 - 2026.06.30 * **Added:** * Swift Package Manager (SPM) support for iOS. * **Improvements:** * Session Replay: improved capture of small, frequently-updating custom paint animations. * Extended Flutter version support to include 3.44.4. ## 4.3.1 - 2026.06.25 * **Bug fix:** * Fixed WebView tracking silently failing in apps with multiple Flutter engines. * Fixed WebView tracking not working on iOS scene-based apps. ## 4.3.0 - 2026.06.11 * **Bug fix:** * Fixed Long Snapshot for views containing WebViews on Android. - **Native SDKs:** * Android: 4.50.0 → 4.51.0 * iOS: 4.50.0 → 4.51.0 ## 4.2.2 - 2026.06.05 * **Bug fix** * Repackage obfuscated Android classes to avoid R8 `a.*` collisions with other AARs. ## 4.2.1 - 2026.05.19 * **Bug fix** * Minor bug fixes and improvements. ## 4.2.0 - 2026.05.08 * **Native SDKs:** * Android: 4.44.0 → 4.50.0 * iOS: 4.46.0 → 4.50.0 * **Agent skills:** Contentsquare now provides [Agent skills for Flutter](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/using-agent-skills/) — structured files that let AI coding assistants such as GitHub Copilot, Cursor, and Claude Code integrate, upgrade, and configure the SDK automatically. ## 4.1.3 - 2026.04.27 * **Improvements:** * Session Replay fidelity was improved ## 4.1.2 - 2026.04.24 * **Improvements:** * Session Replay fidelity was improved * Multi-thread issues were fixed * Dialogs tracking was improved ## 4.1.1 - 2026.03.19 * **Improvements:** * Extend Flutter version support to include 3.27.0 and later (previously 3.27.4+). ## 4.1.0 - 2026.02.27 * **Analytics:** * Introduce the Long Snapshot feature to capture and analyze long screens in the app, such as product listing pages or user profiles. * **Native SDKs:** * Android: 4.43.8 → 4.44.0 * iOS: 4.45.3 → 4.46.0 * **🚨 Minimum Flutter version** * Contentsquare plugin now requires Flutter SDK `3.27.4` or later ## 4.0.3 - 2026.02.03 * **Native SDKs:** * Android: 4.43.3 → 4.43.8 ## 4.0.2 - 2026.01.29 * **Bug fix** * Session Replay: Fixed an issue that could cause `BackdropFilter` widgets to appear mispositioned in replays. ## 4.0.1 - 2025.12.11 * **Bug fix** * SessionReplay: Fixed an issue that could cause white screens to appear on iOS. * **Native SDKs:** * iOS: 4.45.1 → 4.45.3 * **Dependencies:** * Updated protobuf dependency in `pubspec.yaml` to `>=2.0.0 <7.0.0` ## 4.0.0 - 2025.12.05 Breaking changes * `ContentsquareRoot` widget has been removed. * `autostart` is removed. From now on to start the SDK, you need to call `Contentsquare.start()`. * `optIn` call is required to start tracking. By default, the SDK will not start tracking until `optIn` is called. * All screenshots should be re-taken to ensure proper zoning functionality. * `ContentsquareWebViewTrackerBuilder` widget has been removed. - **WebView support:** * From now on, to track WebViews, use the `ContentsquareWebViewWrapper` widget as described in the [WebView documentation](https://docs.contentsquare.com/en/flutter/track-webviews/). - **Zoning** * Screenshots and TVP computation were improved to enhance zoning accuracy. - **Native SDKs:** * iOS: 4.43.0 → 4.45.1 * Android: 4.41.0 → 4.43.3 - **🚨 Minimum Flutter version** * Contentsquare plugin now requires Flutter SDK `3.22.4` or later ## 3.19.3 - 2026.01.16 * **Bug fix** * Session Replay: Fixed an issue that could cause `BackdropFilter` widgets to appear mispositioned in replays. ## 3.19.2 - 2025.12.01 * **Native SDKs:** * iOS: 4.43.0 → 4.45.2 ## 3.19.1 - 2025.10.08 * **Bug fix** * SessionReplay: Fixed an Android issue that could affect the positioning of certain elements. ## 3.19.0 - 2025.10.02 * **Analytics:** * Introduce *Heatmap* feature * **Session Replay:** * Added new APIs to start Session Replay on demand * Introduction of Harmonised Masking in Closed Beta Phase * **Native SDKs:** * Android: 4.40.0 → 4.41.0 * **🚨 Minimum Flutter version** * Contentsquare plugin now requires Flutter SDK `3.19.6` or later ## 3.18.0 - 2025.08.07 * **Native SDKs:** * iOS: 4.42.2 → 4.43.0 * Android: 4.39.1 → 4.40.0 * **Session Replay:** * Support [`fl_chart` ↗](https://pub.dev/packages/fl_chart) widgets and masking * Support Image/Text remote masking configuration in the CSQ Console * Added new APIs to support Event-Triggered Replays * **🚨 Minimum Flutter version announcement** * Starting with the next release (`3.19.0`), Contentsquare plugin will require Flutter SDK to be `3.19.0` or later ## 3.17.1 - 2025.06.27 * **Native SDKs:** * iOS: 4.42.0 → 4.42.2 ## 3.17.0 - 2025.06.20 * **Session Replay** * Improve stability on very heavy screens * **🚨 Minimum Flutter and iOS version change** * Contentsquare plugin now requires Flutter SDK `3.16.9` or later * Contentsquare plugin now requires iOS `13.0` or later * **Native SDKs:** * iOS: 4.40.2 → 4.42.0 * Android: 4.36.1 → 4.39.1 ## 3.16.3 - 2025.05.28 * **Bug fix** * Android: Fixed an issue that could affect remote full masking based on the app version. ## 3.16.2 - 2025.03.19 * **Session Replay** * Support all `ExcludeSemantics` widgets * Support `IgnorePointer` and `AbsorbPointer` widgets ## 3.16.1 - 2025.03.13 * **Bug fix:** * Fix an Android bug where API changed in Android 15 crash with `java.lang.NoSuchMethodError` from `java.util.List`. * **Native SDK update** * Android: 4.36.0 → 4.36.1 ## 3.16.0 - 2025.02.21 * **Session Replay** * Support full remote masking configuration by APP/SDK versions through the CSQ Console * Support Session Replay gestures in the player's event stream * [Add the ability to mask `CustomPaint`](https://docs.contentsquare.com/en/flutter/session-replay/#masking-mechanisms) * Android Webviews in Session Replay have now the expected sizes * **Screenshot** * Fix a crash that could occur when taking a screenshot on Android * **API** * `Contentsquare.start` and `ContentsquareNavigatorObserver` are now officially supported. The `@experimental` annotation has been removed. * **🚨 Minimum Flutter version announcement** * Starting with the next release (`3.17.0`), Contentsquare plugin will require iOS version to be `13.0` or later * Starting with the next release (`3.17.0`), Contentsquare plugin will require Flutter SDK to be `3.16.9` or later * **Native SDK update** * iOS: 4.38.2 → 4.40.2 * Android: 4.34.0 → 4.36.0 ## 3.15.3 - 2025.02.04 * **Bug fix:** * Fixed a bug, where an improperly tracked tap could create an exception. ## 3.15.2 - 2025.01.22 * **Bug fix:** * Fixed a bug, when unable to zone bottom bar * Fixed a bug on iOS, when the webview zones become displaced when screenshot is scrolled * Fixed a bug, when bottom dialog shows up after the language changes ## 3.15.1 - 2024.12.11 * **Zoning** * Fixed a bug where ReliableTargets could be not properly tracked in some cases, when multiple lists containing a Reliable Target in the same index, are switched in the same area of the screen. ## 3.15.0 - 2024.12.04 * **🚨 Minimum Flutter version announcement** * Starting with the next release (`3.16.0`), Contentsquare plugin will require Flutter SDK `3.13.9` or later * **Experience Analytics** * Introduce collection of Flutter errors feature * **Session Replay** * Support Text widgets when they are wrapped with `Semantics` or contain `semanticsLabel` * Improve performance and stability * Support `Opacity` widget * Fix a bug in `onSessionReplayLinkChange` for android where the link is not updated after the app returns from background * **Other** * Resolve an issue that could prevent building obfuscated Android applications with Android Gradle Plugin (AGP) versions 8.4.0 and later Warning Versions of the SDK earlier than 3.15.0 do not support AGP versions 8.4.0 and later. To ensure compatibility with AGP >= 8.4.0 , upgrade to Contentsquare Flutter SDK version 3.15.0 or later. * **Native SDK update** * iOS: 4.37.2 → 4.38.2 * Android: 4.33.2 → 4.34.0 ## 3.14.159 - 2024.11.05 * **WebView support:** * Improve support for WebViews * **Logging:** * Fix an issue where warning logs were incorrectly displayed as error logs * **Dependencies:** * Updated protobuf dependency in `pubspec.yaml` to `>=2.0.0 <4.0.0` ## 3.14.1 - 2024.10.22 * **Privacy** * Fix a bug occurring to `resumeTracking` when `CSInApp` is enabled * **Native SDKs:** * Android: 4.33.1 → 4.33.2 ## 3.14.0 - 2024.10.17 * **API** * Adds `ContentsquareNavigatorObserver` to automatically track screen changes (as an [experimental](https://docs.contentsquare.com/en/flutter/experimental/) feature) * Adds `start` method to manually start the SDK (as an [experimental](https://docs.contentsquare.com/en/flutter/experimental/) feature) * **Session Replay:** * Adds more fidelity in replays * Texts and icons have now high fidelity * Font uploading is no longer needed for android and iOS * **🚨 Minimum Flutter version change** * Contentsquare plugin now requires Flutter SDK `3.10.6` or later * **Native SDKs:** * iOS: 4.36.0 → 4.37.2 * Android: 4.32.1 → 4.33.1 ## 3.13.1 - 2024.09.24 * **🚨 Minimum Flutter version announcement** * Starting with the next release (`3.14`), Contentsquare plugin will requires Flutter SDK `3.10.1` or later * **Analytics:** * Fix an issue occurring on iOS Zoning screenshot when a custom root `ViewController` is used * **Session Replay:** * Fix an issue occurring in Session Replay when a `CustomPainter` animation is disposed * **Native SDKs:** * iOS: 4.36.0 → 4.36.1 ## 3.13.0 - 2024.09.13 * **WebViews** * Improved webViews tracking with the new widget `ContentsquareWebViewWrapper` * **Native SDKs:** * iOS: 4.35.0 → 4.36.0 * Android: 4.31.0 → 4.32.1 ## 3.12.0 - 2024.08.14 * **Session Replay:** * Support dynamic `QualityLevels` in the `SessionReplay` (low, medium, and high) * Improve `SessionReplay` performance * Fidelity improvements * Support `CustomPaint` * Support borders * Support checkboxes, radio buttons, and switches * Support SVG images (for `flutter_svg` package) * Additional support for `Decorations` * Fixed error that occurs when `RichText` is masked * **Native SDKs:** * iOS: 4.33.1 → 4.35.0 * Android: 4.29.1 → 4.31.0 ## 3.11.1 - 2024.06.18 * **Native SDKs:** * iOS: 4.33.0 → 4.33.1 * Android: 4.29.0 → 4.29.1 ## 3.11.0 - 2024.06.11 * **Session Replay:** * Improve fidelity * Support images and gradient colors in `ShapeDecoration` * **ApiErrors:** * Introduce a `gentle` HttpOverride * Fix a bug with tracking requests in `dio` package * **Native SDKs:** * iOS: 4.32.0 → 4.33.0 * Android: 4.28.0 → 4.29.0 ## 3.10.0 - 2024.04.29 * **Session Replay:** * Added support for `WidgetSpan` * **Native SDKs:** * iOS: 4.31.2 → 4.32.0 * Android: 4.27.1 → 4.28.0 * **🚨 Minimum Flutter version change** * Contentsquare plugin now requires Flutter SDK 3.3.10 or later. ## 3.9.0 - 2024.04.02 * **Session Replay:** * Add public API: `onSessionReplayLinkChange` to listen to Session Replay URL changes during app lifecycle * Deprecate public API: `currentSessionReplayUrl` * Performance improvement in Android Session Replay * Partially support gradient colors in Session Replay as solid color * Fix a bug happening when CS in-app is opened while Session Replay is running, on Android * Fix a minor bug displaying a warning as an error during Session Replay * **Platform support:** * Contentsquare SDK is now completely disabled on unsupported platforms (Desktop and Web) and non mobile apps can now be built safely. * **Native SDKs:** * iOS: 4.30.2 → 4.31.2 * Android: 4.26.0 → 4.27.1 ## 3.8.0 - 2024.03.04 * **API:** * `forgetMe` has been deprecated * **Session Replay:** * Fix a bug that could occur when using the `span` widget * Fix a bug that stops the Session Replay when translation animation is set to infinity, that could happen if BottomNavigationBar's selectedFontSize is set to 0 * **Analytics:** * Fix an issue in webviews using the tracking tag that impacted the launch of Analytics * **Screenshot:** * Fixed a bug that could lead to a restart of the app state during the usage of CS in-app tool * **Native SDKs:** * iOS: 4.29.1 → 4.30.2 * Android: 4.24.1 → 4.26.0 * ⚠️ `compileSdkVersion` requirement has fallen back to `33` * Added support to use ProGuard for minification and shrinking ## 3.7.0 - 2024.01.26 * **Screenshots:** * A bug provoking state restart while taking screenshots from CS in-app is fixed * A bug provoking state restart of ContentsquareRoot when displaying CS in-app is fixed * **[Session Replay](https://docs.contentsquare.com/en/flutter/session-replay/#configure-webviews)** * Fix an issue on Android Session Replays * Support of webviews was added to the Session Replay for both Android and iOS platforms (check the documentation for additional implementation steps) * From now on, the masking configuration can be changed dynamically during the Session Replay on the Flutter elements * **Native SDKs:** * iOS: 4.27.0 → 4.29.1 * Android: 4.23.1 → 4.24.1 * ⚠️ `compileSdkVersion` should be bumped to `34` Version 3.6.0 retraction Version 3.6.0 of the Contentsquare Flutter plugin has been identified to contain a deployment issue for iOS. As a result, this version has been retracted and is no longer available for use. Upgrade to the [latest version](https://docs.contentsquare.com/en/flutter/). ## 3.5.1 - 2023.12.20 * **\[🚨 Maximum Flutter version]** * Add support of the latest Flutter version (3.16 and later) ## 3.5.0 - 2023.12.01 * **[API Errors:](https://docs.contentsquare.com/en/flutter/error-analysis/)** * Support of the `API Errors` feature has been added to Android platform * **[Session Replay](https://docs.contentsquare.com/en/flutter/session-replay/)** * Support of the `Session Replay` feature has been added to Android platform * **[Reliable Targets](https://docs.contentsquare.com/en/flutter/reliable-targets/)** * Support of the `Reliable Targets` feature has been added to both Android and iOS platforms * **[User Identifier](https://docs.contentsquare.com/en/flutter/session-replay/#send-user-identifier)** * Support of the `User Identifier` feature has been added to both Android and iOS platforms * **Native SDKs:** * Android: 4.21.0 → 4.23.1 * iOS: 4.25.0 → 4.27.0 * **\[🚨 Maximum Flutter version]** * Supports Flutter up to `3.13.9`. * Support of the Flutter version 3.16 and later is added back in the plugin `3.5.1`. Update the plugin if you are using Flutter 3.16 or later. ## 3.4.0 - 2023.09.14 * **Custom Variables:** * Support of the `Custom Variables` feature has been added to Android * **[API Errors:](https://docs.contentsquare.com/en/flutter/error-analysis/)** * Support of the `API Errors` feature has been added to iOS * **[Session Replay](https://docs.contentsquare.com/en/flutter/session-replay/)** * Minor fidelity improvements * **Native SDKs:** * Android: 4.20.0 → 4.21.0 * iOS: 4.24.0 → 4.25.0 * **\[🚨 Maximum Flutter version]** * Supports Flutter up to `3.13.9`. * Support of the Flutter version 3.16 and later is added back in the plugin `3.5.1`. Update the plugin if you are using Flutter 3.16 or later. ## 3.3.0 - 2023.08.01 * **Native SDKs:** * Android: 4.19.0 → 4.20.0 * iOS: 4.23.0 → 4.24.0 * **[Session Replay](https://docs.contentsquare.com/en/flutter/session-replay)** * Minor fidelity improvements * **Custom Variables:** * Support of the Custom Variables feature has been added to iOS * **API Errors:** * Added a log when API Errors collection is enabled or disabled in iOS (for future usage) * **\[🚨 Maximum Flutter version]** * Supports Flutter up to `3.13.9`. * Support of the Flutter version 3.16 and later is added back in the plugin `3.5.1`. Update the plugin if you are using Flutter 3.16 or later. ## 3.2.1 - 2023.07.04 * **Bug fix:** * Fixed an issue on Android, causing a crash during the initialization of the SDK. Bug was introduced since the release of 3.1.0 * **\[🚨 Maximum Flutter version]** * Supports Flutter up to `3.13.9`. * Support of the Flutter version 3.16 and later is added back in the plugin `3.5.1`. Update the plugin if you are using Flutter 3.16 or later. ## 3.2.0 - 2023.06.30 * **Bug fix:** Fix critical bug for clients who use Flutter < 3.0 introduced in the CS SDK release 3.1.0 * **API**: * New method getter `currentSessionReplayUrl` (iOS Only) * [Session Replay](https://docs.contentsquare.com/en/flutter/session-replay/) fidelity improvements: * Shadows * Clipping * Radius * Transparency * Blur * **\[🚨 Maximum Flutter version]** * Supports Flutter up to `3.13.9`. * Support of the Flutter version 3.16 and later is added back in the plugin `3.5.1`. Update the plugin if you are using Flutter 3.16 or later. ## 3.1.0 - 2023.06.20 * **Native SDKs:** * Android: 4.18.1 → 4.19.0 * iOS: 4.22.1 → 4.23.0 * [Session Replay](https://docs.contentsquare.com/en/flutter/session-replay/) improvements: * Added icons support * Performance improvement for unmasked images * **\[🚨 Maximum Flutter version]** * Supports Flutter up to `3.13.9`. * Support of the Flutter version 3.16 and later is added back in the plugin `3.5.1`. Update the plugin if you are using Flutter 3.16 or later. ## 3.0.0 - 2023.05.17 Breaking change Remove support for `sendTouchEvent`. * **Native SDKs:** * Android: 4.17.0 → 4.18.1 * iOS: 4.21.0 → 4.22.1 * [Session Replay](https://docs.contentsquare.com/en/flutter/session-replay/) feature is available for iOS only. For more information, reach out to your Contentsquare contact. * **\[🚨 Maximum Flutter version]** * Supports Flutter up to `3.13.9`. * Support of the Flutter version 3.16 and later is added back in the plugin `3.5.1`. Update the plugin if you are using Flutter 3.16 or later. ## 2.3.0 - 2023.04.13 * **Native SDKs:** * Android: 4.16.0 → 4.17.0 * iOS: 4.20.0 → 4.21.0 ## 2.2.0 - 2023.03.09 * **Native SDKs:** * Android: 4.15.0 → 4.16.0 ## 2.1.0 - 2023.03.02 * **Native SDKs:** * iOS: 4.18.0 → 4.20.0 ## 2.0.1 - 2023.02.28 * **Bug fix:** Track Transactions now supports any value while it would previously fail if the given transaction value contained decimals. ## 2.0.0 - 2023.01.30 Breaking change First party support for `webview_flutter` plugin has been removed for now. Use the generic webview tracking API in the meantime. See [the updated documentation](https://docs.contentsquare.com/en/flutter/track-webviews/#examples) for concrete implementation examples. * **WebView Tracking:** * **\[🚨 Breaking Change 🚨] Feature:** You can now use the SDK with any version of the `webview_flutter` plugin. However to do so we had to remove the first party support for this plugin. You can still use the generic webview tracking API. See [the updated documentation](https://docs.contentsquare.com/en/flutter/track-webviews/#examples) for concrete implementation examples. * **\[🚨 Breaking Change 🚨] Refactoring:** `JavascriptChannel` has been renamed to `ContentsquareJavascriptChannel` to avoid naming conflicts with other plugins. * **Refactoring:** `tracker.initializeWebViewTracking` has been renamed to `tracker.startPageTracking`. Using `tracker.initializeWebViewTracking` is deprecated and will be removed in a future release. ## 1.3.2 - 2022.12.23 Data Breaking change Screenshots for Android apps are not compatible with the previous versions and need to be retaken. * **Native SDKs:** * Android: 4.14.0 → 4.15.0 * iOS: 4.17.0 → 4.18.0 * **Fix:** Bump the lowest supported Dart SDK version from 2.12.0 to 2.15.0 ## 1.3.1 - 2022.12.22 - Deprecated Deprecation notice This version is deprecated because it introduces an incompatibility between the screenshots API and the touch events API, which breaks the zoning analysis feature. ## 1.3.0 - 2022.11.24 * **Native SDKs:** * Android: 4.13.1 → 4.14.0 * iOS: 4.13.0 → 4.17.0 ## 1.2.0 - 2022.11.14 * **Screenshots:** Beta third-party WebView tracking support (see [flutter\_inappwebview ↗](https://pub.dev/packages/flutter_inappwebview)) ## 1.1.0 - 2022.11.07 * **Screenshots:** Beta WebView tracking support (only for the [official WebView plugin ↗](https://pub.dev/packages/webview_flutter)) ## 1.0.1 - 2022.10.31 * **Fix:** Update dependency of `contentsquare` on `contentsquare_plugin_interface` ## 1.0.0 - 2022.10.24 - Deprecated ⚠️ This version is deprecated due to bad dependency which prevents the plugin from compiling. Use the latest version of the plugin instead. * **License:** License update ## 0.5.3 - 2022.07.13 * **Bug fix:** Fixed an issue on Android, where CS in-app features menu caused a crash while using the opt-out and opt-in operations * **Native SDKs:** Android 4.11.0 ## 0.5.2 - 2022.07.04 * **Error when building in profile mode:** Bump `compileSdkVersion` to 31 to support Gradle version >= `4.2.0` ## 0.5.1 - 2022.05.30 * **Screenshots:** * Stability improvement for `Navigator` pushed screens ## 0.5.0 - 2022.05.12 * **Screenshots:** * Fix issue on generating accurate targets for gestures * Only include widgets which are currently visible * **Native SDKs:** Android 4.9.0 and iOS 4.13.0 ## 0.4.2 - 2022.04.14 * **Screenshots:** Fixed an issue where screenshot captured was not rendering the right screen. * **Gesture tracking:** Fixed an issue on our gesture detector that could cause an exception to be thrown in edge cases. * **Native SDKs:** Android 4.8.0 and iOS 4.12.0 ## 0.4.1 - 2022.03.25 * **Screenshots:** Fixed screenshot capture infinite loading on Android caused by WebView; fixed screenshot capture infinite loading on iOS caused by conflict with `background_locator` plugin; fixed visual bug with the app bar; fixed empty screenshot on iOS related to autostart disabled. * **Native SDKs:** Android 4.8.0 and iOS 4.11.0 ## 0.4.0 - 2022.03.01 * **Crash at app launch on Android:** Fixed a bug introduced crashing the app on Android, at app start. ## 0.3.0 - 2022.02.18 * **Gesture tracking:** Gesture tracking optimization; fixed issue preventing scrolling in WebView; * **Screenshots:** Size Optimization. * **Native SDKs:** Android 4.7.0 and iOS 4.11.0 ## 0.2.3 - 2022.02.07 * **Native SDKs:** Android 4.7.0 and iOS 4.10.1 ## 0.2.2 - 2022.01.13 * **Gesture tracking:** Fixed performance issue related to gesture tracking * **Screenshots:** Support screenshot capture on iOS * **Native SDKs:** Android 4.3.0 and iOS 4.10.0 ## 0.2.1 - 2022.12.17 * **Gesture tracking:** Now support gesture tracking accurately. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare Flutter SDK changelog","url":"https://docs.contentsquare.com/en/flutter/changelog/","inLanguage":"en","dateModified":"2026-08-12T11:32:18+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - Flutter (classic) description: Requirements and limitations to develop with the Flutter SDK lastUpdated: 12 August 2026 source_url: html: https://docs.contentsquare.com/en/flutter/compatibility/ md: https://docs.contentsquare.com/en/flutter/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). Before implementing the SDK, make sure your app meets the following technical prerequisites to avoid integration issues and ensure optimal performance. ## Supported platforms Only Flutter application on the following platforms are supported by the `Contentsquare Flutter SDK`: * Android * iOS Calling the SDK on other platforms is safe but will not have any effect. If you need to use the SDK on another platform, contact our support team. Hybrid applications are not supported. By hybrid application, we mean iOS and Android apps that integrate Flutter as an [add-to-app module ↗](https://docs.flutter.dev/add-to-app) ## Compatibility matrix Each version of the Contentsquare Flutter SDK will be linked to specific, fixed versions of each native SDK. to make that clear, here is a compatibility table to consider when choosing your version of the bridge (refer to the Flutter SDK Changelog to know what the changes are for each version). Note If the Maximum Flutter Version is not specified, it means that the bridge is compatible with all versions of Flutter up to the latest one. Warning Versions of the SDK earlier than 3.15.0 do not support Android Gradle Plugin versions 8.4.0 and later. To ensure compatibility with AGP >= 8.4.0 , upgrade to Contentsquare Flutter SDK version 3.15.0 or later. | Contentsquare Flutter SDK Version | iOS SDK Version | Android SDK Version | Minimum Flutter Version | Maximum Flutter Version | | - | - | - | - | - | | 4.4.4 | 4.51.1 | 4.51.0 | 3.27.0 | - | | 4.4.3 | 4.51.1 | 4.51.0 | 3.27.0 | - | | 4.4.2 | 4.51.1 | 4.51.0 | 3.27.0 | - | | 4.4.1 | 4.51.0 | 4.51.0 | 3.27.0 | - | | 4.4.0 | 4.51.0 | 4.51.0 | 3.27.0 | - | | 4.3.1 | 4.51.0 | 4.51.0 | 3.27.0 | - | | 4.3.0 | 4.51.0 | 4.51.0 | 3.27.0 | - | | 4.2.2 | 4.50.0 | 4.50.0 | 3.27.0 | - | | 4.2.1 | 4.50.0 | 4.50.0 | 3.27.0 | - | | 4.2.0 | 4.50.0 | 4.50.0 | 3.27.0 | - | | 4.1.3 | 4.46.0 | 4.44.0 | 3.27.0 | - | | 4.1.2 | 4.46.0 | 4.44.0 | 3.27.0 | - | | 4.1.1 | 4.46.0 | 4.44.0 | 3.27.0 | - | | 4.1.0 | 4.46.0 | 4.44.0 | 3.27.4 | - | | 4.0.3 | 4.45.3 | 4.43.8 | 3.22.4 | - | | 4.0.2 | 4.45.3 | 4.43.3 | 3.22.4 | - | | 4.0.1 | 4.45.3 | 4.43.3 | 3.22.4 | - | | 4.0.0 | 4.45.1 | 4.43.3 | 3.22.4 | - | | 3.19.3 | 4.45.2 | 4.41.0 | 3.19.6 | - | | 3.19.2 | 4.45.2 | 4.41.0 | 3.19.6 | - | | 3.19.1 | 4.43.0 | 4.41.0 | 3.19.6 | - | | 3.19.0 | 4.43.0 | 4.41.0 | 3.19.6 | - | | 3.18.0 | 4.43.0 | 4.40.0 | 3.16.9 | - | | 3.17.1 | 4.42.2 | 4.39.1 | 3.16.9 | - | | 3.17.0 | 4.42.0 | 4.39.1 | 3.16.9 | - | | 3.16.3 | 4.40.2 | 4.36.1 | 3.13.9 | - | | 3.16.2 | 4.40.2 | 4.36.1 | 3.13.9 | - | | 3.15.3 | 4.38.2 | 4.34.0 | 3.10.6 | - | | 3.14.159 | 4.37.2 | 4.33.2 | 3.10.6 | - | | 3.13.1 | 4.36.1 | 4.32.1 | 3.3.10 | - | | 3.12.0 | 4.35.0 | 4.31.0 | 3.3.10 | - | | 3.11.1 | 4.33.1 | 4.29.1 | 3.3.10 | - | | 3.10.0 | 4.32.0 | 4.28.0 | 3.3.10 | - | | 3.9.0 | 4.31.2 | 4.27.1 | 2.8.0 | - | | 3.8.0 | 4.30.2 | 4.26.0 | 2.8.0 | - | | 3.7.0 | 4.29.1 | 4.24.1 | 2.8.0 | - | | 3.6.0 (deprecated) | 4.28.0 | 4.24.1 | 2.8.0 | - | | 3.5.1 | 4.27.0 | 4.23.1 | 2.8.0 | - | | 3.4.0 | 4.25.0 | 4.21.0 | 2.8.0 | 3.13.9 | | 3.3.0 | 4.24.0 | 4.20.0 | 2.8.0 | 3.13.9 | | 3.2.0 | 4.23.0 | 4.19.0 | 2.8.0 | 3.13.9 | | 3.1.0 | 4.23.0 | 4.19.0 | 2.8.0 | 3.13.9 | | 3.0.0 | 4.22.1 | 4.18.1 | 2.8.0 | 3.13.9 | | 2.3.0 | 4.21.0 | 4.17.0 | 2.8.0 | - | | 2.2.0 | 4.20.0 | 4.16.0 | 2.8.0 | - | | 1.3.2 | 4.18.0 | 4.15.0 | 2.8.0 | - | | 1.2.0 | 4.13.0 | 4.13.1 | 2.8.0 | - | | 1.1.0 | 4.13.0 | 4.13.1 | 2.8.0 | - | | 1.0.1 | 4.13.0 | 4.13.1 | 2.0.0 | - | | 0.5.3 | 4.13.0 | 4.11.0 | 2.0.0 | - | | 0.4.2 | 4.12.0 | 4.8.0 | 2.0.0 | - | | 0.3.0 | 4.11.0 | 4.7.0 | 2.0.0 | - | | 0.2.3 | 4.10.1 | 4.7.0 | 2.0.0 | - | | 0.1.0 | 4.3.0 | 4.1.0 | 2.0.0 | - | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Flutter SDK","url":"https://docs.contentsquare.com/en/flutter/compatibility/","inLanguage":"en","dateModified":"2026-08-12T11:32:18+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Contentsquare CLI - Flutter (classic) description: How to use the Contentsquare CLI plugin lastUpdated: 07 August 2026 source_url: html: https://docs.contentsquare.com/en/flutter/contentsquare-cli/ md: https://docs.contentsquare.com/en/flutter/contentsquare-cli/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). A Dart plugin that offers a command-line interface for users of the Contentsquare package. ## Installation Add `contentsquare_cli` as a **dev dependency**. ```shell flutter pub add -d contentsquare_cli ``` **pubspec.yaml** ```yaml dev_dependencies: contentsquare_cli: ^1.1.0 ``` then run ```shell dart run contentsquare_cli ``` ## Usage ### upload-debug-files command This command enables you to upload debug files generated by the `flutter build` command to Contentsquare. This allows you to read the [Flutter errors](https://docs.contentsquare.com/en/flutter/error-analysis/#error-reporter) generated in an [obfuscated or de-symbolized](https://docs.contentsquare.com/en/flutter/error-analysis/#symbolization-and-de-obfuscation) app. #### Configuration To use the command, provide the following identification elements. These can be passed directly as arguments each time you run the command or set up in a configuration file within your project for a more streamlined command usage. The required information includes: * **The targeted platform** `ios` or `android`, corresponding to the `flutter build` command. * **The project ID** 1. Login to the Contentsquare platform on [https://app.contentsquare.com ↗](https://app.contentsquare.com) 2. Make sure to be on the right project 3. The project ID can be found in the URL query parameter `project`: `https://app.contentsquare.com/#/{MODULE_NAME}?project={PROJECT_ID}&hash={HASH}]` * **Valid API credentials** Follow the dedicated documentation from the Help Center to get the client ID and client Secret: [How to create API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593). * **The debug info directory** Provided to the `--split-debug-info` option during build command * **The obfuscation map path (optional)** If you use the `--obfuscate` option during the build process, you can specify the path for the obfuscation map by adding the build option `--extra-gen-snapshot-options=--save-obfuscation-map=[YOUR DESIRED FILE PATH]`. ##### Using the YAML configuration file You can supply this information by adding a `contentsquare_cli.yaml` file to the root of your project. **contentsquare\_cli.yaml** ```yaml contentsquare_cli: android: client_id: "[ANDROID CLIENT ID]" client_secret: "[ANDROID CLIENT SECRET]" project_id: "[ANDROID PROJECT ID]" debug_info_dir: "[PATH PROVIDED TO THE --split-debug-info option]" obfuscation_mapping_file: "[PATH TO THE OBFUSCATION MAP]" ios: client_id: "[IOS CLIENT ID]" client_secret: "[IOS CLIENT SECRET]" project_id: "[IOS PROJECT ID]" debug_info_dir: "[PATH PROVIDED TO THE --split-debug-info option]" obfuscation_mapping_file: "[PATH TO THE OBFUSCATION MAP]" ``` ##### Using the command line arguments Alternatively, this information can be provided directly as arguments on the command line. | Option | Description | | - | - | | --platform | The target platform for which the debug files are uploaded | | --client-id | The client ID of [API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593) | | --client-secret | The client SECRET of [API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593) | | --project-id | The Contentsquare project ID | | --debug-info-dir | The path from `--split-debug-info` option | | --obfuscation-mapping-file | The generated obfuscation map path | Note Use `--help` option for further information Tip You can combine these two approaches: for example, use the YAML file to store paths and the project ID, while providing the client identifier and secret as command-line arguments. #### Examples Let's take the case of debug files generated by this `flutter build` command: ```shell flutter build apk --release --split-debug-info=myDebugInfoDir --obfuscate --extra-gen-snapshot-options=--save-obfuscation-map=app.android.map.json ``` Using this configuration file: **contentsquare\_cli.yaml** ```yaml contentsquare_cli: android: client_id: "my-client-id-android" client_secret: "myClientSecretAndroid" project_id: "00000" debug_info_dir: "myDebugInfoDir" obfuscation_mapping_file: "app.android.map.json" ios: client_id: "my-client-id-ios" client_secret: "myClientSecretIos" project_id: "00001" debug_info_dir: "myDebugInfoDir" obfuscation_mapping_file: "app.ios.map.json" ``` You can invoke the upload-debug-files command as follows: ```shell dart run contentsquare_cli upload-debug-files --platform=android ``` If you prefer using the command line only: ```shell dart run contentsquare_cli upload-debug-files --platform=android --client-id=my-client-id-android --client-secret="myClientSecretAndroid" --project-id=00000 --debug-info-dir=./myDebugInfoDir --obfuscation-mapping-file=./app.android.map.json ``` Note For automatic execution, integrate this command in a release script or in a CI/CD pipeline. ## Changelog ### 1.1.0 - 2026.08.06 * Update dependencies ### 1.0.1 - 2024.12.10 * Update package metadata ### 1.0.0 - 2024.11.05 * Introduce the `upload-debug-files` command ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Contentsquare CLI","description":"How to use the Contentsquare CLI plugin","url":"https://docs.contentsquare.com/en/flutter/contentsquare-cli/","inLanguage":"en","dateModified":"2026-08-07T10:21:42+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Error Analysis - Flutter (classic) description: How to use Contentsquare Error Analysis in your Flutter apps lastUpdated: 15 May 2026 source_url: html: https://docs.contentsquare.com/en/flutter/error-analysis/ md: https://docs.contentsquare.com/en/flutter/error-analysis/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). Error Analysis automatically captures API errors and network failures in your Flutter app and surfaces them in the Contentsquare platform. ## Prerequisites ### Contentsquare SDK is included You must include the [Contentsquare SDK](https://docs.contentsquare.com/en/flutter/) first using the same integration method and understand [how the SDK works](https://docs.contentsquare.com/en/flutter/how-the-sdk-works/). ### Updating to latest SDK version To enable Error Analysis in your application and ensure optimal stability, make sure to always use the last SDK version. ### Screen tracking implemented Tracking will start at the 1st screenview event, it is required to have screen tracking implemented. Make sure to follow the [Flutter Track screens](https://docs.contentsquare.com/en/flutter/track-screens/) sections. ### Reminder about User consent If you are in the process of implementing the SDK for the 1st time, or if you choose to take this update as an opportunity to review your privacy-related implementation, ensure that you follow the [Flutter Privacy](https://docs.contentsquare.com/en/flutter/privacy/) section and use the [Opt-in API](https://docs.contentsquare.com/en/flutter/privacy/#opt-in) to get the user consent, otherwise no data will be collected. ## Get Started ### Start the SDK You do not need to do anything to start the Error Analysis SDK, it will start itself with Contentsquare SDK. ### Validate SDK integration When the SDK starts, you should see a log like this one: ```plaintext // success case CSLIB ℹ️ Info: Contentsquare Error Analysis [SDKVersionNumber] starting in app : [your.app.packageName] // fail case // << No public fail log ``` ## API Errors ### Automatic network inspection API Errors automatically collects failed network requests. ### Removing Personal Data in request URL path By default, the API Errors feature collects the URL path of the failed API requests. To prevent the collection of Personal Data in the URL path, you can rewrite the request URL path with the `Contentsquare.setURLMaskingPatterns` SDK API. Replace a step of the path - meaning between two slashes (/) - containing Personal Data with a variable: * `:user_id` becomes CS\_ANONYMIZED\_USER\_ID * `:address` becomes CS\_ANONYMIZED\_ADDRESS #### Example ```dart import 'package:contentsquare/contentsquare.dart'; Contentsquare.setURLMaskingPatterns(patterns: [ 'https://www.contentsquare.com/users/:user_id/address/:address', ]); ``` ##### Result | URL before masking | URL after masking | | - | - | | `https://www.contentsquare.com/users/123/address/castle+black` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS` | | `https://www.contentsquare.com/users/123/address/castle+black/reset-token/abcdef123456` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS/reset-token/abcdef123456` | ### Debugging and Logging If in-app features are enabled, a info log should appear with the details of the event (see [Flutter Debugging and Logging](https://docs.contentsquare.com/en/flutter/in-app-features/#debugging-and-logging) section): ```plaintext CSLIB ℹ️ Info: API Error - GET 401 https://api.client.com ``` ### How API Errors works #### Initialization Our SDK automatically starts upon application launch and seamlessly captures failed network requests. #### Configuration Once started, our SDK fetches its config from our servers. It will start collecting data from network events if the API Errors setting is enabled in the config (this is handled by the Contentsquare team). #### Tracking The SDK monitors only API Errors with a 4xx or 5xx response code, and generates analytics data. These events are then locally stored, and eventually sent to our servers in batches. Warning To ensure that API Errors occurring at app launch are accurately tracked, ensure the session is being tracked (the user is included in tracked users and has not opted out), and a first screenview event has been sent. Warning During the initialization, the Contentsquare SDK overrides the `HttpOverrides.global` property. If you have to override `HttpOverrides.global` in your app - [use a custom HttpOverrides](https://docs.contentsquare.com/en/flutter/error-analysis/#use-a-custom-httpoverrides). #### Sending data For each network error, a new event will be sent in Analytics and Session Replay data. Check the following sections to learn more about how data is processed and sent: * [Analytics requests](https://docs.contentsquare.com/en/flutter/how-the-sdk-works/#sending-data) * [Session Replay requests](https://docs.contentsquare.com/en/flutter/session-replay/#requests) ### API Troubleshooting Details API Errors troubleshooting details feature enhances your ability to collect additional information about API errors, facilitating faster troubleshooting. With this feature, you can view three types of additional API error details in the Event Stream of Session Replay: * The HTTP headers of the request and the response. * The body (the data sent by the request or received in the response). * The query parameters of the request endpoint (of the URL of the information you request for). Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. See [API Troubleshooting Details ↗](https://support.contentsquare.com/hc/en-us/articles/37271885035537) for more details. ### Collected data points Only network calls in error (4xx or 5xx response codes) will be collected. Here is the exhaustive list of data collected: * URL (without query strings) * HTTP method * Response code * Timestamp of the request * Timestamp of the response * HTTP headers of the request * HTTP headers of the response * HTTP body of the request * HTTP body of the response * Query parameters ### Known limitations and recommendations #### Conflict with Firebase Performance Monitoring ##### Android Contentsquare Error Analysis is not compatible with Firebase Performance Monitoring auto-collection. Only one of the two will log events, and usually, the events will be automatically logged by the Contentsquare Error Analysis. To log events to Firebase Performance Monitoring, we suggest [logging it manually ↗](https://rnfirebase.io/perf/usage#http-request-tracing). ##### iOS Contentsquare Error Analysis is compatible with Firebase Performance auto-collection, but the HTTP body from the response won't be collected by the Error Analysis SDK. Contentsquare Error Analysis may not be compatible with other network auto-collection tools. ### Use a custom HttpOverrides Use `ContentsquareHttpOverrides` if you need to override the global `HttpOverrides`. ```dart import 'dart:io'; import 'package:contentsquare/contentsquare.dart' show ContentsquareHttpOverrides; class YourCustomHttpOverrides extends HttpOverrides { @override HttpClient createHttpClient(SecurityContext? context) { return super.createHttpClient(context); } } void main() { HttpOverrides.global = ContentsquareHttpOverrides( httpOverrides: YourCustomHttpOverrides(), ); } ``` Note Your custom `HttpOverrides` will function as expected under the normal conditions. The `ContentsquareHttpOverrides` will operate exclusively as a proxy. Note If during the initialization it is observed that another `HttpOverrides` is being used globally and it is not `ContentsquareHttpOverrides`, it will be automatically replaced with `ContentsquareHttpOverrides`, as illustrated in the example. ## Error Reporter ### Handle the Flutter errors You can collect unhandled errors from the framework by using the [FlutterError.onError ↗](https://api.flutter.dev/flutter/foundation/FlutterError/onError.html) callback. However, errors that occur outside of Flutter's callbacks, such as asynchronous errors, will not be captured. To handle these, consider implementing the [PlatformDispatcher.onError ↗](https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/onError.html) or [runZonedGuarded ↗](https://api.flutter.dev/flutter/dart-async/runZonedGuarded.html) callbacks. #### Example * Using PlatformDispatcher.onError ```dart void main() async { WidgetsFlutterBinding.ensureInitialized(); FlutterError.onError = (FlutterErrorDetails details) { // Collects Flutter errors Contentsquare().collectFlutterError(details: details); }; WidgetsBinding.instance.platformDispatcher.onError = (exception, stackTrace) { // Collects all unhandled errors from the root isolate, including platform-level errors Contentsquare().collectError(error: exception, stackTrace: stackTrace); return false; }; runApp(MyApp()); } ``` * Using runZonedGuarded ```dart void main() async { runZonedGuarded(() { FlutterError.onError = (FlutterErrorDetails details) { // Collects Flutter errors Contentsquare().collectFlutterError(details: details); }; runApp(MyApp()); }, (error, stack) { // Collects all unhandled errors in the zone Contentsquare().collectError(error: error, stackTrace: stack); }); } ``` #### Flutter error presentation Contentsquare automatically [presents ↗](https://api.flutter.dev/flutter/foundation/FlutterError/presentError.html) the Flutter errors. You can disable it by using the optional `presentErrorDetails` parameter in `collectFlutterError` API. ```dart Contentsquare().collectFlutterError(details: details, presentErrorDetails: false); ``` #### Compatibility with Firebase Crashlytics Integrating Crashlytics as an additional error reporting solution is straightforward: include the corresponding instruction within each callback. ##### Example with Firebase Crashlytics ```dart void main() async { WidgetsFlutterBinding.ensureInitialized(); await Firebase.initializeApp(); FlutterError.onError = (FlutterErrorDetails details) { Contentsquare().collectFlutterError(details: details, presentErrorDetails: false); FirebaseCrashlytics.instance.recordFlutterError(details); }; WidgetsBinding.instance.platformDispatcher.onError = (exception, stackTrace) { Contentsquare().collectError(error: exception, stackTrace: stackTrace); FirebaseCrashlytics.instance.recordError(exception, stackTrace); return false; }; runApp(MyApp()); } ``` ### Validate integration 1. Enable the [in-app features](https://docs.contentsquare.com/en/flutter/in-app-features/#enable-in-app-features). 2. Run your application. You should see a log printed in the console: ```plaintext ┌─────────────────────────────────────────────────────────────────────────────── │ ℹ️ INFO ℹ️ (CSLIB) ├─────────────────────────────────────────────────────────────────────────────── │ Errors Reporter module has started. └─────────────────────────────────────────────────────────────────────────────── ``` #### Validate error reporting With [in-app features](https://docs.contentsquare.com/en/flutter/in-app-features/#enable-in-app-features) enabled, any errors occurring in your application should generate a log in the console: ```plaintext ┌─────────────────────────────────────────────────────────────────────────────── │ ℹ️ INFO ℹ️ (CSLIB) ├─────────────────────────────────────────────────────────────────────────────── │ Error was collected. │ Exception: type 'String' is not a subtype of type 'int' in type cast └─────────────────────────────────────────────────────────────────────────────── ``` ### Symbolization and de-obfuscation Note The following step are only needed if you are using the `--split-debug-info` or `--obfuscate` options with the `flutter build` commands To be able to read errors from an application built with Flutter obfuscation and/or de-symbolisation, you will need to upload the debug files to Contentsquare. 1. [Enable the `contentsquare_cli` plugin](https://docs.contentsquare.com/en/flutter/contentsquare-cli/#installation) 2. [Run the upload command](https://docs.contentsquare.com/en/flutter/contentsquare-cli/#upload-debug-files-command) The upload command must be executed immediately after the Flutter build. Automating the upload As Flutter overwrites debug files for the same platform with each build, if you fail to upload the debug files in time, you won't be able to read errors from the previous release. You should run the upload command within your CI/CD pipeline or build script after every release build. #### Minimum required Flutter version * Android: 3.10.6 * iOS: 3.13.0 ### How Error Reporter works #### Initialization Error Reporter is started automatically and begins to collect the reported errors when your application is launched #### Configuration Once started, our SDK fetches its configuration from our servers. It will start reporting errors if the Error Reporter setting is enabled (this is handled by the Contentsquare team). You have to implement an error handler strategy and collect the received errors. See [Flutter errors](https://docs.contentsquare.com/en/flutter/error-analysis/#handle-the-flutter-errors) for examples #### Reporting When an error occurs, a report is created and stored locally in the device. The report is sent to our servers as soon as possible and then removed from the local storage. Warning To make sure errors are correctly tracked, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent. See [Track screens](https://docs.contentsquare.com/en/flutter/track-screens) for more details. #### Sending error data For each error, a new event will be sent to analytics and Session Replay data when the network conditions allow for the server to be reached. ### Native crashes Crashes from the native parts of your application can be captured with additional setup. See 📚 [iOS Crash Reporter](https://docs.contentsquare.com/en/ios/error-analysis/#crash-reporter). See 📚 [Android Crash Reporter](https://docs.contentsquare.com/en/android/error-analysis/#crash-reporter). ### WebView errors Errors occurring in web pages loaded in WebViews can be collected if Webview tracking is setup in your app. See 📚 [Webview Tracking implementation](https://docs.contentsquare.com/en/webview-tracking-tag/). Once WebView tracking is implemented, errors collection can be set up. See 📚 [Errors (in WebView)](https://docs.contentsquare.com/en/webview-tracking-tag/error-analysis/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Error Analysis","description":"How to use Contentsquare Error Analysis in your Flutter apps","url":"https://docs.contentsquare.com/en/flutter/error-analysis/","inLanguage":"en","dateModified":"2026-05-15T10:41:37+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Experimental annotation - Flutter (classic) description: What is experimental in the Contentsquare Flutter SDK lastUpdated: 02 June 2026 source_url: html: https://docs.contentsquare.com/en/flutter/experimental/ md: https://docs.contentsquare.com/en/flutter/experimental/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). In our continuous effort to enhance the Contentsquare Flutter SDK, there are instances where we develop new features that we want to make available to our customers ahead of their official global release. These features are marked as **experimental** to indicate their status. ## What is the Experimental Annotation? The `@experimental` annotation is an annotation we apply to certain features within the SDK. This annotation indicates that while the feature is accessible for use, it is not yet fully stable and may undergo changes. The experimental status allows us to share innovative capabilities with our clients earlier, but it also serves as a caution that the feature is still under evaluation. Note The experimental annotation is not a guarantee that the feature will be included in the SDK stable release. ## Why Do We Use the Experimental Annotation? Marking an experimental API is crucial for several reasons: * **API Stability:** Although thoroughly tested internally, the API might still evolve based on customer feedback. * **Client Needs:** We want to ensure that the feature fully addresses our clients needs before it becomes a permanent part of the SDK. * **Transparency:** We want to be transparent about the status of the feature and its potential for change. ## What Does It Mean for You? Adopting an experimental feature means you are using a feature that could be modified or removed at any time, even without a change in the SDK major version number. While these features grant early access to new functionality, there are important points to consider: * **Logs**: When using an experimental feature, you will see a log message indicating that the feature is experimental. * **Risk of Breaking Changes:** As these features are still under development, they may undergo significant changes without prior notice. Note Experimental warning log might be visible even when SDK is not started. This does not submit any data to remote. It is only information notifying you that an experimental feature is used. Note * **Documentation and Support:** We will provide up-to-date documentation, including examples of how to use the experimental feature. * **Changelog Updates:** Any introduction of or changes to an experimental feature will be documented in the changelog, ensuring transparency. ## Experimental Feature Lifecycle Experimental features follow one of three potential paths: ### 1. Positive Outcome If the feature proves successful and meets client needs, it will graduate from experimental status. The annotation will be removed, and the feature will be integrated into the SDK as a stable component. The documentation and the patch note will be updated to reflect this change. ### 2. Negative Outcome If the feature is determined to be unnecessary or ineffective, it will quickly move toward deprecation. This process involves marking the feature as `@deprecated` in the upcoming release, signaling to clients that the feature will no longer be supported. The feature will then be fully removed in the following minor version of the SDK. The documentation will be updated to clearly communicate the deprecation and eventual removal of the feature. ### 3. Work in Progress If further development is needed, the feature will remain experimental, with ongoing adjustments to its API, behavior, and scope. ## Providing Feedback on Experimental Features We highly value your input on experimental features, as your feedback plays a crucial role in shaping the final version of these features. If you're using an experimental feature, we encourage you to share your experiences, including any issues you encounter, suggestions for improvement, or use cases that the feature supports well. The most direct way to provide feedback is by submitting a support ticket. When doing so, mention that you are using an experimental feature and provide any relevant details. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Experimental annotation","description":"What is experimental in the Contentsquare Flutter SDK","url":"https://docs.contentsquare.com/en/flutter/experimental/","inLanguage":"en","dateModified":"2026-06-02T10:48:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: How the SDK works - Flutter (classic) description: Understand how the Flutter SDK loads, tracks, and send data lastUpdated: 28 April 2026 source_url: html: https://docs.contentsquare.com/en/flutter/how-the-sdk-works/ md: https://docs.contentsquare.com/en/flutter/how-the-sdk-works/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). The SDK must be initialized by calling `Contentsquare().start()` and requires `Contentsquare().optIn()` to begin collecting data. ## Configuration Upon initialization, our SDK fetches its configuration from our servers. Depending on the segmentation size defined in your contract, it will start collecting data from system and user events detected during runtime. ## Tracking The SDK monitors application lifecycle events and the view hierarchy, generating analytics data from app behavior, screen content, and user interaction. These events are stored locally and eventually sent to our servers in batches. We aggregate this data to create actionable visual insights in our Web Application, enabling you to gather insights. ## Sending data * Android Checkout the [Native Android SDK documentation for Sending data](https://docs.contentsquare.com/en/android/how-the-sdk-works/#sending-data) * iOS Checkout the [Native iOS SDK documentation for Sending data](https://docs.contentsquare.com/en/ios/how-the-sdk-works/#sending-data) ## Session definition A session is one continuous period of user interaction. It starts upon app launch and persists through state changes, including putting the app in the background or terminating and restarting it. As long as users interact at least once every 30 minutes, it remains the same session. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"How the SDK works","description":"Understand how the Flutter SDK loads, tracks, and send data","url":"https://docs.contentsquare.com/en/flutter/how-the-sdk-works/","inLanguage":"en","dateModified":"2026-04-28T22:02:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - Flutter (classic) description: Learn how Contentsquare deals with Personal Data and related APIs lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/flutter/privacy/ md: https://docs.contentsquare.com/en/flutter/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). The Contentsquare Flutter Bridge and SDKs are compliant with the Play Store and App Store Privacy guidelines and with the EU General Data Protection Regulation (GDPR). Refer to our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/) for further information. ## Handling User Consent While Contentsquare only collects usage data on your app, we will treat every new user as opted-out by default. To start tracking, the Opt-in API must be called. Note If, for any reason, you believe that securing user consent may not be necessary for your app, address this concern during the implementation process with your main contact. ## Opt-in Use the Opt-in API to get user consent. Calling this API will generate a user ID and initiate tracking. ```dart Contentsquare().optIn(); ``` ## Opt-Out Permanently breaking the link and stopping all data collection. When this API is called, tracking stops immediately, all settings are reset (session number, page number, user ID...) and all files related to Contentsquare tracking are deleted. Contentsquare will never track and collect any data from the user's phone unless the Opt-in API is called again. ```dart Contentsquare().optOut(); ``` ## Forget me Deprecated This API is deprecated as of plugin version 3.8.0. To achieve the same effect use Opt-out API to delete all files and settings including the user ID, and call Opt-in API on next app launch if tracking needs to resume. ```dart Contentsquare().forgetMe(); ``` ## Give me my data We allow the client to provide to their users their Contentsquare user ID. This ID is a non binding identifier which can be used to make a data request to Contentsquare. You are able to get an ID only if the user has not Opted-out. ```dart final userId = await Contentsquare().getUserId(); ``` ## Stop / Resume Tracking Although we do not gather any humanly readable text from the user's screens, we understand that there may be some areas that you want to completely exclude from tracking. For this reason, we also support stopping and resuming the complete tracking mechanism. Tracking will automatically resume if the app is killed and restarted. ```dart Contentsquare().stopTracking(); Contentsquare().resumeTracking(); ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Learn how Contentsquare deals with Personal Data and related APIs","url":"https://docs.contentsquare.com/en/flutter/privacy/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: In-app features - Flutter (classic) description: Implement in-app features with the Contentsquare Flutter SDK lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/flutter/in-app-features/ md: https://docs.contentsquare.com/en/flutter/in-app-features/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). In addition to its tracking functionalities, the SDKs incorporate certain features tailored for Contentsquare users, including **Screenshot Capture** and **SDK Logs**. ## Implement in-app features (iOS Only) Note This implementation phase is required on the iOS side only (on Android, there is nothing to do). To allow Contentsquare users to enable in-app features: 1. [Add the custom URL scheme in your app Info](#1-add-the-custom-url-scheme-in-your-app-info) 2. [Call the SDK when the app is launched via a deeplink](#2-call-the-sdk-when-the-app-is-launched-via-a-deeplink) ### 1. Add the custom URL scheme in your app Info For in-app features to function, your app needs to be accessible via a custom URL scheme. This can be achieved by implementing **ONE** of the following approaches: #### Using Xcode 1. Open your project settings 2. Select the app target 3. Select the `Info` settings 4. Scroll to `URL Types` 5. Set the URL scheme to `cs-$(PRODUCT_BUNDLE_IDENTIFIER)` #### Or using a Text editor 1. Open the `Info.plist` of your project 2. Add the following snippet: **Info.plist** ```xml <key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>cs-$(PRODUCT_BUNDLE_IDENTIFIER)</string> </array> </dict> </array> ``` ### 2. Call the SDK when the app is launched via a deeplink In `ios/Runner/AppDelegate.swift`, add a new method to the `AppDelegate` class: **ios/Runner/AppDelegate.swift** ```swift import ContentsquareModule override func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool { Contentsquare.handle(url: url) return super.application(app, open: url, options: options) } ``` Here is what your `AppDelegate` class should look like after adding the in-app features: **ios/Runner/AppDelegate.swift** ```swift import UIKit import Flutter import ContentsquareModule @UIApplicationMain @objc class AppDelegate: FlutterAppDelegate { override func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { GeneratedPluginRegistrant.register(with: self) return super.application(application, didFinishLaunchingWithOptions: launchOptions) } // Add this method: override func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool { Contentsquare.handle(url: url) return super.application(app, open: url, options: options) } } ``` ## Enable in-app features In-app features can be enabled in different ways: ### Scan the QR Code If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code displayed with your phone. Take a look at the native documentation for further information. ### Alternative methods We provide alternative methods to enable in-app features especially for iOS Simulator and Android Emulator. * Android Follow the [Native Android SDK documentation for Enable in-app features](https://docs.contentsquare.com/en/android/in-app-features/) * iOS Follow the [Native iOS SDK documentation for Enable in-app features](https://docs.contentsquare.com/en/ios/in-app-features/) ## Debugging and Logging Contentsquare provides Logging capabilities that allow you to see the raw event data logged by your app. Use this when for validation purposes during the instrumentation phase of development and can help you discover errors and mistakes in your analytics implementation and confirm that all events are being logged correctly. ## Screenshot capture To unlock the full data-visualization capabilities of Contentsquare, the SDK provides a way to capture screenshots of your app screens. These screenshots can only be taken by Contentsquare's users on their device. They are not captured from your end-users device. It means your Personal Data is safe, as long as you use a test user account. Warning For screenshot capture to work, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. * Android Follow the [Native Android SDK documentation for Screenshot Capture](https://docs.contentsquare.com/en/android/in-app-features/#screenshot-capture) * iOS Follow the [Native iOS SDK documentation for Screenshot Capture](https://docs.contentsquare.com/en/ios/in-app-features/#screenshot-capture) ## Known limitations * In debug mode, screenshots are not reliable and may differ from those taken in release mode. For accurate and consistent results, use screenshots from release mode. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"In-app features","description":"Implement in-app features with the Contentsquare Flutter SDK","url":"https://docs.contentsquare.com/en/flutter/in-app-features/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Reliable Targets - Flutter (classic) description: Reliable targets enables the analysis of data across various Screenshots from different dates and versions, including layouts or A/B testing variations lastUpdated: 02 June 2026 source_url: html: https://docs.contentsquare.com/en/flutter/reliable-targets/ md: https://docs.contentsquare.com/en/flutter/reliable-targets/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). Contentsquare SDK uses zoning identifiers that relies heavily on the structure of the widget tree. Consequently, changes to the widget tree, such as moving, nesting, or removing a widget, may result in the loss of tracking data. For instance, consider the widget tree of a Flutter app as illustrated below: **main.dart** ```dart Widget _buildMyAwesomeContent() { return Column( children: const [ Text('Answer to the Ultimate Question of Life, The Universe, and Everything'), Text('is'), Text('42'), ], ); } ``` In many cases, maintaining a `Reliable Target`, despite changes in its position within the tree, is essential. This consistency ensures reliable analysis of data across different `Screenshots`, dates, and versions, including variations in layouts or A/B testing. Having a `Reliable Target` for a widget enables the analysis of data across various `Screenshots` from different dates and versions, including layouts or A/B testing variations. Here are some scenarios where the Reliable Targets feature proves beneficial: * Tracking elements capable of dynamically shifting on a page (example: customizable profile page). * Monitoring elements across various app versions, even if their positions change (example: carousel transitioning from top to bottom). * Tracking elements amidst A/B testing (example: testing old and new product pages within the same version). * Monitoring elements used across multiple pages (example: search bar). * Ensuring a unique identifier for a call to action regardless of its location on the screen (example: "Add to Cart" button). To facilitate this, the `Contentsquare` Flutter SDK offers a `ReliableTarget` widget, designed to encapsulate the widget intended for reliable tracking. The `ReliableTarget` widget requires a mandatory `name` argument for identifying the component to track. Below is an example of implementing it with the provided code: **main.dart** ```dart Widget _buildMyAwesomeContent() { return ReliableTarget( name: '42_is_the_answer', child: Column( children: const [ Text('Answer to the Ultimate Question of Life, The Universe, and Everything'), Text('is'), Text('42'), ], ), ); } ``` Limitations * `name` MUST be unique * `name` should NOT be empty * `name` for the same `ReliableTarget` must be the same across different versions of the app ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Reliable Targets","description":"Reliable targets enables the analysis of data across various Screenshots from different dates and versions, including layouts or A/B testing variations","url":"https://docs.contentsquare.com/en/flutter/reliable-targets/","inLanguage":"en","dateModified":"2026-06-02T10:48:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Security - Flutter (classic) description: Data transfer and security information lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/flutter/security/ md: https://docs.contentsquare.com/en/flutter/security/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). The Flutter SDK is designed with security and privacy in mind. ## Transmission and hosting All data is encrypted in transport over HTTPS. Our hosting solution is a PCI DSS Level 1 Service Provider. ## What is not collected * Passwords from password fields * Geo location information * Information from contacts, emails, or any other user identifiable information. * Text from labels, buttons, and any other widget which contains text * Accessibility information from any widget which the user interacts with * Labels printed on the screen of any kind. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Security","description":"Data transfer and security information","url":"https://docs.contentsquare.com/en/flutter/security/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Session Replay - Flutter (classic) description: How to implement Session Replay with the Contentsquare Flutter SDK lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/flutter/session-replay/ md: https://docs.contentsquare.com/en/flutter/session-replay/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). Session Replay enables replaying real sessions to observe how users interact with your product, by capturing screen content - including text and images - as users navigate your mobile app. For more details, see [Introduction to Session Replay for Apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) in the Help Center. ## Starter guide ### Prerequisites #### Update to latest SDK version To enable Session Replay in your app and get the most stable version, it is required to [upgrade the SDK](https://docs.contentsquare.com/en/flutter/#install-the-sdk) to its latest version. #### Implement screen tracking Ensure screen tracking is implemented, since Session Replay collection starts at the first screenview event. See [Track screens](https://docs.contentsquare.com/en/flutter/track-screens/). #### Handle User consent Ensure user consent is handled for Contentsquare data collection, especially if you're implementing the SDK for the first time. See [Privacy](https://docs.contentsquare.com/en/flutter/privacy/) section. Moreover if you need to obtain a specific end-user's consent for Session Replay or to start Session Replay data collection only under certain conditions (in specific geolocations for instance), see [Define when Session Replay starts](#define-when-session-replay-starts) Note Mandatory data collection settings are configured by Contentsquare in your project parameters. [Learn more about Data collection configurations ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) on the Help Center. ### Configure Session Replay masking #### Masking behavior By default, the Contentsquare SDK is configured to mask all content displayed on the user interface (UI) to prevent unnecessary data collection. For more details, see what a fully masked screen looks like in [Masking mechanisms](#masking-mechanisms). **For testing purposes**, use this setup: * Either unmasking all the content by setting the [default masking](#default-masking) status to false. * Or unmasking most content with the [Text and Image unmasking configuration ↗](https://support.contentsquare.com/hc/en-us/articles/37271682878353-Data-masking-in-Session-Replay-Mobile-Apps) in your Console parameters. **For more granular control in deployment mode**, you can use the [Text and Image unmasking configuration ↗](https://support.contentsquare.com/hc/en-us/articles/37271682878353-Data-masking-in-Session-Replay-Mobile-Apps) in your Console parameters in combination with [SDK public masking APIs](#public-masking-apis) to fine-tune exactly which elements remain masked. Warning Always keep sensitive data masked to ensure compliance with privacy regulations and to protect users' personal data. ### Configure Event-Triggered Replays (optional) If Event-Triggered Replays is included in your contract, you can set up ETR events to enable specific screen and session collection in Session Replay. See [Event-Triggered Replays (ETR)](#event-triggered-replays-etr). ### Configure Webviews (optional) If your mobile app includes Webviews, specific implementation steps are required to ensure they are properly reflected in Session Replay: * Implement [Webview tracking](https://docs.contentsquare.com/en/webview-tracking-tag/) * Handle [personal data within WebViews](https://docs.contentsquare.com/en/webview-tracking-tag/session-replay/#personal-data-handling) ### Test your setup #### Enable Session Replay on your device If the Session Replay sampling rate is less than 100%, only a portion of sessions are collected. To ensure data collection on your device for testing and debugging purposes, you can force it from the In-app Features settings by following these steps: 1. [Enable in-app features](https://docs.contentsquare.com/en/flutter/in-app-features/) 2. Open in-app features settings with a long press on the screenshot button 3. Under "Session Replay", toggle "Enable Session Replay" on 4. Kill the app 5. Upon restarting the app, a new session will start with Session Replay enabled. ##### iOS example  #### How do I know if Session Replay is enabled? There are 2 places where you can verify if Session Replay is enabled: **In the logs:** The log `Session Recording is starting` will confirm that Session Replay is enabled. **In in-app features settings:** Below the "Enable "will start at next app start" *(see below [Access the replay](#access-the-replay))*, you will either see: * `No replay link available` which means Session Replay is not running for the current session * `Get Replay link` which means Session Replay is running for the current session #### Access the Replay The session can be accessed by tapping on `Get replay link` button from the in-app features settings:  The replay will be **available within 5 minutes**. Only the *concluded* screen views are processed, and we identify a screenview has *concluded* when we begin receiving data for the subsequent screenview or if the session has ended. This means that you will be able to replay your session up to the previous screenview if the session is still ongoing. ## Define when Session Replay starts If you need to ensure that Session Replay data is collected only under certain conditions — for example, only after receiving explicit user consent for Session Replay or in specific geolocations — follow these instructions: ### Disable Automatic Session Replay Initialization 1. Call `Contentsquare().configure(contentsquareOptions: options);` **before** `start()`. The initialization of the SDK should look like this: ```dart Contentsquare().configure( contentsquareOptions: ContentsquareOptions( isSessionReplayAutoStartEnabled: false, ), ); await Contentsquare().start(); ``` Warning `configure` must be called before `start` ### Start Session Replay Once your app has determined that Session Replay can start — for example, via a reverse geocoding service or after receiving specific user consent for Session Replay — you can call `Contentsquare().startSessionReplay()` to start Session Replay. Note Calling `startSessionReplay()` does not force Session Replay data collection. It enables the Session Replay module, allowing it to begin checking whether the global Replay sampling rate or Event Triggered Replay conditions are met. Session Replay data collection will only start if these conditions are satisfied. For more information, see [Data collection for Session Replay (Apps) ↗](https://support.contentsquare.com/hc/en-us/articles/37271951720721) on the Help Center. The following log confirms Session Replay data collection has started: * Android ```log CSLIB: Session Replay is starting ``` * iOS ```log CSLIB ℹ️ Info: Session Replay is starting ``` ## Personal Data Masking The Session Replay feature replays every interaction of your users with your app. To respect the user's right to privacy, the Contentsquare SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our [Masking rules](#masking-rules) Warning When using Contentsquare with Flutter, if you decide to use unmasked elements leading to collection of new data or use already collected data but for a different purpose, it is up to you to update your app's privacy documentation accordingly. Here are some common examples of data collected via un-masked session Replay: Search history, Purchase history, Advertising data, etc. See [Types of data and purpose](https://docs.contentsquare.com/en/flutter/privacy/) already described in the Contentsquare iOS SDK Privacy Manifest. Contentsquare is not intended nor designed to collect sensitive personal data (such as health, financial, racial data). It is the customer's responsibility not to send any sensitive personal data to Contentsquare. ### Masking mechanisms Masking depends on the type of element: * **Images**: A blurred representation is sent in place of the original content. * **SVG images**: A blurred representation is sent in place of the original content. * **CustomPaint**: custom-made `CustomPaint` elements are not collected. Instead, a blurred representation is sent in place of the original content. [Framework specific decorative `CustomPaint`](#unmaskable-framework-specific-custompaint-classes) that do not contain sensitive data are still collected. * **Text**: Replaced by \* (asterisk) characters, matching the original character count. Whitespace characters (spaces, tabs, line breaks) are preserved. For instance, `the lazy fox` is collected as `*** **** ***`. All other visual properties (text color, background color, alignment, etc.) are collected. * **TextFields**: Same as Text * **TextField with `obscureText`**: Both the obscured text and the briefly revealed character are replaced by • (bullet). * **Other types**: no specific data is collected but visual properties are collected. * **Icons**: Single characters belonging to the Private Use Area `U+E000..U+F8FF` are collected. If you believe a particular element might disclose personal data through any of these properties, you must mask it using one of the methods outlined below. A reliable method to assess how a view is rendered in a replay is to navigate to the desired view with the CS SDK active, then use the [quick replay link](#access-the-replay). #### Masking example Here's an illustration of a masked view: `Original` -> `Replay fully unmasked` -> `Replay fully masked`  ### Masking rules Masking rules can be applied in two ways: 1. **Through remote masking configuration in the CSQ Console (for admin users):** These configurations are managed directly in the Console and take effect for all sessions as soon as the app is restarted or brought to the foreground. See [How to customize masking rules from the Data Masking tab ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) on the Help Center. 2. **Using public masking APIs in the SDK (for mobile application developers):** These configurations require developer implementation and will be applied only after the mobile app has gone through its release cycle. Masking rules set via the CSQ Console or the public APIs are applied according to different priorities, as described below. The SDK determines whether a view is masked by evaluating the rules in the order specified below. Once a rule is triggered, the state is set, and subsequent rules are not applied: When using `SessionReplayMaskingScope` and `MaskingConfig`, it's essential to understand the priority of masking rules in the widget tree. The masking rules specified in a `SessionReplayMaskingScope` widget will affect its descendants, and if nested scopes are used, the innermost (closest) scope takes precedence. Once a rule is triggered, the state is set, and subsequent rules are not applied: | Rule | Configured via | | - | - | | 1. The app or plugin version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text or Image masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. The `MaskingConfig` object provided to a `SessionReplayMaskingScope` widget sets the masking rules for its child and descendants. | API | | 5. The `MaskingConfig` object provided to the `start()` method sets the masking rules for the entire app. | API | | 6. Remote Text or Image unmasking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 7. Otherwise the widget remains masked except for `CustomPaints` and `SvgImages` | default | ### Public Masking APIs #### Default masking By default all images, text, and Text fields will be masked. SVGs and CustomPaints are not masked. #### Masking/Un-masking in Flutter `SessionReplayMaskingScope` is a Flutter widget that applies specified masking rules to its descendant widgets. This can be used when you want to mask sensitive information during Session Replays, such as user data or private texts. `MaskingConfig` is a class that determines what type of content should be masked during Session Replays. You can customize the masking behavior by setting the masking options for texts, text fields, and images. #### How to use SessionReplayMaskingScope To use `SessionReplayMaskingScope`, wrap the desired widgets with the `SessionReplayMaskingScope` widget and provide a `MaskingConfig` object to configure the masking rules. Here's an example of how to use `SessionReplayMaskingScope`: ```dart SessionReplayMaskingScope( maskingConfig: MaskingConfig.maskAll(), child: const Text('Hello world'), ); ``` In this example, `MaskingConfig.maskAll()` is used to mask the `Text` widget. You can also use nested `SessionReplayMaskingScope` widgets to apply different masking rules to different parts of your widget tree. Here's an example: ```dart SessionReplayMaskingScope( maskingConfig: MaskingConfig.maskAll(), child: Column( children: [ const Text('This text will be masked'), SessionReplayMaskingScope( maskingConfig: MaskingConfig(maskTexts: false), child: Text('This text will NOT be masked'), ), ], ), ); ``` In this example, the first `Text` widget will be masked, while the second one will not be masked due to the `maskTexts: false` option in the nested `SessionReplayMaskingScope`. #### How to use MaskingConfig `MaskingConfig` allows you to configure the masking behavior for different types of content: * `maskTexts`: If set to `true`, any widget that creates a `RenderParagraph` (example: `Text`, `RichText`) will be masked. * `maskTextFields`: If set to `true`, any widget that creates a `RenderEditable` (example: `TextFormField`, `TextField`) will be masked. * `maskImages`: If set to `true`, any widget that creates an image (example: `Image`, `BoxDecoration.image`) will be masked. * `maskSvgImages`: If set to `true`, any widget that creates an SVG image through `flutter_svg` will be masked. * `maskCustomPaints`: If set to `true`, any custom-made widget that creates a `CustomPaint` will be masked. [Framework specific decorative `CustomPaint`](#unmaskable-framework-specific-custompaint-classes) not containing any sensitive data are not masked. * `maskCharts`: If set to `true`, any widget that creates a chart using the [`fl_chart` ↗](https://pub.dev/packages/fl_chart) package will be masked. You can create a custom `MaskingConfig` object by using the constructor: ```dart const MaskingConfig({ bool maskTexts, bool maskImages, bool maskTextFields, bool maskSvgImages, bool maskCustomPaints, }) ``` For easier readability and convenience, you can use the following factory constructors: * `MaskingConfig.maskAll()`: Returns a `MaskingConfig` object with all values set to `true`, meaning everything will be masked. * `MaskingConfig.unMaskAll()`: Returns a `MaskingConfig` object with all values set to `false`, meaning nothing will be masked. If any masking parameter is omitted in the `MaskingConfig` object, its value is inherited from the nearest `SessionMaskingScope` widget in the widget tree. Note By default, `Contentsquare` masks all types of content (texts, text fields, and images) except the SVG images and CustomPaints during Session Replays. It achieves this by providing a default `MaskingConfig` object if none is specified. The default configuration masks everything, ensuring that sensitive information is protected. However, you can override the default masking behavior by providing your own `MaskingConfig` object when starting the SDK via the `start` method. This allows you to customize the masking rules for your app according to your requirements. Note If you did not include any sensitive content in `CustomPaint`s or SVG images, prefer to use `MaskingConfig` with `maskCustomPaints` and `maskSvgImages` set to false, to avoid unnecessary masking and guarantee the best Session Replay fidelity. Note You can set the default `MaskingConfig` for the entire app by providing a `MaskingConfig` object to the `start` method. ```dart final maskingConfig = MaskingConfig(maskTexts: false); await Contentsquare().start(maskingConfig: maskingConfig); ``` ## Event-Triggered Replays (ETR) Event-Triggered Replays (ETR) is an add-on feature that allows you to selectively collect specific screens or sessions for Session Replay, based on predefined custom events. Once configured, ETR events can be used to filter specific replays, or view these events as they happen in the player event stream. To enable ETR, contact your CSM or Implementation Manager. For more information, see [Event-Triggered Replays ↗](https://support.contentsquare.com/hc/en-us/articles/4412027865874) in the Help Center. Note When ETR is enabled, the SDK collects data for the entire session even if none of the ETR methods described below are called. After collection, only the sessions or screens that match the global replay sampling rate or are associated with ETR events are retained. As a result, you may notice a network activity during all sessions, regardless of whether ETR has been triggered or not. Warning To protect end-user personal data, ensure that appropriate masking configurations are applied to all screens even the ones that are not associated with ETR events. ### Trigger Replay for the Session Use the following function to trigger Session Replay for the entire current session, with the parameter `name` as "ETR event". ```dart Contentsquare().triggerReplayForCurrentSession(name: name) ``` ### Trigger Replay for the Screen Use the following function to trigger Session Replay for the entire current screen, with the parameter `name` as "ETR event". ```dart Contentsquare().triggerReplayForCurrentScreen(name: name) ``` ## Advanced features for Experience Monitoring Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. ### Send user identifier Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier: email, phone number, customer ID… As these values are typically personal data, from the moment the SDK is collecting the `User Identifier`, we immediately encode the value using a hashing algorithm so that the information is hidden and can never be accessed. Use the following code to send a user identifier: ```dart Contentsquare().sendUserIdentifier('the_neo@one.com'); ``` When called, the native SDK will log: ```plaintext CSLIB ℹ️ Info: User identifier hashed sent {value} ``` ### Sending a user identifier for each session You may consider sending the user identifier for each session. Although triggering the user identifier at app launch will cover most cases, it may not be adequate in all scenarios. For instance, a session might start when the app is brought to the foreground after being in the background for more than 30 minutes. For further details, refer to the [Session definition](https://docs.contentsquare.com/en/ios/how-the-sdk-works/#session-definition) section. That is why we also recommend sending the user identifier every time the app enters foreground. ### Limitations * User identifier max length is 100 characters (if the limit is exceeded, the user identifier will not be handled and you will see an error message in the native Console/Logcat) * Only the first 15 user identifiers per view will be processed on server side * The SDK will trim and lowercase user identifier * User identifier event are not visible in `LogVisualizer` ## Session Replay Quality ### Quality Levels Session Replay is designed by reconstructing the app's tree structure from selected frames. To minimize performance impact during a session, different quality levels are dynamically applied. Each quality level determines whether certain styles are preserved or omitted while maintaining the overall screen structure and appearance. #### High Quality Level  At this level, all supported styles are captured every 200ms, provided a new frame is available. This ensures a comprehensive reproduction of the session's visual fidelity. #### Low Quality Level This level captures supported styles only when user interaction ceases, such as during screen scrolling. images are reduced to their average color representation. ### Quality Level Adjustment Our plugin continuously monitors its performance while running. Upon detecting a performance issue, the quality level is automatically reduced to mitigate any potential impact on the application. The quality level may increase when navigating to a new screen, provided the performance issue is resolved. Quality levels are visibly indicated in the Session Player event stream.  ## Integrations Contentsquare provides the ability to retrieve the link of the replay to be attached to other vendors such as Voice of Customer or Crash reporting tools. ### Get current replay Link Generate a link to the replay of the current session. This link can be pushed to any internal or 3rd-party tool as a custom property/variable. For instance, you can add the replay link to: * Each user request sent to your customer service tool * Each user voting in your Voice of Customer tool * Each user session in your App Performance, Observability tool * ... Note The replay link can also be accessed from the in-app features settings. See [Access the Replay](#access-the-replay). Warning For the API to return a valid replay link, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before it's called, since Session Replay only starts after the first screenview event. #### Function signature ```dart void onSessionReplayLinkChange(void Function(Uri url)? onLinkChanged); ``` #### Parameters `onLinkChanged (void Function(Uri url)?)`: A callback function that receives the updated Session Replay URL. This parameter is nullable. #### Key Features * Real-Time Updates: The callback is triggered every time there is a change in the Session Replay URL. It is also triggered when the callback is first registered, providing the current Session Replay URL. * Single Callback Registration: Only one callback can be active at a time. If the API is called multiple times, the most recent callback registration overrides the previous one. * Optional Callback: The `onLinkChanged` argument is nullable, allowing the API to be used to stop listening to URL changes. Use the following code to retrieve a Session Replay link each time it changes: ```dart Contentsquare().onSessionReplayLinkChange((Uri url) { /// Handle the updated Session Replay URL print('Session Replay URL: $url'); }); ``` Note * Upon registering the callback, if a Session Replay URL is already available, the callback will be triggered immediately. * If there is no Session Replay URL available, the callback will not be triggered until a URL becomes available. * Once registered, the callback will be triggered each time the Session Replay URL changes. To unregister the current callback, pass `null` as the argument: ```dart Contentsquare().onSessionReplayLinkChange(null); ``` When a new link is available, the SDK will also log: ```plaintext CSLIB: SessionReplay link: https://app.contentsquare.com/quick-playback/index.html?pid={projectId}&uu={userId}&sn={sessionNumber}&recordingType=cs ``` Warning You can only have one callback at a time. Calling this API twice will override the previous callback. The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay the session up to the previous screenview if the session is still running. ## How Session Replay works ### Initialization Sessions can be collected for Session Replay if the Session Replay feature has been enabled for your project and the session matches the collection criteria. The following conditions will have an impact on which sessions will be collected: * **User consent**: The users have provided their **consent** (if required) * **Collection rate**: The session is **designated for collection** (see [Collection Rate](#collection-rate)) * **Compatibility**: The **OS version** is supported. * **App version**: The **app version** is not included in the block list (see [App Version Block List](#app-version-block-list)) Note When Session Replay is disabled, no content specific to Session Replay is collected. Additionally, be aware that standard Contentsquare analytics tracking remains unaffected by this. #### Collection Rate Session Replay collection is based on a percentage of the total sessions. By default Session Replay collection is disabled. During the early access phase, the percentage of collected sessions will be set to 1% at the beginning. It will then be adjusted based on: * The traffic on your app * The volume of collected sessions set in the contract #### Compatibility See the [Compatibility matrix](https://docs.contentsquare.com/en/flutter/compatibility/#compatibility-matrix). #### App Version Block List The Contentsquare team can include versions of your app in the block list to prevent Session Replay from initiating on these versions. This functionality proves valuable when a problem is identified on a particular version of your app, such as a situation where masking for Personal Data was not implemented. By employing this feature, Session Replay can continue to operate on other app versions, particularly those with necessary fixes implemented. ### Collection The SDK monitors the application lifecycle events and the view hierarchy, capturing Session Replay data based on app behavior, screen content, and user interaction. These events are initially stored locally and later sent to our servers in batches. Subsequently, we aggregate this data to generate actionable visual insights in our Web Application, facilitating your ability to gather insights. Tip Session collection begins when the first screenview event is triggered. ### Network and Storage By default, Session Replay data can be sent over **cellular network**. However, if your app's context or user preferences necessitate minimal impact on cellular data usage, you can opt to disable data transmission over cellular networks entirely. Once disabled, data will only be sent when the device is connected to Wi-Fi. To make this adjustment in your project's configuration, contact your Contentsquare representative. #### Storage Before being sent, data is stored in local files on disk up to 30MB on iOS and 20MB on Android. If the limit is reached, Session Replay is halted. It will resume at the next app launch once the SDK can transmit the data. ### Requests The maximum request size is 1 MByte. #### iOS Requests are sent: * Every 10 seconds * At app hide * When [Replay Link API](#access-the-replay) is called #### Android Requests are sent: * On screen change * When [Replay Link API](#access-the-replay) is called ## Performance impact We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. ### Performance impact mitigation Most operations related to Session Collection are performed on background threads, for the impact on the main thread to be minimal. We also set up mechanisms that adapts and stop the Session Collection if we detect the feature is using too much memory. We defined our network strategy to have the lesser impact on CPU and battery of the users devices. We measure these impacts, using Apple Dev Tools, for each release of our SDK. Session Collection will also stop if we use up to 30Mbytes of local storage. ### Performance Benchmarks We have conducted performance tests on the SDK to ensure that it has a minimal impact on the app's performance. The tests were conducted on a variety of devices and operating systems to ensure that the SDK performs well across different platforms. These tests use the [Flutter Gallery ↗](https://github.com/flutter/gallery) app as a reference and simulate an intensive normal user interaction with the app during 60 seconds (scrolling, tapping, etc.) using the Session Replay feature. #### iOS For iPhone 14 with iOS 16.3 | Metric | Value | | - | - | | CPU Usage Delta | < 3% | | Memory Usage Delta | < 2% | | Network Usage | < 80kb | #### Android For Pixel 6 with Android 13 | Metric | Value | | - | - | | CPU Usage Delta | < 25% | | Memory Usage Delta | < 20% | | Network Usage | < 80kb | ## Known limitations Session Replay is designed by reconstructing your app's tree structure from selected frames, rather than collecting the screen pixel-by-pixel. Most standard Flutter content — text, text fields, images, SVG images, `CustomPaint`, charts, and clip shapes — is captured faithfully. Some content, however, cannot be reproduced exactly: content rendered outside the Flutter view (such as platform views and native maps) is not collected; Webviews require specific implementation steps to be properly reflected in Session Replay; custom shapes are sent as rectangles; and for unsupported element types (for example, custom `RenderObject` subclasses that paint directly), no specific content is collected but their visual properties — position, size, background — still are. Because the replay is reconstructed from selected frames, animations are captured at intervals rather than frame-by-frame, so fast or subtle motion may appear stepped. * Content rendered outside the Flutter view — platform views, native maps, and other embedded native content — is not collected. * Webviews require specific implementation steps to be properly reflected in Session Replay. See [Track WebViews](https://docs.contentsquare.com/en/flutter/track-webviews/). * Custom shapes are sent as rectangles. * For unsupported element types (for example, custom `RenderObject` subclasses that paint directly), no specific content is collected, but visual properties are. The standard `CustomPaint` widget is supported. * Animations are reconstructed from selected frames, not captured frame-by-frame, so fast or subtle motion may appear stepped. * Blur style is not supported when the app is [obfuscated ↗](https://docs.flutter.dev/deployment/obfuscate). * Overlays shown without a Flutter context (for example, native toasts) may not appear in the replay, particularly on Android. * In debug mode, the stability and performance of Session Replay are not guaranteed. For a reliable and high-performing experience, use release or profile builds. * In the event stream of the Session Replay, a tapped element is displayed as `unknown` if it has a transparent parent. * Masking applied to parent widgets does not apply to the [Draggable.feedback ↗](https://api.flutter.dev/flutter/widgets/Draggable/feedback.html) widget. To ensure proper masking while dragging, wrap the Draggable.feedback widget within its own `CSQMask`. If your app relies on a third-party library that you'd like to see supported in Session Replay, feel free to reach out to us. ## Unmaskable Framework specific `CustomPaint` classes * CupertinoActivityIndicator * CupertinoTextSelectionToolbar * BottomNavigationBar * DatePickerDialog * DropdownButton * InputDecorator * PhysicalShape * LinearProgressIndicator * CircularProgressIndicator * Stepper * TabBar * TextSelectionToolbar * AnimatedIcon * GridPaper * GlowingOverscrollIndicator * Placeholder ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Session Replay","description":"How to implement Session Replay with the Contentsquare Flutter SDK","url":"https://docs.contentsquare.com/en/flutter/session-replay/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track dynamic variables - Flutter (classic) description: Track dynamic variables with the Contentsquare Flutter SDK lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/flutter/track-dynamic-variables/ md: https://docs.contentsquare.com/en/flutter/track-dynamic-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). Dynamic variables are additional information on the session that can be used to segment sessions. For example, they can include information on the A/B Test variations displayed to the current user. ## Defining dynamic variables To define and send a dynamic variable, you just need to use the following API. For each dynamic variable, we send: * `key` (`String`, required) * `stringValue` (`String`, optional) * `intValue` (`int`, optional) exactly one of `stringValue` or `intValue` should be used at the same time. Also, in order for you to be able to handle such errors happening when we try to send the dynamic variable, you should wrap your call in a try/catch as explained in the Usage part. ```dart Contentsquare().sendDynamicVar('my key 1', stringValue: 'testValue'); Contentsquare().sendDynamicVar('my key 1', intValue: 12); ``` Type of the value — The value can be either a number or a string. For each case, available features won't be the same in the Contentsquare app: * For `int`, you will be able to do some algebra. Example: sessions with dynamic variable key = "numberOfFriends" and value >= 10 * For `String`, auto-completion and Regular Expression will be available. Example: sessions with dynamic variable key = "accountType" and value is "Premium" ## Sending a dynamic variable for each session You may want to send a dynamic variable for each session (like the user's country or store). While **triggering the dynamic variable at app launch will cover most cases, it will not be enough**. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See [Session definition](https://docs.contentsquare.com/en/flutter/how-the-sdk-works/#session-definition) section for more information. That is why we also recommend **sending such dynamic variable every time the app enters foreground**. You can use [`didChangeAppLifecycleState` method ↗](https://api.flutter.dev/flutter/widgets/WidgetsBindingObserver/didChangeAppLifecycleState.html) to detect foreground and trigger a dynamic variable. ## Limits ### On the server side * It is possible to save up to 40 distinct dynamic variable keys per screen view. If more are received, only the first 40 keys will be kept. * If you are using the same key twice, the last value associated with the key will be collected. ### On the SDK side * Every dynamic variable is composed of a pair of key (max. 50 characters) and value (max. 255 characters string or number of type Long between 0 and 232 - 1). In case these maximums length are reached, the SDK will automatically trim the exceeding characters. * If key or value are empty, the SDK will instead send the literal string "cs-empty". ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track dynamic variables","description":"Track dynamic variables with the Contentsquare Flutter SDK","url":"https://docs.contentsquare.com/en/flutter/track-dynamic-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track custom variables - Flutter (classic) description: Track custom variables with the Contentsquare Flutter SDK lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/flutter/track-custom-variables/ md: https://docs.contentsquare.com/en/flutter/track-custom-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). Custom variables attach additional information about the screen, user, or session to screenview events. For example, they can contain details about the current layout of a screen, such as day/night mode. ## Defining custom variables To define and send custom variables, follow this implementation: ```dart import 'package:contentsquare/contentsquare.dart'; final customVar1 = CustomVar( index: 1, name: 'customName_1', value: 'customValue_1', ); final customVar2 = CustomVar( index: 2, name: 'customName_2', value: 'customValue_2', ); Contentsquare().send( 'myAwesomeScreenName', customVars: [customVar1, customVar2], ); ``` Warning For consistent analytics, use the same index/name pair values across your application: **Screen A** ```dart const cVar4: CustomVar = { index: 4, key: 'hero_banner_type', value: 'carousel', }; Contentsquare.send('ScreenA', [cVar4]); ``` **Screen B** ```dart const cVar4: CustomVar = { index: 4, key: 'hero_banner_type', value: 'slider', }; Contentsquare.send('ScreenB', [cVar4]); ``` ## Limits ### On the server side * A maximum of 20 distinct custom variables per screenview can be stored. If more are received, only the first 20 custom variables, based on their `index` value, will be retained. * The `index` value of the custom variable determines which ones will be retained. Only index values from 1 to 20 (inclusive) will be considered. ### On the SDK side * Every custom variable is composed of `index`, `name` and `value`. * If the same `index` is used twice in the same screen, only the first (`name`, `value`) pair associated with the `index` will be kept. * A maximum of 20 custom variables can be stored on the same screenview. * If the maximum character length is reached for `name` (512 characters) or `value` (255 characters), the SDK will automatically truncate the additional characters automatically. * If `name` or `value` are empty, the SDK will instead send the literal string `"cs-empty"`. * Maintain a consistent index for a given custom variable throughout the application. For example, if the "screen layout" is collected with an `index` of 3, use the slot 3 for this information on every screen of the application. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track custom variables","description":"Track custom variables with the Contentsquare Flutter SDK","url":"https://docs.contentsquare.com/en/flutter/track-custom-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track screens - Flutter (classic) description: Track screens with the Contentsquare Flutter SDK lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/flutter/track-screens/ md: https://docs.contentsquare.com/en/flutter/track-screens/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). Contentsquare aggregate user behavior and engagement at the screen level. To leverage our full range of features, you must implement effective screen tracking. You can set this up: * [Manually](https://docs.contentsquare.com/en/flutter/track-screens/#track-screens-manually), by calling a dedicated API. * [Automatically](https://docs.contentsquare.com/en/flutter/track-screens/#track-screens-automatically), by using our observer to track screens based on changes in the navigation stack. Warning Sessions without at least one screenview will be discarded. ## Track screens manually Call the `.send(String)` API when a screen appears to track screens manually. When you call the API, the SDK logs a screenview event which identifies the new screen with the screen name you provided. ```dart ContentSquare().send('ScreenName'); ``` Warning If you have implement the manual start of the SDK, you need to start the SDK before sending any screen view. ```dart await Contentsquare().start(); ``` Until this is done, no screen tracking will be collected. ### Back navigation handling Back navigation is not automatically tracked by the SDK. When back navigation occurs the `send` method should be manually invoked with the screen name of the previous screen. #### Example with a custom navigation observer ```dart class CustomNavigationObserver extends NavigatorObserver { @override void didPop(Route route, Route? previousRoute) { ... final previousScreenName = // get the previous screen name Contentsquare().send(previousScreenName); ... } } ``` ### Screen name handling The screen name length is not limited on the SDK side. However, it's important to there is a limit of 2083 characters on the server side. Ensure that screen names do not exceed this limit to prevent any issues with data transmission and processing. ### Handling Screen Views When App Returns from Background The Contentsquare SDK automatically triggers a screen view when the app is moved to the background and subsequently brought back to the foreground. This occurs provided that a screen view with a screen name has been triggered previously. In such cases, the SDK will use the last screen name that was set. ### Implementation recommendations From a functional standpoint, we expect a screenview to be sent: * When the screen becomes visible * When a modal or pop-up is closed, returning the user to the screen * When a route is popped, returning the user to the screen Achieving this can be facilitated through a [NavigatorObserver ↗](https://api.flutter.dev/flutter/widgets/NavigatorObserver-class.html). This observer can be used to listen to route changes and send screenviews accordingly. ### How to name screens As a general rule, aim to keep distinct screen names under 100 characters. Choose names that provide a comprehensive understanding of the screen's content or purpose. This will help you to identify the screen in the Contentsquare interface. Tip We advise against relying on the `runtimeType` of the class, as in the release version, the class name may be obfuscated, rendering the name meaningless. #### Separate words with space, dash, or underscore characters If you want to create screen names with multiple words, it's best to separate them using spaces, dashes, or underscores. Contentsquare will handle the formatting automatically. **Example:** For a sub-category list of a retail app, use `Home and Living - Home Furnishings` instead of ~~`homeLivingHomeFurnishings`~~. ### Screen name limitations Casing sensitivity Screen names are not case sensitive and will appear in lowercase on the Contentsquare platform. ```dart Contentsquare().send('ScreenName') // screenname Contentsquare().send('Screen Name') // screen name Contentsquare().send('screen_name') // screen_name Contentsquare().send('screenname') // screenname ``` #### Use screen template/layout names As a general guideline, opt for names that describe the screen template or layout rather than focusing on specific content (data). This approach will minimize the number of unique screen names, making Contentsquare easier to use and reducing the potential for Personal Data transmission. Examples of screen types falling into this category include Product Detail, Event Detail, Conversation/Chat, and User Profile. ### Screens with multiple states/layouts Screens can have different layouts or states depending on the user context. In this case, append its value to the screen name. **Home screen** | State | Screen name | | - | - | | App landing layout | `Home` | | Women products layout | `Home - Women` | | Men products layout | `Home - Men` | | Sales layout | `Home - Sales` | **Product Detail screen (PDP)** | State | Screen name | | - | - | | Users on a Top for Women PDP | `PDP - Clothing - Women - Tops` | | Users on a Microwave PDP | `PDP - Kitchenware - Electrics - Microwave` | | Users on a Hotel details screen | `PDP - Holiday type - Season - Board` | **User account screen** | State | Screen name | | - | - | | Overview | `My Account - Dashboard` | | Order history | `My Account - Order history` | | Returns | `My Account - Returns` | **Search screen** | State | Screen name | | - | - | | Search | `Search` | | Search results for "Skincare" products | `Search - Skincare` | | Search results error screen | `Search - Error` | **Cart screen** | State | Screen name | | - | - | | Empty cart | `Cart - Empty` | | Items have been added to the cart | `Cart - Populated` | | Issues with availability or pricing | `Cart - Error` | **Checkout screen** | State | Screen name | | - | - | | User provides name, surname, and date of birth | `Checkout - User Details` | | User provides shipping address | `Checkout - Shipping Details` | | User inputs their credit card information | `Checkout - Payment` | ## Track screens automatically Automatic screen view tracking can be done using the `ContentsquareNavigatorObserver`. This will observe the navigation stack of the application and log screen events accordingly. This observer can be attached to any `WidgetApp` (like `MaterialApp`, `CupertinoApp`) or to a `RouterConfig` * WidgetApp ```dart MaterialApp( navigatorObservers: [ContentsquareNavigatorObserver()], ); CupertinoApp( navigatorObservers: [ContentsquareNavigatorObserver()], ); WidgetsApp( navigatorObservers: [ContentsquareNavigatorObserver()], ); ``` * RouterConfig ```dart MaterialApp.router( routerConfig: GoRouter( observers: [ContentsquareNavigatorObserver()], ), ); ``` Warning To ensure effective results, make sure that each [Route ↗](https://api.flutter.dev/flutter/widgets/Route-class.html) is properly named ### Configuration The `ContentsquareNavigatorObserver` can be configured with the following arguments: #### ShouldTrack An optional callback function that determines whether a specific route should be tracked. The function takes a `Route` as input and returns a `bool`. Use this function to selectively exclude certain routes from automatic tracking by returning false for those routes. By default, all routes are tracked. ```dart ContentsquareNavigatorObserver( shouldTrack: (route) { // Exclude /myRoute from tracking if (route.settings.name == '/myRoute') return false; return true; }, ) ``` #### ScreenNameProvider An optional callback function used to customize the screen name for a given route. The function takes a `Route` as input and returns a `String` representing the desired screen name. Use this function to define custom screen names for specific routes. By default, the route's name is used if available; otherwise, the route type will be used. ```dart ContentsquareNavigatorObserver( screenNameProvider: (route) { final screenName = _formatScreenName(route.settings.name); return screenName; }, ) ``` #### CustomVarsProvider An optional callback function used to provide a list of custom variables for a specific route. The function takes a `Route` as input and returns a `List<CustomVar>`. Use this function to attach custom variables to specific routes for tracking purposes. ```dart ContentsquareNavigatorObserver( customVarsProvider: (route) { final routeName = route.settings.name; final productPageRegex = RegExp(r'/product/(\d)+'); // In this example, a product ID is extracted from the route name. // For a route like "/product/1234", the value "1234" will be set as a customVar. if (routeName != null && productPageRegex.hasMatch(routeName)) { final productId = productPageRegex.firstMatch(routeName)?.group(1); if (productId != null) { return [ CustomVar(index: 1, name: 'productId', value: productId), ]; } } return []; }, ) ``` ### Troubleshooting #### Tab bar TabBar views are commonly tracked as individual screens. However, most TabBar implementations push the route to the navigation stack only during initialization, which can make it challenging to properly track navigation events for each tab change. To support TabBar tracking correctly, additional configuration may be necessary. For example, when using AutoTabsRouter from the AutoRoute package, the default behavior does not track tab changes automatically. In this case, combining an AutoRouteObserver with the manual tracking API is required to ensure each tab is tracked as a distinct screen. ```dart class TabRouteObserver extends AutoRouteObserver { @override void didInitTabRoute(TabPageRoute route, TabPageRoute? previousRoute) { Contentsquare().send(route.name); } @override void didChangeTabRoute(TabPageRoute route, TabPageRoute previousRoute) { Contentsquare().send(route.name); } @override void didPop(Route route, Route? previousRoute) { final routeName = previousRoute?.settings.name; if (routeName == null) return; if (_tabRouteNames.contains(routeName)) { Contentsquare().send(routeName); } } } [...] MaterialApp( navigatorObservers: [ ContentsquareNavigatorObserver(), TabRouteObserver(), ], ); ``` #### PageBuilder If you use a `pageBuilder` in your routes, make sure to set the page `.name`. Example using GoRoute: ```dart GoRoute( path: 'checkout', name: 'Checkout Screen', pageBuilder: (context, state) => MaterialPage( name: 'Checkout Screen', key: ValueKey(state.pathParameters), fullscreenDialog: true, child: const CheckoutScreen(), ), ), ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track screens","description":"Track screens with the Contentsquare Flutter SDK","url":"https://docs.contentsquare.com/en/flutter/track-screens/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track WebViews - Flutter (classic) description: Track webviews with the Contentsquare Flutter SDK lastUpdated: 12 August 2026 source_url: html: https://docs.contentsquare.com/en/flutter/track-webviews/ md: https://docs.contentsquare.com/en/flutter/track-webviews/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). WebView tracking links the Flutter SDK to the JavaScript tag running inside the WebView. ## Usage To enable WebView tracking, two steps are required: 1. Inject the Contentsquare Tracking Tag in WebView mode in the web pages loaded in your app's WebViews. For more information on this step, refer to [📚 Mobile Apps WebView Tracking Documentation](https://docs.contentsquare.com/en/webview-tracking-tag/). 2. Make sure JavaScript is enabled in your WebViews. 3. Wrap your WebView widget with `ContentsquareWebViewWrapper` widget and implement it as explained below. ## Implementation Warning Our implementation will work if and only if the WebView widget you are using in your app is relying on an underlying instance of `android.webkit.WebView` on Android and WebKit's `WKWebView` on iOS. The implementation can be done in two different ways depending on how your WebView allows the injection of scripts. These two different ways relies of two subtypes of `WebViewWrapperDelegate`: * `UserScriptWebViewWrapperDelegate` to inject the required Contentsquare script through User Scripts. Choose this if you use the `flutter_inappwebview` package. * `JSChannelWebViewWrapperDelegate` to inject the required Contentsquare script through JavaScript channel. Choose this if you use packages like `webview_flutter` or `flutter_webview_plugin`. ### Examples * Using UserScriptWebViewWrapperDelegate This example uses the [flutter\_inappwebview ↗](https://pub.dev/packages/flutter_inappwebview) `InAppWebView` widget. ```dart ContentsquareWebViewWrapper( delegate: UserScriptWebViewWrapperDelegate( builder: (BuildContext context, String userScript) { return InAppWebView( initialOptions: InAppWebViewGroupOptions( crossPlatform: InAppWebViewOptions( javaScriptEnabled: true, ), ), initialUrlRequest: URLRequest( url: Uri.parse(url), ), initialUserScripts: UnmodifiableListView([ UserScript( // Inject the script properly // by setting the `userScript` as source source: userScript, // Set the injectionTime as AT_DOCUMENT_START injectionTime: UserScriptInjectionTime.AT_DOCUMENT_START, ), ]), ); }, ), ) ``` Note You should always set the property `injectionTime` of `UserScript` to `UserScriptInjectionTime.AT_DOCUMENT_START`. `UnmodifiableListView` is imported from `dart:collection`. * Using JSChannelWebViewWrapperDelegate This example uses the [webview\_flutter ↗](https://pub.dev/packages/webview_flutter) `WebViewWidget` widget. ```dart webViewController.setJavaScriptMode(JavaScriptMode.unrestricted); ContentsquareWebViewWrapper( delegate: JSChannelWebViewWrapperDelegate( addJavaScriptChannel: (WebViewJSChannelHandler handler) { webViewController.addJavaScriptChannel( handler.channelName, onMessageReceived: (jsMessage) { handler.onMessageReceived(jsMessage.message); }, ); }, builder: (context) { return WebViewWidget(controller: webViewController); }, ), ); ``` Note You should always set the channel name to `handler.channelName` and call `handler.onMessageReceived(...)` in the JavaScript channel message callback. **Optional: detect the WebView context on dual-context pages** If the same page is served both in a regular browser and inside your app's WebView (dual-context tracking), the page usually selects which Contentsquare tag to load with an `isWebView()` guard. That guard must detect the WebView context **before** the page's tag script runs — otherwise the browser tag loads instead of the WebView tag (a tag "race condition") and native and web tracking are not linked. With `JSChannelWebViewWrapperDelegate` (for example when using `webview_flutter`), the SDK cannot inject a document-start script, so the reliable early signal is the user agent. Apply `handler.userAgent` to the controller **before** loading the URL: ```dart addJavaScriptChannel: (WebViewJSChannelHandler handler) { // Set the user agent before loading the page so the page // can detect the WebView context early. webViewController.setUserAgent(handler.userAgent); webViewController.addJavaScriptChannel( handler.channelName, onMessageReceived: (jsMessage) { handler.onMessageReceived(jsMessage.message); }, ); }, ``` Warning `WebViewController.setUserAgent(...)` **replaces the entire user agent** — it does not append to it. If your app relies on a custom user agent, applying `handler.userAgent` will overwrite it. In that case, either append the Contentsquare token to your own user agent (for example `setUserAgent('<your user agent> ${handler.userAgent}')`), or use `UserScriptWebViewWrapperDelegate` (for example with `flutter_inappwebview`), where the Contentsquare script that sets `window.CS_isWebView` is injected at document start, so no user agent change is needed. ## Validate WebView tracking To validate the tracking of WebViews, refer to the platform-specific instructions. * [📚 Android documentation](https://docs.contentsquare.com/en/android/track-webviews/#validating-the-implementation-on-the-web-side) * [📚 iOS documentation](https://docs.contentsquare.com/en/ios/track-webviews/#on-the-web-side) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track WebViews","description":"Track webviews with the Contentsquare Flutter SDK","url":"https://docs.contentsquare.com/en/flutter/track-webviews/","inLanguage":"en","dateModified":"2026-08-12T09:38:55+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track transactions - Flutter (classic) description: Track transactions with the Contentsquare Flutter SDK lastUpdated: 09 October 2025 source_url: html: https://docs.contentsquare.com/en/flutter/track-transactions/ md: https://docs.contentsquare.com/en/flutter/track-transactions/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). To associate a user's session with their potential purchases (and corresponding revenue), you must send the transaction via a dedicated API. Each transaction requires the following information: * `price` (`double`, required) * `currency` (`String`, required) * `transactionId` (`String`, optional) ```dart Contentsquare().sendTransaction(430, 'EUR', "testId"); ``` You can also use the `Currency` helper to get the list of ISO 4217 currencies. ```dart Contentsquare().sendTransaction(430, Currency.EUR.toStr()); ``` If the currency passed doesn't match our supported currencies, the SDK will send a currency value of "-1". This value will be interpreted as the default currency of the project. Warning **Each transaction must only be sent once**. A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track transactions","description":"Track transactions with the Contentsquare Flutter SDK","url":"https://docs.contentsquare.com/en/flutter/track-transactions/","inLanguage":"en","dateModified":"2025-10-09T13:23:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Troubleshooting - Flutter (classic) description: Need help? We share probable causes and recommended fixes lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/flutter/troubleshooting/ md: https://docs.contentsquare.com/en/flutter/troubleshooting/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/). When the SDK is not sending data as expected, use this page to identify probable causes and apply recommended fixes. Start by upgrading To narrow down the root cause and eliminate potential issues, upgrade to the [latest version of the SDK](https://docs.contentsquare.com/en/flutter/). If your issue persists after the upgrade and using this section, contact us. ## Sessions are not tracked For sessions to be tracked: * [A first screenview has to be sent](../track-screens/) * [The current user has to opt-in to have their actions tracked](../privacy/#handling-user-consent) ## SDK is not working on my hybrid app Contentsquare SDK [is not compatible](https://docs.contentsquare.com/en/flutter/compatibility/#compatibility-matrix) with hybrid applications. ## Cannot see in-app features on iOS In-app features requires a [specific configuration](https://docs.contentsquare.com/en/flutter/in-app-features/#implement-in-app-features-ios-only) on iOS. ## I lost some zoning data after changing my widget tree Contentsquare SDK uses zoning identifier that relies heavily on the structure of the widget tree. Changes to the widget tree such as moving, nesting, or removing a widget may result in the loss of tracking data. The Contentsquare Flutter SDK provides the [`ReliableTarget` widget](https://docs.contentsquare.com/en/flutter/reliable-targets/), designed to encapsulate the widget intended for reliable tracking. ## Transactions are sent multiple times A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ## Cannot see images and texts are incomprehensible in Session Replay By default, `Contentsquare` masks all types of content (texts, text fields, and images) except the SVG images and CustomPaints during Session Replays. It achieves this by providing a default `MaskingConfig` object if none is specified. The default configuration masks everything, ensuring that sensitive information is protected. However, you can override the default masking behavior by providing your own `MaskingConfig` object when starting the SDK via the `start` method. This allows you to customize the masking rules for your app according to your requirements. This allows you to customize the masking rules for your app according to your requirements. See [MaskingConfig](https://docs.contentsquare.com/en/flutter/session-replay/#how-to-use-maskingconfig) for more information. ## Masking / Unmasking Session Replay using in-app features settings is not reflected in the player The masking / unmasking of Session Replay through the in-app features settings is not yet supported by the Flutter SDK. This setting is intended for debugging purposes only. See [MaskingConfig](https://docs.contentsquare.com/en/flutter/session-replay/#how-to-use-maskingconfig) for more information. ## Session Replay is enabled but I see nothing when connecting to the URL Put your app in background to trigger the sending of the session to the server. Session Replay is not instantaneous and takes from 5 minutes to 30 minutes to be available. For Session Replay to work, sessions must be tracked: * [A first screenview has to be sent](../track-screens/) * [The current user has to opt-in to have their actions tracked](../privacy/#handling-user-consent) ## My replays not an exact rendering of my app There is no collection of the user's screen, but rather a reconstruction interactions based on the data collected by the SDK. The rendering may not be pixel-perfect, but it should give you a good idea of how users interact with your app. There are some [known limitations](https://docs.contentsquare.com/en/flutter/session-replay/#known-limitations) to the Session Replay feature. If you notice a limitation that is not referenced in our documentation, contact us. ## Session Replay requests are not sent from an Android emulator / iOS simulator If you struggle to watch a replay collected on an emulator/simulator, it may be due to some network constraints applied on your computer (VPN, company network restrictions, etc.). Check your configuration and/or use a real device. For more information about our endpoints and requests, see: * [Android - Requests are failing](https://docs.contentsquare.com/en/android/troubleshooting/#requests-are-failing) * [iOS - Requests are failing](https://docs.contentsquare.com/en/ios/troubleshooting/#requests-are-failing) ## Replays are extremely long It is important to remember that **an app kill does not end a session**. See [Session definition](https://docs.contentsquare.com/en/ios/how-the-sdk-works/#session-definition) for more information. If you leave the simulator/emulator running with the app in foreground, the session will not end, even if you are inactive. To better reflect actual end user behavior and avoid unusually long sessions (last hours), put the app in background or kill it. ## I use an HttpOverrides.global does not work During the initialization, the Contentsquare SDK overrides the `HttpOverrides.global` property. If you have to override `HttpOverrides.global` in your app - [use a custom HttpOverrides](https://docs.contentsquare.com/en/flutter/error-analysis/#use-a-custom-httpoverrides). ## SwiftContentsquarePlugin was registered twice There is a known issue with the [`background_locator` ↗](https://pub.dev/packages/background_locator) plugin which causes Contentsquare plugin to be registered twice. This issue has been mitigated and you can ignore this warning. If you are not using the `background_locator` plugin and encounter this warning, contact us. ## Requests are failing In order for Contentsquare to work, you need to make sure the following endpoints are not blocked by your network (VPN): | Request | Endpoint | Detail | | - | - | - | | Config file | `https://mobile-production.content-square.net` | See [Configuration](../how-the-sdk-works/#configuration) | | Analytics data (EU) | `https://m.csqtrk.net` `https://m.ba.contentsquare.net` `https://m.aa.contentsquare.net` | See [Sending data](../how-the-sdk-works/#sending-data) | | Analytics data (US) | `https://m-aus1.contentsquare.net` `https://m.bf.contentsquare.net` `https://m.af.contentsquare.net` | See [Sending data](../how-the-sdk-works/#sending-data) | | Monitoring | `https://l.contentsquare.net` | Used by the SDK to send SDK monitoring analysis in JSON format over HTTPS. | | Session Replay data (EU) | `https://ka-aeu1.contentsquare.net` `https://ka.ba.contentsquare.net` `https://ka.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Session Replay data (US) | `https://ka-aus1.contentsquare.net` `https://ka.bf.contentsquare.net` `https://ka.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Screenshot (EU) | `https://s.contentsquare.net` `https://b.ba.contentsquare.net` `https://b.aa.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Screenshot (US) | `https://s-aus1.contentsquare.net` `https://b.bf.contentsquare.net` `https://b.af.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Resources manager (EU) | `https://srm.ba.contentsquare.net` `https://srm.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Resources manager (US) | `https://srm.bf.contentsquare.net` `https://srm.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | ## App with multiple `RenderView`s The Contentsquare SDK does not support the use of multiple `RenderViews` within the same application. Using multiple `RenderViews` may cause the SDK to behave incorrectly. ## Webview heatmap support The Contentsquare SDK does not support `Heatmap` for webviews. ### Long Screenshot: Large Capture Limitation **Symptom:** The Long Screenshot capture completes the creation process, but then fails at the very end without a clear error message. **Explanation:** Long Screenshots can produce a very large amount of data. For reliability and performance reasons, the server enforces a maximum payload size (\~75 MB). Very long or content-heavy screens may exceed this limit, causing the screenshot to be rejected. **Workaround:** Capture a shorter area (reduce the scroll length) and/or reduce the amount of on-screen content (for example fewer or lighter elements), then retry the Long Screenshot. ## Screenshots fidelity ### Horizontal scrollviews Horizontal scrollviews are not supported during *Long Screenshot* and will be captured as if they were static. This may lead to screenshots that are not fully representative of what the user sees. ### Multiple vertical scrollviews When multiple vertical scrollviews are present on the same screen during *Long Screenshot*, the SDK will handle only the first one and ignore the others. This may lead to screenshots that are not fully representative of what the user sees. If the scrollviews are nested, the SDK will handle the outer scrollview and ignore the inner ones. ### Webviews The SDK does not capture the webviews inside the scrollviews during *Long Screenshot*. ### Dynamic content The SDK captures a screenshot of the screen at a given time. If the content of the screen changes dynamically (for example, due to animations or loading content) during the capture process, the resulting screenshot may not be fully representative of what the user sees. This could be the case when using widgets like `FlexibleSpaceBar` that can change size during the capture process or any other widgets handling animations. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Troubleshooting","description":"Need help? We share probable causes and recommended fixes","url":"https://docs.contentsquare.com/en/flutter/troubleshooting/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - iOS (classic) description: The Contentsquare iOS SDK changelog lastUpdated: 11 August 2026 source_url: html: https://docs.contentsquare.com/en/ios/changelog/ md: https://docs.contentsquare.com/en/ios/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). 📬 Stay updated! ## 4.52.1 - 2026.08.06 **Analytics** * Improved reliability of exposure rate and scroll rate **Session Replay** * **Bug fix:** fixed SwiftUI image foreground color issues. * **Bug fix:** fixed an issue where the keyboard was sometimes not displayed. * **Bug fix:** fixed a rare crash related to SwiftUI. ## 4.52.0 - 2026.07.29 * Bug fixes and performance improvements. ## 4.51.2 - 2026.07.27 Deprecated version This version is deprecated. Upgrade to the [latest version](https://docs.contentsquare.com/en/ios/). **Webviews** * **Bug fix:** fixed a synchronisation issue that could result in a "Webview Not Tracked" in the Session Replay Player * **Bug fix:** fixed an issue where coming back from background into a webview would result in a "Webview Not Tracked" in the Session Replay Player ## 4.51.1 - 2026.07.20 Deprecated version This version is deprecated. Upgrade to the [latest version](https://docs.contentsquare.com/en/ios/). * Re-signed the release artefacts with a new valid certificate to resolve a code-signing validation failure (`CSSMERR_TP_CERT_REVOKED`). No functional changes. ## 4.51.0 - 2026.06.05 **Session Replay** * Improve stability when calling APIs from background threads. * Fix harmonized masking behavior for fully SwiftUI-based apps. * Use the CSQ SDK version for full masking rules. **Analytics** * A more explicit message is displayed when the screenshot size exceeds server-side limit ## 4.50.0 - 2026.05.04 Minimum deployment change The minimum deployment target is now iOS 13.0 **Analytics** * The Session timeout definition changes from **30 minutes after being in background** to **30 minutes after last event**. See [Session definition](https://docs.contentsquare.com/en/ios/how-the-sdk-works/#session-definition). This change may impact reported session counts in the Contentsquare platform. The underlying data collection remains unchanged; only the session-splitting logic is affected. * Heatmaps: Improved tap data accuracy for screens with multiple scroll containers **Session Replay** * Add new API to stop Session Replay on demand ## 4.46.4 - 2026.07.20 * Re-signed the release artefacts with a new valid certificate to resolve a code-signing validation failure (`CSSMERR_TP_CERT_REVOKED`). No functional changes. ## 4.46.3 - 2026.04.10 **Session Replay** * Improved performance of view hierarchy processing, reducing CPU usage. * Fixed a threading issue that could cause occasional crashes. * Fixed an issue where some images could be missing in replays. **Analytics** * Improved runtime stability **Errors** * Enhanced tracking of initial crashes after application installation. ## 4.46.2 - 2026.03.20 **Session Replay** * Fixed a crash related to SVG images when harmonized masking is enabled **Analytics** * Fixed an issue where a screenshot capture would cause the app to become unresponsive ## 4.46.1 - 2026.03.05 **Analytics** * Zoning / Heatmap: Add support for SwiftUI `drawingGroup` **Session Replay** * Fixed a protobuf serialization crash * Fixed a crash related to `NSAttributedString` encoding ## 4.46.0 - 2026.02.13 **Session Replay** * Improved session synchronization between Session Replay and Product Analytics * Enhanced playback reliability when using `stopTracking()` followed by `resumeTracking()` * Strengthened playback stability when `optOut()` is triggered * Fixed nil replay link when callback is subscribed before `start()` * Enhanced stability when using `csMasking` SwiftUI modifier * Improved robustness against race conditions involving weak SwiftUI component references * Optimized handling of collections with unusually long durations **Errors** * Improved API error handling by ensuring URLs remain visible when invalid masking patterns are provided via `ErrorAnalysis.setURLMaskingPatterns()` **Analytics** * Improved Zoning metrics accuracy for some custom SwiftUI components * Fixed an issue where a screenshot captures would fail for React Native applications ## 4.45.6 - 2025.12.30 **Session Replay** * Fixed a crash due to infinite recursion when a sublayer references the parent view as delegate (issue observed in CorePlot) ## 4.45.5 - 2025.12.19 **Session Replay** * Supported `drawingGroup` for iOS 26+. * Fixed a rare crash when Session Replay stops. **Analytics** * Fixed a bug where some SwiftUI images wouldn't be displayed in the Zoning module ## 4.45.4 - 2025.12.12 **Session Replay** * Improved performance for large scroll view in SwiftUI. **Analytics** * Added support for SVG assets in the Zoning module ## 4.45.3 - 2025.12.05 **Session Replay** * Fixed an issue where `stopTracking` caused some screens to be unplayable. ## 4.45.2 - 2025.11.20 **Session Replay** * Fixed a rare crash that could occur when restarting Session Replay. * Resolved an issue where the app became unresponsive when calling `SKStoreReviewController.requestReview()` on older iOS versions. **Error Analysis** * Fixed a rare crash that occurred during API error collection. ## 4.45.1 - 2025.11.20 **Analytics** * Improved screen tracking with cross-platform SDKs ## 4.45.0 - 2025.11.14 API removal `forgetMe` API has been removed in this release. If you are still using this API, refer to [Privacy](https://docs.contentsquare.com/en/ios/privacy/#forget-me) for more details. **Analytics** * Fixed a crash related to Zoning and Heatmap data collection on iOS 26 devices **Session Replay** * Introduction of Harmonised Masking in Closed Beta Phase * Fixed a crash related to gesture capture on iOS 26 devices * Fixed an issue where the background color of an Image wouldn't be correctly rendered * Fixed a protobuf serialization crash on iOS 26 devices * Performance improvement on iOS 26 devices ## 4.44.3 - 2025.10.24 **Session Replay** * Fixed a rare crash related to gesture. ## 4.44.2 - 2025.10.24 **Session Replay** * Fixed a crash related to `AVPlayerViewController`. ## 4.44.1 - 2025.10.17 **Core SDK** * Fixed an issue with the SDK internal `Codable` conformance extension for `NSTextAlignment`. **Analytics** * Heatmaps: Fixed an issue where some taps would be inaccurate on iOS 26 devices ## 4.44.0 - 2025.10.06 **🚨 API removal notice** * Deprecated the `forgetMe` API is scheduled to be removed in the next 4.45.0 release. If you are still using this API, refer to [Privacy](https://docs.contentsquare.com/en/ios/privacy/#forget-me) for more details. **Analytics** * Improved iOS 26 support for Zoning and Heatmap analysis * ⚠️ Starting iOS 26: reliable targets are compatible with UIKit `accessibilityIdentifier` only. Read more at [Reliable targets](https://docs.contentsquare.com/en/ios/collected-data-points/#reliable-targets) * Improved data collection on segmented controls **Session Replay** * Improved iOS 26 support to display correctly text and images on SwiftUI views for apps built with Xcode 26 * Fix a crash related to bitmap rendering ## 4.43.3 - 2025.09.24 **Session Replay** * Fixed a bug where gradient backgrounds were not properly collected for React Native **Analytics** * Heatmaps: Fixed a crash related to frame computations ## 4.43.2 - 2025.08.19 **Core SDK** * Improved internal feature flag stability ## 4.43.1 - 2025.08.07 **Session Replay** * Fixed an issue where SwiftUI images were missing from the replay on iOS 26 devices for apps built with Xcode 16 ## 4.43.0 - 2025.07.31 **Session Replay** * Image/Text masking configuration in the CSQ Console * Added new APIs to start Session Replay on demand * Support Event Triggered Replay ## 4.42.4 - 2025.07.22 **Session Replay** * Fixed an issue related to CSInApp on iPad * Support for React Native New Architecture Text **WebView** * Fixed an issue related to config ## 4.42.3 - 2025.07.02 **Session Replay** * Improved Session Replay screen change consistency on Capacitor apps ## 4.42.1 - 2025.06.17 **Analytics** * Zoning Analysis: Fix a segmented controls identification issue **Session Replay** * Added support of apps changing key window * Fixed an issue related to session timeout that might lead to blank replays **Error Analysis** * Prevented a crash for HTTP/3 based requests ## 4.42.0 - 2025.06.11 **Survey** * Introducing [Surveys](../surveys/) (Beta). You can now integrate surveys into your apps using the designated trigger and collect feedback from end users. **Analytics** * Fixed an issue where a session could be mistakenly extended when the app is in background * Heatmaps: Improved handling of system view controllers **Privacy** * Updated of the Privacy manifest with additional collected data types **Session Replay** * Fixed an issue related to event batching that can lead to a blank replay * Improved performance for large scroll view * Improved support of SwiftUI for drawable content * Allowed to send data when device is connected to a hotspot ## 4.41.3 - 2025.05.16 **Analytics** * Fixed a potential issue for screenshots captured in a Flutter application **Session Replay** * Fixed a synchronisation issue between Contentsquare and Heap platforms ## 4.41.2 - 2025.05.06 * Fixed default value for session timeout ## 4.41.1 - 2025.04.16 **Session Replay** * Improved performance for large ScrollView ## 4.41.0 - 2025.04.02 **Analytics** * Fixed an issue where the long screenshot would contain blank content * Improved handling of `insetGroup` `Tableviews` in the long screenshot **Session Replay** * Fixed some `UIScrollView` updates not detected with iOS >= 18.2 ## 4.40.2 - 2025.02.20 **Analytics** * Fixed an issue that prevents Flutter screenshots to show up in the Zoning module ## 4.40.1 - 2025.02.18 **Analytics** * Zoning Analysis: Fixed an issue where obfuscated class names would lead to inconsistent metrics ## 4.40.0 - 2025.02.12 **Session Replay** * Fixed an issue where Session Replay was not playable when [Enable Session Replay](https://docs.contentsquare.com/en/ios/session-replay/#enable-session-replay-on-your-device) was toggled on * Full masking configuration by App/SDK version in the CSQ Console ## 4.39.0 - 2025.01.09 **Analytics** * The session number will be incremented when the application or the SDK version number has changed ## 4.38.3 - 2024.12.10 * Fix for webview not collected when added to view hierarchy with zero size. * Fix crash related to failed Tag fetching. ## 4.38.2 - 2024.11.28 **Session Replay** * Pass SDK version to Session Replay requests for further data processing. ## 4.38.1 - 2024.11.20 **Session Replay** * Fix masking of SwiftUI elements for all types of view modifiers * Fix a rare crash caused by pattern-based background color ## 4.38.0 - 2024.10.25 **Analytics** * The long screenshot capture is properly cancelled when the application goes to background * Fix an issue where sessions could be abnormally long when the application is in background ## 4.37.3 - 2024.10.22 **Session Replay** * Prevent a crash due to an issue with the rendering of certain SwiftUI elements. ## 4.37.2 - 2024.10.15 **Session Replay** * Fix webview replay for Flutter apps. ## 4.37.1 - 2024.10.01 **Analytics** * Fixed inconsistent target paths in Zoning Analysis by excluding zero-size WKWebView from index calculations. * Resolved screenshot failure when the Contentsquare Tag is not found in WKWebview. **Error Analysis** * Fixed a slowdown of network calls and a potential crash while collecting API errors. ## 4.37.0 - 2024.09.27 **Core** * New public API: projectID (the id of the project on the Contentsquare platform) * New public API: `sessionNumber` (the number of the session for the current user) **Analytics** * **Exposure Metrics:** Add a new API to prevent a UIScrollView from generating exposure events. For more details, check the [Exposure Metrics section](https://docs.contentsquare.com/en/ios/collected-data-points/#exposure-metrics) **Session Replay** * Immediately stop replay when collection rate is set to 0 ## 4.36.1 - 2024.09.20 **Session Replay** * Fixed an issue where some SwiftUI system images were missing from the replay ## 4.36.0 - 2024.09.06 **Core** * No data will be collected for applications running on iOS < 13.0 **Error Analysis** * The upload-symbols script now supports network proxies. * Error messages for the upload-symbols script are improved for clarity. **Session Replay** * Session Replay can now be blocked for certain application versions based on a pattern or range. * Improved support for text dynamic colors. **WebViews** * Automatically injects the global variable `window.CS_isWebView` in your pages to help you detect if they are loaded from a WebView. ## 4.35.1 - 2024.08.14 **Core SDK** * The in-app menu can now be displayed over modal views, such as Alerts and Action sheets * Limit SwiftProtobuf version up to 1.26.0, to prevent a potential crash ## 4.35.0 - 2024.08.05 **Analytics** * **Custom Variables:** Custom variables are now sent properly with the automatic screenview when the app enters foreground **Session Replay** * **Data consumption:** Session Replay will send much less data in some cases **WebViews** * Added Automatic Tag Injection to track locally hosted pages. ## 4.34.0 - 2024.07.02 **Core SDK** * **Delivery:** Remove Carthage support **Session Replay** * Fix an issue when masking a SwiftUI TextField with borders * Fix an issue where content might not be visible when app enters foreground * Improve shadow support for SwiftUI ## 4.33.1 - 2024.06.13 **Session Replay** * Fix memory usage for image capture. ## 4.33.0 - 2024.05.30 **Analytics** * Reliable targets: When a duplicated reliable target is found on screen, the SDK will not use the reliable target but fallback to the regular target path * Screenshot: The long screenshot capture is cancelled when the app is put in background ## 4.32.0 - 2024.04.23 **Analytics** * **Zoning:** Fix an issue where some UI elements could be captured twice * Fix an issue that could cause an erroneous session duration computation * Fix memory leaks **Session Replay** * Font are supported for NSAttributedString **Error Analysis** * CSCrashReporter is updated to 1.0.0 ## 4.31.2 - 2024.03.25 **Core SDK** * **Delivery:** Fix an issue with Xcode 15.3 when SDK is installed through Swift Package Manager ## 4.31.1 - 2024.03.19 **Core SDK** * **Delivery:** Fix a privacy manifest issue for required reason API `NSPrivacyAccessedAPICategorySystemBootTime` ## 4.31.0 - 2024.03.18 **Analytics** * Specific UI components can now be excluded from the screenshot capture, on specific screens, via the project configuration * Improve the capture of long screenshots, for screens with multiple scrolling components * Fix an issue on screenshot that could cause some views to be overlapped * Fix some memory leaks **Session Replay** * Add SR link retrieval inside the logs when then API callback is triggered * Fix on SR link where it would be updated twice when session is incremented **Error Analysis** * Add an API to disable errors auto collection ## 4.30.2 - 2024.02.29 **Error Analysis** * Fix an issue where network requests with status code 2xx are collected as API Errors. ## 4.30.1 - 2024.02.27 **Error Analysis** * Fix an issue where API Error details are not collected. ## 4.30.0 - 2024.02.23 **Session Replay** * Add new callback API for updates on replay link * Deprecate existing API to get replay link **Error Analysis** * Fix a rare issue in the Crash Reporter, that could cause a crash ## 4.29.1 - 2024.01.26 **Core SDK** * **Delivery:** Fix an internal configuration issue that would cause an App Store rejection because of our dynamic framework ## 4.29.0 - 2024.01.23 Deprecated version This version is deprecated. Upgrade to the [latest version](https://docs.contentsquare.com/en/ios/). **Core SDK** * **Session Replay:** Fix a bug where the masking of a view wouldn't be applied properly **Error Analysis iOS SDK** * **Delivery:** Error Analysis package is now delivered inside the main package **Core SDK**. If you had previously integrated the Error Analysis module into your application, you will need to remove it from your dependencies. Depending on how you integrated Error Analysis you can follow the instructions below: - SPM In the app's targets `General settings tab, in the Frameworks, Libraries, and Embedded Content` section remove `ContentsquareErrorAnalysisModule`. - CocoaPods 1. Remove one of the following line from your Podfile: ```ruby pod 'CS_ErrorAnalysis' pod 'CS_ErrorAnalysis_STATIC' ``` 2. Run command `pod update` - Carthage Update the reference in your Cartfile: **Cartfile** ```diff binary "https://raw.githubusercontent.com/ContentSquare/CS_iOS_SDK/master/carthage/ContentsquareErrorAnalysisModule.json" github "ContentSquare/CS_iOS_CrashReporter" ~> 0.0.3 ``` - Manually 1. Remove `ContentsquareErrorAnalysisModule.xcframework` stored in the project folder 2. Select the target of your project in Xcode and go to tab `General` -> `Frameworks, Libraries and Embedded Content` and remove `ContentsquareErrorAnalysisModule.xcframework` by selecting it and clicking on `-` 3. Select the target of your project in Xcode and go to tab `General` -> `Frameworks, Libraries and Embedded Content` and add `CSCrashReporter.xcframework` by clicking on `+` then `Add Other...` -> `Add Files...` 4. Clean build folder (in Xcode `Product` > `Clean Build Folder...`) and build/run your app You can then remove all `import ContentsquareErrorAnalysisModule` occurrences in the source code of your app. ## 4.28.0 - 2023.12.19 Deprecated version This version is deprecated. Upgrade to the [latest version](https://docs.contentsquare.com/en/ios/). **Core SDK** * **Privacy manifest:** SDK now includes a privacy manifest. See [App Store Privacy Guidelines Compliance](https://docs.contentsquare.com/en/ios/privacy/#app-store-privacy-guidelines-compliance) section for more details * **Signature:** SDK is now digitally signed and can be verified automatically in Xcode 15 * **ForgetMe:** This API is now deprecated. See the [Privacy section](https://docs.contentsquare.com/en/ios/privacy/#forget-me) for more details. * **Session Replay:** Fix a crash related to threading issues in SRM module * **Session Replay:** Fix an issue when masking containers in SwiftUI * **CS InApp:** Fix a crash when accessing replay link * **Screenshots:** Fix a bug where taking a screenshot could cause the app to freeze on some screens containing multiple `UIWindow` **Error Analysis iOS SDK** * **Privacy manifest:** SDK now includes a privacy manifest * **Signature:** SDK is now digitally signed and can be verified automatically in Xcode 15 ## 4.27.1 - 2023.11.30 **Core SDK** * **Zoning analysis:** Fix a bug where a long screenshot wouldn't be scrollable in the Zoning module * **Zoning analysis:** Fix a bug where some elements of a long screenshot wouldn't appear in the Zoning module ## 4.27.0 - 2023.11.16 **Core SDK** * **Zoning analysis:** Improve the support of SwiftUI LazyStacks in the Zoning module * **Session Replay:** Fix a bug that could cause applications using `AVPlayer` to crash ## 4.26.0 - 2023.10.18 **Core SDK** * **Screenshots:** Display more detailed error message in case of failure **Error Analysis iOS SDK** * **WebView errors:** Collect JS, API, and custom errors occurring in WebViews. More info on [WebView errors](https://docs.contentsquare.com/en/webview-tracking-tag/error-analysis/) * **Crash Reporter:** Added support for compressed dSYMs and [fastlane](https://docs.contentsquare.com/en/ios/error-analysis/#use-fastlane-to-upload-dsyms). More info on [Upload dSYMs](https://docs.contentsquare.com/en/ios/error-analysis/#use-script-to-upload-dsyms) ## 4.25.2 - 2023.09.22 **Core SDK** * **Zoning analysis:** Fix an issue with Screenshots that could lead to incorrect data ## 4.25.1 - 2023.09.13 **Error Analysis iOS SDK** * **API Errors:** Fix a crash when passing nil data to `URLSession.uploadTask(with request: URLRequest, from bodyData: Data)` for background sessions. ## 4.25.0 - 2023.08.25 **Core SDK** * **Zoning analysis:** Fix an issue with identifying some elements * **Session Replay:** Fix an issue with gesture displayed over WebViews * **Session Replay:** Improve screen duration calculation ## 4.24.0 - 2023.07.14 **Core SDK** * **Session Replay:** Fix a memory leak that could happen when Session Replay was stopped * **Session Replay:** Fix an issue with views being wrongly masked/unmasked * **Misc:** Fix a bug where user sessions would span over abnormally long periods of time. **Error Analysis iOS SDK** * **API Errors:** Fix a memory leak related to URLSessionDelegate ## 4.23.0 - 2023.06.09 **Core SDK** * **Custom Variables:** The [Custom Variables feature](https://docs.contentsquare.com/en/ios/track-custom-variables/) is now in General Availability * **Screenshots:** Long Screenshots feature is now in General Availability * **Exposure Metrics:** Exposure metrics feature is now in General Availability * **Zoning analysis:** [Reliable targets feature](https://docs.contentsquare.com/en/ios/collected-data-points/#reliable-targets) is now available for UIKit views * **Integrations:** It's now possible to use [Adobe Analytics](https://docs.contentsquare.com/en/ios/use-adobe-analytics/) with Contentsquare * **Track WebView:** Introducing new WebView tracking relying on [Web Tracking Tag](https://docs.contentsquare.com/en/webview-tracking-tag/). * **Session Replay:** WebView support. See [Session Replay WebView documentation doc](https://docs.contentsquare.com/en/ios/session-replay/#configure-webviews) * **Session Replay:** Fix a masking issue for TextField on SwiftUI * **Session Replay:** Fix a memory leak related to masking * **Session Replay:** Fix an issue that would cause some collected screens to appear grey in the Session Replay player * **Session Replay:** Add a new API 'sendUserIdentifier' to search a replay based on a personal user identifier [See the Session Replay Send user identifier section](https://docs.contentsquare.com/en/ios/session-replay/#send-user-identifier). **Error Analysis iOS SDK** * **API Errors:** Update log level to info for API Errors activation log. ## 4.22.1 - 2023.05.05 **Core SDK** * **Exposure Metrics:** Exposure metrics feature is now part of the SDK (Beta phase). It will help you measure engagement directly in zoning by showing which zones are attracting clicks, or on the contrary being ignored. * **Screenshots:** Improved support of 'LazyVStack', the content is now properly captured * **Session Replay:** Fix a bug where buttons with background images wouldn't be displayed correctly **Error Analysis iOS SDK** * **Crash Reporter:** Create script to upload dSYM files to symbolicate crashes. * **Crash Reporter:** Collect stack trace and details for crashes. * **Misc:** Fix a bug that caused an error when the SDK was imported. ## 4.21.0 - 2023.04.07 **Core SDK** * **Misc:** Fix a bug where user sessions would span over abnormally long periods of time. * **Misc:** Add contextual information in the log displayed when an API is used before the SDK can start. **Error Analysis iOS SDK** * **Crash Reporter:** Collect basic information for crashes. * **⚠️ Added [PLCrashReporter ↗](https://github.com/microsoft/plcrashreporter) dependency:** * **API Errors:** Compress API Error details and limit the size of the collected information. * **API Errors:** Limit API errors to 20 per screenview. ## 4.20.0 - 2023.02.24 **Core SDK** * **Custom Variables:** The [Custom Variables feature](https://docs.contentsquare.com/en/ios/track-custom-variables/) is now part of the SDK (Beta phase). * **Screenshots:** Fix a bug where taking a screenshot of a modal view would fail. **Error Analysis iOS SDK** * **API Errors:** API Troubleshooting details. * **API Errors:** Print a console log for screen-related events sent before first screen event. ## 4.19.0 - 2023.01.26 **Core SDK** * **Session Replay:** Fix a bug where SwiftUI Texts wouldn't be masked/unmasked properly * **Misc:** Fix user ID renewal bug on simulator **Error Analysis iOS SDK** * **API Errors:** Fix a bug where API Errors were sometimes missed. * **API Errors:** Add a new API to mask URL by patterns. ## 4.18.0 - 2022.12.16 **Core SDK** * **Session Replay:** Fix a bug where UITextFields wouldn't be masked properly * **Session Replay:** Fix a bug where UITextFields wouldn't be rendered properly in the replay * **Session Replay:** Fix a bug where gestures on masked TextFields wouldn't be handled correctly * **Misc:** Fix a bug where the screenshot button would disappear in landscape mode **Error Analysis iOS SDK** * **API Errors:** Collect failed network requests ## 4.17.0 - 2022.10.24 * **Drop support for iOS 11.** Minimum support version is now iOS 12.4. [See Compatibility section](https://docs.contentsquare.com/en/ios/compatibility/). * **Session Replay:** Add a Log when Session Replay data exceeds the 8 MB limit for a screenview * **Session Replay:** Improve background on unmasking/masking in UIKit and SwiftUI * **Session Replay:** Custom components (or system components not listed) are now masked in the default masking state * **Session Replay:** Masking is applied recursively to all children unless a specific rule has been applied to one of them. See [Masking and Unmasking behaviors on a parent view](https://docs.contentsquare.com/en/ios/session-replay/#masking-and-unmasking-behaviors-on-a-parent-view) * **Log visualizer** Enabled by default when in-app features are activated ## 4.16.0 - 2022.09.12 * **Session Replay:** Fix a bug where the texts built with SwiftUI wouldn't appear in the replays * **Session Replay:** Fix a bug where the modals and alerts wouldn't appear in the replays * **Screenshots:** Fix a bug where tab bar icons wouldn't be displayed properly * **Misc:** Add a CSLIB log when a request from CS SDK fails * **Dynamic Variables:** Key length increased from 50 to 512 chars ## 4.15.1 - 2022.07.26 * **Misc:** Fix a bug where the SDK would send several `AppHide` events when app goes to background ## 4.15.0 - 2022.07.21 * **Screenshots:** Fix a bug where tab bar icons wouldn't be displayed properly * **Misc:** Fix a bug where the app would become inactive after calling a review prompt with SKStoreReviewController.requestReview() ## 4.14.0 - 2022.06.08 * **Session Replay:** Add new high-level APIs to ease the masking implementation: `maskTexts`, `maskImages`, `maskTextInputs` [See the Session Replay Data Masking section](https://docs.contentsquare.com/en/ios/session-replay/#personal-data-masking) * **Session Replay:** SwiftUI is now fully supported in Session Replay; all SwiftUI elements are properly collected * **Session Replay:** Fix a bug where Session Replay data collection wouldn't stop when Contentsquare.stopTracking() is called * **Screenshots:** Fix a bug where WebViews would have incorrect position * **Misc:** Improvements and bug fixes ## 4.13.0 - 2022.05.05 * **Session Replay:** Add a new API 'setDefaultMasking' to ease the masking implementation [See the Session Replay Data Masking section](https://docs.contentsquare.com/en/ios/session-replay/#personal-data-masking) * **Session Replay:** Add a new event in the replay when the quality of the replay has changed * **Session Replay:** Add new events in the replay when the replay starts and stops * **Session Replay:** Fix a bug where Session Replay data collection wouldn't start as expected * **WebViews tracking:** Update of the WebViews injection mechanism to support new events sent by the WebView Tracking Tag (Dynamic variable, Transaction, Opt-in, Opt-out) [See the WebView Tracking Tag documentation](https://docs.contentsquare.com/en/webview-tracking-tag/) * **Screenview tracking:** Disabled automatic screenview after background/foreground when screen name is empty [See Screenview after app in background section](https://docs.contentsquare.com/en/ios/track-screens/#screenview-after-app-in-background) * **Misc:** Improvements and bug fixes ## 4.12.0 - 2022.04.05 * **Contentsquare visual identity:** Updated Contentsquare logo and screenshot button to match the new visual identity * **Screenshots:** More accurate message displayed in case of error. * **Session Replay:** Add feature to select different quality levels for Wi-Fi and Cellular [See the Session Replay Quality Levels section](https://docs.contentsquare.com/en/ios/session-replay/#quality-levels) * **Session Replay:** Fix a bug where the session number would not be correctly incremented. * **Session Replay:** Fix a bug where the Session Replay link would be erroneous. * **Session Replay:** Misc improvements and bug fixes ## 4.11.0 - 2022.02.04 * **Session Replay:** Data consumption optimization on scrollable views; Fixed an issue where sessions were wrongly flagged as collected. * **Included in tracking:** When in-app features are enabled, the device is now always included in tracking. * **Manual Integration:** Updated process for dynamic and static linking. See "Manual Integration" in [How to include it section](https://docs.contentsquare.com/en/ios/#install-the-sdk) * **Misc:** Minor improvements and bug fixes. ## 4.10.1 - 2022.01.14 * **Static Framework:** Fixed an error when uploading app to App Store Connect. * **Manual Integration:** Our SDK can be integrated manually. ## 4.10.0 - 2021.12.13 * **SDK Version:** Fixed a bug caused by a new Xcode option introduced in version 13 called "Manage Version and Build Number", enabled by default in the App Store distribution process. This option is overriding the SDK version with the application version. * **Static Framework:** Fixed a build error when code coverage is disabled. Manual Install is not supported anymore, use Swift Package Manager or CS\_iOS\_SDK\_STATIC instead. [See How to include it section](https://docs.contentsquare.com/en/ios/#install-the-sdk). * **Framework:** Fixed a warning in Xcode 13 and newer. * **Session Replay:** Added a screenview event to assign inactivity period to the right screen. * **Network connectivity:** Now able to identify 5G network. ## 4.9.0 - 2021.11.04 * **Swift Package Manager**: Our SDK is now distributed on Swift Package Manager. [See How to include it section](https://docs.contentsquare.com/en/ios/#install-the-sdk). * **CocoaPods Static Framework**: Our SDK can be linked statically on CocoaPods. [See How to include it section](https://docs.contentsquare.com/en/ios/#install-the-sdk). * **Drop support for iOS 10.** Minimum supported version is now iOS 11. [See Compatibility section](https://docs.contentsquare.com/en/ios/compatibility/) * **SDK Log Visualizer:** This new module lets you see the live stream of events detected by our SDK (logs) directly in Contentsquare. Check out the [Viewing logs in the Contentsquare platform section](https://docs.contentsquare.com/en/ios/in-app-features/#viewing-logs-in-the-contentsquare-platform). * **Misc:** Minor improvements and bug fixes. ## 4.8.0 - 2021.10.06 * **Session Replay:** Minor improvements around fidelity and start logic. * **Misc:** Minor improvements and bug fixes. ## 4.7.0 - 2021.09.22 * **⚠️ SDK now uses XCFrameworks for Carthage**: follow [this guide ↗](https://github.com/Carthage/Carthage#migrating-a-project-from-framework-bundles-to-xcframeworks) to migrate from framework bundles to XCFrameworks. * **⚠️ Added Swift Protobuf dependency:** If you are using **Carthage** or **static framework**, follow [the dedicated documentation](https://docs.contentsquare.com/en/ios/#install-the-sdk) to add this dependency to your project. [More info on Swift Protobuf ↗](https://github.com/apple/swift-protobuf). * **Xcode Compatibility:** From this version, the SDK only works with Xcode 12.5 and newer. * **Disable Session Replay for specific app versions:** Introducing capability to disable Session Replay for specific app versions (controlled from back office). * **Session Replay improvements:** Optimizations around **data format, storage and sending strategy**; **Fidelity improvements** (dialogs, text, buttons). * **Fixed Session Replay issue when using Simulator**: causing the data to be sent on the wrong endpoint. * **Fixed Session Replay bug:** causing a crash with WebKit in some cases. * **Misc:** Minor improvements and bug fixes. ## 4.6.1 - 2021.08.31 * **Misc:** Minor improvements and bug fixes. ## 4.6.0 - 2021.08.10 * **Disable auto-start:** Option to start the SDK in a manual method instead of starting automatically. Check out the [Manual Start section](https://docs.contentsquare.com/en/ios/track-screens/#manual-start) ## 4.5.0 - 2021.07.26 * **Session Replay:** Fidelity improvements; Improved data sending for better performance; supports keyboard display; * **Stability:** Fixed a crash caused by Session Replay code in edge cases. * **Misc:** Minor improvements and bug fixes. ## 4.4.0 - 2021.06.23 * **Session Replay:** Fidelity improvements; displays when app is put in background; when masked, text is now replaced by `lalala`; ability to send data over cellular network (if feature is enabled); requests are now compressed; replay link button added to in-app features settings. * **In-app features:** Fixed a bug that caused in-app features enabling to fail the first times. * **Misc:** Minor improvements and bug fixes. ## 4.3.1 - 2021.06.03 **React Native related:** Fixed a bug on alerts impacting iOS app running with React Native 0.64+. **WebViews:** Fixed a potential issue related to WebViews management. ## 4.3.0 - 2021.05.26 * **Session Replay:** We now support dialogs and device orientation (landscape mode); fidelity improvements and bug fixes; mask/un-mask types from in-app features settings; * **Screenshot button:** Fixed an issue that made the button disappear on long press * **Screenshot:** Display error message when capturing screenshot before screenview * **Track screen:** when API called but no screen name is pushed, the SDK will use a default value "missing screenName" with the name of the View Controller. * **Logs:** Logs intended for Contentsquare SDK developers (Verbose) are now hidden to make it less confusing, it means you can now filter on `CSLIB`. We also improved logs to debug WebView tracking. ## 4.2.0 - 2021.03.12 * **Session Replay:** Session Replay feature is now part of the SDK and disabled by default. This feature is only accessible to customers participating in the Early Access program. For more information reach out to your Contentsquare contact. ## 4.1.0 - 2021.01.21 * **Screenshot capture:** Fix a bug causing the app to crash when capturing a screenshot in an edge case scenario. * **Screenshot capture:** Screen name is now displayed when capturing a screenshot (on the "screenshot in progress/success/fail" screens) * **WebView:** WebView tracking back-office setting has been removed. WebView tracking is now always enabled. * **Misc:** Minor improvements and bug fixes. ## 4.0.1 - 2021.01.11 **Session:** Corrected a bug preventing a session to end because of a dynamic variable triggered before App Start. ## 4.0.0 - 2020.10.28 * **In-app features activation:** A simpler and unified way to enable features living inside the SDK (Screenshot Capture and Logs) along with its tracking capabilities. See [Enable in-app features section](https://docs.contentsquare.com/en/ios/in-app-features/) * **WebView:** Minor improvement to enable WebView zoning analysis * **Screenshot**: Minor improvement for handling clipped views **Upgrading from a previous version:** Make sure to remove the screenshot mode flag (`Contentsquare.enableScreenshots = true`) used to enable screenshot mode and to [implement in-app features](https://docs.contentsquare.com/en/ios/in-app-features/#implement-in-app-features). ## 3.2.1 - 2020.08.26 * **Disable logs and clipboard access on iOS 14:** The upcoming iOS 14 will embark a banner notifying users when apps are accessing the clipboard. To prevent this from happening, Logs are disabled on iOS 14. ## 3.2.0 - 2020.07.27 * **Drop support for iOS 9.** Minimum support version is now iOS 10. [See Compatibility section](https://docs.contentsquare.com/en/ios/compatibility/) * **Dynamic Variables:** Key and value are now trimmed when maximum length is exceeded. If key or value are empty, the SDK now sends the literal string "cs-empty" instead. [See Dynamic Variables section](https://docs.contentsquare.com/en/ios/track-dynamic-variables/) * **Transaction currency:** Lower and Uppercase are both supported. * **Screenshots:** Improvements for React Native screens and screenshot size * **Logs:** Some improvements for logs. * **SwiftUI Support:** Now providing official support for SwiftUI (Screenshot Mode, gestures tracking, etc.) * Minor improvements and bug fixes. ## 3.1.1 - 2020.04.07 * Minor bug fix ## 3.1.0 - 2020.03.30 * **New logs:** This version brings completely redesigned logs for better understanding of the SDK behavior. See dedicated section [Debugging and logging](https://docs.contentsquare.com/en/ios/in-app-features/#debugging-and-logging). * **Enable Screenshot Mode:** New name for the API allowing for Screenshot Mode enablement: `enableScreenshot`. The previous API `isDebug` is now marked as deprecated. * **Screenshot Button**: Fix issue related to screenshot button disappearing in some situations: behind a modal, after keyboard displayed, etc. * **Dynamic Variables:** The API is now available in Objective-C. This is also a Prerequisite for React Native support. * **Track Transactions - Currency:** We now provide the ability to pass the currency as an "alphanumeric code" (example: "USD") on top of the "numeric code" (example: "840"). See the dedicated section [Track transactions](https://docs.contentsquare.com/en/ios/track-transactions/). * Minor improvements and bug fixes ## 3.0.0 - 2020.01.15 * **Breaking change:** the main class `ContentSquare` is renamed `Contentsquare` (lower-case `s`) and the framework is now called `ContentsquareModule`. * Gesture tracking: now using the native system gesture recognizer * **Performance improvements**: Impact on CPU has been reduced. See [Impact on performance](https://docs.contentsquare.com/en/ios/impact-on-performance/) section. * **Xcode/Swift Compatibility:** From this version, the SDK will be compatible with all future Swift versions * **Dynamic Variables:** Enforce limitation for the key and value length. * Minor improvements and bug fixes * **Static framework** is now available. See [Using the static framework (manual install)](https://docs.contentsquare.com/en/ios/) tab in the "*Add Contentsquare to your app*" section. ## 2.2.2 - 2019.11.20 * Adding support to Swift 5.1.2 and Xcode 11.2 **/!\ *This version does not support previous Xcode versions.*** ## 2.2.1 - 2019.10.11 * Improvement around events storage management when the device storage is full ## 2.2 - 2019.09.26 * **Dynamic Variables:** Send custom data to Contentsquare for session segmentation. [Dynamic Variables API](https://docs.contentsquare.com/en/ios/track-dynamic-variables/) * **Screenshot mode launched at App start:** No need to shake the device to trigger Screenshot Mode dialog. Benefits: works on a simulator and avoids conflict with features based on shake detection. * **CollectionView and TableView tracking:** We improve the gestures tracking accuracy for those elements. * **Support for Swift 5.1 and Xcode 11** * Use lower priority QoS for event requests * Minor improvements related to screenshots ## 2.1.3 - 2019.08.07 * Minor improvement to prepare transaction API support for React Native. ## 2.1.2 - 2019.07.29 * Another minor improvement to make our SDK compatible with other SDKs. ## 2.1.1 - 2019.07.19 * Minor improvement to make our SDK compatible with other SDKs. ## 2.1 - 2019.06.12 * **Track screens**: Implement the new [Track Screen API](https://docs.contentsquare.com/en/ios/track-screens/) to accurately track `screen_view` events for all your app screens. * **User Consent required by default**: The default privacy setting for every new app will be set to opted-out by default. This means every new user will be opted-out until the [Opt-in API](https://docs.contentsquare.com/en/ios/privacy/#opt-in) will be called. * Swift 5 support * Xcode 10.2 support * Screenshots improvements * Add support for HKD currency when tracking Transactions * Other minor improvements and bug fixes ## 2.0 - 2019.03.20 * Add screen URL customization * URL structure change: added the screen title in the query parameter to match a standard format between iOS and Android * **Screenshot mode** * **WebView tracking** * Screen screenshot quality improvements * Minor improvements and bug fixes ## 1.0.6 - 2018.12.06 * Minor improvements and bug fixes ## 1.0.5 - 2018.11.22 * Minor improvements and bug fixes ## 1.0.4 - 2018.11.15 * Change screen elements identification (target view path collected with gestures). ## 1.0.3 - 2018.11.01 * Add Xcode 10.1 support * Fixed integration bug related to private modules ## 1.0.2 - 2018.10.22 * Minor improvements and bug fixes ## 1.0.1 - 2018.10.18 * SDK is now available on `CocoaPods` and `Carthage` * Minor improvements and bug fixes ## 1.0 - 2018.09.14 * iOS SDK 1st version ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare iOS SDK changelog","url":"https://docs.contentsquare.com/en/ios/changelog/","inLanguage":"en","dateModified":"2026-08-11T14:12:25+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Collected data points - iOS (classic) description: Events and metadata collected by the iOS SDK lastUpdated: 05 June 2026 source_url: html: https://docs.contentsquare.com/en/ios/collected-data-points/ md: https://docs.contentsquare.com/en/ios/collected-data-points/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). The iOS SDK collects request metadata, gesture events, lifecycle events, transactions, and dynamic variables, all serialized as JSON and sent to the server in batches. * The events are in JSON format, which lists the properties and their description in comment. * Events are sent to the server in batches. * A batch is a subset of events originating from one session. A session can send events in more than one batch. * The batch size is defined in a run configuration file specific to each app (50 events by default). ## Requests meta data Each batch has a common header, a set of device specific, and repeatable information and an array of events, which is immutable. The header is composed at the moment of sending, so it has to be constant info ONLY. The array in the payload is data stored at the moment of collection. The structure of the batches of events will have the following format: ```javascript { pid:8, // int - ProjectId - represented in the mobile config format uid:"ac1529a7-59f6-49d9-b254-6f0a22f57284", // String - uuid Unique user ID dt:4, // int - device type (loosely enforced enum - [sdk-phone : 4, sdk-tablet :5]) dma:"Samsung", // String - device manufacturer. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. dmo:"SG", // String - device model. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. os:"10.0", // String - os version (Android version name 8.0, 9.0, 10.0) l:"en_US", // String - Language in iso-639 format https://www.ibabbleon.com/iOS-Language-Codes-ISO-639.html tz:"Europe/Paris", // String - timezone https://en.wikipedia.org/wiki/List_of_tz_database_time_zones now:1522159618000, // long - timestamp when the batch was sent to:{ // object - type origin of the event an:"appname" // String - application name st:"sdk-android", // String - type of sdk sf:"release", // string - sdk flavor/variant [release/debug/god] }, r:{ // Device - resolution. w:1080, // int - width h:1920 // int - height d: 1.5 // The device density as float. Its values can vary between (0.75 and 10) }, pl:[] // JSON array payload - list of event objects, see below } ``` ## Events ### Events meta data All events have a common first part (don't confuse it with the header explained above). This common section is data which is common for all events by type but is gathered at the moment the event occurred. This common section is a part of the actual event payload. ```javascript { upt:1522, // long - system update in milliseconds euid:"euid", // String - event UUID url:"app-and://identifier/mainPath/secondaryPath?title=screeName", // String - screenName is passed in the title query Parameter scn:4, // int - the number of screens already shown in the session c:3, // int - connectivity type [-1 - offline, 0 - error, 1 - wifi, 2 - 2g, 3 - 3g, 4 - 4g] ci:"verizon", // String - carrier_id when user is on mobile network o:1, // int - orientation [0 = portrait, 1 = landscape] vo:{ // object - version origin of the event sv:"2.1", // string version of the sdk sb:4, // int - sdk build number av:"appVersion", // String - application version af:"appFlavor" // String - application string - [release/debug/god] ab:1 // int - application build number }, sn:1, // int - session id (positive int) t:12894726459435 // long - timestamp of the event (in milliseconds) } ``` All event specific properties are appended to this JSON object. ### App Start This event describes the absolute start of the app. The trigger for this event is the absolute start of the app. This is the first event sent when the SDK is invoked. ```javascript ea: 0; // int - event action - defined above ``` ### App Show This event is sent when the user brings the app in the foreground (switching from another app, exiting lock screen, etc.). This event means the app is focused. ```javascript ea: 1; // int - event action - defined above ``` ### App Hide This event is sent when the user exits (minimizes) the app, or switches to something else. This event means the app is not focused and the session might end, but we have not completely ended the session yet, as the user might return. ```javascript ea: 2; // int - event action - defined above ``` ### Screenview Everything starts with a View event. This is an event which describes the equivalent of a "page view" on the web. This event is sent when the Track Screen API is called. ```javascript ea:4 // int - event action - defined above st:"title", // String - screen title sl:34543 // int - (load time) screen load time (diff between last action and this event) ``` ### Tap Single Finger gesture event, when the user is interacting with a loaded screen. This is an event which describes the equivalent of a "click" in the web. This event is defined by the following sequence of touch events: * Touch Down -> N x Touch Move -> Touch Up ```javascript ea:6 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ur: true, // boolean - was this a "responsive" touch event (the target view had a handler) ``` ### Long press Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Duration: > 500ms * Distance: < 24 dp ```javascript ea:8 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ``` ### Drag (Slow Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity < 100 dp/s ```javascript ea:9 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance dragged tvv:100 // int - target view velocity while dragging dp/s ``` ### Flick (Fast Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity > 100 dp/s ```javascript ea:10 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view graph path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance scrolled tvv:100 // int - target view velocity while scrolling dp/s ``` ### Transaction To track transactions we provide a public API which can send a transaction object (see section [Track Transactions](https://docs.contentsquare.com/en/ios/track-transactions/)). This object must contain the following parameters: ```javascript ea:16, // int - event action - defined above tr:{ // a json object with different properties defining the transaction made vl: 20.0, // mandatory - float - the value of the transaction cu: 978, // mandatory - int - the ISO 4217 code of the currency of the transaction id: "32akjkljklJ575775" // optional - string - an id for the transaction } ``` ### Dynamic variables To track dynamic variables we provide a public API (see [Dynamic variables](https://docs.contentsquare.com/en/ios/track-dynamic-variables/)). **Event with a string value** ```javascript ea:18, // int - event action - defined above k:"key", // String - Custom key assigned by client. v:"value" // String - Custom value assigned by client. ``` **Event with a number value** ```javascript ea:19, // int - event action - defined above k:"key", // String - Custom key assigned by client. v: 2344 // Integer - Custom value assigned by client. ``` ## Reliable targets Limitations * For now, reliable targets are available for UIKit only. * If the view doesn't qualify to be a reliable target then we use our current mechanism for zoning * Reliable identifier must be unique per screen * In iOS 26, `restorationIdentifier` and `tag` are no longer supported for reliable targets. As such, `accessibilityIdentifier` is the sole property used for this purpose. In the Zoning Analysis module, reliable targets are assigned to zones to ensure that a `UIView` remains accessible in the view hierarchy, even if it has been moved within the same page. Having a reliable target for a view or a container of views enables the analysis of data across various Screenshots from different dates and versions, including layouts or A/B testing variations. One of the following properties must be assigned for a view to have a reliable target. Our SDK will check the properties in this order: 1. [`accessibilityIdentifier` ↗](https://developer.apple.com/documentation/uikit/uiaccessibilityidentification/1623132-accessibilityidentifier) 2. [`restorationIdentifier` ↗](https://developer.apple.com/documentation/uikit/uiviewcontroller/1621499-restorationidentifier) 3. [`tag` ↗](https://developer.apple.com/documentation/uikit/uiview/1622493-tag) ### accessibility Identifier if the view has `accessibilityIdentifier` it uses it as first priority and provides a short reliable target. Example: ```swift /* [SalesViewController] ViewOne | viewTwo / | \ viewThree viewFour viewFive */ let viewOne = UIView() viewOne.accessibilityIdentifier = "rootView" let viewTwo = UIView() viewTwo.restorationIdentifier = "dichotomy" let viewThree = UIButton() viewThree.accessibilityIdentifier = "on_sale" let viewFour = UIButton() viewFour.accessibilityIdentifier = "new_arrivals" let viewFive = UIButton() viewFive.accessibilityIdentifier = "for_kids" viewTwo.addSubview(viewThree) viewTwo.addSubview(viewFour) viewTwo.addSubview(viewFive) viewOne.addSubview(viewTwo) // viewThree target would be: UIButton[ai:SalesViewController.on_sale] // viewFour target would be: UIButton[ai:SalesViewController.new_arrivals] // We change the view hierarchy viewThree.removeFromSuperview() viewFour.addSubview(viewThree) // viewThree target would be: UIButton[ai:SalesViewController.on_sale] // viewFour target would be: UIButton[ai:SalesViewController.new_arrivals] ``` ### restoration Identifier If the view has `restorationIdentifier` and no `accessibilityIdentifier` then it provides a long reliable target. ```swift /* [SalesViewController] ViewOne / viewTwo / \ viewThree viewFour */ let viewOne = UIView() viewOne.restorationIdentifier = "trichotomy" let viewTwo = UIView() viewTwo.restorationIdentifier = "dichotomy" let viewThree = UIView() let viewFour = UIView() viewTwo.addSubview(viewThree) viewTwo.addSubview(viewFour) viewOne.addSubview(viewTwo) // viewThree target would be: [root]>UIView[ri:SalesViewController.trichotomy]>UIView[ri:SalesViewController.dichotomy]>UIView:eq(0) // viewFour target would be: [root]>UIView[ri:SalesViewController.trichotomy]>UIView[ri:SalesViewController.dichotomy]>UIView:eq(1) ``` ### tag If the view has no `accessibilityIdentifier` and no `restorationIdentifier` then our SDK will use the `tag` that has been set, and will provide a long reliable target as well. tag yields the same identifiers as accessibility with a different tag ex: `[root]>UIView[tg:444]>UIView[tg:223]>UIView:eq(1)` ### Workaround for SwiftUI: using `.overlay` to get Reliable Target Identifiers SwiftUI views do not expose stable, introspectable identifiers at runtime. This presents a challenge when attempting to programmatically identify or interact with SwiftUI components - especially for use cases such as analytics tracking, UI testing, or runtime introspection. To work around this limitation, you can inject a transparent overlay that contains a `UIView` with a defined `accessibilityIdentifier`. This allows tooling to detect and reference the view reliably at runtime. Warning Since this approach adds an actual `UIView` on top of your SwiftUI view, it intercepts user interactions. As a result, interactive components below the overlay (like buttons) will no longer receive touches unless they are explicitly layered above it. ```swift struct AccessibleView: UIViewRepresentable { let accessibilityIdentifier: String func makeUIView(context: Context) -> UIView { let view = UIView() view.accessibilityIdentifier = accessibilityIdentifier return view } func updateUIView(_ uiView: UIView, context: Context) { uiView.accessibilityIdentifier = accessibilityIdentifier } } ``` This component embeds a transparent `UIView` with the desired `accessibilityIdentifier`, which becomes visible to accessibility, UI testing, or tracking layers. **Example:** Identifying a *non-interactive* list cell. Here is a typical usage pattern where the overlay is applied to a *non-interactive* cell. Any interactive elements (like a button) are rendered above the overlay to remain functional: ```swift var body: some View { ZStack(alignment: .topTrailing) { VStack { Image(product.imageName) .resizable() .aspectRatio(contentMode: .fit) .frame(width: 100, height: 100) Text(product.title) } // This overlay makes the view identifiable at runtime .overlay(AccessibleView(accessibilityIdentifier: "reliableID")) // This button is placed above the overlay so it remains tappable Button("Tap Me") { // Perform action } .padding([.top, .trailing], 8) } .padding() } ``` This pattern can be used when you want to identify list rows, cards, or containers that do not react to taps, but still need to be tagged for runtime analysis or inspection. Recommendations * Only use `.overlay(AccessibleView(accessibilityIdentifier:...))` on *non-interactive* containers. * Ensure interactive elements are layered above the overlay if interaction is needed. * Generate identifiers in a stable, unique per screen and predictable way, e.g.: ```swift let reliableID = "section-\(sectionIndex)-product-\(product.id)" ``` ## Exposure Metrics In the Zoning Analysis module, Exposure Metrics provide information on the size of the display zone in the application, and data about content exposure in scrolling elements. ### Behavior for scrollable elements Exposure Metrics data for scrolling is only calculated on the first scrollable element in the screen. Other scrolling elements in the view hierarchy are not taken into account. This event is defined by the following content: ```javascript ea:23 // int - event action dx:10, // int - normalized x content offset dy:10, // int - normalized y content offset du: 5, // int - duration of the movement (in milliseconds) ``` #### Exclude `UIScrollView` type object from Exposure Metrics Limitations * Exclusion mechanism is available for UIKit only, for objects inheriting from `UIScrollView`. - Swift ```swift let scrollView = UIScrollView() // or UICollectionView, UITableView or any class inheriting from UIScrollView scrollView.excludeFromExposureMetric() ``` - Objective-C ```objective-c UIScrollView *scrollView = [[UIScrollView alloc] init]; [scrollView excludeFromExposureMetric]; ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Collected data points","description":"Events and metadata collected by the iOS SDK","url":"https://docs.contentsquare.com/en/ios/collected-data-points/","inLanguage":"en","dateModified":"2026-06-05T17:39:25+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - iOS (classic) description: Requirements and limitations to develop with the Contentsquare iOS SDK lastUpdated: 07 May 2026 source_url: html: https://docs.contentsquare.com/en/ios/compatibility/ md: https://docs.contentsquare.com/en/ios/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). The Contentsquare iOS SDK requires a minimum iOS version and specific language and framework configurations. * **Programming languages:** The iOS SDK supports and tracks content on any screen developed in **Objective-C or Swift (version >= 4.2)**. * **SwiftUI:** is officially supported * **iOS version:** starting with SDK 4.50.0 we support **iOS 13.0 and later** * Starting with SDK 4.36.0, **no data will be collected for applications running on iOS < 13.0**, although technically the SDK supports iOS 12.4. * ReactNative requires a minimum of iOS 13.0 * All devices released since 2015 can be updated to iOS 13.0 * `SFSafariViewController` is **not** supported ## Known limitations and recommendations ### Screenshot fidelity: Combining Visual Effects with Filters **Symptom:** Some elements of the screenshots may not be visible, such as `UITabBar` buttons. **Explanation:** Our capturing method prevents to capture views when Visual effects are combined with filters. Our tools captures as much as Xcode's 'Debug View Hierarchy' feature. If you want to preview what is going to be rendered, you can use this feature to visualize your screen. See [Capturing a Snapshot of a UIVisualEffectView ↗](https://developer.apple.com/documentation/uikit/uivisualeffectview#Capture-a-snapshot-of-a-visual-effect-view). ### Screenshot fidelity: Customized layers applied on a container view **Symptom:** Some elements of the screenshots may not be displayed correctly in the **Zoning Analysis**. **Explanation:** Our capture method relies on views to determine zoning elements. A view containing subviews is a container and when a container is assigned a customized [layer ↗](https://developer.apple.com/documentation/uikit/uiview/1622436-layer), it may not appear in the **Zoning Analysis**. **Workaround:** Instead of applying customized layer to the container, prefer applying it on view of type, or subtype, `UIImageView` or `UIControl`. ### Screenshot fidelity: Floating header/footer missing in Zoning **Symptom:** Some elements of the screenshots don't exist in the **Zoning Analysis**. **Explanation:** The **Zoning Analysis** module does not support `UITableViewHeaderFooterView` in `UITableView` and `UICollectionReusableView` in `UICollectionView` due to their highly dynamic memory and rendering behavior. ### Screenshot fidelity: Floating header/footer duplicated in Zoning **Symptom:** Some elements appear multiple times in the **Zoning Analysis**. **Explanation:** The **Screenshot** captures the currently visible content on screen. When a floating header/footer remains visible during scrolling, it may be captured at different positions throughout the **Long screenshot process**, resulting in duplications. ### Screenshot fidelity: Multiple vertical scrollViews **Symptom:** The **Long Screenshot** cinematic may not start on mobile, or the resulting screenshot might be unscrollable in **Zoning Analysis**. **Explanation:** When multiple vertical scrollViews are present on a screen, the **Long Screenshot** cinematic will attempt to run only on the last vertical scrollView the user interacted with. Other scrollable areas will not be automatically scrolled or captured by the cinematic process, even if they contain content. In practice, this means the automatic scrolling (and full content capture) is limited to a single scrollView per screen, based on user interaction. ### Screenshot fidelity: Lottie animations **Symptom:** Lottie Animation elements are not visible in the **Zoning Analysis**. **Explanation:** The **Zoning Analysis** module does not support `LottieAnimationView` because the SDK can't select a specific frame to capture. ### Gestures not attached to `UIImageView` **Symptom:** When analysing the tap rate on an image, we see 0% when we know it is not possible. **Explanation:** By default `UIImageView` have their `isUserInteractionEnabled` property set to false ([See Apple documentation ↗](https://developer.apple.com/documentation/uikit/uiimageview/1621063-isuserinteractionenabled)). This means that the `UIImageView` won't receive any input event. All events will be handled by the first parent to have `isUserInteractionEnabled` set to true (usually the first parent will do). **Workaround:** Create a zone on the parent view to get the taps on the image. ### `UICollectionViewCompositionalLayout` TVP lack of consistency **Explanation:** As explained in the [Apple documentation ↗](https://developer.apple.com/documentation/uikit/uicollectionviewcompositionallayout), `UICollectionViewCompositionalLayout` is a highly dynamic layout creation object. We are not able to ensure TVP value is the same between different usages. ### Long Screenshot: Large Capture Limitation **Symptom:** The Long Screenshot capture completes the creation process, but then fails at the very end without a clear error message. **Explanation:** Long Screenshots can produce a very large amount of data. For reliability and performance reasons, the server enforces a maximum payload size (\~75 MB). Very long or content-heavy screens may exceed this limit, causing the screenshot to be rejected. **Workaround:** Capture a shorter area (reduce the scroll length) and/or reduce the amount of on-screen content (for example fewer or lighter elements), then retry the Long Screenshot. ### Zoning Limitation in SwiftUI with scrolling (Lazy)Stack and (Lazy)Grid * **Screenshot and Gesture Tracking Limitations:** * Using `LazyStack`, or `LazyGrid` nested in a `ScrollView` may present limitations in screenshot and gesture tracking due to differences in memory management compared to UIKit. * Intricate hierarchies of `LazyStacks` or `LazyGrids` can lead to inconsistent identification of elements, impacting the reliability of element identification. **Prefer to use single layered Lazy components**, when possible. * **Rotation Limitation:** * Unique identification of elements within SwiftUI `Stack`, `Grid`, `LazyStack`, or `LazyGrid` is not guaranteed after a rotation, so, **rotation is not supported** for `Stack`, `Grid`, `LazyStack`, or `LazyGrid`. * **Scrolling Element Offset Limitation:** * The consistency of unique identifiers is not guaranteed when the scrolling element is displayed starting at an offset different than zero. Check the following Help Center article for more information about the symptom, root cause and potential mitigation solutions: [I can't create a zone on a list element on iOS (SwiftUI) ↗](https://support.contentsquare.com/hc/en-us/articles/4408117004690) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/ios/compatibility/","inLanguage":"en","dateModified":"2026-05-07T10:39:19+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Disabling Automatic SDK Initialization - iOS (classic) description: Learn how to disable the autostart feature and programmatically start the SDK when needed lastUpdated: 09 October 2025 source_url: html: https://docs.contentsquare.com/en/ios/disable-autostart/ md: https://docs.contentsquare.com/en/ios/disable-autostart/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). If you prefer to control when the SDK starts, you can disable the autostart feature and programmatically start the SDK when needed. The first step is to add the required key to your `Info.plist`. The key is `CSDisableAutostart` of type boolean. To disable the autostart, you need to set its value to `true`: * Disable autostart using Xcode:  * Disable autostart using a text editor: **Info.plist** ```xml <key>CSDisableAutostart</key> <true/> ``` Then call `start()` in the `application:didFinishLaunchingWithOptions:` of your `UIApplicationDelegate`: ```swift import UIKit @main class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { Contentsquare.start() return true } // ... } ``` When you call the start method, the SDK automatically starts tracking users' interactions with the app (gestures, lifecycle events and crashes). Warning Calling `start()` in `UISceneDelegate#scene(_:willConnectTo:options:)` does not work. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Disabling Automatic SDK Initialization","description":"Learn how to disable the autostart feature and programmatically start the SDK when needed","url":"https://docs.contentsquare.com/en/ios/disable-autostart/","inLanguage":"en","dateModified":"2025-10-09T13:23:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Error Analysis - iOS (classic) description: How to use Contentsquare Error Analysis in your iOS apps lastUpdated: 07 July 2026 source_url: html: https://docs.contentsquare.com/en/ios/error-analysis/ md: https://docs.contentsquare.com/en/ios/error-analysis/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. Error Analysis automatically captures API errors and network failures in your app and surfaces them in the Contentsquare platform. ## Prerequisites ### Screen tracking implemented Tracking will start at the 1st screenview event, it is required to have screen tracking implemented. Make sure to follow the [iOS Track](https://docs.contentsquare.com/en/ios/track-screens/) screens sections. ### Reminder about User consent If you are in the process of implementing the SDK for the 1st time (or choose to take this update as an opportunity to review your Privacy related implementation), make sure to follow the [iOS Privacy](https://docs.contentsquare.com/en/ios/privacy/) section and use the [Opt-in API](https://docs.contentsquare.com/en/ios/privacy/#opt-in) to get the user consent, otherwise no data will be collected. ## API errors ### Automatic collection API errors automatically collects failed network requests that use `URLSession`. ### Disable automatic collection Automatic collection can be disabled by setting `CSDisableAPIErrorsAutoCollection` to `YES` in the Info.plist. ### Add custom monitoring for specific network requests The API errors automatically collects most network requests for your app. However, some requests might not be collected or you might use a different library to make network requests. In these cases, you can use the following API `HTTPMetric` to manually collect data. * Swift ```swift guard let url = URL(string: "https://www.apple.com") else { return } let request: URLRequest = URLRequest(url: url) let metric = HTTPMetric(request: request) let session = URLSession(configuration: .default) let dataTask = session.dataTask(with: request) { (urlData, response, error) in if let httpResponse = response as? HTTPURLResponse { metric.setStatusCode(httpResponse.statusCode) } metric.stop() } dataTask.resume() ``` * Objective-C ```objective-c NSURL *url = [NSURL URLWithString:@"https://www.apple.com"]; NSURLRequest *request = [[NSURLRequest alloc]initWithURL:url]; HTTPMetric *metric = [[HTTPMetric alloc]initWithRequest:request]; NSURLSession *session = [NSURLSession sessionWithConfiguration:NSURLSessionConfiguration.defaultSessionConfiguration]; NSURLSessionDataTask *task = [session dataTaskWithRequest:request completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) { NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response; [metric setStatusCode:httpResponse.statusCode]; [metric stop]; }]; [task resume]; ``` ### Removing Personal Data in request URL path By default, the API Errors feature collects the URL path of the failed API requests. To prevent the collection of Personal Data in the URL path, you can rewrite the request URL path with the `setURLMaskingPatterns` SDK API. ```swift /// This API must be called at App launch. public static func setURLMaskingPatterns(_ patterns: [String]) ``` Replace a step of the path - meaning between two slashes (/) - containing Personal Data with a variable: * `:user_id` becomes CS\_ANONYMIZED\_USER\_ID * `:address` becomes CS\_ANONYMIZED\_ADDRESS #### Example ```swift ErrorAnalysis.setURLMaskingPatterns([ "https://www.contentsquare.com/users/:user_id/address/:address" ]) ``` | URL before masking | URL after masking | | - | - | | `https://www.contentsquare.com/users/123/address/castle+black` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS` | | `https://www.contentsquare.com/users/123/address/castle+black/reset-token/abcdef123456` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS/reset-token/abcdef123456` | ### Validate API error integration #### Validate API error collection is enabled If in-app features are enabled, a log should appear indicating if API errors is enabled or disabled: ```plaintext CSLIB ℹ️ Info: API Errors is enabled ``` #### Validate API error collection If you have [logging enabled](https://docs.contentsquare.com/en/ios/in-app-features/#debugging-and-logging), you will see API errors: * Displayed in [Contentsquare Log Visualizer](https://docs.contentsquare.com/en/ios/in-app-features/#viewing-logs-in-the-contentsquare-platform). * As an Info log: ```plaintext CSLIB ℹ️ Info: API Error - GET 401 https://api.client.com ``` ### How API errors works #### Initialization The way our SDK works is by auto-starting with the application launch and automatically collects failed network requests that use `URLSession`. #### Configuration Once started, our SDK fetches its config from our servers. It will start collecting data from network events if the API errors setting is enabled in the config (this is handled by the Contentsquare team). #### API errors collection The SDK monitors only the API errors with response code equal or above 400, and generates analytics data. These events are then locally stored, and eventually sent to our servers in batches. Warning To make sure API errors occurring at app launch are correctly tracked, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. See [when to send your first screenview](https://docs.contentsquare.com/en/ios/track-screens/#when-to-send-your-first-screenview) for more details. #### Sending API errors data For each network error, a new event will be sent in analytics and Session Replay data. Check the following sections to learn more about how data is processed and sent: * [Analytics requests](https://docs.contentsquare.com/en/ios/how-the-sdk-works/#sending-data) * [Session Replay requests](https://docs.contentsquare.com/en/ios/session-replay#requests) ### API Troubleshooting Details API errors troubleshooting details enables you to collect more information about API errors so you can troubleshoot errors faster. With this feature you will be able to see three types of additional API error details in the Event Stream of Session Replay. * The HTTP headers of the request and the response. * The body (the data sent by the request or received in the response). * The query parameters of the request endpoint (of the URL of the information you request for). Note This feature is only available for Experience Monitoring Mobile customers. Contact your CSM for more details on the validation and implementation process. See [API Troubleshooting Details ↗](https://support.contentsquare.com/hc/en-us/articles/37271885035537) for more details. ### Collected data points Only network calls with error (response code above 400) will be collected. Here is the list of data collected: * URL (without query strings) * HTTP method * Response code * Timestamp of the request * Timestamp of the response * HTTP headers of the request * HTTP headers of the response * HTTP body of the request * HTTP body of the response * Query parameters of the request endpoint ### Known limitations and recommendations #### Automatic collection limitations The auto collection doesn't work for the following methods: ```swift func data(for request: URLRequest) async throws -> (Data, URLResponse) func data(from url: URL) async throws -> (Data, URLResponse) func upload(for request: URLRequest, from bodyData: Data) async throws -> (Data, URLResponse) func upload(for request: URLRequest, fromFile fileURL: URL) async throws -> (Data, URLResponse) func download(for request: URLRequest) async throws -> (URL, URLResponse) func download(from url: URL) async throws -> (URL, URLResponse) func downloadTask(withResumeData: Data) -> URLSessionDownloadTask func downloadTask(withResumeData: Data, completionHandler: (URL?, URLResponse?, Error?) -> Void) -> URLSessionDownloadTask func streamTask(withHostName: String, port: Int) -> URLSessionStreamTask func streamTask(with: NetService) -> URLSessionStreamTask func webSocketTask(with: URL) -> URLSessionWebSocketTask func webSocketTask(with: URLRequest) -> URLSessionWebSocketTask func webSocketTask(with: URL, protocols: [String]) -> URLSessionWebSocketTask ``` **Workaround:** For the `async` methods, use the corresponding Contentsquare methods: ```swift try await URLSession.shared.cs.data(for: request) try await URLSession.shared.cs.data(from: url) try await URLSession.shared.cs.upload(for: request, from: data) try await URLSession.shared.cs.upload(for: request, fromFile: file) try await URLSession.shared.cs.download(for: request) try await URLSession.shared.cs.download(from: url) ``` For other methods, use the custom monitoring APIs. #### Conflict with Firebase Performance SDK on auto-collection API errors is compatible with Firebase Performance auto-collection, but the HTTP body from the response won't be collected by the Error Analysis SDK. **Workaround**: [Disable auto collection](#disable-automatic-collection) and use [API `HTTPMetric`](#add-custom-monitoring-for-specific-network-requests) to manually collect data. It may also not be compatible with other network auto collection tools. ## Crash Reporter ### Setup Firebase Crashlytics compatibility mode The Contentsquare Crash Reporter is compatible with [Firebase Crashlytics ↗](https://firebase.google.com/docs/crashlytics). You must initialize it before Firebase Crashlytics to make sure all crashes are reported. #### Basic Setup Call `onCrashReporterStart()` to launch Firebase Crashlytics after the Contentsquare Crash Reporter starts: * Swift ```swift ErrorAnalysis.onCrashReporterStart { _ in FirebaseApp.configure() } ``` * Objective-C ```objective-c [ErrorAnalysis onCrashReporterStart:^(BOOL _) { [FIRApp configure]; }]; ``` #### Integration with Firebase Crashlytics and Firebase Performance When using Firebase Crashlytics, [Firebase Performance ↗](https://firebase.google.com/docs/perf-mon), and the Contentsquare Crash Reporter, initializing Firebase Performance traces before all SDKs are fully initialized may lead to app crashes. Recommended setup: * Initialize Firebase Crashlytics first * Then initialize Contentsquare Crash Reporter * Trigger Firebase Performance traces only after `FirebaseApp.configure()` Reach out to your Contentsquare contact to learn more about potential alternatives. ### Upload dSYMs *"When Xcode compiles your source code into machine code, it generates a list of symbols in your app — class names, global variables, and method and function names. These symbols correspond to the file and line numbers where they're defined; this association creates a debug symbol"* [See Apple's documentation for more details ↗](https://developer.apple.com/documentation/xcode/building-your-app-to-include-debugging-information/). When an app crashes, the operating system collects diagnostic information about what the app was doing at the time of crash. Some of the most important parts of the crash report are presented as hexadecimal addresses. To translate those addresses into readable function names and line numbers from your source code, a process called symbolication is used. [See Apple's documentation for more details ↗](https://developer.apple.com/documentation/xcode/adding-identifiable-symbol-names-to-a-crash-report/). To symbolicate the crashes reported by a specific version of your app and make them readable, you need to provide the symbol files (dSYMs) that were generated when your app was built. #### Build your app with dSYMs Make sure Xcode is generating dSYMs for your app: 1. Open your project in Xcode. 2. Select the project file in the Xcode Navigator. 3. Select your main target. 4. Select the `Build Settings` tab and click `All` to show all the build settings. 5. Filter by `Debug Information Format`. 6. Set `Debug Information Format` to `DWARF with dSYM File` for all the build types you want to generate dSYMs. 7. Rebuild your main target. #### Locate dSYMs ##### Download dSYMs from the App Store If you build your main target using bitcode (`Bitcode Enabled` turned on in build settings) and you uploaded your app's symbols to the App Store, you need to download the dSYMs from the App Store: 1. Log in to [App Store Connect ↗](https://appstoreconnect.apple.com/login), then select `My Apps`. 2. Select your app from the grid. 3. Select the build you want to download a dSYM for. 4. Click `Build Details` > `Download dSYM`. In case you use bitcode to build your main target but you didn't upload your dSYMs to the App Store, you need to [find your dSYMs on your local machine](#find-dsyms-on-your-local-machine) and [restore hidden symbols using the BCSymbolMaps](#restore-hidden-symbols-using-bcsymbolmaps) Xcode generates. ##### Find dSYMs on your local machine You can find the dSYMs in the `.xcarchive` directory on disk: 1. In Xcode, open the Organizer window (*Window -> Organizer*). 2. Select your app from the list. 3. Control-click an archive and select `Show in Finder`. 4. A Finder window should appear. Control-click the `xcarchive` package and select `Show Package Contents`. 5. There should be a dSYMs directory that contains the dSYMs generated in Xcode's archiving process. If you use the `Download Debug Symbols` option from Xcode's organizer, the recompiled bitcode dSYMs are also downloaded to this directory. #### Restore hidden symbols using BCSymbolMaps Restoring hidden symbols using BCSymbolMaps is only required if you built your main target using bitcode (`Bitcode Enabled` turned on in build settings). If you used bitcode but downloaded the dSYMs from the App Store, the dSYMs will be recompiled and you can skip this step. To restore hidden symbols you can run the following command: ```shell dsymutil -symbol-map /path/to/archive/BCSymbolMaps /path/to/dsym.dSYM ``` #### Get project ID 1. Login to the Contentsquare platform on [https://app.contentsquare.com ↗](https://app.contentsquare.com) 2. Make sure to be on the right project 3. The project ID can be found in the URL query parameter `project`: `https://app.contentsquare.com/#/{MODULE_NAME}?project={PROJECT_ID}&hash={HASH}]` #### Get project credentials Follow the dedicated documentation from the Help Center to get the **client ID** and **client Secret**: [How to create API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/9292880837660). #### Use script to upload dSYMs To upload dSYMs to Error Analysis you need to use the provided `upload-symbols` script. You need to provide the path where the dSYM files are located as a positional argument, and the Project ID, Client ID and Client Secret either as keyword arguments or set them as environment variables. Additionally, you can use a proxy by specifying the proxy URL. Print more detailed logs by using the `--verbose` flag. | Key | Environment Key | | - | - | | --project-id | ERROR\_ANALYSIS\_PROJECT\_ID | | --client-id | ERROR\_ANALYSIS\_CLIENT\_ID | | --client-secret | ERROR\_ANALYSIS\_CLIENT\_SECRET | | --proxy | ERROR\_ANALYSIS\_PROXY\_URL | If both are provided, the keyword arguments will prevail over the environment variables. #### Set up Xcode to automatically upload dSYM files The following steps describe how to configure Xcode to automatically upload your dSYMs whenever you build your app. 1. Open your project's Xcode workspace, then select its project file in the left Project navigator. 2. From the TARGETS list, select your main build target. 3. Click the **Build Phases** tab, then complete the following steps so that Xcode can process your dSYMs and upload the files. 1. Click + > **New Run Script Phase**. Make sure this new Run Script phase is your project's last build phase; otherwise, dSYMs might not be ready. 2. Expand the new **Run Script** section. 3. In the script field (located under the Shell label), add the following run script. The `upload-symbols` script is located in the SPM checkout path for the SDK. Copy the following script. ```shell # Only upload symbols for App Store build. # Replace `Release` with the configuration used when uploading to the App Store. if [ "${CONFIGURATION}" != "Release" ]; then exit 0 fi ${BUILD_DIR%Build/*}SourcePackages/checkouts/apple-sdk/scripts/upload-symbols "${DWARF_DSYM_FOLDER_PATH}" --project-id "PROJECT_ID" --client-id "CLIENT_ID" --client-secret "CLIENT_SECRET" ``` In the **Input Files** section, make sure you have the paths for the locations of the following files: ```text ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME} ``` ```plaintext ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME} ``` ```plaintext ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Info.plist ``` ```plaintext $(TARGET_BUILD_DIR)/$(EXECUTABLE_PATH) ``` Make sure `User Script Sandboxing` is set to NO in Xcode Build Settings. If you do not want to disable it, add the paths of all your dSYM files one by one in **Input Files**. #### Use fastlane to upload dSYMs The instructions require fastlane `1.93.0` or later. 1. Add fastlane plugin to your project: 1. Run `fastlane add_plugin fastlane-plugin-contentsquare`. 2. Select `Git URL` and input [https://github.com/ContentSquare/contentsquare-fastlane-plugin.git ↗](https://github.com/ContentSquare/contentsquare-fastlane-plugin.git). See [fastlane Plugins ↗](https://docs.fastlane.tools/plugins/using-plugins/) for more information. 2. Call fastlane plugin in your build process: `upload_symbols_to_error_analysis(project_id: your_project_id, client_id: "your_client_id", client_secret: "your_client_secret")` Note You need to use `bundle exec fastlane [lane]` to run fastlane. ### Validate crash reporter integration #### Validate crash collection is activated Enabling crash reporting will conflict with any attached debuggers, so make sure a debugger isn't attached when you crash the app. In case a debugger is attached to the device, Crash Reporter won't be initialized and a log will be printed in the console: ```plaintext CSLIB ℹ️ Info: Debugger present, crash reporter is not initialized ``` To test if Crash Reporter is working properly, you first need to disconnect your test device or simulator from Xcode debugger: * Tap on the *Edit scheme...* option of your current scheme * Disable the *Debug executable* option in your scheme configuration. * Build and run your current scheme. If Crash Reporter is successfully initialized when you launch your application, you should see a log printed in the console: ```plaintext CSLIB ℹ️ Info: Crash reporter is initialized ``` Alternatively, you can detach your application from Xcode debugger by stopping it after it is launched. This way Crash Reporter will be initialized and will start reporting crashes, but you won't be able to see the logs printed in the console: * Build and run your current scheme. * Wait until the app is up and running. * Click on Stop running the scheme. * Open the app directly from your test device or simulator. #### Validate crash reporting Run your application and force a crash (you can do it by adding a `fatalError()` in your code). Launch the application again using Xcode and you should see a log printed in the console that indicates that a crash has been detected and sent: ```plaintext CSLIB ℹ️ Info: Crash event detected and sent for userID: <user-id>, session: <session-number> on screen: <screen-number> - crashID: <crash-id> ``` ### How Crash Reporter works #### Initialization Crash Reporter is started automatically and begins to report crashes when your application is launched. #### Configuration Once started, our SDK fetches its configuration from our servers. It will start reporting crashes if the Crash Reporter setting is enabled (this is handled by the Contentsquare team). #### Reporting When a crash occurs, a report is created and stored locally in the device. Once the app is launched again, the report is sent to our servers and then removed from the local storage. Warning To make sure crashes occurring at app launch are correctly tracked, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. See [when to send your first screenview](https://docs.contentsquare.com/en/ios/track-screens/#when-to-send-your-first-screenview) for more details. #### Sending crash data For each crash, a new event will be sent to analytics and Session Replay data when the app is launched again after the crash occurred and the network conditions allow for the server to be reached. Our requests use [`lowPriority` ↗](https://developer.apple.com/documentation/foundation/urlsessiontask/1411509-lowpriority). ### Collected data points Crash Reporter handles multiple types of crashes, including: * Mach kernel exceptions * Fatal signals * C++ exceptions * Objective-C exceptions For each crash we collect information of the application, system, process, threads, stack traces and some other events metadata you can find in [collected data points](https://docs.contentsquare.com/en/ios/collected-data-points/). ### Known limitations and recommendations #### Compatibility with other crash reporters Beyond Firebase Crashlytics (see [Setup Firebase Crashlytics compatibility mode](#setup-firebase-crashlytics-compatibility-mode)), the Contentsquare Crash Reporter is not compatible with other crash reporters. For more details, reach out to your Contentsquare contact. ## WebView errors Errors occurring in web pages loaded in WebViews can be collected if Webview tracking is set up in your app. See 📚 [Webview Tracking implementation](https://docs.contentsquare.com/en/webview-tracking-tag/). Once WebView tracking is implemented, errors collection can be set up. See 📚 [Errors (in WebView)](https://docs.contentsquare.com/en/webview-tracking-tag/error-analysis/) ## Impact on Performance We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. The following performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | iPhone 11 Pro 64GB | | iOS version | 16.5 | | Test App built using Xcode version | 15.3 | | Test App built with Swift version | 5.8 | Note The numbers provided below will vary depending on the user's device, iOS version, SDK version, and if you use Swift or not, which Swift version you use if you do, if you enabled bitcode or not and which options you used when building your IPA for App Store distribution. | Property | Value | | - | - | | Max RAM usage | <2MB | | Max SDK CPU peak on event | <2% | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Error Analysis","description":"How to use Contentsquare Error Analysis in your iOS apps","url":"https://docs.contentsquare.com/en/ios/error-analysis/","inLanguage":"en","dateModified":"2026-07-07T11:03:44+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: How the SDK works - iOS (classic) description: Understand how the iOS SDK is initialized, configured, tracks, and sends data lastUpdated: 28 April 2026 source_url: html: https://docs.contentsquare.com/en/ios/how-the-sdk-works/ md: https://docs.contentsquare.com/en/ios/how-the-sdk-works/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). The SDK auto-starts at application launch, attaches to the current process, and intercepts the events and gestures needed to capture analytics data. ## Configuration Once started, our SDK fetches its configuration from our servers. Then, depending on the segmentation size (defined by our team when you sign a contract) and the user consent status, it will start collecting analytics data from system and user events it detects from the runtime. ## Data collection ### Analytics data collection The SDK monitors the application lifecycle events, the view hierarchy, and generates data from the behavior of the app, the content of the screen and the user interactions. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. ### Session Replay data collection See [Session Replay Initialization](https://docs.contentsquare.com/en/ios/session-replay/#data-collection) to learn how Session Replay data collection works. ## Sending data ### Sending analytics data Analytics data are sent in batches of maximum 50 events. Requests are triggered when network conditions allow for the server to be reached and: * The current batch of events has reached 50 * Or the app is put in background Our requests use [`lowPriority` ↗](https://developer.apple.com/documentation/foundation/urlsessiontask/1411509-lowpriority). ### Sending Session Replay Data See [Session Replay Requests](https://docs.contentsquare.com/en/ios/session-replay/#requests) to learn more about how Session Replay data is sent. ### Sending crash Data See [Send Crash data](https://docs.contentsquare.com/en/ios/error-analysis/#sending-crash-data) to learn more about how crash data is sent. ## Session definition A session is one continuous period of user interaction. It starts upon app launch and persists through state changes, including putting the app in the background or terminating and restarting it. As long as users interact at least once every 30 minutes, it remains the same session. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"How the SDK works","description":"Understand how the iOS SDK is initialized, configured, tracks, and sends data","url":"https://docs.contentsquare.com/en/ios/how-the-sdk-works/","inLanguage":"en","dateModified":"2026-04-28T22:02:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Impact on performance - iOS (classic) description: Metrics to evaluate the performance impact of Contentsquare iOS SDK on your apps lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/ios/impact-on-performance/ md: https://docs.contentsquare.com/en/ios/impact-on-performance/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). Contentsquare strives to be non-intrusive and transparent to client app developers. The following are the technical specifics we can share on performance. The following performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | iPhone 11 Pro | | iOS version | 16.5 | | Test App built using Xcode version | 15.3 | | Test App built with Swift version | 5.8 | We conducted the tests using a default `Master-Detail` app built using ad hoc distribution with no app thinning and with Swift symbols stripped. In the app, the SDK was making calls to the public APIs, running, and collecting data in its default state. Note The numbers provided below will vary depending on the user's device, iOS version, SDK version, and if you use Swift or not, which Swift version you use if you do, if you enabled bitcode or not and which options you used when building your IPA for App Store distribution. | Property | Value | | - | - | | SDK size (installed size, no Bitcode) | 5.2Mb | | Max RAM usage | <2Mb | | Max SDK CPU peak on event | <3% | | Data transmitted over network for a default batch size of 50 events The size of the batch can be customized if needed | \~29kb | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Impact on performance","description":"Metrics to evaluate the performance impact of Contentsquare iOS SDK on your apps","url":"https://docs.contentsquare.com/en/ios/impact-on-performance/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: In-app features - iOS (classic) description: Implement in-app features with the Contentsquare iOS SDK lastUpdated: 02 June 2026 source_url: html: https://docs.contentsquare.com/en/ios/in-app-features/ md: https://docs.contentsquare.com/en/ios/in-app-features/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). Alongside its tracking capabilities, the SDK embeds some features aimed at Contentsquare users such as [Screenshot Capture](#screenshot-capture) and [SDK Logs](#debugging-and-logging). ## Implement in-app features To allow Contentsquare users to enable in-app features, you must perform 2 implementation tasks: 1. [Add the custom URL scheme in your app Info](#1-add-the-custom-url-scheme-in-your-app-info) 2. [Call the SDK when the app is launched via a deeplink](#2-call-the-sdk-when-the-app-is-launched-via-a-deeplink) ### 1. Add the custom URL scheme in your app Info You have to allow your app to be opened via a custom URL scheme which can be done using one of the following methods: #### Xcode 1. Open your project settings 2. Select the app target 3. Select the `Info` settings 4. Scroll to `URL Types` 5. Set the URL scheme to `cs-$(PRODUCT_BUNDLE_IDENTIFIER)` #### Text editor 1. Open the `Info.plist` of your project 2. Add the following snippet: **Info.plist** ```xml <key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>cs-$(PRODUCT_BUNDLE_IDENTIFIER)</string> </array> </dict> </array> ``` ### 2. Call the SDK when the app is launched via a deeplink Depending on the project, there are multiple ways to handle the deeplink opening. Choose the method matching your project structure: * AppDelegate In your `AppDelegate` class, complete or implement the function `application(app, open url:, options:)` with: `Contentsquare.handle(url: url)` * SceneDelegate In your `WindowSceneDelegate` class, you need to: 1. Update `func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions)` with: ```swift if let url = connectionOptions.urlContexts.first?.url { Contentsquare.handle(url: url) } ``` 2. Complete or implement `func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>)` with: ```swift if let url = URLContexts.first?.url { Contentsquare.handle(url: url) } ``` * SwiftUI In the `body` of your main App struct, add the `onOpenURL` modifier and call the `Contentsquare` SDK to handle the URL: ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { MyView() .onOpenURL { url in Contentsquare.handle(url: url) } } } } ``` ### Enable in-app features Once the implementation is done, in-app features can be enabled in different ways: #### Scan the QR code If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code displayed with your iPhone.  #### Use the custom link for simulator If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and select "Copy link" (to copy the deeplink) and paste it in Safari on your Simulator to trigger the in-app features.  Note If you don't have access to the Contentsquare platform, you can ask the Contentsquare team to share the link with you. #### Using the Terminal In a Terminal console, open an URL in your current simulator with the following command (replacing `CUSTOM_LINK` with yours): ```shell xcrun simctl openurl booted "CUSTOM_LINK" ``` ### Debugging and Logging Contentsquare provides Logging capabilities that allow you to see the raw event data logged by your app in the macOS Console App, Xcode, or in the Contentsquare platform. Use this for validation purposes during the instrumentation phase of development and can help you discover errors and mistakes in your analytics implementation and confirm that all events are being logged correctly. #### Viewing Logs in Xcode or the macOS Console app By default, almost all logs are disabled. There is only one log that is always visible to notify that the SDK has started: ```plaintext CSLIB ℹ️ Info: Contentsquare SDK v4.52.1 starting in app: {{bundleID}} ``` To enable all logs, activate [in-app features](#enable-in-app-features). Logging is directly linked to in-app features state: it starts when in-app features are enabled and stops when you disable in-app features. To view logs: 1. Make sure the device you are using is plugged to your Mac or is on the same Wi-Fi network (skip this step if you are using a simulator) 2. Start the macOS Console app *(make sure that info messages are included: [Choose Action > Include Info Messages ↗](https://support.apple.com/guide/console/customize-the-log-window-cnsl35710/mac))* or Xcode. 3. Filter logs on `CSLIB`  #### Viewing logs in the Contentsquare platform To view logs directly on the platform, you can use Log visualizer. Log visualizer is a helper tool to see SDK logs without logging tools. It requires having platform access for your project and enabling in-app features. See the [SDK Log Visualizer Help Center Article ↗](https://support.contentsquare.com/hc/en-us/articles/37271699876625) for more information. ### Screenshot capture To unlock the full data-visualization capabilities of Contentsquare, the SDK provides a way to capture screenshots of your app screens. These screenshots can only be taken by Contentsquare's users on their device. They are not captured from your end-users device. It means your Personal Data is safe, as long as you use a test user account. Warning * For screenshot capture to work, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. * Horizontal scrollable containers are not supported.  Screenshots are used in the **Zoning Analysis** module to look at zone-level metrics (Tap rate, Swipe rate...):  ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"In-app features","description":"Implement in-app features with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/ios/in-app-features/","inLanguage":"en","dateModified":"2026-06-02T10:48:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - iOS (classic) description: Learn how Contentsquare deals with Personal Data and related APIs lastUpdated: 07 July 2026 source_url: html: https://docs.contentsquare.com/en/ios/privacy/ md: https://docs.contentsquare.com/en/ios/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). Customers ("Customer(s)", "you," or "your"), as app developers and/or publishers, shall ensure compliance with applicable data privacy laws and regulatory guidelines while using Contentsquare SDK for your app. This section explains the data processing involved in the use of Contentsquare SDK and provides information to help you comply with data protection laws, including the GDPR, e-privacy directive, and the [French Data Protection authority (CNIL) guidelines on mobile applications ↗](https://www.cnil.fr/sites/cnil/files/2025-05/recommendation-mobiles-app.pdf). This section is for informational purposes only and is not legal advice. If you are not sure of how to comply with data protection laws that apply to you, refer to legal counsel. To learn about Contentsquare privacy practices, see our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Purpose of processing and categories of personal data collected Here is the list of categories of personal data Contentsquare collects by default that are part of our [privacy manifests](https://docs.contentsquare.com/en/ios/privacy/#privacy-manifest). All collected personal data listed below is linked to the end-user via the [Contentsquare User ID](https://docs.contentsquare.com/en/ios/privacy/#contentsquare-user-id) we generate. Warning The Contentsquare SDK provides features that allow you to send to Contentsquare additional types of personal data (such as username, email address, customer ID, account number): [Dynamic variables](https://docs.contentsquare.com/en/ios/track-dynamic-variables/), [Custom variables](https://docs.contentsquare.com/en/ios/track-custom-variables/), [User identifier](https://docs.contentsquare.com/en/ios/session-replay/#send-user-identifier), [Screen names](https://docs.contentsquare.com/en/ios/track-screens/), [Session Replay (unmasking elements)](https://docs.contentsquare.com/en/ios/session-replay/#personal-data-masking). If you decide to use these features to collect new types of personal data or use already collected data but for a different purpose, it is up to you to describe these privacy practices in your app manifest. | Categories | Data type | Purposes | | - | - | - | | Identifiers | User ID | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Product Interaction such as touch gestures (taps, swipes), user journey (pages visited), time of engagement, or transactions | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Other usage data (any other data about end-user activity in the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Other Data types | Other Data types (technical data, any other data inputted by customers in the dynamic variables, data used as part of the Session Replay feature where applicable) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Diagnostics | Crashes, such as crash logs | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](https://docs.contentsquare.com/en/ios/error-analysis/)) | | Diagnostics | Performance data, such as launch time, freeze rate, or energy use | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](https://docs.contentsquare.com/en/ios/error-analysis/) | | Diagnostics | Other diagnostic data (any other data collected for the purposes of measuring technical diagnostics related to the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](https://docs.contentsquare.com/en/ios/error-analysis/) | | Search History | Information about searches performed by an end-user in the app | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Session Replay module](https://docs.contentsquare.com/en/ios/session-replay/)) | | Purchase History | Transaction data about an end-user (such as order reference, amount, bought items) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | See how the data types and purposes are reflected in the [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy). Note Contentsquare is not designed to collect sensitive personal data (such as health, financial, or racial data). It is your responsibility to prevent any sensitive data from being sent to Contentsquare. If you accidentally send sensitive data, contact your customer success manager to immediately delete them from Contentsquare servers. ## User Identifiers ### Contentsquare User ID The SDK generates a randomized hash unique user ID (UUID) that is specific to each end-user on a given device. Contentsquare cannot identify an end-user across devices with this UUID. This UUID is not persisted when the app is deleted and re-installed. The SDK generates a new UUID after install or re-install. ### IDFA Contentsquare does not collect the IDFA (Advertising ID) or any other ads-related personal data of the end-user since the Contentsquare SDK is not linked with Third-Party Data (as defined by Apple) for targeted advertising or advertising measurement purposes, nor shared with a data broker. ## Data retention and storage location ### Data retention By default, end-users personal data are kept for 13 months. The retention of end-users personal data collected via the Session Replay is customizable by customers, from 3 to 24 months. ### Storage location End-users personal data are stored in Europe or in the US, depending on your location. For more details on applicable hosting locations, refer to our [subprocessors list ↗](https://contentsquare.com/privacy-center/subprocessors/). ## Informing your End-User The Contentsquare SDK collects end-user's personal data on your app. As a data controller, app developers, or app publishers, it is your responsibility to provide appropriate information to your end-users on how their personal data is handled when using the CSQ SDK, for example via a privacy policy or cookie banner. Contentsquare provides a sample [description of the services ↗](https://contentsquare.com/privacy-center/sample-cookie-description/) (including Experience Analytics and Product Analytics) to help customers meet their transparency obligations. This description is for information only and is not legal advice. ## Handling User Consent Contentsquare collects usage data on your app. **By default, the SDK will consider every new user to be opted-out.** To start tracking, the SDK [Opt-in API](#opt-in) must be called. You are responsible for handling the UI asking end-users for their consent and allowing them to manage their privacy settings. Use the following APIs to pass the user decision to the Contentsquare SDK. Note If data protection laws that apply to you do not require end-user consent for your app, discuss it during implementation with your Contentsquare contact (as this would go against Apple Privacy guidelines). ### Opt-in Use the Opt-in API to get end-user consent. Calling this API will generate a user ID and initiate tracking. * Swift ```swift Contentsquare.optIn() ``` * Objective-C ```objective-c [Contentsquare optIn]; ``` ### Opt-Out When this API is called, tracking stops immediately, all settings are reset (session number, page number) and all files and directory including personal data collected via the SDK created by Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track and collect any data from the user's phone unless the Opt-in API is called again. * Swift ```swift Contentsquare.optOut() ``` * Objective-C ```objective-c [Contentsquare optOut]; ``` ### Handling your end-user's data subject requests In case Contentsquare receives a request from an individual that identifies as an end-user of your app, Contentsquare will promptly refer such individual directly to you, as the data controller and will support you with any means available to resolve such request. Contentsquare has launched a portal for managing data subject requests to its customers respond to data subjects within the legal deadlines. Therefore, you can forward any data subject request (such as data deletion or data access request) you receive to Contentsquare via this Data Subject Portal at [https://contentsquare.com/privacy-center/data-subject-request-portal/ ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ### Get your end-user's Contentsquare User ID Since Contentsquare SDK does not collect by default any directly identifiable personal data about your end-user, we cannot help you respond to an end-user's data subject request without their Contentsquare User ID. Use this API to get the Contentsquare User ID of your end-user and forward the end-user's data subject request (such as data deletion or data access request) via Contentsquare's [portal ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). * Swift ```swift Contentsquare.userID() ``` * Objective-C ```objective-c [Contentsquare userID]; ``` Note You are able to get an ID only if the user is not Opted-out. ### Pause / Resume Tracking To completely stop data collection of your end-users of your app, use the pause and resume tracking APIs. When `stop/pause` is called, the Contentsquare SDK pauses all tracking (Analytics, Session Replay, Errors) of your end-users. When `resume` is called, the Contentsquare SDK resumes all tracking (Analytics, Session Replay, Errors) and starts collecting your end-users personal data again with the same Contentsquare user ID. * Swift ```swift Contentsquare.stopTracking() // ... Contentsquare.resumeTracking() ``` * Objective-C ```objective-c [Contentsquare stopTracking]; // ... [Contentsquare resumeTracking]; ``` Note As this mechanism pauses the tracking, make sure that you call resume once your user exits the sensitive screen. Best practice would be to link these method calls to lifecycle events on UIView/UIViewControllers. ### Forget me Removed This API has been removed as of SDK version 4.45.0. Use Opt-out API to delete all files and settings, including end-users personal data collected via the Contentsquare SDK, and call Opt-in API on next app launch if tracking needs to resume. **Permanently breaking the link between the collected data and actual user.** This resets all settings and deletes all files and directories, including personal data collected via the Contentsquare SDK, from the end-user's device (that is Contentsquare User ID and all related personal data is deleted). If the end-user is opted in to be tracked by the Contentsquare SDK, next time the end-user starts the app, the SDK will re-start its collection mechanisms as if this was the first ever run for a new end-user, under a new Contentsquare User ID. Configurations will be fetched from the server and application tracking will be on. Note 'Forget me' only works when user is opted in. * Swift ```swift Contentsquare.forgetMe() ``` * Objective-C ```objective-c [Contentsquare forgetMe]; ``` ## Disable user tracking across sessions If you don't want to link the different sessions of an end-user to the same Contentsquare User ID, follow these instructions to reset the Contentsquare User ID at each app start: 1. [Disable SDK auto-start](https://docs.contentsquare.com/en/ios/track-screens/#manual-start) 2. Implement the following: ```swift func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) { Contentsquare.start() Contentsquare.optOut() Contentsquare.optIn() // ... } ``` Starting the SDK manually using `start()` will ensure that opt-out is called right after the start of the SDK (no event tracked in between). Calling `optOut()` will delete the previous Contentsquare User ID. Calling `optIn()` will set a new one. Note If you are monitoring the network requests, you may see event requests being sent at app start. This is expected as there may be events from the previous session that haven't been sent yet. The [opt-out API](#opt-out) makes sure to send all end-user's personal data stored locally before stopping the tracking and wiping all data. ### Session Replay personal data masking mechanisms As part of Session Replay capabilities, Contentsquare provides masking mechanisms to prevent unwanted end-user's personal data from the Session Replay module from being transmitted to Contentsquare. See [Session Replay Personal data masking](https://docs.contentsquare.com/en/ios/session-replay/#personal-data-masking) for more information. ## App Store Privacy Guidelines Compliance As customer app developers, it is your responsibility to comply with the [App Store Privacy guidelines ↗](https://developer.apple.com/app-store/review/guidelines/#privacy). ### Privacy manifest The Contentsquare SDK includes a [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy) describing the types of end-users personal data collected, the purpose of processing and the reasons for using APIs. [See Apple's website for more information ↗](https://developer.apple.com/app-store/app-privacy-details/). ### Tracking and App Tracking Transparency (ATT) App Store (Apple) requests App developers to receive end-users' permission to track them or access Advertising ID using the [AppTrackingTransparency framework ↗](https://developer.apple.com/documentation/apptrackingtransparency) (ATT). **It is not required to ask for end-users' permission through the ATT when using Contentsquare, as it does not fall under the** ["tracking" definition of Apple ↗](https://developer.apple.com/app-store/app-privacy-details/#user-tracking). The data collected by the Contentsquare SDK is not linked with Third-Party Data (as defined by Apple) for targeted advertising or advertising measurement purposes, nor shared with a data broker. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Learn how Contentsquare deals with Personal Data and related APIs","url":"https://docs.contentsquare.com/en/ios/privacy/","inLanguage":"en","dateModified":"2026-07-07T18:43:59+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Migrate from CocoaPods to Swift Package Manager - iOS (classic) description: Step-by-step guide to migrate your Contentsquare iOS SDK integration from CocoaPods to Swift Package Manager lastUpdated: 01 July 2026 source_url: html: https://docs.contentsquare.com/en/ios/migrate-from-cocoapods/ md: https://docs.contentsquare.com/en/ios/migrate-from-cocoapods/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). CocoaPods is no longer supported for integrating the Contentsquare iOS SDK in your app. **If you stay on CocoaPods, you will stop receiving SDK updates. Migrate to Swift Package Manager to continue receiving new features and fixes.** ## Before you begin * Xcode 16.0 or later is required. * Make sure you have an up-to-date copy of your project in source control before starting. ## Migration steps ### 1. Remove the Contentsquare SDK from your Podfile Open your `Podfile` and remove the Contentsquare SDK pod reference: ```ruby pod 'CS_iOS_SDK' # or pod 'CS_iOS_SDK_STATIC' ``` Then run `pod install` to update your project: ```shell pod install ``` Note This approach keeps CocoaPods in your project for other dependencies. You can continue using CocoaPods alongside Swift Package Manager. ### 2. Add the Contentsquare SDK via Swift Package Manager 1. In Xcode, go to `File > Add Packages…`. 2. Enter the following repository URL: ```plaintext https://github.com/ContentSquare/CS_iOS_SDK.git ``` 1) Select the latest version or the version used in your project. 1. Click `Add Package`. ### 3. Add the `-ObjC` linker flag To ensure the SDK starts correctly, add `-ObjC` as a linker flag: 1. In your target's `Build Settings`, search for `Other Linker Flags`. 2. Add `-ObjC`. ### 4. Remove leftover SwiftProtobuf dependency If you previously added `pod 'SwiftProtobuf'` to work around a known CocoaPods issue, remove that reference from your project. SwiftProtobuf is included automatically via SPM. Also remove `https://github.com/apple/swift-protobuf.git` from `Package Dependencies` if you had added it before SDK version 4.35.1. ### 5. Build and verify Build your project. If the build succeeds and the SDK initializes correctly, the migration is complete. Tip To verify the SDK is running, filter your Xcode or macOS Console logs by `CSLIB`. ## If you want to fully remove CocoaPods If you're not using CocoaPods for any other dependencies and want to completely remove it from your project: 1. Run `pod deintegrate` in your project directory. 2. Delete `Podfile` and `Podfile.lock`. 3. Open the `.xcodeproj` file directly instead of the `.xcworkspace`. Warning Only do this if you have no other CocoaPods dependencies in your project. ## Troubleshooting ### Symbol not found at runtime If you see an error like: ```text dyld: Symbol not found: _OBJC_CLASS_$_... ``` Make sure the `-ObjC` linker flag is present under `Build Settings` > `Linking` > `Other Linker Flags` for your app target. ### Module not found at build time If Xcode cannot find the `ContentsquareModule` import, check that the `CS_iOS_SDK` package is listed under your target's `Frameworks, Libraries, and Embedded Content` in the General tab. ## Next Steps Consider upgrading to the [CSQ SDK](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/) for the latest unified experience with both Experience Analytics and Product Analytics capabilities. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Migrate from CocoaPods to Swift Package Manager","description":"Step-by-step guide to migrate your Contentsquare iOS SDK integration from CocoaPods to Swift Package Manager","url":"https://docs.contentsquare.com/en/ios/migrate-from-cocoapods/","inLanguage":"en","dateModified":"2026-07-01T21:01:22+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Security - iOS (classic) description: Data transfer and security information lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/ios/security/ md: https://docs.contentsquare.com/en/ios/security/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). The iOS SDK is designed with security and privacy in mind. ## Transmission and hosting Our server uses HTTPS to make sure that data is encrypted in transport. Our hosting solution is a PCI DSS Level 1 Service Provider. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Security","description":"Data transfer and security information","url":"https://docs.contentsquare.com/en/ios/security/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Session Replay - iOS (classic) description: How to implement Session Replay with the Contentsquare iOS SDK lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/ios/session-replay/ md: https://docs.contentsquare.com/en/ios/session-replay/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). Session Replay enables replaying real sessions to observe how users interact with your product, by capturing screen content - including text and images - as users navigate your mobile app. For more details, see [Introduction to Session Replay for Apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) in the Help Center. ## Starter guide ### Prerequisites #### Update to latest SDK version To enable Session Replay in your app and get the most stable version, it is required to [upgrade the SDK](https://docs.contentsquare.com/en/ios/#install-the-sdk) to its latest version. #### Implement screen tracking Ensure screen tracking is implemented, since Session Replay collection starts at the first screenview event. See [Track screens](https://docs.contentsquare.com/en/ios/track-screens/). #### Handle User consent Ensure user consent is handled for Contentsquare data collection, especially if you're implementing the SDK for the first time. See [Privacy](https://docs.contentsquare.com/en/ios/privacy/) section. Moreover if you need to obtain a specific end-user's consent for Session Replay or to start Session Replay data collection only under certain conditions (in specific geolocations for instance), see [Define when Session Replay starts](#define-when-session-replay-starts) Note Mandatory data collection settings are configured by Contentsquare in your project parameters. [Learn more about Data collection configurations ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) on the Help Center. ### Configure Session Replay masking #### Masking behavior By default, the Contentsquare SDK is configured to mask all content displayed on the user interface (UI) to prevent unnecessary data collection. For more details, see what a fully masked screen looks like in [Masking mechanisms](#masking-mechanisms). **For testing purposes**, use this setup: * Either unmasking all the content by setting the [default masking](#default-masking) status to false. * Or unmasking most content with the [Text and Image unmasking configuration ↗](https://support.contentsquare.com/hc/en-us/articles/37271682878353-Data-masking-in-Session-Replay-Mobile-Apps) in your Console parameters. **For more granular control in deployment mode**, you can use the [Text and Image unmasking configuration ↗](https://support.contentsquare.com/hc/en-us/articles/37271682878353-Data-masking-in-Session-Replay-Mobile-Apps) in your Console parameters in combination with [SDK public masking APIs](#public-masking-apis) to fine-tune exactly which elements remain masked. Warning Always keep sensitive data masked to ensure compliance with privacy regulations and to protect users' personal data. ### Configure Event-Triggered Replays (optional) If Event-Triggered Replays is included in your contract, you can set up ETR events to enable specific screen and session collection in Session Replay. See [Event-Triggered Replays (ETR)](#event-triggered-replays-etr). ### Configure Webviews (optional) If your mobile app includes Webviews, specific implementation steps are required to ensure they are properly reflected in Session Replay: * Implement [Webview tracking](https://docs.contentsquare.com/en/webview-tracking-tag/) * Handle [personal data within WebViews](https://docs.contentsquare.com/en/webview-tracking-tag/session-replay/#personal-data-handling) ### Configure custom fonts (optional) To ensure UIKit text elements are rendered in Session Replay exactly as they appear in your app, you can add fonts in `otf`, `ttf`, `woff`, or `woff2` formats directly from the player. See [Managing iOS Fonts In The Player ↗](https://support.contentsquare.com/hc/en-us/articles/37271807874577) in the Help Center documentation. ### Test your setup #### Enable Session Replay on your device If the Session Replay sampling rate is less than 100%, only a portion of sessions are collected. To ensure data collection on your device for testing and debugging purposes, you can force it from the In-app Features settings by following these steps: 1. [Enable in-app features](https://docs.contentsquare.com/en/ios/in-app-features/) 2. Open in-app features settings with a long press on the screenshot button 3. Under "Session Replay", toggle "Enable Session Replay" on 4. Kill the app 5. Start app, a new session is starting with Session Replay enabled  #### How do I know if Session Replay is enabled? There are 2 places where you can check if Session Replay is enabled: **In the logs:** The log `Session Recording is starting` will confirm that Session Replay is enabled. **In in-app features settings:** Below the "Enable "will start at next app start" *(see below [Access the replay](#access-the-replay))*, you will either see: * `No replay link available` which means Session Replay is not running for the current session * `Get Replay link` which means Session Replay is running for the current session #### Access the Replay The session can be accessed by tapping on `Get replay link` button from the in-app features settings:  The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay your session up to the previous screenview if the session is still running. ## Define when Session Replay starts If you need to ensure that Session Replay data is collected only under certain conditions — for example, only after receiving explicit user consent for Session Replay or in specific geolocations — follow these instructions: ### Disable Automatic Session Replay Initialization 1. Deactivate SDK autostart as explained in [Disabling Automatic SDK Initialization](https://docs.contentsquare.com/en/ios/disable-autostart/) 2. Call `Contentsquare.configure(options:)` **before** `start()`. The initialization of the SDK should look like this: ```plaintext Contentsquare.configure(options: .init(isSessionReplayAutoStartEnabled: false)) Contentsquare.start() ``` Warning `configure` must be called before `start` ### Start Session Replay Once your app has determined that Session Replay can start—for example, via a reverse geocoding service or after receiving specific user consent for Session Replay— you can call `Contentsquare.startSessionReplay()` to start Session Replay. Note Calling startSessionReplay() does not force Session Replay data collection. It enables the Session Replay module, allowing it to begin checking whether the global Replay sampling rate or Event Triggered Replay conditions are met. Session Replay data collection will only start if these conditions are satisfied. Find more info in [Data collection for Session Replay (Apps) ↗](https://support.contentsquare.com/hc/en-us/articles/4412027865874) in the Help Center. To confirm that Session Replay data collection has started, look for the appearance of the following log: ```plaintext CSLIB ℹ️ Info: Session Recording is starting ``` ## Personal Data Masking The Session Replay feature replays every interaction of your users with your app. To respect the user's right to privacy, the Contentsquare SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our [Masking rules](#masking-rules) Warning **Privacy Manifest:** If you decide to use unmasked elements leading to collection of new data or use already collected data but for a different purpose, it is up to you to update the privacy practices described in your app manifest accordingly. Here are some common examples of data collected via unmasked session Replay: Search history, Purchase history, Advertising data, etc. See [Types of data and purpose](https://docs.contentsquare.com/en/ios/privacy/) already described in the Contentsquare iOS SDK Privacy Manifest. **Important:** Contentsquare is not intended nor designed to collect sensitive personal data (for example health, financial, or racial data). It is the customer's responsibility not to send any sensitive personal data to Contentsquare. ### Masking mechanisms Masking depends on the type of element: * `UIKit.UIImage` and `SwiftUI.Image`: image isn't collected, a placeholder is sent instead of the content; the "IMG" placeholder will be displayed in the frame of the element. * `UIKit.UILabel` and `UIKit.UITextView`: text is replaced by "la" repeated as many times as needed to equal the original character count. White characters are preserved. For instance `the lazy fox` is collected as `lal lala ala`. All other visual properties are collected (text color, background color, alignment, etc.). * `UIKit.UITextField`: same as `UIKit.UILabel` or `UIKit.UITextView` unless `isSecureTextEntry` is set to `true`. In this case all characters, including whitespaces are replaced with "•". * `SwiftUI.Text`: element is replaced by a black rectangle. * For all other types: no specific data is collected but all visual properties are collected: size, background color, corner radius, etc. If you think a specific element can reveal personal data from one of these properties mask it using one of the methods presented below. An efficient way to check how a view is rendered in the Session Replay is to navigate to the desired view with the CS SDK running then use the [quick replay link](#access-the-replay). #### Original vs Replay fully masked * UIKit  * SwiftUI  ### Masking rules Masking rules can be applied in two ways: 1. **Through remote masking configuration in the CSQ Console (for admin users):** this is managed directly in the Console and takes effect for all sessions as soon as the app is restarted or brought to the foreground. See [How to customize masking rules from the Data Masking tab ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) in the Help Center. 2. **Using public masking APIs in the SDK (for mobile application developers):** these APIs require developer implementation and will be applied only after the mobile app has gone through its release cycle. The SDK determines whether views, images, and texts are masked according to the following rules, ranked from highest to lowest priority. Once a rule is triggered, the state is set, and subsequent rules are not applied. #### General rules | Rules (highest to lowest priority) | Configured via | | - | - | | 1. The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text or Image masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. An [instance](#maskingun-masking-by-instance) is specifically masked or unmasked | API | | 4. A [parent](#masking-and-unmasking-behaviors-on-a-parent-view) is specifically masked or unmasked | API | | 5. A [type](#maskingun-masking-by-type) is masked or unmasked | API | | 6. A parent [type](#maskingun-masking-by-type) is masked or unmasked | API | | 7. Remote Text or Image unmasking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 8. Otherwise the [default masking state](#default-masking) is applied | API | #### Text input fields rules `UIKit.UITextField`, `UIKit.UITextView` and `SwiftUI.TextField` text inputs follow specific rules as the risk of leaking personal data is higher with these elements: | Rules (highest to lowest priority) | Configured via | | - | - | | 1. The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text inputs masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. An [instance](#maskingun-masking-by-instance) is specifically masked or unmasked | API | | 4. A [type](#maskingun-masking-by-type) is masked or unmasked | API | | 5. Otherwise a text input field remains masked | default | Note Default masking and parent masking don't change the masking state of text inputs. ### Public masking APIs #### Default masking All iOS views and subclasses of `UIView` are fully masked by default. The SDK provides an API to change the default masking state: ```swift /// Change the masking state of all types of views. /// - Parameter mask: true restores the default masking state. /// false unmasks every type of views. static func setDefaultMasking(_ mask: Bool) ``` Note Setting the default masking state to `false` does not affect `UITextField`, `SwiftUI.TextField` and `WKWebView`. #### Masking/Un-masking by instance * UIKit Use `mask(view:)` and `unmask(view:)` methods to deal with a specific instance. Masking is applied recursively to all subviews unless specified otherwise (cf. [Masking and Unmasking behaviors on a parent view](#masking-and-unmasking-behaviors-on-a-parent-view)). **Following the previous example on un-masking UIButtons:** you are in default masking, the `UIButton` are unmasked but a screen shows a button, `myButton`, that contains sensitive information. You can mask it with `mask(view: myButton)`. * SwiftUI Mask or unmask a SwiftUI `View` instance by using the following view modifier. Masking is applied recursively to all subviews unless specified otherwise (cf. [Masking and Unmasking behaviors on a parent view](#masking-and-unmasking-behaviors-on-a-parent-view)). ```swift @ViewBuilder func csMasking(_ shouldMask: Bool) -> some View ``` #### Masking/Un-masking by type Although the SDK allows masking elements by type for convenience but it isn't the recommended masking mechanism because it impacts all screens of your application. Use this when you have a specific class for presenting user information or for displaying the user profile picture to make sure it always stays masked, for instance. * UIKit Use `mask(viewsOfType:)` and `unmask(viewsOfType:)` methods if you want to handle a specific type, whether system or custom. **Example: un-masking UIButtons**: If default masking is set to true, and you don't want any button to be masked, call `unmask(viewsOfType: UIButton.self):` to specify that all instances of `UIButton` and its subclasses should not be masked. * SwiftUI Mask or un-mask by type using the following methods: ```swift /// Masks or unmasks all text elements. /// /// The text elements are `Text` for SwiftUI and `UILabel` for UIKit static func maskTexts(_ mask: Bool) ``` ```swift /// Masks or unmasks all image elements. /// /// The image elements are `Image` for SwiftUI and `UIImageView` for UIKit. static func maskImages(_ mask: Bool) ``` ```swift /// Masks or unmasks all text input elements. /// /// The text input elements are `TextField`, `SecureField`, `TextEditor` for SwiftUI /// and `UITextField`, `UITextView` for UIKit. /// static func maskTextInputs(_ mask: Bool) ``` Warning These APIs will also affect **UIKit masking**. You can use only these APIs and mask/unmask both UIKit and SwiftUI elements. #### Masking and Unmasking behaviors on a parent view ##### UIKit Masking is applied recursively to all children unless a specific rule has been applied to one of them. In this case, this rule also applies recursively. **Examples** Consider the following structure: ```plaintext (parent view) ------------------------ | "Parent Label" | | | | (child view) | | -------------------- | | | "Child Label" | | | | | | | -------------------- | | | ------------------------ ``` Here's how the masking rules applied affect the parent and child labels: | Rules applied | Parent Label | Child Label | | - | - | - | | No rule applied | Masked | Masked | | Parent view unmasked | Unmasked | Unmasked | | Parent view unmasked and child view masked | Unmasked | Masked | | Default masking = false | Unmasked | Unmasked | | Default masking = false and parent view masked | Masked | Masked | See [Masking rules](#masking-rules). **Unmasking an instance when its type is masked** If you've masked `UILabel` types specifically or are in default masking, call `unmask(view: myLabel)` so that all `UILabel` **instances** are masked except `myLabel`. **Mask an instance when its type is unmasked** If you've unmasked the `UILabel` type specifically or are using default masking, call `mask(view: myLabel)` so that no `UILabel` is masked except `myLabel`. ### Implementation recommendations * UIKit Masking operations should **always be performed before the target view is added to the window** to avoid any Personal Data leak. For instance, you can set up masking in the `didFinishLaunching` callback of your app or if you need to change masking behavior while your app is launched: this can be done in `loadView`, `viewDidLoad` or `viewWillAppear` if you use a `ViewController`. * SwiftUI Masking operations should be done as early as possible. For masking [by type](#maskingun-masking-by-type), in the setup of your app for instance. For masking [by instance](#maskingun-masking-by-instance), in the body of your `View` by calling the `csMasking` modifier. ### Keeping track of what is masked The SDK doesn't provide a list of what is currently masked, if you need to keep track, you probably will have to write your specific wrapper. ### Masking operations performance impact Repeating the same operation has little to no impact. For example, you can call `unmask(viewsOfType: UIButton.self)` multiple times without impacting the SDK or your app performance. ## Event-Triggered Replays (ETR) Event-Triggered Replays (ETR) is an add-on feature that allows you to selectively collect specific screens or sessions for Session Replay, based on predefined custom events. Once configured, ETR events can be used to filter specific replays, or view these events as they happen in the player event stream. To enable ETR, contact your CSM or Implementation Manager. For more information, see [Event-Triggered Replays ↗](https://support.contentsquare.com/hc/en-us/articles/4412027865874) in the Help Center. Note When ETR is enabled, the SDK collects data for the entire session even if none of the ETR methods described below are called. After collection, only the sessions or screens that match the global replay sampling rate or are associated with ETR events are retained. As a result, you may notice a network activity during all sessions, regardless of whether ETR has been triggered or not. Warning To protect end-user personal data, ensure that appropriate masking configurations are applied to all screens even the ones that are not associated with ETR events. ### Trigger Replay for the Session Use the following function to trigger Session Replay for the entire current session, with the parameter `name` as "ETR event". ```swift Contentsquare.triggerReplayForCurrentSession(name: name) ``` ### Trigger Replay for the Screen Use the following function to trigger Session Replay for the entire current screen, with the parameter `name` as "ETR event". ```swift Contentsquare.triggerReplayForCurrentScreen(name: name) ``` ## Advanced features for Experience Monitoring Note These features are only available for Experience Monitoring Mobile customers. Reach out to your Contentsquare contact for more details. ### Send user identifier Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier: email, phone number, customer ID… As these values are typically personal data, from the moment the SDK is collecting the User Identifier, we immediately encode the value using a hashing algorithm so that the information is hidden and can never be accessed. Warning **Note about Privacy Manifest:** If you decide to use User Identifier to collect new data or use already collected data but for a different purpose, it is up to you to update the privacy practices described in your app manifest accordingly. Here are some common examples of data collected via User Identifier: Email, Other user contact info, etc. See [Purpose of processing and categories of personal data collected](https://docs.contentsquare.com/en/ios/privacy/#purpose-of-processing-and-categories-of-personal-data-collected) already described in the Contentsquare iOS SDK Privacy Manifest. Use the following code to send a user identifier: ```swift Contentsquare.sendUserIdentifier("any_identifier") ``` When called, the SDK will log: ```plaintext CSLIB ℹ️ Info: User identifier hashed sent {value} ``` ### Sending a user identifier for each session You may want to send the user identifier for each session. While triggering the user identifier at app launch will cover most cases, it will not be enough. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See Session definition section for more information. That is why we also recommend sending the user identifier every time the app enters foreground. You can use [`didBecomeActiveNotification` notification ↗](https://developer.apple.com/documentation/uikit/uiapplication/1622953-didbecomeactivenotification) and [`sceneDidBecomeActive(_:)` callback ↗](https://developer.apple.com/documentation/uikit/uiscenedelegate/3197915-scenedidbecomeactive) to detect foreground and trigger a `sendUserIdentifier()`. ### Limitations * User identifier max length is 100 characters (if the limit is exceeded, the user identifier will not be handled and you will see an error message in the Console/Logcat) * Only the first 15 user identifiers per view will be processed on server side * The SDK will trim and lowercase user identifier * User identifier event are not visible in Log visualizer ## Integrations Contentsquare provides the ability to retrieve the link of the replay to be attached to other vendors such as Voice of Customer or Crash reporting tools. ### Get current replay Link Generate a link to the replay of the current session. This link can be pushed to any internal or 3rd-party tool as a custom property/variable. For instance, you can add the replay link to: * Each user request sent to your customer service tool * Each user voting in your Voice of Customer tool * Each user session in your App Performance, Observability tool * ... Note The replay link can also be accessed from the in-app features settings. See [Access the Replay](#access-the-replay). You can register to replay link creation and updates using the following API: ```swift Contentsquare.onSessionReplayLinkChange { link in self.currentCSReplayLink = link } ``` When you call this API, the SDK logs: ```plaintext CSLIB ℹ️ Info: Callback for SessionReplay link update is registered. ``` Warning You can only have one callback at a time. Calling this API twice will override the previous callback. To unregister the current callback, pass `nil` as the argument: ```swift Contentsquare.onSessionReplayLinkChange(nil) ``` When you call this API, the SDK logs: ```plaintext CSLIB ℹ️ Info: Callback for SessionReplay link update is unregistered. ``` When a new link is available, the SDK logs: ```plaintext CSLIB ℹ️ Info: SessionReplay link updated: https://app.contentsquare.com/quick-playback/index.html?pid={projectId}&uu={userId}&sn={sessionNumber}&recordingType=cs ``` Warning For the callback to be called, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event must have been sent, since Session Replay only starts after the first screenview event. If you have a Contentsquare account, you can use this link to directly watch your current Session Replay on the Contentsquare Platform. The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay the session up to the previous screenview if the session is still running. ## How Session Replay works ### Initialization Sessions can be collected for Session Replay if the Session Replay feature has been enabled for your project and the session matches the collection criteria. The following conditions will have an impact on which sessions will be collected: * **User consent**: The users have given their **consent** (if required) * **Collection rate**: The session is being **drawn for collection** (see Collection Rate below) * **Compatibility**: The **OS version** is supported. * **App version**: The **app version** is not part of the block list (see App version block list below) When Session Replay is turned off, no content specific to Session Replay is collected whatsoever. The standard Contentsquare analytics tracking remains unaffected by this. #### Collection rate Session Replay collection is based on a percentage of the total sessions. By default Session Replay collection is disabled. During the early access phase, the percentage or collected sessions will be set to 1% at the beginning. It will then be adjusted according to: * The traffic on your app * The volume of collected sessions set in the contract #### Compatibility See [Compatibility](https://docs.contentsquare.com/en/ios/compatibility/). #### App version block list Contentsquare team can add versions of your app in the block list to make sure Session Replay does not start on these versions. This is done when a problem is discovered on a specific version of your app, such as a Personal Data for which the masking was forgotten. This allows to keep Session Replay to work on the other app versions (especially the new ones with the fix). ### Data Collection The SDK monitors the application lifecycle events and the view hierarchy, and generates Session Replay data from the behavior of the app, the content of the screen and the interaction of the user. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. Tip Session collection will start at the 1st screenview event. ### Quality levels Session Replay has three quality levels available: High, Medium, Low. Quality level is defined by the frame rate and the image quality. The quality level is defined independently for **Wi-Fi** and **Cellular Network**. The default level for both is **Medium**. For more information on network data consumption see: [Performance Impact section](#performance-impact). Note If you require a particular setting, reach out to your Contentsquare contact that will make the adjustment in the project configuration. #### Quality-level examples Select the image to open it in full size and GIF format. [](https://docs.contentsquare.com/_astro/ios-quality-level.CjUY6Jo0.gif) ### Network and Storage By default, Session Replay data can be sent over **cellular network**. If the particular context of your app or users requires a very limited impact on cellular data consumption, **sending data over cellular network can be completely disabled**. Once disabled, data will be sent when the device is using Wi-Fi. Reach out to your Contentsquare contact that will make the adjustment in the project configuration. #### Storage Before being sent, data is stored in local files on disk up to 30MB on iOS and 20MB on Android. If the limit is reached, Session Replay is stopped. It will restart at the next app launch once the SDK is able to send the data. ### Requests The maximum request size is 1Mbyte. Requests are sent: * Every 10 seconds * At app hide * When [Replay Link API](#get-current-replay-link) is called ## Performance impact We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. ### Performance impact mitigation Most operations related to Session Collection are performed on background threads, for the impact on the main thread to be minimal. To make sure of this, we run performance tests on testing applications, using XCTMetric and Hitch Time Ratio measures. We also set up mechanisms that stop the Session Collection if we detect the feature is using too much memory. We defined our network strategy to have the lesser impact on CPU and battery of the users devices. We measure these impacts, using Apple Dev Tools, for each release of our SDK. Session Collection will also stop if we use up to 30Mbytes of local storage. You can reduce the quality level if you want to favor performance impact over quality. ### Performance test results The following performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | iPhone 7 | | iOS version | 15.7.8 | | Test App built using Xcode version | 14.3.1 | | Test App built with Swift version | 5.8 | | Quality level | High | | Default Masking State | Disabled | We conducted the tests using a default `Master-Detail` app built using ad hoc distribution with no app thinning and with Swift symbols stripped. In the app, the SDK was making calls to the public APIs, running, and collecting data in its default state. Note The numbers provided below will vary depending on the user's device, iOS version, SDK version, and if you use Swift or not, which Swift version you use if you do, if you enabled bitcode or not and which options you used when building your IPA for App Store distribution. Note Screens built with SwiftUI produce, on average, 120% of the SR data produced by similar screens built with UIKit. | Property | Value | | - | - | | Max CPU overhead | <10% | | Max RAM usage | <5MB | | Session Replay data transmitted over network during 1 minute of use | | | - with "High quality" level | <2Mbytes | | - with "Medium quality" level | <1Mbytes | | - with "Low quality" level | <900Kbytes | ## Known limitations ### Color [Init `UIColor` with Color ↗](https://developer.apple.com/documentation/uikit/uicolor/3550899-init) doesn't work in dark mode. **Workaround:** Use [`UIColor.init(named:)` ↗](https://developer.apple.com/documentation/uikit/uicolor/2877380-init). ### Maps Maps can potentially contain Personal Data and are therefore replaced by a placeholder with no ability to un-mask them. ### NSAttributedString handling The extracted text doesn't support the `expansion`, `obliqueness`, `paragraphStyle` and `textEffect` attributes. ### Multiline labels UIKit labels configured for multiple lines may overflow their bounding box, depending on the font and text length. A longer text increases the risks of causing an overlap with elements below (e.g.: other text, or image). ### Multiple windows Multi-window is not supported. ### System elements capture System elements are not collected. For instance, we do not collect: * `UIImagePickerController` * `SKStoreReviewController` * All `AVFoundation` components such as: * `AVPlayerViewController` for videos * `AVCaptureVideoPreviewLayer` for camera ### System elements masking Bottom line is that masking/unmasking any element is possible only if you have a reference or you know the type of the element that you want to mask. Since the access to the instance/type of Alert and Menu components is not documented in [Apple documentation ↗](https://developer.apple.com/documentation/uikit/uialertcontroller#overview), developers cannot directly mask/unmask these components or parts of them with CS public masking APIs. However, there are workarounds to mask/unmask them, as described below. #### Alerts ##### UIKit A possible workaround to fully mask a UIKit Alert is to pass the `UIAlertController` `view` property to the `mask(view:)` and `unmask(view:)` APIs. ##### SwiftUI SwiftUI Alerts cannot be specifically masked or unmasked. If the [default masking](#default-masking) is `false` and you want to mask an alert, a possible workaround is to mask all the app by changing the default masking to `true` when the alert appears and back to `false` when it disappears. Warning There is no workaround to unmask only an alert if the default masking is `true`. #### Menus Menus cannot be specifically masked or unmasked. If the [default masking](#default-masking) is `false` and you want to mask a menu, a possible workaround is to mask all the app by changing the default masking to `true` when the menu appears and back to `false` when it disappears. Warning There is no workaround to unmask only a menu if the default masking is `true`. ### System images ```swift Image(systemName: "pencil") ``` On iOS 17.0 and later, system images are considered as text within the masking rules. Any system-provided images used in your app's UI is subject to the same privacy and masking regulations as text content. ### Animations Animations lasting longer than 35 ms may be partially rendered in the replay, potentially resulting in a broken or incomplete layout for the rest of the animation. This does not affect the rest of the session, and the app will render correctly again on the next user interaction or detected animation. ### iOS 26 rendering Rendering limitation of apps compiled with Xcode 26 and running on iOS 26 include: * Some SwiftUI button backgrounds are not displayed correctly * Liquid Glass design and transparency effects are not faithfully rendered ### Apple Pay button The Apple Pay button is not rendered in the replay and appears as blank space. ## Troubleshooting ### Requests are not sent from an iOS simulator If you struggle to watch a replay collected on an emulator/simulator, it may be due to some network constraints applied on your computer (VPN, company network restrictions, etc.). Check your configuration or use a real device. See [Requests are failing](https://docs.contentsquare.com/en/ios/troubleshooting/#requests-are-failing) for more information about our endpoints and requests. ### Very long session on an iOS simulator If you leave the simulator/emulator running with the app in foreground, the session will not end, even if you are inactive. This can lead to artificially long sessions (several hours). To better emulate actual user behavior, put the app in background or kill it. Note An app kill **does not end a session**. See [Session definition](https://docs.contentsquare.com/en/ios/how-the-sdk-works/#session-definition). ### Uncaught exception due to NSAttributedString If the following exception is encountered: `NSInvalidArgumentException: -[__NSCFType CGColor]: unrecognized selector sent to instance`, It is probably due to an Objective-C bridging issue in `Foundation`, which makes it possible to pass `CGColor` instances as values for the `foregroundColor` and `strikeThroughColor` attributes of a `NSAttributedString`. While a `UILabel` with such an attributed string will be displayed correctly, its `textColor` attribute will have the wrong type, and the SDK won't be able to handle it, causing a crash in Session Replay. Because of this, it is important to ensure that actual `UIColor` instances are passed as values, as per the [official documentation ↗](https://developer.apple.com/documentation/foundation/nsattributedstring/key/1533563-foregroundcolor). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Session Replay","description":"How to implement Session Replay with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/ios/session-replay/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Surveys - iOS (classic) description: How to implement Surveys in your iOS app lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/ios/surveys/ md: https://docs.contentsquare.com/en/ios/surveys/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). Note Surveys are in Beta. If you are interested, reach out to your Contentsquare contact. Learn how to integrate, configure, and validate surveys using the Contentsquare SDK. Contentsquare mobile surveys enable collection of user feedback through configurable surveys displayed in mobile applications. These surveys capture the voice of your customers, providing valuable insights into how users perceive your app. By analyzing survey responses, you can make informed decisions for site improvements or identify issues you may not have been aware of. ## Before you begin To enable Surveys in your app and get the most stable version, it is required to [install](https://docs.contentsquare.com/en/ios/) or [upgrade](https://docs.contentsquare.com/en/ios/changelog/) the SDK to its latest version. If you install the SDK for the first time, these steps are required: * [Install the SDK](https://docs.contentsquare.com/en/ios/#install-the-sdk) * [Check the logs](https://docs.contentsquare.com/en/ios/#check-the-logs) * [Get user consent](https://docs.contentsquare.com/en/ios/#get-user-consent) To capture and review session replays where a survey is triggered, you'll also need to implement [Session Replay](https://docs.contentsquare.com/en/ios/session-replay/). ## Trigger surveys Triggering surveys allows for a clear separation between survey management and app development: * Marketing and Product Teams use the Contentsquare platform to create surveys and decide when they should appear by assigning them to a specific trigger (for example, `purchase-complete`). * Developers place these triggers in the application's code at key moments in the user journey. This allows your business teams to launch, update, and manage survey campaigns independently, without requiring a new app release. ### Step 1: Define and implement triggers Your mobile app can trigger a survey by referencing a predefined trigger name tied to a specific event or behavior. ```swift Contentsquare.triggerSurvey(triggerName: String) ``` Triggers act as flexible placeholders and are not bound to individual surveys—allowing your business team to assign or update surveys later without requiring code changes. For example, if you want to collect Net Promoter Score (NPS) feedback after a user completes a purchase: 1. Determine the precise moments in the user journey where you want to collect feedback and define the trigger name, for example `purchase-complete`. 2. Implement this trigger right after the purchase completes: ```swift Contentsquare.triggerSurvey("purchase-complete") ``` When this code is executed, it signals that the `purchase-complete` event has occurred, which in turn displays the corresponding survey to the user. Define triggers early Implement as many relevant survey triggers as possible during the initial setup. This reduces the need for future app updates if new surveys are added later. Triggers can safely exist in the code even if no survey is currently linked to them—these events will be ignored until a matching survey is configured. ### Step 2: Set up your first test survey To validate the integration, start by creating a test survey in the test environment of your application. * Create and activate a test survey on the Surveys platform by following [these steps ↗](https://support.contentsquare.com/hc/en-us/articles/37271718906513-How-to-create-a-survey). * When creating the survey, assign a test survey trigger — this is the trigger you'll implement in your application. ### Step 3: Validate the integration Validate the integration on the test environment of your application. 1. Implement the test survey trigger in your application code. 2. Launch the app and navigate as an end user to simulate the behavior or event associated with the trigger. 3. Confirm that the survey UI appears as expected. 4. Check SDK logs to ensure the trigger is recognized. Look for a log entry like: `CSLIB: Will attempt triggering survey`. 5. After successful validation, deactivate the test survey. ## Key considerations * Surveys can only be triggered and displayed when the device has an active internet connection * Session Replay does not capture the survey nor the user interactions with it * Only one survey can be displayed for a given trigger. If multiple surveys are configured for the same trigger, the SDK will display the one with the most specific matching criteria. If the criteria are identical, the most recently created survey will be shown ## Collected data The SDK collects the following data related to surveys: * Survey interaction events (for example, impressions, completion, or close actions) * Targeting parameters used for displaying surveys, such as the targeting percentage * Survey responses ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Surveys","description":"How to implement Surveys in your iOS app","url":"https://docs.contentsquare.com/en/ios/surveys/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Third-party libraries license - iOS (classic) description: Contentsquare iOS SDK includes several third-party libraries, which are licensed under their own respective licenses lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/ios/third-party-libraries-license/ md: https://docs.contentsquare.com/en/ios/third-party-libraries-license/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). The iOS SDK includes third-party libraries; the tables below list each library, its license, and copyright notice. ## Core SDK | Libraries | License | Copyright | | - | - | - | | SwiftProtobuf | Apache-2.0 license | Copyright (c) 2014 - 2017 Apple Inc. and the project authors | ## Error Analysis SDK | Libraries | License | Copyright | | - | - | - | | PLCrashReporter | MIT | Copyright (c) Microsoft Corporation. and the project authors | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Third-party libraries license","description":"Contentsquare iOS SDK includes several third-party libraries, which are licensed under their own respective licenses","url":"https://docs.contentsquare.com/en/ios/third-party-libraries-license/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track custom variables - iOS (classic) description: Track custom variables with the Contentsquare iOS SDK lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/ios/track-custom-variables/ md: https://docs.contentsquare.com/en/ios/track-custom-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). Custom variables attach additional information about the screen, user, or session to screenview events. For example, they can include information on the current layout of a screen, like day/night mode. Warning **Note about Privacy Manifest:** If you decide to use Custom Variables to collect new data or use already collected data but for a different purpose, it is up to you to update the privacy practices described in your app manifest accordingly. See [Purpose of processing and categories of personal data collected](https://docs.contentsquare.com/en/ios/privacy/#purpose-of-processing-and-categories-of-personal-data-collected) already described in the Contentsquare iOS SDK Privacy Manifest. ## Defining custom variables To define and send custom variables, follow this: * Swift ```swift import ContentsquareModule let cvar1 = CustomVar(index: 1, name: "CustomVarName1", value: "CustomVarValue1") let cvar2 = CustomVar(index: 2, name: "CustomVarName2", value: "CustomVarValue2") Contentsquare.send(screenViewWithName: "ScreenName", cvars: [cvar1, cvar2]) ``` Warning For consistent analytics, use the same index/name pair values across your application: **Screen A** ```swift let cvar4 = CustomVar(index: 1, name: "hero_banner_type", value: "carousel") Contentsquare.send(screenViewWithName: "ScreenA", cvars: [cvar4]) ``` **Screen B** ```swift let cvar4 = CustomVar(index: 1, name: "hero_banner_type", value: "slider") Contentsquare.send(screenViewWithName: "ScreenB", cvars: [cvar4]) ``` * Objective-C ```objective-c @import ContentsquareModule; CustomVar *cvar1 = [[CustomVar alloc] initWithIndex:1 stringName:@"CustomVarName1" stringValue:@"CustomVarValue1"]; CustomVar *cvar2 = [[CustomVar alloc] initWithIndex:2 stringName:@"CustomVarName2" stringValue:@"CustomVarValue2"]; [Contentsquare sendWithScreenViewWithName:@"ScreenName" cvars:@[cvar1, cvar2]]; ``` Warning For consistent analytics, use the same index/name pair values across your application: **Screen A** ```objective-c CustomVar *cvar4 = [[CustomVar alloc] initWithIndex:4 stringName:@"hero_banner_type" stringValue:@"carousel"]; [Contentsquare sendWithScreenViewWithName:@"ScreenA" cvars:@[cvar4]]; ``` **Screen B** ```objective-c CustomVar *cvar4 = [[CustomVar alloc] initWithIndex:4 stringName:@"hero_banner_type" stringValue:@"slider"]; [Contentsquare sendWithScreenViewWithName:@"ScreenB" cvars:@[cvar4]]; ``` ## Limits ### On the server side * It is possible to save up to 20 distinct custom variables per screenview. If more are received, only the first 20 custom variables, based on their `index` value, will be kept. * The `index` value of the custom variable is used to determine which custom variables to be kept. Only `index` value between 1 and 20 will be taken into account. ### On the SDK side * Every custom variable is composed of `index`, `name` and `value`. * If you are using the same `index` twice in the same screen, only the first (`name`, `value`) pair associated with the `index` will be kept. * In case `name`(max. 512 characters) or `value`(max. 255 characters) maximum character length is reached, the SDK will automatically trim the exceeding characters. * If `name` or `value` are empty, the SDK will instead send the literal string `"cs-empty"`. * Use a consistent index for a given custom var within an application — for instance, if the "screen layout" is collected with an `index` of 3, use the slot 3 for this information on every screen of the application. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track custom variables","description":"Track custom variables with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/ios/track-custom-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track dynamic variables - iOS (classic) description: Track dynamic variables with the Contentsquare iOS SDK lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/ios/track-dynamic-variables/ md: https://docs.contentsquare.com/en/ios/track-dynamic-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). Dynamic variables are additional information on the session that can be used to segment sessions. For example, they can include information on the A/B Test variations displayed to the current user. Warning **Note about Privacy Manifest:** If you decide to use Dynamic Variables to collect new data or use already collected data but for a different purpose, it is up to you to update the privacy practices described in your app manifest accordingly. Here are some common examples of data collected via dynamic variables: Contact info, Financial info, Location (country...), etc. See [Purpose of processing and categories of personal data collected](https://docs.contentsquare.com/en/ios/privacy/#purpose-of-processing-and-categories-of-personal-data-collected) already described in the Contentsquare iOS SDK Privacy Manifest. ## Defining dynamic variables To define and send a dynamic variable, you just need to use the following API: * Swift ```swift // string value Contentsquare.send(dynamicVar: DynamicVar(key: String, value: String)) // int value Contentsquare.send(dynamicVar: DynamicVar(key: String, value: UInt32)) ``` * Objective-C ```objective-c // string value DynamicVar *dynamicVarString = [[DynamicVar alloc] initWithKey:(NSString * _Nonnull) stringValue:(NSString * _Nonnull) error:(NSError * _Nullable __autoreleasing * _Nullable)]; [Contentsquare sendWithDynamicVar:dynamicVarString]; // int value DynamicVar *dynamicVarInt = [[DynamicVar alloc] initWithKey:(NSString * _Nonnull) intValue:(uint32_t) error:(NSError * _Nullable __autoreleasing * _Nullable)]; [Contentsquare sendWithDynamicVar: dynamicVarInt]; ``` To define and send a dynamic variable, directly use the key and String/UInt32 value: **Type of the value** — The value can be either a **whole number** or a **string**. For each case, available features won't be the same in the Contentsquare app: * For **whole numbers**, you will be able to do some algebra. Example: *sessions with dynamic variable key = "numberOfFriends" and value >= 10* * For **strings**, auto-completion and Regular Expression will be available. Example: *sessions with dynamic variable key = "accountType" and value = "Premium"* ## Sending a dynamic variable for each session You may want to send a dynamic variable for each session (like the user's country or store). While **triggering the dynamic variable at app launch will cover most cases, it will not be enough**. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See [Session definition](https://docs.contentsquare.com/en/ios/how-the-sdk-works/#session-definition) section for more information. That is why we also recommend **sending such dynamic variable every time the app enters foreground**. You can use [`didBecomeActiveNotification` notification ↗](https://developer.apple.com/documentation/uikit/uiapplication/1622953-didbecomeactivenotification) and [`sceneDidBecomeActive(_:)` callback ↗](https://developer.apple.com/documentation/uikit/uiscenedelegate/3197915-scenedidbecomeactive) to detect foreground and trigger a dynamic variable. ## Limits ### On the server side * It is possible to save up to 40 distinct dynamic variable keys per screenview. If more are received, only the first 40 keys will be kept. * If you are using the same key twice on the same screenview, the last value associated with the key will be collected. ### On the SDK side * Every dynamic variable is composed of a pair of key (max. 512 characters) and value (max. 255 characters string or number of type `UInt32` between 0 and 232 - 1). In case these maximums length are reached, the SDK will automatically trim the exceeding characters. * If key or value are empty, the SDK will instead send the literal string "cs-empty". ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track dynamic variables","description":"Track dynamic variables with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/ios/track-dynamic-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track screens - iOS (classic) description: Track screens with the Contentsquare iOS SDK lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/ios/track-screens/ md: https://docs.contentsquare.com/en/ios/track-screens/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). Contentsquare aggregates user behavior and engagement at the screen level. To do so, it is required to track screen transitions by calling a dedicated API. When the API is called, the SDK logs a `screen_view` event that identifies the new screen with the screen name provided. Warning Sessions without at least one screenview will be discarded. * Swift ```swift import ContentsquareModule Contentsquare.send(screenViewWithName: String, cvars: [CustomVar] = []) ``` * Objective-C ```objective-c @import ContentsquareModule; [Contentsquare sendWithScreenViewWithName:(NSString * _Nonnull)]; // or [Contentsquare sendWithScreenViewWithName:(NSString * _Nonnull) cvars:(NSArray<CustomVar *> * _Nonnull)]; // To add custom variables to screen tracking ``` ## Screen name handling The screen name is limited to 2083 characters. However, this limit is not enforced by the SDK, but rather by the Contentsquare servers. Note If the Track screen API is called without passing a screen name, the event will still be processed with default value: `missing screenName ([ViewController className])` Warning **Note about Privacy Manifest:** If you decide to use Screen names to collect new data or use already collected data but for a different purpose, it is up to you to update the privacy practices described in your app manifest accordingly. See [Purpose of processing and categories of personal data collected](https://docs.contentsquare.com/en/ios/privacy/#purpose-of-processing-and-categories-of-personal-data-collected) already described in the Contentsquare iOS SDK Privacy Manifest. ## Screenview after app in background The SDK triggers a screenview automatically after the app is put in background and foreground, as long as a screenview with a screen name has been triggered previously. It will use the last screen name set. ## Implementation recommendations From a functional standpoint, we expect a screenview to be sent: * Right after the SDK has started * When the screen appears * When a modal/pop-up is closed and the user is back on the screen * When the app is put in the foreground (after an app hide) We advise you to take a look at our reference implementations of screenviews in [our sample app ↗](https://github.com/ContentSquare/iOS-sample-app). Learning from them is the best way to make sure your implementations are correct. Regardless, here is some general advice. ### When to send your first screenview Most events collected by the SDK require a screenview event to be sent first so they can be associated with that screen; otherwise, they will be discarded. If you need to collect events from the moment the app launches, you should trigger a screenview event immediately after the SDK has started. #### Automatic start If the SDK is started automatically, you should send your first screenview when your app's life cycle begins. For instance, you can send it in `application:didFinishLaunchingWithOptions:` of your `UIApplicationDelegate` if you are using UIKit, or in the `init()` of your `App` struct if you are using SwiftUI: * UIKit ```swift func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // ... Contentsquare.send(screenViewWithName: "Launch screen") // ... return true } ``` * SwiftUI ```swift @main struct MyApp: App { init() { // ... Contentsquare.send(screenViewWithName: "Launch screen") // ... } } ``` #### Manual start If the SDK is started manually, you should send your first screenview right after calling `start()`: ```swift Contentsquare.start() Contentsquare.send(screenViewWithName: "Launch screen") ``` ### General rules From a functional standpoint, we expect a screenview to be sent: * When the screen appears on the device * When a modal or pop-up is displayed * When a modal or pop-up is closed, returning the user to the screen * When the app is brought back to the foreground (after being minimized) - UIKit As a general rule of thumb, you should send your screenviews in `viewWillAppear(_ animate: Bool)`. Be aware that only doing this might not cover all your cases though, and you might need to send screenview events in other parts of your code. - SwiftUI If you are using SwiftUI to build your application, you should send your screenview in `.onAppear()`. Be aware that only doing this might not cover all your cases though, and you might need to send screenview events in other parts of your code. ```swift import ContentsquareModule var body: some View { Text("My first screen") .foregroundColor(Color.blue) .onAppear() { Contentsquare.send(screenViewWithName: "First screenView") } } ``` Known limitation Apps using the SwiftUI [`.drawingGroup(opaque:colorMode:)` ↗](https://developer.apple.com/documentation/swiftui/view/drawinggroup\(opaque:colormode:\)) modifier may experience issues with Zoning Analysis. This modifier flattens a subtree of views into a single offscreen image (bitmap) before rendering it. As a result, individual components within the group are not accessible to the SDK, making it impossible to apply zoning to them. ### ScrollViews with paging Be careful when tagging screens with paged ScrollViews: if you want to create a screenview event whenever the user changes the page, do so in UIScrollViewDelegate's `scrollViewDidEndDecelerating(_ scrollView: UIScrollView)` function. Make sure that you do not trigger a double tag when the screen appears, or when you come back to the screen after the app being hidden. Also make sure not to send a screenview when the user slightly interacts with a page, but without really changing pages. ### Popups and modals When dealing with popups and modals, if you are having issues triggering a screenview event for the underlying view when the modal closes we have the following advice. You could overcome this issue by using a delegate pattern, and setting the underlying screen as the modal's delegate. The modal would call some delegate method when it is dismissed. The underlying screen would implement that method, where it would make the screenview. iOS 13 and later On iOS 13 and more, modals can be dismissed by swiping down. In that case, `unwindFromSegue` won't be triggered. The new `presentationControllerDidDismiss(_ presentationController:)` function of `UIAdaptivePresentationControllerDelegate` will be triggered instead. Implement this function and call `Contentsquare.send(screenViewWithName:)` there for the tracking to be correct on all iOS versions. [Check out our sample app ↗](https://github.com/ContentSquare/iOS-sample-app/blob/master/Shared/Showcases/Screen%20Views/Modals/ModalPresentingViewController.swift) for more details about the implementation. ### Back navigation and navigation between screens Make sure that screenview events will be triggered when a user will go to the previous screen (example: Home → Profile → Home), it is expected to have a screenview event for the Home screen that might be reached with the back navigation button. Normally, if you send your screenviews in `viewWillAppear`, this should work fine. ### Redirecting the user to another screen (authentication, home) when closing the app/re-opening the app For some apps, you might want to redirect users whenever they hide your app, for example for security purposes (bank apps, password managers, etc...). If that is the case, pay specific attention to the way screenview events are sent, in order not to track a screen which is not actually shown users. ### Application life cycle When your application returns from the background to the foreground, the SDK automatically logs a screenview with the title of the last logged screenview, so you don't have to handle this transition yourself. ## How to name screens As a general rule, keep the number of distinct screen names under 100. Since these names are used to map your app in Contentsquare, choose names that are clear and comprehensive. ### Separate words with spaces, dashes, or underscores When generating screen names with multiple words, separate them using spaces, dashes, or underscores. For instance, use `Home & Living - Home Furnishings` instead of ~~`homeLivingHomeFurnishings`~~ for a sub-category in a retail app. Casing sensitivity Screen names are not case sensitive and will appear in lowercase on the Contentsquare platform. ```swift Contentsquare.send(screenViewWithName: "ScreenName") // screenname Contentsquare.send(screenViewWithName: "Screen Name") // screen name Contentsquare.send(screenViewWithName: "screen_name") // screen_name Contentsquare.send(screenViewWithName: "screenname") // screenname ``` ### Use screen template/layout names As a general recommendation, use names referring to the screen template/layout rather than referring to the specific content (data). This will help: * To keep the number of distinct screen names low and therefore make Contentsquare easier to use * Remove the risk of sending Personal Data to Contentsquare List of screen types falling into that category: *Product detail, Event detail, Conversation/Chat, User profile...* ### Screens with multiple states/layouts Screens can have different layouts or states depending on the user context. In this case, append its value to the screen name. **Home screen** | State | Screen name | | - | - | | App landing layout | `Home` | | Women products layout | `Home - Women` | | Men products layout | `Home - Men` | | Sales layout | `Home - Sales` | **Product Detail screen (PDP)** | State | Screen name | | - | - | | Users on a Top for Women PDP | `PDP - Clothing - Women - Tops` | | Users on a Microwave PDP | `PDP - Kitchenware - Electrics - Microwave` | | Users on a Hotel details screen | `PDP - Holiday type - Season - Board` | **User account screen** | State | Screen name | | - | - | | Overview | `My Account - Dashboard` | | Order history | `My Account - Order history` | | Returns | `My Account - Returns` | **Search screen** | State | Screen name | | - | - | | Search | `Search` | | Search results for "Skincare" products | `Search - Skincare` | | Search results error screen | `Search - Error` | **Cart screen** | State | Screen name | | - | - | | Empty cart | `Cart - Empty` | | Items have been added to the cart | `Cart - Populated` | | Issues with availability or pricing | `Cart - Error` | **Checkout screen** | State | Screen name | | - | - | | User provides name, surname, and date of birth | `Checkout - User Details` | | User provides shipping address | `Checkout - Shipping Details` | | User inputs their credit card information | `Checkout - Payment` | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track screens","description":"Track screens with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/ios/track-screens/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track transactions - iOS (classic) description: Track transactions with the Contentsquare iOS SDK lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/ios/track-transactions/ md: https://docs.contentsquare.com/en/ios/track-transactions/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). To associate a user's session with their potential purchases (and corresponding revenue), you must send the transaction via a dedicated API. For each transaction, we send: * Price (mandatory) * Currency (mandatory) * Transaction ID (optional) - Swift ```swift // numeric currency // CustomerTransaction(id: String?, value: Float, currency: Currency) let transaction = CustomerTransaction(id: "transaction_id", value: 430.99, currency: Currency.eur) Contentsquare.send(transaction: transaction) // alphanumeric currency // CustomerTransaction(id: String?, value: Float, currency: String) let transaction = CustomerTransaction(id: "transaction_id", value: 430.99, currency: "EUR") Contentsquare.send(transaction: transaction) ``` - Objective-C ```objective-c // numeric currency CustomerTransaction *transaction = [[CustomerTransaction alloc] initWithId:@"transaction_id" value:430.99 currency:CurrencyEur]; [Contentsquare sendWithTransaction:transaction]; // alphanumeric currency CustomerTransaction *transaction = [[CustomerTransaction alloc] initWithId:@"transaction_id" value:430.99 stringCurrency:"EUR"]; [Contentsquare sendWithTransaction:transaction]; ``` Warning **Each transaction must only be sent once**. A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ## Currency The currency is conforming to the [ISO 4217 ↗](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) standard. The currency can be passed either as "alphanumeric code" or "numeric code". If the currency passed doesn't match the supported currencies, the SDK will send a currency value of `-1`. It will be processed as the default currency of the project. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track transactions","description":"Track transactions with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/ios/track-transactions/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track Webviews - iOS (classic) description: Track webviews with the Contentsquare iOS SDK lastUpdated: 23 April 2026 source_url: html: https://docs.contentsquare.com/en/ios/track-webviews/ md: https://docs.contentsquare.com/en/ios/track-webviews/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). WebView tracking links the Contentsquare SDK to the JavaScript tag running inside your WebViews to support analytics and Session Replay for web content displayed within your app. iOS compatibility Contentsquare **only** allows to track instances of `WKWebView`. `SFSafariViewController` is **not** supported: The Contentsquare SDK **cannot** track what is happening within its context, and its content will **not** be visible in Session Replay. ## Enable tracking in WebViews ### Where to inject your WebViews? It is **essential** that you inject your WebViews in `viewWillAppear()`. Additionally, when setting a delegate on your WebView, ensure that it is implemented and set **before** calling `Contentsquare.register(webView: WKWebView)`. If this order is not respected, your delegate will **not** receive any callbacks. ### WebView registration Use the following API: * Swift ```swift // Start tracking the given WKWebView Contentsquare.register(webView: WKWebView) ``` * Objective-C ```objective-c // Start tracking the given WKWebView Contentsquare registerWithWebView:(WKWebView * _Nonnull)]; ``` ### Tag setup To complete the implementation, inject the **CS Tag in WebView mode** on your pages. See 📚 [Mobile Apps WebView Tracking Documentation](https://docs.contentsquare.com/en/webview-tracking-tag/#manual-injection). ## Let's sum it up Let's illustrate our implementation with a `UIViewController`. In your `viewWillAppear()` method, add the following: * Swift ```swift override func viewWillAppear(_ animated: Bool) { super.viewWillAppear(animated) // Inject the Bridge between the CS Tag in WebView mode and the SDK Contentsquare.register(webView: webView) } ``` * Objective-C ```objective-c - (void)viewWillAppear:(BOOL)animated { [super viewWillAppear:animated]; // Inject the Bridge between the CS Tag in WebView mode and the SDK [Contentsquare registerWithWebView:self.webView]; } ``` ## Validate WebView tracking ### On the native side Once you open the screen with the tracked WebView in your app, you should see the following logs in sequence: 1. **WebView registered:** ```plaintext CSLIB ℹ️ Info: [WebView] Registering WebView on native side for page: [URL]. Waiting for Web Tracking Tag messages… ``` 2. **Web page loaded:** ```plaintext CSLIB ℹ️ Info: [WebView] Navigated to new page: [URL]. Waiting for Web Tracking Tag messages… ``` ### On the Web side Once the Web Tracking tag runs in the web page, you should see the following logs in sequence: 1. **JavaScript bridge detected:** ```plaintext CSLIB ℹ️ Info: [WebView] CSJavascriptBridge is detected on page: [URL] ``` 2. **Tag configuration received — confirms successful tag to SDK communication:** ```plaintext CSLIB ℹ️ Info: [WebView JS log] (TAG_CONFIGURATION) [Config] ``` #### Validating Pageview and Gestures tracking Page views sent through the Web Tracking Tag are displayed the same way as native screen views: ```plaintext CSLIB ℹ️ Info: Screenview - Screen name: "{{page name given}}" - Screen number: 11 ``` Taps and swipes detected by the Web Tracking Tag are also displayed the same way as taps and swipe on native elements, but the end of the target contains HTML DOM elements: ```plaintext CSLIB ℹ️ Info: Tap - Target: ...>UIViewControllerWrapperView:eq(0)>UIView:eq(0)>WKWebView:eq(0)|webview|img#picture-holder ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track Webviews","description":"Track webviews with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/ios/track-webviews/","inLanguage":"en","dateModified":"2026-04-23T15:45:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Troubleshooting - iOS (classic) description: Need help? We share probable causes and recommended fixes lastUpdated: 29 July 2026 source_url: html: https://docs.contentsquare.com/en/ios/troubleshooting/ md: https://docs.contentsquare.com/en/ios/troubleshooting/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). When the SDK is not sending data as expected, use this page to identify probable causes and apply recommended fixes. ## Requests are failing In order for Contentsquare to work, you need to make sure the following endpoints are not blocked by your network (VPN): | Request | Endpoint | Detail | | - | - | - | | Config file | `https://mobile-production.content-square.net` | See [Configuration](../how-the-sdk-works/#configuration) | | Analytics data (EU) | `https://m.csqtrk.net` `https://m.ba.contentsquare.net` `https://m.aa.contentsquare.net` | See [Sending data](../how-the-sdk-works/#sending-data) | | Analytics data (US) | `https://m-aus1.contentsquare.net` `https://m.bf.contentsquare.net` `https://m.af.contentsquare.net` | See [Sending data](../how-the-sdk-works/#sending-data) | | Monitoring | `https://l.contentsquare.net` | Used by the SDK to send SDK monitoring analysis in JSON format over HTTPS. | | Session Replay data (EU) | `https://ka-aeu1.contentsquare.net` `https://ka.ba.contentsquare.net` `https://ka.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Session Replay data (US) | `https://ka-aus1.contentsquare.net` `https://ka.bf.contentsquare.net` `https://ka.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Screenshot (EU) | `https://s.contentsquare.net` `https://b.ba.contentsquare.net` `https://b.aa.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Screenshot (US) | `https://s-aus1.contentsquare.net` `https://b.bf.contentsquare.net` `https://b.af.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Resources manager (EU) | `https://srm.ba.contentsquare.net` `https://srm.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Resources manager (US) | `https://srm.bf.contentsquare.net` `https://srm.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | ## Error message "Contentsquare SDK cannot execute operation" If the following message appears in the logs: ```plaintext CSLIB ℹ️ Info:⚠️ Contentsquare SDK cannot execute operation because it hasn't been started. ``` It means SDK API calls were done incorrectly. In this case: **gestures and lifecycle events won't be tracked by the SDK.** Two possible explanations exist for this issue: * The SDK is manually started and API calls were made before call to `start`. * The SDK is automatically started and API calls were made before the `AppDelegate.willFinishLaunchingWithOptions`. Ensure that it doesn't happen or contact our support team if you have a specific need. ## Providing a debug build for investigation 1. Build your app for iOS device (not simulator) 2. Open the product folder for your app  3. Copy the .app from Debug-iphoneos and send it to the Contentsquare team  ## Wrong tag loaded in WebView When using Manual tag injection for dual context (WebView and Browser tracking on the same webpage), the SDK injects a script that may load after the page, causing the wrong tag to load in the WebView. Use one of the following solutions: * Add your own user script before the webview loads the page: ```swift let userScript = WKUserScript( source: "window.isWebView = true;", injectionTime: .atDocumentStart, forMainFrameOnly: false ) webView.configuration.userContentController.addUserScript(userScript) ``` Then make sure to include the added script variable in the webview check on the page itself: ```javascript function isWebView() { return navigator.userAgent.indexOf('CS_WebView') !== -1 || typeof CSJavascriptBridge != 'undefined' || !!window.CS_isWebView || window.isWebView; // Your added variable } /// ... ``` * Add a query parameter to the URL of the page you are loading in the WebView: ```swift URL(string: "https://www.apple.com/?isWebView=1") ``` Then add it to the conditions in the page script itself: ```javascript function isWebView() { return navigator.userAgent.indexOf('CS_WebView') !== -1 || typeof CSJavascriptBridge != 'undefined' || !!window.CS_isWebView || new URLSearchParams(window.location.search).get('isWebView') === '1'; } /// ... ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Troubleshooting","description":"Need help? We share probable causes and recommended fixes","url":"https://docs.contentsquare.com/en/ios/troubleshooting/","inLanguage":"en","dateModified":"2026-07-29T20:54:18+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Use Adobe Analytics - iOS (classic) description: Leverage our native integration to use Adobe Analytics segments in Contentsquare, with the Contentsquare iOS SDK lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/ios/use-adobe-analytics/ md: https://docs.contentsquare.com/en/ios/use-adobe-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). Analyze your data from anywhere in the customer journey using your Adobe Analytics segments. Contentsquare allows you to use your Adobe Analytics segments in every Contentsquare feature (Journey Analysis, Page Comparator, Session Replay). Warning Sessions without at least one screenview will be discarded. You should implement your screen tracking plan first, to have your Adobe Analytics integration work. See [Track screens](../track-screens/). ## Prerequisites 1. Follow the instructions from [Adobe Analytics for mobile apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271665881745) 2. Add the [AEPAnalytics iOS SDK ↗](https://github.com/adobe/aepsdk-analytics-ios) to your project ## Code implementation Note **Adobe SDK code requirements** * Make sure you register at least `AEPIdentity` and `AEPAnalytics` extensions before starting `AEPCore`. Check the [Getting Started with Adobe Analytics iOS Extension ↗](https://github.com/adobe/aepsdk-analytics-ios/blob/main/Documentation/AEPAnalytics.md) repository for that. **Why 30 minutes before sending a new csMatchingKey** * 30 minutes is Contentsquare default session duration. * Setting a value **higher** than 30 minutes would cause overlapping on our sessions, and would impact negatively the data import from Adobe. * Setting a value **lower** than 30 minutes would make you to send more data to Adobe. This could cause the variable to reach Adobe's threshold, causing Adobe to filter values, and potentially impact your billing. See [Low-traffic value in Adobe Analytics ↗](https://experienceleague.adobe.com/docs/analytics/technotes/low-traffic.html) - Swift **AppDelegate.swift** ```swift var canSendCSMatchingKey = false func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // ... your existing code .. MobileCore.registerExtensions([Identity.self, Analytics.self, ....], { // ... your existing code .. self.canSendCSMatchingKey = true self.sendCSMatchingKeyIfNeeded() }) // When going back to foreground, more than 30 minutes may have elapsed. // In this situation Contentsquare SDK may create a new session // This is why `sendCSMatchingKeyIfNeeded` must be called in this situation NotificationCenter.default.addObserver(self, selector: #selector(sendCSMatchingKeyIfNeeded), name: UIApplication.didBecomeActiveNotification, object: nil) // ... your existing code .. } @objc func sendCSMatchingKeyIfNeeded() { guard canSendCSMatchingKey else { return } let csMatchingKeyTimestampKey = "csMatchingKey_ts" let csMatchingKeyValidityMs = 1_800_000 // 30 minutes let currentTimestamp = Int(Date().timeIntervalSince1970 * 1000) let csMatchingKeyIsPreviousTimestamp = UserDefaults.standard.integer(forKey: csMatchingKeyTimestampKey) guard (currentTimestamp - csMatchingKeyIsPreviousTimestamp) > csMatchingKeyValidityMs else { return } UserDefaults.standard.set(currentTimestamp, forKey: csMatchingKeyTimestampKey) let csMatchingKey = "csMatchingKey" let csMatchingKeyValue = "\(Double.random(in: 0..<1))_\(currentTimestamp)" Contentsquare.send(dynamicVar: DynamicVar(key: csMatchingKey, value: csMatchingKeyValue)) MobileCore.track(state: "csMatchingKey_state", data: [csMatchingKey: csMatchingKeyValue]) } ``` - Objective-C **AppDelegate.m** ```objective-c @interface AppDelegate () @property (nonatomic, assign) BOOL canSendCSMatchingKey; @end @implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { self.canSendCSMatchingKey = NO; // ... your existing code .. [AEPMobileCore registerExtensions:@[AEPMobileEdgeIdentity.class, AEPMobileAnalytics.class] completion:^{ // ... your existing code .. self.canSendCSMatchingKey = YES; [self sendCSMatchingKeyIfNeeded]; }]; // When going back to foreground, more than 30 minutes may have elapsed. // In this situation Contentsquare SDK may create a new session // This is why `sendCSMatchingKeyIfNeeded` must be called in this situation [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(sendKeyIfNeeded) name:UIApplicationDidBecomeActiveNotification object:nil]; // ... your existing code .. return YES; } - (void)sendCSMatchingKeyIfNeeded { if (!self.canSendCSMatchingKey) { return; } NSString *csMatchingKeyTimestampKey = @"csMatchingKey_ts"; NSInteger csMatchingKeyValidityMs = 1800000; // 30 minutes NSInteger currentTimestamp = (NSInteger)([[NSDate date] timeIntervalSince1970] * 1000); NSInteger csMatchingKeyIsPreviousTimestamp = [[NSUserDefaults standardUserDefaults] integerForKey:csMatchingKeyTimestampKey]; if ((currentTimestamp - csMatchingKeyIsPreviousTimestamp) <= csMatchingKeyValidityMs) { return; } [[NSUserDefaults standardUserDefaults] setInteger:currentTimestamp forKey:csMatchingKeyTimestampKey]; NSString *csMatchingKey = @"csMatchingKey"; NSString *csMatchingKeyValue = [NSString stringWithFormat:@"%f_%f", (double)arc4random() / UINT32_MAX, currentTimestamp]; DynamicVar *csMatchingKeyDynamicVar = [[DynamicVar alloc] initWithKey:csMatchingKey stringValue:csMatchingKeyValue error:(NSError * _Nullable __autoreleasing * _Nullable)]; [Contentsquare sendWithDynamicVar:csMatchingKeyDynamicVar]; [AEPMobileCore trackState:@"csMatchingKey_state" data:@{csMatchingKey:csMatchingKeyValue}]; } @end ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Use Adobe Analytics","description":"Leverage our native integration to use Adobe Analytics segments in Contentsquare, with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/ios/use-adobe-analytics/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Use Google Tag Manager - iOS (classic) description: Leverage our native integration to send Google Tag Manager events to Contentsquare, with the Contentsquare iOS SDK lastUpdated: 02 June 2026 source_url: html: https://docs.contentsquare.com/en/ios/use-google-tag-manager/ md: https://docs.contentsquare.com/en/ios/use-google-tag-manager/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/). If you are using Firebase to track events such as screenviews or transactions, you can trigger these events for Contentsquare with minimal effort, thanks to Google Tag Manager. ## Prerequisite If you are following this Google Tag Manager integration process, you should already have followed the Google Tag Manager + Firebase setup as described in [Google's Tag Manager + Firebase: Getting Started ↗](https://developers.google.com/tag-manager/ios/) You also need to integrate the Contentsquare SDK [see section: Add Contentsquare to your app](https://docs.contentsquare.com/en/ios/#install-the-sdk). ## Screenview events This section covers how to trigger a Contentsquare screenview event for every Firebase screenview event. Firebase allows you to [log screenviews automatically or manually ↗](https://firebase.google.com/docs/analytics/screenviews) for an exhaustive coverage of your app screens. ### Variables Contentsquare screenview events require a `name` parameter. Firebase has 2 ways to track screens: #### 1. Variable for automatically tracked screens Firebase's `screen_view` events have an `_sc` parameter (for screen class) which we can use as parameter for screens that are **automatically tracked**. We will create a variable called **Automatic Screenview Name** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `_sc`  #### 2. Variable for manually tracked screens Firebase's `screen_view` events have a `_sn` parameter (for screen name) which we can use as parameter for screens that are **manually tracked**. We will create a variable called **Manual Screenview Name** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `_sn`  We can also create variables for our own custom parameters, for example, we can send a `screen_view` event like this: ```swift Analytics.logEvent(AnalyticsEventScreenView, parameters: [ AnalyticsParameterScreenName: "MyScreenName", "is_user_logged_in": "true" ]) ``` and create a variable called **Is User Logged In** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `is_user_logged_in` Check out [Configure variables in Tag Manager ↗](https://developers.google.com/tag-platform/tag-manager/ios/v5#configure_variables_in_tag_manager) for more information. ### Screenview trigger We will need to tell Google Tag Manager when to send a Contentsquare screenview, and for that we need to create a **Trigger**. Firebase sends screenviews as events of name `screen_view`, so we need to create a trigger for that event. * Name your trigger `Screenview Trigger` * **Trigger Type** should be set to **Custom** * Trigger should fire on **Some Events** * For the Event, the **Event Name** should be **equal** to `screen_view`  ### Create the custom function Tag In Google Tag Manager, a **Tag** is what configures what happens when some trigger is activated. It will be automatically linked to a custom class which we will create in a later step. The **Tag Type** should be a **Function Call**. You will also need to fill in the **Class Name** field with a class name of your liking, typically related to what the tag is about (here we chose `ContentsquareScreenviewTag`), which you will re-use later.  ### Adding the trigger and the variables to the Tag Edit the `ContentsquareScreenviewTag` Tag: Tip Type `{{` or click `+` to make sure you are referencing existing GTM variables. * Add an argument with the key `auto_screen_name` and the variable **`{{Automatic Screenview Name}}`** as the value * Add an argument with the key `manual_screen_name` and the variables **`{{Manual Screenview Name}} | {{Is User Logged In}}`** or **`{{Manual Screenview Name}}`** as the value * Add **Contentsquare Screenview Trigger** as the Tag's trigger It should look like this now:  ### Create the custom function Tag class In your app code, create a class of the same name as the `Class Name` you configured in the GTM interface, for example `ContentsquareScreenviewTag`. This is how GTM connects the configuration and the actual class to trigger. This class is used to call the Contentsquare screenview tracking function as follows: * Swift ```swift @objc(ContentsquareScreenviewTag) final class ContentsquareScreenviewTag: NSObject, TAGCustomFunction { @objc func execute(withParameters parameters: [AnyHashable : Any]!) -> NSObject! { let autoScreenName = parameters[AnyHashable("auto_screen_name")] as? String let manualScreenName = parameters[AnyHashable("manual_screen_name")] as? String let screenName = manualScreenName ?? autoScreenName ?? "No screen name!" Contentsquare.send(screenViewWithName: screenName) return nil } } ``` * Objective-C ```objective-c @implementation ContentsquareScreenviewTag <TAGCustomFunction> - (NSObject*)executeWithParameters:(NSDictionary*)parameters { NSString *autoScreenName = [parameters objectForKey:@"auto_screen_name"]; NSString *manualScreenName = [parameters objectForKey:@"manual_screen_name"]; NSString *screenName = manualScreenName ? : (autoScreenName ? : @"No screen name!"); [Contentsquare sendWithScreenViewWithName:screenName]; return nil; } @end ``` Now, every time Firebase sends a screenview event, Contentsquare will send one as well. ## Screenview events with Custom Variables Custom Variables Custom variables are additional information on the page, the user or the session, sent with screenviews. For more information about custom variables, see [Track Custom Variables](https://docs.contentsquare.com/en/ios/track-custom-variables/). It is possible to send custom variables along with the screenview events. To do so: 1. Follow **Use Google Tag Manager** > [Screenview events](#screenview-events) 2. Add extra arguments to the `ContentsquareScreenviewTag` Tag as follows: * *Key:* the index of the custom variable * *Value:* a string that will contain the custom variable name and value such as `CVAR_NAME : {{Event Name}}` Note The value of the custom variable is composed of a name and a value: `NAME : VALUE` concatenated into a single string and separated by `:`. It should look like this:  For Custom Variables You are free to implement your own logic for filling key and value in GTM, but the application side must be able to receive and extract for each custom variable: 1. An index 2. A name 3. A value In the code of your application, edit the code of your class to handle the added custom variables: * Swift ```swift @objc(ContentsquareScreenviewTag) final class ContentsquareScreenviewTag: NSObject, TAGCustomFunction { @objc func execute(withParameters parameters: [AnyHashable : Any]!) -> NSObject! { let autoScreenName = parameters[AnyHashable("auto_screen_name")] as? String let manualScreenName = parameters[AnyHashable("manual_screen_name")] as? String let screenName = manualScreenName ?? autoScreenName ?? "No screen name!" var cvars = [CustomVar]() for (gTagKey, gTagValue) in parameters { guard let gTagKey = gTagKey as? String, let cvarIndex = UInt32(gTagKey), let gTagValue = gTagValue as? String else { continue } let cvarKeyValue = gTagValue.components(separatedBy: ":") if cvarKeyValue.count == 2 { let name = cvarKeyValue[0].trimmingCharacters(in: .whitespaces) let value = cvarKeyValue[1].trimmingCharacters(in: .whitespaces) let cvar = CustomVar(index: cvarIndex, name: name, value: value) cvars.append(cvar) } } Contentsquare.send(screenViewWithName: screenName, cvars: cvars) return nil } } ``` * Objective-C ```objective-c @implementation ContentsquareScreenviewTag<TAGCustomFunction> - (NSObject*)executeWithParameters:(NSDictionary*)parameters { NSString *autoScreenName = parameters[@"auto_screen_name"]; NSString *manualScreenName = parameters[@"manual_screen_name"]; NSString *screenName = manualScreenName ?: autoScreenName ?: @"No screen name!"; NSMutableArray *cvars = [NSMutableArray array]; for (NSString *gTagKey in parameters) { NSUInteger cvarIndex = [gTagKey integerValue]; NSString *gTagValue = parameters[gTagKey]; NSArray *cvarKeyValue = [gTagValue componentsSeparatedByString:@":"]; if (cvarKeyValue.count == 2) { NSString *name = [cvarKeyValue[0] stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceCharacterSet]]; NSString *value = [cvarKeyValue[1] stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceCharacterSet]]; CustomVar *cvar = [[CustomVar alloc] initWithIndex:cvarIndex name:name value:value]; [cvars addObject:cvar]; } } [Contentsquare sendScreenViewWithName:screenName cvars:cvars]; return nil; } @end ``` With this code, the custom variables will be sent by Contentsquare automatically along with the screenview. ## Transaction events A Contentsquare transaction event can also be triggered for every Firebase `ecommerce_purchase` event (See Firebase [Objective-C ↗](https://firebase.google.com/docs/reference/ios/firebaseanalytics/api/reference/Constants#/c:FIREventNames.h@kFIREventPurchase)/[Swift ↗](https://firebase.google.com/docs/reference/swift/firebaseanalytics/api/reference/Constants#analyticseventpurchase) documentation). To do so, you will need to follow the setup described below. ### Variables We have to create at least two variables to be able to build a transaction event: Value and Currency. Optionally, it is also possible to pass a transaction identifier, meaning you would need to create an additional variable to be able to use it. #### Value (mandatory)  #### Currency (mandatory)  #### Transaction ID (optional)  ### Trigger Create the following custom trigger.  ### Tag Create a **Function call** Tag called `ContentsquareTransactionTag`, pass the two to three variables created earlier as arguments (skip the `id` line if you do not want to use it) and set its trigger to the one you just created.  ### Implementing the function call We need to create a `ContentsquareTransactionTag` class, and have it adhere to the `TAGCustomFunction` protocol to link it to the Google Tag Manager custom Tag of the same name. Take good to be able to create and send a Contentsquare Transaction successfully, when you create a Firebase purchase event you will have to at least pass values for `kFIRParameterValue` and `kFIRParameterCurrency`, and can optionally pass a value for `kFIRParameterTransactionID`, when you create a Firebase purchase event. * Swift ```swift @objc(ContentsquareTransactionTag) final class ContentsquareTransactionTag: NSObject, TAGCustomFunction { @objc func execute(withParameters parameters: [AnyHashable : Any]!) -> NSObject! { if let currency = parameters[AnyHashable("currency")] as? String, let value = parameters[AnyHashable("value")] as? Float { let identifier = parameters[AnyHashable("id")] as? String Contentsquare.send(transaction: CustomerTransaction.init(id: identifier, value: value, currency: currency)) } return nil } } ``` * Objective-C ```objective-c @implementation ContentsquareTransactionTag <TAGCustomFunction> - (NSObject*)executeWithParameters:(NSDictionary*)parameters { NSString *identifier = [parameters objectForKey:@"transaction_id"]; NSNumber *value = [parameters objectForKey:@"value"]; NSString * currency = [parameters objectForKey:@"currency"]; if (currency && value) { [Contentsquare sendWithTransaction:[[CustomerTransaction alloc] initWithId:identifier value:[value floatValue] stringCurrency:currency]]; } return nil; } @end ``` Now, every time Firebase sends an `ecommerce_purchase` event, Contentsquare will send one as well. ## Dynamic variable events We can send values from any Firebase event as a Contentsquare dynamic variable: ```swift Analytics.logEvent("addToCart", parameters: [ "product_count": 12, "product_name": "ProductA" ]) ``` ### Variables The `addToCart` event has parameters `product_count`, `product_name`, we will create variables called **Product Count** and **Product Name** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `product_count`/`product_name` Check out [Configure variables in Tag Manager ↗](https://developers.google.com/tag-platform/tag-manager/ios/v5#configure_variables_in_tag_manager) for more information. ### Triggers We need to create a **Trigger** to tell Google Tag Manager when to send a Contentsquare dynamic variable, so we will create one for the event `addToCart`. * Name your trigger `AddToCartTrigger` * **Trigger Type** should be set to **Custom** * Trigger should fire on **Some Events** * For the Event, the **Event Name** should be **equal** to `addToCart` ### Create the custom function Tag We need to create a function tag **AddToCartDynamicVar** * The **Tag Type** set to **Function Call** * The **Class Name** set to **DynamicVarTag** (we'll create this class later) * Add two arguments, `Key: cs_dynamic_var_key, Value: Product`, `Key: cs_dynamic_var_value, Value: {{Product Name}}: {{Product Count}}` * The **Triggering** set to **AddToCartTrigger** It should look like this now:  ### Create the custom function Tag class In your app code, create a class named `DynamicVarTag`, assuming you used the name we suggested when creating the Tag in the GTM interface. If you named it otherwise, make sure to use the same name here, as it is how GTM connects the configuration and the actual class to trigger. We will use this class to call the Contentsquare dynamic variable function as follows. ```swift import GoogleTagManager import ContentsquareModule @objc(DynamicVarTag) final class DynamicVarTag: NSObject, TAGCustomFunction { @objc func execute(withParameters parameters: [AnyHashable : Any]!) -> NSObject! { guard let dynamicVarKey = parameters["cs_dynamic_var_key"] as? String else { return nil } let dynamicVarValue = parameters["cs_dynamic_var_value"] if let dynamicVarStringValue = dynamicVarValue as? String { let dynamicVarString = DynamicVar(key: dynamicVarKey, value: dynamicVarStringValue) Contentsquare.send(dynamicVar: dynamicVarString) } else if let dynamicVarIntValue = dynamicVarValue as? UInt32 { let dynamicVarInt = DynamicVar(key: dynamicVarKey, value: dynamicVarIntValue) Contentsquare.send(dynamicVar: dynamicVarInt) } return nil } } ``` Now, every time Firebase sends an `addToCart` event, Contentsquare will send a dynamic variable `DynamicVar(key: "Product", value: "ProductA: 12")`. Note To create another tag for a dynamic variable, you can use the `DynamicVarTag` class again. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Use Google Tag Manager","description":"Leverage our native integration to send Google Tag Manager events to Contentsquare, with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/ios/use-google-tag-manager/","inLanguage":"en","dateModified":"2026-06-02T10:48:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - React Native (classic) description: The Contentsquare React Native Bridge changelog lastUpdated: 07 August 2026 source_url: html: https://docs.contentsquare.com/en/react-native/changelog/ md: https://docs.contentsquare.com/en/react-native/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). 📬 Stay updated! ## Contentsquare SDK ### 6.4.2 - 2026.07.21 * **Native SDKs:** * iOS: 4.51.0 → 4.51.1 ### 6.4.1 - 2026.07.10 * **Native SDKs:** * Android: 4.51.0 → 4.51.2 ### 6.4.0 - 2026.06.12 * **Native SDKs:** * Android: 4.50.0 → 4.51.0 * iOS: 4.50.0 → 4.51.0 * **WebViews Bug fix** * Android: Fixed an issue when navigating back within WebViews ### 6.3.0 - 2026.05.12 * **Native SDKs:** * Android: 4.44.1 → 4.50.0 * iOS: 4.46.3 → 4.50.0 * **Session Replay** * Support Image/Text remote masking configuration in the CSQ Console ### 6.2.0 - 2026.04.22 @contentsquare/react-native-cli **v1.0.0** is now available. See [the dedicated changelog](#contentsquarereact-native-cli). * **Native SDKs:** * Android: 4.44.0 → 4.44.1 * iOS: 4.46.0 → 4.46.3 * **Bug fix** * Fixed a duplicate `hasListener` symbol conflict with third-party libraries * **WebViews** * Removed unnecessary super calls in bridge handlers * Removed the upper version limit for the React Native peer dependency. The Contentsquare SDK has been validated up to React Native version 0.85. ### 6.1.0 - 2026.02.26 * **Native SDKs:** * Android: 4.43.8 → 4.44.0 * iOS: 4.45.1 → 4.46.0 * **Bug fix** * Fixed iOS module headers to ensure compatibility with CocoaPods projects using `use_frameworks! :linkage => :static`. * Fixed 0.82.x Session Replay compatibility issues * Official support for React Native up to 0.84.x ### 6.0.5 - 2026.02.11 * **Native SDKs:** * Android: 4.43.3 → 4.43.8 * **Bug fix** * Fixed a crash in Android WindowCallbackWrapper ### 6.0.3 - 2026.02.03 * **Bug fix** * WebViews: Fixed an issue with the `userAgent` prop being overwritten ### 6.0.2 - 2025.12.15 Contentsquare CLI * **v0.1.4** is now available. Update to this version if your app uses React Native 0.82 or later. See [CLI configuration](https://docs.contentsquare.com/en/react-native/error-analysis/#cli-configuration) for more information Session Replay * **iOS React Native 0.82.x** is not fully compatible with Session Replay feature. - **Bug fix** * Changed the default value of `disableInteractionAutocapture` to `false` to re-enable interaction capture by default - Fixed an issue with pod installation failing on React Native versions below 0.80 - Official support for React Native up to 0.82.x ### 6.0.1 - 2025.12.05 Breaking changes * `autostart` is removed. From now on to start the SDK, you need to call `Contentsquare.start()`. * `optIn` call is required to start tracking. By default, the SDK will not start tracking until `optIn` is called. * `forgetMe` API has been removed. Use `optOut` instead, see [Privacy section](https://docs.contentsquare.com/en/react-native/privacy/#opt-out). * All screenshots should be re-taken to ensure proper zoning functionality. Contentsquare CLI * **v0.1.3** is now available for version 6.0.1 and later. See [CLI configuration](https://docs.contentsquare.com/en/react-native/error-analysis/#cli-configuration) for more information - **Native SDKs:** * iOS: 4.43.3 → 4.45.1 * Android: 4.43.2 → 4.43.3 ### 5.1.3 - 2025.12.26 * **Native SDK:** * **[Android native SDK 4.43.6](https://docs.contentsquare.com/en/android/changelog/#4436---20251226)** ### 5.1.2 - 2025.12.01 * **Native SDK:** * **[Android native SDK 4.43.2](https://docs.contentsquare.com/en/android/changelog/#4432---20251124)** ### 5.1.1 - 2025.10.23 * Fixed a crash in Android WebViews when loading pages with SSL certificates ### 5.1.0 - 2025.10.01 Warning **ForgetMe:** This API will be deprecated. * **Native SDK:** * **[iOS native SDK 4.43.3](https://docs.contentsquare.com/en/ios/changelog/#4433---20250924)** * Official support for React Native up to 0.81.x * Added support for `react-native-linear-gradient` library on iOS * Fixed iOS new architecture module headers to ensure compatibility with CocoaPods projects using `use_frameworks! :linkage => :static`. ### 5.0.2 - 2025.09.02 * Fixed missing logging methods * Fixed missing declaration files ### 5.0.1 - 2025.08.22 * **Native SDK:** * **[iOS native SDK 4.43.2](https://docs.contentsquare.com/en/ios/changelog/#4432---20250819)** * Fixed event emission timing issue ### 5.0.0 - 2025.07.30 * **Official support** for React Native up to `0.80.x` and the [New Architecture ↗](https://reactnative.dev/architecture/landing-page). * **Native SDKs:** * **[Android SDK 4.39.4](https://docs.contentsquare.com/en/android/changelog/#4394---20250722)** * **[iOS SDK 4.42.4](https://docs.contentsquare.com/en/ios/changelog/#4424---20250722)** * **Breaking Changes:** * **Webviews**: [New WebView injection method](https://docs.contentsquare.com/en/react-native/track-webviews/#cswebview-component). Starting with 5.0.0, wrap your WebView inside the `<CSWebView/>` component. The implementation using the `renderWebView` attribute is no longer available. ```jsx import React from "react"; import { WebView } from "react-native-webview"; import { CSWebView } from "@contentsquare/react-native-bridge"; const WebviewWithTagScreen = () => { return ( // Removed — this implementation is no longer available starting with V5.0.0 <CSWebView url="https://www.mywebpage.com" renderWebView={(onLayout, webViewUrl) => { return ( <WebView onLayout={onLayout} source={{ uri: webViewUrl }} /> ); }} /> <CSWebView> <WebView source={{ uri: "https://www.mywebpage.com" }} /> </CSWebView> ); }; export default WebviewWithTagScreen; ``` * **Transactions**: To send transactions with String type currencies, use `sendTransactionWithStringCurrency` instead of `sendTransaction` which has been removed. ```javascript import Contentsquare, { Currency } from "@contentsquare/react-native-bridge"; Contentsquare.sendTransactionWithStringCurrencysendTransaction(10.99, "USD"); Contentsquare.sendTransactionWithStringCurrencysendTransaction(200.99, "eur", "my_transaction_2"); ``` * **Session Replay**: To subscribe to Session Replay link changes, use `getCurrentSessionReplayLink` instead of `onSessionReplayLinkChange` which has been removed. ```jsx const link = await Contentsquare.getCurrentSessionReplayLink(); useEffect(() => { const subscriber = Contentsquare.onSessionReplayLinkChange((link) => { currentSessionReplaylink = link; }); return () => { if (subscriber) { subscriber.remove(); } }; }, []); ``` * **Dropped support** for React Native versions `< 0.71`. ### 4.16.1 - 2025.07.22 * **Native SDKs:** * **[iOS native SDK 4.42.3](https://docs.contentsquare.com/en/ios/changelog/#4423---20250702)** * **Bug fix:** iOS - Improved state observation for WebView ### 4.16.0 - 2025.05.21 * **Native SDKs:** * **[Android native SDK 4.38.2](https://docs.contentsquare.com/en/android/changelog/#4382---20250516)** * **[iOS native SDK 4.41.3](https://docs.contentsquare.com/en/ios/changelog/#4413---20250516)** * Improves the masking feature for Session Replay on Android * Official support for React Native up to 0.79.x ### 4.15.0 - 2025.04.15 * **Native SDKs:** * **[Android native SDK 4.37.0](https://docs.contentsquare.com/en/android/changelog/#4370---20250402)** ### 4.14.0 - 2025.04.02 * **Bug fix:** Prevented a crash when the new architecture is enabled. Learn more about [compatibility](https://docs.contentsquare.com/en/react-native/compatibility/) with the new architecture in React Native. ### 4.13.1 - 2025.03.24 * **Native SDKs:** * **[Android native SDK 4.36.2](https://docs.contentsquare.com/en/android/changelog/#4362---20250321)** ### 4.13.0 - 2025.02.26 * **Native SDKs:** * **[Android native SDK 4.36.0](https://docs.contentsquare.com/en/android/changelog/#4360---20250210)** * **[iOS native SDK 4.40.2](https://docs.contentsquare.com/en/ios/changelog//#4402---20250220)** * **Bug fix:** Removed conflicted dependencies * Official support for React Native up to 0.78.x **Session Replay** * Full masking configuration by App/SDK version in the CSQ Console ### 4.12.0 - 2025.02.10 * **Native SDKs:** * **[Android native SDK 4.35.0](https://docs.contentsquare.com/en/android/changelog/#4350---20250102)** * **[iOS native SDK 4.39.0](https://docs.contentsquare.com/en/ios/changelog//#4390---20250109)** * **Bug fix:** iOS - Resolve crashes caused by unnecessary React import ### 4.11.2 - 2024.12.10 * **Native SDKs:** * **[iOS native SDK 4.38.3](https://docs.contentsquare.com/en/ios/changelog/#4383---20241210)** * **Bug fix:** iOS - Resolve missing webview screens in Session Replay ### 4.11.1 - 2024.12.04 * **Bug fix:** iOS - Fix a crash in the Error Analysis module occurring on React Native 0.76.x ### 4.11.0 - 2024.11.21 * **Native SDKs:** * **[Android native SDK 4.34.0](https://docs.contentsquare.com/en/android/changelog/#4340---20241025)** * **[iOS native SDK 4.38.1](https://docs.contentsquare.com/en/ios/changelog/#4380---20241025)** * Official support for React Native up to 0.76.x * Simpler implementation method for CSWebView * **Bug fix:** iOS - Prevents text duplication in Session Replay when using `react-native-linear-gradient` and `@react-native-masked-view/masked-view` packages. ### 4.10.1 - 2024.10.14 * **Native SDKs:** * **[Android native SDK 4.33.1](https://docs.contentsquare.com/en/android/changelog/#4331---20241007)** * **Android** * Improved `CSMask` component ### 4.10.0 - 2024.10.08 * **Native SDKs:** * **[Android native SDK 4.33.0](https://docs.contentsquare.com/en/android/changelog/#4330---20241002)** * **[iOS native SDK 4.37.1](https://docs.contentsquare.com/en/ios/changelog/#4371---20241001)** * **iOS** * Added support for the `react-native-linear-gradient` library * **Track transactions** * Enhancements to the `sendTransaction` method * ⛔️ DEPRECATED `sendTransactionWithStringCurrency`: use `sendTransaction` instead * **Error Analysis** * Collect information for crashes in React Native ### 4.9.0 - 2024.09.13 * **Native SDKs:** * **[Android native SDK 4.32.1](https://docs.contentsquare.com/en/android/changelog/#4321---20240910)** * **[iOS native SDK 4.36.0](https://docs.contentsquare.com/en/ios/changelog/#4360---20240906)** * **iOS** * Added support for the `@react-native-masked-view` library * **Bug fix:** CSWebView injection ### 4.8.0 - 2024.08.21 * **Native SDKs:** * **[Android native SDK 4.31.0](https://docs.contentsquare.com/en/android/changelog/#4310---20240802)** * **[iOS native SDK 4.35.1](https://docs.contentsquare.com/en/ios/changelog/#4351---20240814)** * Official support for React Native up to 0.75.x * **Bug fix:** Android - Resolved an issue where navigating back in the webview history would result in a white screen * **Bug fix:** Android - Fixed a crash issue when manually initializing the SDK ### 4.7.0 - 2024.07.15 * **Native SDKs:** * **[Android native SDK 4.30.0](https://docs.contentsquare.com/en/android/changelog/#4300---20240701)** * **[iOS native SDK 4.34.0](https://docs.contentsquare.com/en/ios/changelog/#4340---20240702)** * Improved SDK thread safety * Improved SDK ProGuard rules ### 4.6.1 - 2024.07.02 * **Bug fix:** Fixing an issue with source and URL prop changes in CSWebView ### 4.6.0 - 2024.06.19 * **Native SDKs:** * **[Android native SDK 4.29.1](https://docs.contentsquare.com/en/android/changelog/#4291---20240611)** * **[iOS native SDK 4.33.1](https://docs.contentsquare.com/en/ios/changelog/#4331---20240613)** * Improved `CSMask` component. ### 4.5.1 - 2024.06.17 * **Native SDK:** * **[Android native SDK 4.27.1](https://docs.contentsquare.com/en/android/changelog/#4271---20240329)** ### 4.5.0 - 2024.05.17 * **Native SDK:** * **[iOS native SDK 4.32.0](https://docs.contentsquare.com/en/ios/changelog/#4320---20240423)** * Official support for React Native up to 0.74.x ### 4.4.0 - 2024.04.08 **🚨 Minimum React Native version announcement** Starting with this release, Contentsquare Bridge for React Native will require React Native version to be 0.70 or later * **Native SDKs:** * **[Android native SDK 4.27.0](https://docs.contentsquare.com/en/android/changelog/#4270---20240327)** * **[iOS native SDK 4.31.2](https://docs.contentsquare.com/en/ios/changelog/#4312---20240325)** * **Bug fix:** Fixing an issue in Expo involving a missing library import. * **Bug fix:** Fixing an issue on Android related to the use of nested `CSMask` components. ### 4.3.1 - 2024.02.29 * **Native SDKs:** * **[iOS native SDK 4.30.2](https://docs.contentsquare.com/en/ios/changelog/#4302---20240229)** * **Bug fix:** Fixing an issue where occasionally closing a WebView freezes the view. ### 4.3.0 - 2024.02.28 * **Native SDKs:** * **[Android native SDK 4.26.0](https://docs.contentsquare.com/en/android/changelog/#4260---20240220)** * **[iOS native SDK 4.30.1](https://docs.contentsquare.com/en/ios/changelog/#4301---20240227)** * **Session Replay** * New method to subscribe to Session Replay Link changes * ⛔️ DEPRECATED `getCurrentSessionReplayLink`: use `onSessionReplayLinkChange` instead ### 4.2.0 - 2024.01.30 * **Native SDKs:** * **[iOS native SDK 4.29.1](https://docs.contentsquare.com/en/ios/changelog/#4291---20240126)** * CSWebView support for webview source object ### 4.1.0 - 2024.01.17 \[⛔️ DEPRECATED] * **Native SDKs:** * **[Android native SDK 4.24.0](https://docs.contentsquare.com/en/android/changelog/#4240---20231215)** * **[iOS native SDK 4.28.0](https://docs.contentsquare.com/en/ios/changelog/#4280---20231219)** * **Bug fix:** Remove style on `CSMask` ### 4.0.1 - 2024.01.05 * **Bug fix:** URL injection method in WebView ### 4.0.0 - 2024.01.03 * Official support for React Native up to 0.73.x * **BREAKING CHANGE:** New WebView injection method. Refer to new documentation to check implementation [Track WebViews](https://docs.contentsquare.com/en/react-native/track-webviews/) ### 3.10.0 - 2023.12.21 \[⛔️ DEPRECATED] ### 3.9.0 - 2023.11.28 * **Native SDKs:** * **[Android native SDK 4.23.1](https://docs.contentsquare.com/en/android/changelog/#4231---20231124)** * **[iOS native SDK 4.27.0](https://docs.contentsquare.com/en/ios/changelog/#4270---20231116)** * **Custom variables** feature is now available on Android * Improved **WebView injection** for Android * **Bug fix:** Prevent a potential error on Android `CSMask` ### 3.8.0 - 2023.11.06 * **Native SDKs:** * **[Reverted to Android native SDK 4.20.0](https://docs.contentsquare.com/en/android/changelog/#4200---20230713)** * **The Custom variables** feature is NOT available on Android * **[iOS native SDK 4.25.2](https://docs.contentsquare.com/en/ios/changelog/#4252---20230922)** * **Session Replay** * Added a new method `setUserIdentifier` * **Bug fix:** Fixed a bug on Android when using the `start` method * **Bug fix:** Fixed a bug on Android when using the `CSMask` ### 3.7.1 - 2023.10.04 \[⛔️ DEPRECATED] * **Bug fix:** Fixed a crash that occurred when manually starting the application while InApp features were active ### 3.7.0 - 2023.09.19 \[⛔️ DEPRECATED] * **Native SDKs:** * **[Android native SDK 4.21.0](https://docs.contentsquare.com/en/android/changelog/#4210---20230829)** * **[iOS native SDK 4.25.1](https://docs.contentsquare.com/en/ios/changelog/#4251---20230913)** * **Session Replay** * Added a new method `setDefaultMasking` * **Custom variables** feature is now available on Android * **Bug fix:** Fix a crash caused by `CSMask` ### 3.6.1 - 2023.08.25 * Support `use_frameworks!` in Podfile ### 3.6.0 - 2023.08.02 * **Native SDKs:** * **[Android native SDK 4.20.0](https://docs.contentsquare.com/en/android/changelog/#4200---20230713)** * **[iOS native SDK 4.24.0](https://docs.contentsquare.com/en/ios/changelog/#4240---20230714)** * Official support for React Native up to 0.72.x * **Bug fix:** Fixed WebView Injection on Android - there was an issue with WebView injection failing during the initial visit of a WebView * **Bug fix:** Fixed `CSMask` - there was an issue with `CSMask` impacting the screen layout * Zoning analysis: Reliable targets feature is now available on iOS * Session Replay: Collecting gesture events is now available on iOS * **Error Analysis**: * Enabled collection of failed network requests (API Errors) * Enabled collection of API Error troubleshooting details (Available in the Session Replay) * Added a method to mask API errors using template URL `ErrorAnalysis.setUrlMaskingPatterns` ### 3.5.0 - 2023.06.22 * **Native SDKs:** * **[Android native SDK 4.19.0](https://docs.contentsquare.com/en/android/changelog/#4190---20230614)** * **[iOS native SDK 4.23.0](https://docs.contentsquare.com/en/ios/changelog/#4230---20230609)** * **Session Replay:** * Fixed an animation glitch. * Added a method to programmatically retrieve the Session Replay link. * Different quality settings are available. ### 3.4.1 - 2023.06.07 * Fix a bug where React Native project with version below 0.70 couldn't find `CSMask` import. ### 3.4.0 - 2023.05.19 Warning If your **RN version is below 0.70.0**, Make sure to follow **[this configuration](https://docs.contentsquare.com/en/react-native/compatibility/#for-react-native-project-below-0700)** when implementing this Bridge version. * The Bridge uses **[Android native SDK 4.18.1](https://docs.contentsquare.com/en/android/changelog/#4181---20230516)** and **[iOS native SDK 4.22.1](https://docs.contentsquare.com/en/ios/changelog/#4221---20230505)** * [Session Replay](https://docs.contentsquare.com/en/react-native/session-replay/) feature is available for iOS and Android. For more information, reach out to your Contentsquare contact. ### 3.3.1 - 2023.05.02 Warning If your **RN version is below 0.70.0**, Make sure to follow **[this configuration](https://docs.contentsquare.com/en/react-native/compatibility/#for-react-native-project-below-0700)** when implementing this Bridge version. * Fix of an Xcode 14 issue ### 3.3.0 - 2023.04.03 Warning If your **RN version is below 0.70.0**, Make sure to follow **[this configuration](https://docs.contentsquare.com/en/react-native/compatibility/#for-react-native-project-below-0700)** when implementing this Bridge version. * **Custom Variables:** The [Custom Variables feature](https://docs.contentsquare.com/en/react-native/track-custom-variables/) is now supported by the bridge (for iOS only, beta version). * Adding masking component for future Session Replay feature (WIP) ### 3.2.0 - 2023.03.08 * The Bridge uses **[iOS native SDK 4.20.0](https://docs.contentsquare.com/en/ios/changelog/#4200---20230224)** * Official support for React Native up to 0.71.x * Add error callback to dynamic variables method ### 3.1.0 - 2023.01.12 * The Bridge uses **[Android native SDK 4.15.0](https://docs.contentsquare.com/en/android/changelog/#4150---20221220)** and **[iOS native SDK 4.18.0](https://docs.contentsquare.com/en/ios/changelog/#4180---20221216)** ### 3.0.0 - 2022.12.12 * Upgrade maximum React Native version compatibility to 0.70.x * **BREAKING CHANGE:** New WebView injection method ### 2.8.0 - 2022.12.01 * The Bridge uses **[Android native SDK 4.14.0](https://docs.contentsquare.com/en/android/changelog/#4140---20221103)** and **[iOS native SDK 4.16.0](https://docs.contentsquare.com/en/ios/changelog/#4160---20220912)** * Add Expo compatibility ### 2.7.0 - 2022.08.03 * The Bridge uses **[Android native SDK 4.11.0](https://docs.contentsquare.com/en/android/changelog/#4110---20220707)** and **[iOS native SDK 4.15.1](https://docs.contentsquare.com/en/ios/changelog/#4151---20220726)** ### 2.6.0 - 2022.05.10 * The Bridge uses **[Android native SDK 4.9.0](https://docs.contentsquare.com/en/android/changelog/#490---20220415)** and **[iOS native SDK 4.13.0](https://docs.contentsquare.com/en/ios/changelog/#4130---20220505)** * Official support for React Native up to 0.68.x * Fix a screenshot issue with some ReactNative UI components (RNSVGSvgView) ### 2.5.3 - 2022.04.19 * Fix unreliable WebView injection. * Official support for React Native up to 0.67.x ### 2.5.2 - 2022.2.16 * Fixing a crash caused by WebViews in some specific cases. ### 2.5.1 - 2022.1.21 * The Bridge uses **[Android native SDK 4.7.0](https://docs.contentsquare.com/en/android/changelog/#470---20220114)** and **[iOS native SDK 4.10.1](https://docs.contentsquare.com/en/ios/changelog/#4101---20220114)** ### 2.5.0 - 2022.1.18 * Official support for React Native up to 0.66.x * The Bridge uses **[Android native SDK 4.6.0](https://docs.contentsquare.com/en/android/changelog/#460---20211215)** and **[iOS native SDK 4.10.0](https://docs.contentsquare.com/en/ios/changelog/#4100---20211213)** ### 2.4.0 - 2021.11.18 * **WebView tracking:** WebView tracking is now available. See [Track WebViews section](https://docs.contentsquare.com/en/react-native/track-custom-variables/) * **Implementing deeplink support for in-app features (iOS):** You can now handle the deeplink URL directly from your JavaScript code, in addition to being able to handle it the native way * The Bridge uses **[Android native SDK 4.4.0](https://docs.contentsquare.com/en/android/changelog/#440---20211018)** and **[iOS native SDK 4.9.0](https://docs.contentsquare.com/en/ios/changelog/#490---20211104)** * **Drop support for iOS 10.** Minimum supported version is now iOS 11. [See Compatibility section](https://docs.contentsquare.com/en/ios/compatibility/) ### 2.3.0 - 2021.09.02 * **Disable auto-start:** Option to start the SDK in a manual method instead of starting automatically. * The Bridge uses **[Android native SDK 4.3.0](https://docs.contentsquare.com/en/android/changelog/#430---20210810)** and **[iOS native SDK 4.6.0](https://docs.contentsquare.com/en/ios/changelog/#460---20210810)** ### 2.2.1 - 2021.07.08 * The Bridge uses **[Android native SDK 4.2.1](https://docs.contentsquare.com/en/android/changelog/#421---20210707)** and **[iOS native SDK 4.4.0](https://docs.contentsquare.com/en/ios/changelog/#440---20210623)** ### 2.2.0 - 2021.06.28 * The Bridge uses **[Android native SDK 4.2.0](https://docs.contentsquare.com/en/android/changelog/#420---20210614)** and **[iOS native SDK 4.4.0](https://docs.contentsquare.com/en/ios/changelog/#440---20210623)** * Official support for React Native 0.64.x * Fixed issue that caused some apps to freeze ### 2.1.0 - 2021.03.11 * The Bridge uses **[Android native SDK 4.1.0](https://docs.contentsquare.com/en/android/changelog/#410---20210216)** and **[iOS native SDK 4.1.0](https://docs.contentsquare.com/en/ios/changelog/#410---20210121)** ### 2.0.0 - 2020.11.03 * The Bridge uses **[Android native SDK 4.0.0](https://docs.contentsquare.com/en/android/changelog/#400---20201029)** and **[iOS native SDK 4.0.0](https://docs.contentsquare.com/en/ios/changelog/#400---20201028)** ### 1.1.1 - 2020.08.26 * The Bridge uses **[iOS native SDK 3.2.1](https://docs.contentsquare.com/en/ios/changelog/#321---20200826)** ### 1.1.0 - 2020.08.21 * The Bridge uses **[Android native SDK 3.2](https://docs.contentsquare.com/en/android/changelog/#320---20200730)** and **[iOS native SDK 3.2](https://docs.contentsquare.com/en/ios/changelog/#320---20200727)** * Official support for React Native 0.63.x ### 1.0.0 - 2020.04.23 * The bridge is now available at `@contentsquare/react-native-bridge`. * The Bridge uses **Android native SDK 3.1.0** and **iOS native SDK 3.1.1** * Bridge only supports React Native >=0.60 * Dynamic Variables are supported *** ## `@contentsquare/react-native-cli` See [CLI configuration](https://docs.contentsquare.com/en/react-native/error-analysis/#cli-configuration) for configuration details. ### 1.0.0 - 2026.04.21 **Breaking Change:** The CLI package name has changed from `@contentsquare/cli` to [`@contentsquare/react-native-cli` ↗](https://www.npmjs.com/package/@contentsquare/react-native-cli). If you already have the CLI installed: 1. Update the package name in your `package.json`: ```jsx "devDependencies": { "@contentsquare/cli": "<file_path_to_the_downloaded_.tgz_package>", "@contentsquare/react-native-cli": "1.0.0", } ``` 2. Update the paths in your [source maps](https://docs.contentsquare.com/en/react-native/error-analysis/#cli-configuration) upload configuration: * Android **android/app/build.gradle** ```groovy apply from: "../../node_modules/@contentsquare/cli/scripts/contentsquare.gradle" apply from: "../../node_modules/@contentsquare/react-native-cli/scripts/contentsquare.gradle" ``` * iOS **Bundle React Native code and images** ```shell CONTENTSQUARE_XCODE="$SRCROOT/../node_modules/@contentsquare/cli/scripts/contentsquare-xcode.sh" CONTENTSQUARE_XCODE="$SRCROOT/../node_modules/@contentsquare/react-native-cli/scripts/contentsquare-xcode.sh" ``` * Fix support for Gradle 9+ ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare React Native Bridge changelog","url":"https://docs.contentsquare.com/en/react-native/changelog/","inLanguage":"en","dateModified":"2026-08-07T10:11:06+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Collected data points - React Native (classic) description: Events and metadata collected by the Contentsquare SDKs lastUpdated: 05 June 2026 source_url: html: https://docs.contentsquare.com/en/react-native/collected-data-points/ md: https://docs.contentsquare.com/en/react-native/collected-data-points/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). The React Native SDK collects request metadata, gesture events, lifecycle events,, transactions, and dynamic variables, all serialized as JSON and sent to the server in batches. * The events are in JSON format, which lists the properties and their description in comment. * Events are sent to the server in batches. * A batch is a subset of events originating from one session. A session can send events in more than one batch. * The batch size is defined in a run configuration file specific to each app (50 events by default). ## Requests meta data Each batch has a common header, a set of device specific, and repeatable information and an array of events, which is immutable. The header is composed at the moment of sending, so it has to be constant info ONLY. The array in the payload is data stored at the moment of collection. The structure of the batches of events will have the following format: ```javascript { pid:8, // int - ProjectId - represented in the mobile config format uid:"ac1529a7-59f6-49d9-b254-6f0a22f57284", // String - uuid Unique user ID dt:4, // int - device type (loosely enforced enum - [SDK-phone : 4, SDK-tablet :5]) dma:"Samsung", // String - device manufacturer. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. dmo:"SG", // String - device model. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. os:"7.0", // String - os version (Android version name 6.0, 7.0, 8.0) l:"en_US", // String - Language in iso-639 format https://www.ibabbleon.com/iOS-Language-Codes-ISO-639.html tz:"Europe/Paris", // String - timezone https://en.wikipedia.org/wiki/List_of_tz_database_time_zones now:1522159618000, // long - timestamp when the batch was sent to:{ // object - type origin of the event an:"appname" // String - application name st:"SDK-android", // String - type of SDK sf:"release", // string - SDK flavor/variant [release/debug/god] }, r:{ // Device - resolution. w:1080, // int - width h:1920 // int - height d: 1.5 // The device density as float. Its values can vary between (0.75 and 10) }, pl:[] // JSON array payload - list of event objects, see below } ``` ## Events ### Events meta data All events have a common first part (don't confuse it with the header explained above). This common section is data which is common for all events by type but is gathered at the moment the event occurred. This common section is a part of the actual event payload. ```javascript { upt:1522, // long - system update in milliseconds euid:"euid", // String - event UUID url:"app-and://identifier/mainPath/secondaryPath?title=screeName", // String - screenName is passed in the title query Parameter scn:4, // int - the number of screens already shown in the session c:3, // int - connectivity type [-1 - offline, 0 - error, 1 - wifi, 2 - 2g, 3 - 3g, 4 - 4g] ci:"verizon", // String - carrier_id when user is on mobile network o:1, // int - orientation [0 = portrait, 1 = landscape] vo:{ // object - version origin of the event sv:"2.1", // string version of the SDK sb:4, // int - SDK build number av:"appVersion", // String - application version af:"appFlavor" // String - application string - [release/debug/god] ab:1 // int - application build number }, sn:1, // int - session id (positive int) t:12894726459435 // long - timestamp of the event (in milliseconds) } ``` All event specific properties are appended to this JSON object. ### App Start This event describes the absolute start of the app. The trigger for this event is the absolute start of the app. This is the first event sent when the SDK is invoked. ```javascript ea: 0; // int - event action - defined above ``` ### App Show This event is sent when the user brings the app in the foreground (switching from another app, exiting lock screen, etc.). This event means the app is focused. ```javascript ea: 1; // int - event action - defined above ``` ### App Hide This event is sent when the user exits (minimizes) the app, or switches to something else. This event means the app is not focused and the session might end, but we have not completely ended the session yet, as the user might return. ```javascript ea: 2; // int - event action - defined above ``` ### Screenview Everything starts with a View event. This is an event which describes the equivalent of a "page view" on the web. This event is sent when the Track Screen API is called. ```javascript ea:4 // int - event action - defined above st:"title", // String - screen title sl:34543 // int - (load time) screen load time (diff between last action and this event) ``` ### Tap Single Finger gesture event, when the user is interacting with a loaded screen. This is an event which describes the equivalent of a "click" in the web. This event is defined by the following sequence of touch events: * Touch Down -> N x Touch Move -> Touch Up ```javascript ea:6 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ur: true, // boolean - was this a "responsive" touch event (the target view had a handler) ``` ### Long press Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Duration: > 500ms * Distance: < 24 dp ```javascript ea:8 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ``` ### Drag (Slow Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity < 100 dp/s ```javascript ea:9 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance dragged tvv:100 // int - target view velocity while dragging dp/s ``` ### Flick (Fast Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity > 100 dp/s ```javascript ea:10 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view graph path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance scrolled tvv:100 // int - target view velocity while scrolling dp/s ``` ### Transaction To track transactions, we provide a public API which can send a transaction object (see section [Track Transactions](https://docs.contentsquare.com/en/react-native/track-transactions/)). This object must contain the following parameters: ```javascript ea:16, // int - event action - defined above tr:{ // a json object with different properties defining the transaction made vl: 20.0, // mandatory - float - the value of the transaction cu: 978, // mandatory - int - the ISO 4217 code of the currency of the transaction id: "32akjkljklJ575775" // optional - string - an id for the transaction } ``` ## Dynamic variables To track dynamic variables we provide a public API which can send a custom event object (see section [Dynamic variables](https://docs.contentsquare.com/en/react-native/track-dynamic-variables/)). ```javascript // Dynamic variable event with a string value ea:18, // int - event action - defined above k:"key", // String - Custom key assigned by client. v:"value" // String - Custom value assigned by client. ``` ```javascript // Dynamic variable event with a number value ea:19, // int - event action - defined above k:"key", // String - Custom key assigned by client. v: 2344 // Integer - Custom value assigned by client. ``` ## Reliable targets (iOS only) Beta Version The purpose of this beta is to test the feature with a selected group of users to gather feedback and identify any areas for improvement before its official release. Contentsquare is committed to using this feedback to enhance the feature and make it as user-friendly as possible. If you encounter any issues or have any questions during the implementation of the Reliable targets, do not hesitate to reach out to your Implementation Manager for support. The identifier associated with each view in your app is the concatenation of the list of its ancestors in the React Native tree view. This means that if you have the following component: **basicComponent.js** ```javascript const basicComponent = () => { return ( <View> <Text>Hello world!</Text> <TextInput placeholder="Enter your name" /> </View> ); }; ``` You may always want to use the same id for this component, even if you publish a new version of the app in which it has been moved in the tree view. Having a reliable target for a view or a container of views enables the analysis of data across various Screenshots from different dates and versions, including layouts or A/B testing variations. Here are examples of how the reliable targets feature can be used: * Tracking elements that can dynamically move on a page (example: Customizable profile page). * Tracking elements that you want to monitor from one version to another, even if their position changes (example: Moving carousel position from top to bottom). * Tracking elements during A/B testing (example: Testing new and old Product page on the same version). * Tracking elements that can be used on multiple pages (example: Search bar). * Ensuring that a call to action has a unique identifier wherever it appears on a screen (example: AddtoCart button). The Contentsquare React Native SDK provides a `CSReliableTarget` component that can be used to wrap the component you want to track reliably. `CSReliableTarget` accepts a mandatory `name` prop that allows the identification of the component to track. **componentWithReliableTarget.js** ```javascript const componentWithReliableTarget = () => { return ( <CSReliableTarget name="MyComponentTracked"> <View> <Text>Hello world!</Text> <TextInput placeholder="Enter your name" /> </View> </CSReliableTarget> ); }; ``` Note Each target name must be unique to effectively use the feature. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Collected data points","description":"Events and metadata collected by the Contentsquare SDKs","url":"https://docs.contentsquare.com/en/react-native/collected-data-points/","inLanguage":"en","dateModified":"2026-06-05T17:39:25+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - React Native (classic) description: Requirements and limitations to develop with the Contentsquare React Native Bridge lastUpdated: 28 July 2026 source_url: html: https://docs.contentsquare.com/en/react-native/compatibility/ md: https://docs.contentsquare.com/en/react-native/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). Before implementing the SDK, make sure your app meets the following technical prerequisites to avoid integration issues and ensure optimal performance. Compatibility Notice - React Native New Architecture As of **version 5.0.0**, the Contentsquare React Native SDK officially supports **React Native's New Architecture**. You can now enable the New Architecture in your app without encountering compatibility issues from the SDK itself. **Important Notes** * Zoning Analysis * When transitioning from the legacy architecture, make sure to **retake Screenshots** to ensure accurate **Zoning**. Data collected under the legacy architecture is not transferable. * While the SDK supports the New Architecture, some third-party libraries may still present issues when used in this setup. * If you encounter rendering or integration problems refer to the respective library's issue tracker or upgrade to the latest compatible version. ## Supported platforms Only React Native application on the following platforms are supported by the `Contentsquare React Native Bridge`: * Android * iOS If you need to use the SDK on another platform, contact our support team. Hybrid applications are not supported. By hybrid application, we mean [integrating React Native component ↗](https://reactnative.dev/docs/integration-with-existing-apps) to existing native applications. ## Compatibility matrix Each version of the Contentsquare bridge will be linked to specific, fixed versions of each native SDK. to make that clear, here is a compatibility table to consider when choosing your version of the bridge. Refer to the [React Native Bridge Changelog](https://docs.contentsquare.com/en/react-native/changelog/) to know what the changes are for each version. The Contentsquare bridge is validated against the latest React Native version. We support all React Native versions that are maintained and listed on the official [React Native documentation ↗](https://reactnative.dev/versions). | Bridge Version | iOS SDK Version | Android SDK Version | Min React Native Version | Max React Native Version | | - | - | - | - | - | | 6.4.2 | 4.51.1 | 4.51.2 | 0.71.0 | latest | | 6.4.1 | 4.51.0 | 4.51.2 | 0.71.0 | latest | | 6.4.0 | 4.51.0 | 4.51.0 | 0.71.0 | latest | | 6.3.0 | 4.50.0 | 4.50.0 | 0.71.0 | latest | | 6.2.0 | 4.46.3 | 4.44.1 | 0.71.0 | 0.85.x | | 6.1.0 | 4.46.0 | 4.44.0 | 0.71.0 | 0.84.x | | 6.0.5 | 4.45.1 | 4.43.8 | 0.71.0 | 0.82.x | | 6.0.3 | 4.45.1 | 4.43.3 | 0.71.0 | 0.82.x | | 6.0.2 | 4.45.1 | 4.43.3 | 0.71.0 | 0.82.x | | 6.0.1 | 4.45.1 | 4.43.3 | 0.71.0 | 0.81.x | | 5.1.3 | 4.43.3 | 4.43.6 | 0.71.0 | 0.81.x | | 5.1.2 | 4.43.3 | 4.43.2 | 0.71.0 | 0.81.x | | 5.1.1 | 4.43.3 | 4.39.4 | 0.71.0 | 0.81.x | | 5.1.0 | 4.43.3 | 4.39.4 | 0.71.0 | 0.81.x | | 5.0.2 | 4.43.2 | 4.39.4 | 0.71.0 | 0.80.x | | 5.0.1 | 4.43.2 | 4.39.4 | 0.71.0 | 0.80.x | | 5.0.0 | 4.42.4 | 4.39.4 | 0.71.0 | 0.80.x | | 4.16.1 | 4.42.3 | 4.38.2 | 0.70.0 | 0.79.x | | 4.16.0 | 4.41.3 | 4.38.2 | 0.70.0 | 0.79.x | | 4.15.0 | 4.40.2 | 4.37.0 | 0.70.0 | 0.78.x | | 4.14.0 | 4.40.2 | 4.36.2 | 0.70.0 | 0.78.x | | 4.13.1 | 4.40.2 | 4.36.2 | 0.70.0 | 0.78.x | | 4.13.0 | 4.40.2 | 4.36.0 | 0.70.0 | 0.78.x | | 4.12.0 | 4.39.0 | 4.35.0 | 0.70.0 | 0.76.x | | 4.11.2 | 4.38.3 | 4.34.0 | 0.70.0 | 0.76.x | | 4.11.1 | 4.38.1 | 4.34.0 | 0.70.0 | 0.76.x | | 4.11.0 | 4.38.1 | 4.34.0 | 0.70.0 | 0.76.x | | 4.10.1 | 4.37.1 | 4.33.1 | 0.70.0 | 0.75.x | | 4.10.0 | 4.37.1 | 4.33.0 | 0.70.0 | 0.75.x | | 4.9.0 | 4.36.0 | 4.32.1 | 0.70.0 | 0.75.x | | 4.8.0 | 4.35.1 | 4.31.0 | 0.70.0 | 0.75.x | | 4.7.0 | 4.34.0 | 4.30.0 | 0.70.0 | 0.74.x | | 4.6.1 | 4.33.1 | 4.29.1 | 0.70.0 | 0.74.x | | 4.6.0 | 4.33.1 | 4.29.1 | 0.70.0 | 0.74.x | | 4.5.1 | 4.32.0 | 4.27.1 | 0.70.0 | 0.74.x | | 4.5.0 | 4.32.0 | 4.27.0 | 0.70.0 | 0.74.x | | 4.4.0 | 4.31.2 | 4.27.0 | 0.70.0 | 0.73.x | | 4.3.1 | 4.30.2 | 4.26.0 | 0.65.0[1](#user-content-fn-1) | 0.73.x | | 4.2.0 | 4.29.1 | 4.24.0 | 0.65.0[1](#user-content-fn-1) | 0.73.x | ## Important note about React Native apps with native code Depending on if you created your app as a React Native first app, or if you gradually added some React Native code to your Native first app, you might be using some non JavaScript elements in your app, and a mix of native screens and JavaScript screens. If that is the case, it is your responsibility to track all of the screens, either by calling our native SDKs directly in the first case, or the bridge in the second. The same remark applies for other functionalities of the SDK - for example, you might need to send a Transaction Event via the native SDK or via the bridge, depending on the technology used to create your buying page. Have a look at the [Android](https://docs.contentsquare.com/en/android/) and [iOS](https://docs.contentsquare.com/en/ios/) SDKs to find out how to call them in native parts of your app. Also, we specifically cover the use of the JavaScript bridge in this documentation. You should never call the Bridge's NativeModule directly yourself. If for any reason you do so, know that we cannot certify that your implementation will work as expected. Only call our SDKs through the JavaScript Contentsquare module we provide in you JavaScript code (as explained in this document), or directly in your native code. ## Note about using Contentsquare along with Expo To use the SDK on an Expo app, you need to have an Expo project with EAS (Expo Application Services). The SDK compatibility with Expo projects requires the extra steps described below. ### Configuration Add the plugin and your Contentsquare bundle identifier to your app configuration file: **app.json** ```jsx { "expo": { ..., "ios": { "bundleIdentifier": "com.cs.expo.app", // replace with your bundle id ... }, "android": { "package": "com.cs.expo.app", // replace with your bundle id ... }, "plugins": [ "@contentsquare/react-native-bridge", ], } ``` ### Run To run your Expo app with the Contentsquare SDK, you can't use Expo Go since it needs native files and features. To run your app, use `expo run:ios` or `expo run:android`. Or, you can replace the scripts to your app in your project's `package.json`: **package.json** ```javascript "scripts": { ... "android": "expo run:android", "ios": "expo run:ios", }, ``` ## React Native version specific configurations ### For React Native project below 0.70.0 Warning If you have a **React Native version below 0.70.0**, you must add this specific configuration inside your `metro.config.js` file **metro.config.js** ```javascript module.exports = { // ...your current configuration // add the code below resolver: { sourceExts: ["js", "jsx", "json", "ts", "tsx"], }, }; ``` ### For React Native project between 0.69 - 0.70 Warning If you have a **React Native version between 0.69 - 0.70**, make these changes inside your Android app * Update compileSdkVersion to 33 ### For React Native project between 0.65 - 0.68 Warning If you have a **React Native version between 0.65 - 0.68**, make these changes inside your Android app * Update compileSdkVersion to 33 * Update Gradle Plugin Version to a minimum of v7.1.1 * Update Gradle Wrapper to a minimum of v7.3.3 ## Footnotes 1. Make sure to add [this configuration](#for-react-native-project-below-0700) if your RN version is below 0.70.0, and [this configuration](#for-react-native-project-between-069---070) to the Android app if your RN version is between 0.69.0 and 0.70.0, or [this configuration](#for-react-native-project-between-065---068) to the Android app if your RN version is between 0.65.0 and 0.68.0. [↩](#user-content-fnref-1) [↩2](#user-content-fnref-1-2) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Contentsquare React Native Bridge","url":"https://docs.contentsquare.com/en/react-native/compatibility/","inLanguage":"en","dateModified":"2026-07-28T18:22:24+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Error Analysis - React Native (classic) description: How to use Contentsquare Error Analysis in your React Native apps lastUpdated: 06 August 2026 source_url: html: https://docs.contentsquare.com/en/react-native/error-analysis/ md: https://docs.contentsquare.com/en/react-native/error-analysis/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. Error Analysis automatically captures API errors and network failures in your React Native app and surfaces them in the Contentsquare platform. ## Prerequisites ### Screen tracking implemented Tracking will start at the 1st screenview event, it is required to have screen tracking implemented. Make sure to follow the [React Native Track screens](https://docs.contentsquare.com/en/react-native/track-screens/) sections. ### Reminder about User consent If you are in the process of implementing the SDK for the 1st time (or choose to take this update as an opportunity to review your Privacy related implementation), make sure to follow the [React Native Privacy](https://docs.contentsquare.com/en/react-native/privacy/) section and use the [Opt-in API](https://docs.contentsquare.com/en/react-native/privacy/#opt-in) to get the user consent, otherwise no data will be collected. ## Get Started ### Add Contentsquare Error Analysis to your app If you have already integrated the Contentsquare Bridge and enabled Error Analysis on Experience Analytics Mobile, the Error Analysis SDK should seamlessly function. However, additional configuration is required specifically for Android apps. #### Add Gradle plugin on Android With the use of a Gradle plugin, an instrumentation of your code will be performed to collect the data about network errors. Add the Contentsquare Network Gradle plugin to the plugins block in both your root-level and app-level Gradle files: * Groovy **build.gradle** ```groovy buildscript { repositories { maven { url "https://plugins.gradle.org/m2" } } dependencies { classpath("com.contentsquare.gradle:error-analysis-network:1.8.0") } } ``` * Kotlin **build.gradle.kts** ```kotlin buildscript { repositories { maven { url = uri("https://plugins.gradle.org/m2") } } dependencies { classpath("com.contentsquare.gradle:error-analysis-network:1.8.0") } } ``` - Groovy **app/build.gradle** ```groovy apply plugin: "com.contentsquare.error.analysis.network" ``` - Kotlin **aapp/build.gradle.kts** ```groovy apply(plugin = "com.contentsquare.error.analysis.network") ``` ### Start the SDK You do not need to do anything to start the Error Analysis SDK, it will start itself with Contentsquare SDK. ## API Errors ### Automatic network inspection API Errors automatically collects failed network requests. ### Removing Personal Data in request URL path By default, the API Errors feature collects the URL path of the failed API requests. To prevent the collection of Personal Data in the URL path, you can rewrite the request URL path with the `ErrorAnalysis.setURLMaskingPatterns` SDK API. Replace a step of the path - meaning between two slashes (/) - containing Personal Data with a variable: * becomes CS\_ANONYMIZED\_USER\_ID * becomes CS\_ANONYMIZED\_ADDRESS #### Example ```javascript import { ErrorAnalysis } from "@contentsquare/react-native-bridge"; ErrorAnalysis.setURLMaskingPatterns([ "https://www.contentsquare.com/users/:user_id/address/:address", ]); ``` ##### Result | URL before masking | URL after masking | | - | - | | `https://www.contentsquare.com/users/123/address/castle+black` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS` | | `https://www.contentsquare.com/users/123/address/castle+black/reset-token/abcdef123456` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS/reset-token/abcdef123456` | ### Debugging and Logging If in-app features are enabled, a info log should appear with the details of the event (see [React Native Debugging and Logging](https://docs.contentsquare.com/en/react-native/in-app-features/#debugging-and-logging) section): * Android ```text I/CSLIB: API Error - GET 401 https://api.client.com ``` * iOS ```text CSLIB ℹ️ Info: API Error - GET 401 https://api.client.com ``` ### How API Errors works #### Initialization The way our SDK works is by auto-starting with the application launch and automatically collects failed network requests. #### Configuration Once started, our SDK fetches its config from our servers. It will start collecting data from network events if the API Errors setting is enabled in the config (this is handled by the Contentsquare team). #### Tracking The SDK monitors only the API Errors with response code above 400, and generates analytics data. These events are then locally stored, and eventually sent to our servers in batches. Warning To make sure API Errors occurring at app launch are correctly tracked, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. #### Sending data For each network error, a new event will be sent in analytics and Session Replay data. Check the following sections to learn more about how data is processed and sent: * [Analytics requests](https://docs.contentsquare.com/en/react-native/how-the-sdk-works/#sending-data) * [Session Replay requests](https://docs.contentsquare.com/en/react-native/session-replay/#requests) ### API Troubleshooting Details API Errors troubleshooting details enables you to collect more information about API errors so you can troubleshoot errors faster. With this feature you will be able to see three types of additional API error details in the Event Stream of Session Replay. * The HTTP headers of the request and the response. * The body (the data sent by the request or received in the response). * The query parameters of the request endpoint (of the URL of the information you request for). Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. See [API Troubleshooting Details ↗](https://support.contentsquare.com/hc/en-us/articles/37271885035537) for more details. #### Mask API Error By Template URL This method will mask URLs of failing API calls to URLs that match the template URL. Use colon (`:`) to indicate a dynamic parameter. ```javascript import { ErrorAnalysis } from "@contentsquare/react-native-bridge"; ErrorAnalysis.setURLMaskingPatterns([ "https://<domain>/:status_code/person/:person_id/store/:store_id", ]); ``` ### Collected data points Only network calls in error (response code above 400) will be collected. Here the exhaustive list of data collected: * URL (without query strings) * HTTP method * Response code * Timestamp of the request * Timestamp of the response * HTTP headers of the request * HTTP headers of the response * HTTP body of the request * HTTP body of the response * Query parameters of the request endpoint ### Known limitations and recommendations #### Conflict with Firebase Performance Monitoring ##### Android Contentsquare Error Analysis is not compatible with Firebase Performance Monitoring auto-collection. Only one of the two will log events, and usually, the events will be automatically logged by the Contentsquare Error Analysis. To log events to Firebase Performance Monitoring, we suggest [logging it manually ↗](https://rnfirebase.io/perf/usage#http-request-tracing). ##### iOS Contentsquare Error Analysis is compatible with Firebase Performance auto-collection, but the HTTP body from the response won't be collected by the Error Analysis SDK. **Workaround**: Disable Firebase automatic monitoring: ```javascript // <project-root>/firebase.json { "react-native": { "perf_auto_collection_enabled": false } } ``` Contentsquare Error Analysis may not be compatible with other network auto-collection tools. ## Crash Reporter The Crash Reporter feature automatically captures and reports application crashes to help you identify and debug critical issues in your React Native app. It supports both native crashes (Android/iOS) and JavaScript crashes. ### Overview The Crash Reporter provides: * **Native crash collection**: Captures crashes occurring in the native Android and iOS layers * **JavaScript crash collection**: Captures unhandled JavaScript errors and exceptions * **Automatic symbolication**: Provides readable stack traces for easier debugging * **Session context**: Links crashes to user sessions for better context ### Native crashes Native crashes occur in the platform-specific code (Android or iOS) and require additional setup for proper symbolication. #### Requirements ##### Android To enable crash collection and symbolication for Android native crashes, you need to add the Contentsquare Crash Gradle plugin. Add the plugin to both your root-level and app-level Gradle files: * Groovy **build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.crash" version "1.9.1" apply false } ``` **app/build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.crash" } ``` * Kotlin **build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.crash") version "1.9.1" apply false } ``` **app/build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.crash") } ``` ##### iOS For iOS applications, crash collection is automatically enabled when you integrate the Contentsquare Bridge. No additional dependencies or configuration are required. Note The iOS crash reporter is built into the Contentsquare SDK and will automatically start collecting crash data once the SDK is initialized. ### JavaScript crashes #### Validate JavaScript crashes integration ##### Validate JavaScript error handler is activated If the JavaScript Crash reporter has been successfully initialized an info log should appear in React Native logs: ```text CSLIB ℹ️ Info: CSErrorHandler is set as javascript global error handler. ``` ##### Validate JavaScript crash reporting To test that the JavaScript Crash Reporter is working properly, you can throw an unhandled JavaScript error in **production mode**. Development mode disables the crash reporter to reduce noise during development. The next time you start your application, the JavaScript crash will be sent to our servers. If you have logging enabled, you will see the upload reflected in the logs for iOS or Android. * Android ```text I/CSLIB: React Native Crash event detected and sent for userID: <user-id>, session: <session-number> on screen: <screen-number> crashID: <crash-id> ``` * iOS ```text CSLIB ℹ️ Info: React Native Crash event detected and sent for userID: <user-id>, session: <session-number> on screen: <screen-number> crashID: <crash-id> ``` #### Source Maps Check the [React Native documentation ↗](https://reactnative.dev/docs/debugging-release-builds?platform=ios#enabling-source-maps) on how to enable source maps generation for JavaScript, and make sure to adjust the following settings in your project for automatic source map upload: * Android **android/app/build.gradle** ```groovy ... apply plugin: "com.contentsquare.error.analysis.crash" apply from: "../../node_modules/@contentsquare/react-native-cli/scripts/contentsquare.gradle" ... react { // Ensure the following hermesFlags are present (hermesFlags = ['-O', '-output-source-map']) } ext { contentsquareConfigPath = "../contentsquare-cli.json" // default } ``` Use the `index.android.bundle.map` path in the `sourcemapPath` configuration for android. Example for default path: ```text ./android/app/build/generated/sourcemaps/react/release/index.android.bundle.map ``` * iOS **Bundle React Native code and images** ```shell ... export SOURCEMAP_FILE="$SRCROOT/main.jsbundle.map" WITH_ENVIRONMENT="$REACT_NATIVE_PATH/scripts/xcode/with-environment.sh" REACT_NATIVE_XCODE="$REACT_NATIVE_PATH/scripts/react-native-xcode.sh"; export CONTENTSQUARE_CONFIG_PATH="$SRCROOT/../contentsquare-cli.json" CONTENTSQUARE_XCODE="$SRCROOT/../node_modules/@contentsquare/react-native-cli/scripts/contentsquare-xcode.sh" /bin/sh -c "$WITH_ENVIRONMENT $REACT_NATIVE_XCODE" /bin/sh -c "$WITH_ENVIRONMENT $CONTENTSQUARE_XCODE" ... ``` Use the `main.jsbundle.map` path in the `sourcemapPath` configuration for ios. Example for default path: ```text ./ios/main.jsbundle.map ``` Follow the [iOS documentation](https://docs.contentsquare.com/en/ios/error-analysis/#set-up-xcode-to-automatically-upload-dsym-files) section for "Other dependency managers" to download `upload-symbols` script. Note The added script calls will trigger the Contentsquare CLI with the `update-sourcemap-id` command from the root of your project. This command creates or updates the `contentsquare-sourcemap-info.json` file, which contains the source map ID for both platforms. Add `contentsquare-sourcemap-info.json` to your `.gitignore` to prevent it from being committed to the repository: ```shell echo "contentsquare-sourcemap-info.json" >> .gitignore ``` ### CLI configuration Install the Contentsquare CLI package as a dev dependency to your project: * yarn ```shell yarn add @contentsquare/react-native-cli --dev ``` * npm ```shell npm install @contentsquare/react-native-cli --save-dev ``` The following information is required for the CLI to successfully upload the source maps: * **The targeted platform** `ios` or `android` * **The project ID** 1. Log on the Contentsquare platform on [https://app.contentsquare.com ↗](https://app.contentsquare.com) 2. Make sure to be on the right project 3. The project ID can be found in the URL query parameter `project`: `https://app.contentsquare.com/#/{MODULE_NAME}?project={PROJECT_ID}&hash={HASH}` * **Valid API credentials** Follow the dedicated documentation from the Help Center to get the client ID and client Secret: [How to create API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593). * **The source map path** The path to the source map file in the project. The path should be relative to the project root. To provide this information to the CLI script, either use a JSON configuration file or pass the required information as command line arguments. For automatic source map upload, the preferred way is to use the JSON configuration file. #### Using JSON configuration file Provide the required information by adding a `contentsquare-cli.json` file at the root of your project. **contentsquare-cli.json** ```json { "android": { "clientId": "ANDROID_CLIENT_ID", "clientSecret": "ANDROID_CLIENT_SECRET", "projectId": "ANDROID_PROJECT_ID", "sourcemapPath": "ANDROID_PROJECT_SOURCEMAP_PATH" }, "ios": { "clientId": "IOS_CLIENT_ID", "clientSecret": "IOS_CLIENT_SECRET", "projectId": "IOS_PROJECT_ID", "sourcemapPath": "IOS_PROJECT_SOURCEMAP_PATH" } } ``` #### Using command line arguments Alternatively, the required information can be added as arguments directly on the command line. | Option | Description | | - | - | | `--client-id` | The client ID of [API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593) | | `--client-secret` | The client secret of [API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593) | | `--config` | The path to the configuration file relative to project root. Default value: `contentsquare-cli.json` | | `--help` | Display the help message | | `--platform` | The platform to target: `ios` or `android` | | `--project-id` | The project ID | | `--sourcemap-path` | The path to the source map file | | `--uploadUrl` | The URL of the Contentsquare platform. Default value: `https://api.csq.io` | | `--verbose` | Display verbose output | Note These two solutions can be mixed if, for example, you want to use the multiple JSON files to store different configurations for different environments and pass the path to the file as a `config` argument. If same argument is used in both methods, the command line arguments will prevail over the same argument in the JSON file. How to use `@contentsquare/cli` to manually upload source maps Following exact steps is crucial to ensure the correct deobfuscation of the stack traces: 1. Invoke the Contentsquare CLI with the `update-sourcemap-id` command from the root of your project to create/update `contentsquare-sourcemap-info.json`, that contains the source map ID for both platforms. ```shell npx contentsquare-cli update-sourcemap-id ``` 2. Build a release version of your app. 3. Upload the source maps to the Contentsquare platform by invoking the `upload-sourcemaps` command from the root of your project. ```shell npx contentsquare-cli upload-sourcemaps ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Error Analysis","description":"How to use Contentsquare Error Analysis in your React Native apps","url":"https://docs.contentsquare.com/en/react-native/error-analysis/","inLanguage":"en","dateModified":"2026-08-06T08:47:54+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: How the SDK works - React Native (classic) description: Understand how the React Native bridge loads, tracks, and send data lastUpdated: 28 April 2026 source_url: html: https://docs.contentsquare.com/en/react-native/how-the-sdk-works/ md: https://docs.contentsquare.com/en/react-native/how-the-sdk-works/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). The SDK auto-starts at application launch, attaches to the current process, and intercepts the events and gestures needed to capture analytics data. ## Configuration Once started, our SDK fetches its config from our servers, and then depending on the segmentation size (defined by our team when you sign a contract) it will start collecting data from system and user events it detects from the runtime. ## Tracking The SDK monitors the application lifecycle events and the view hierarchy, and generates analytics data from the behavior of the app, the content of the screen and the interaction of the user. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. ## Sending data 📚 [Native Android SDK documentation for Sending data](https://docs.contentsquare.com/en/android/how-the-sdk-works/#sending-data) 📚 [Native iOS SDK documentation for Sending data](https://docs.contentsquare.com/en/ios/how-the-sdk-works/#sending-data) ## Session definition A session is one continuous period of user interaction. It starts upon app launch and persists through state changes, including putting the app in the background or terminating and restarting it. As long as users interact at least once every 30 minutes, it remains the same session. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"How the SDK works","description":"Understand how the React Native bridge loads, tracks, and send data","url":"https://docs.contentsquare.com/en/react-native/how-the-sdk-works/","inLanguage":"en","dateModified":"2026-04-28T22:02:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Impact on performance - React Native (classic) description: Metrics to evaluate the impact on performance of the SDK on your apps lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/react-native/impact-on-performance/ md: https://docs.contentsquare.com/en/react-native/impact-on-performance/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). Contentsquare strives to be non-intrusive and transparent to client app developers. The following are the technical specifics we can share on performance. *  ### [Android](https://docs.contentsquare.com/en/android/impact-on-performance/) *  ### [iOS](https://docs.contentsquare.com/en/ios/impact-on-performance/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Impact on performance","description":"Metrics to evaluate the impact on performance of the SDK on your apps","url":"https://docs.contentsquare.com/en/react-native/impact-on-performance/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: In-app features - React Native (classic) description: Implement in-app features with the Contentsquare React Native bridge lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/react-native/in-app-features/ md: https://docs.contentsquare.com/en/react-native/in-app-features/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). Alongside its tracking capabilities, the SDKs embed some features aimed at Contentsquare users such as [Screenshot Capture](#screenshot-capture) and [SDK Logs](#debugging-and-logging). ## Implement in-app features This implementation phase is required on the **iOS side only** (on Android, there is nothing to do). You will have to do a few changes on the **native side of your app**: ### 1. Add the custom URL scheme to `Info.plist` In order for your application to open when you scan the QR code or enter the URL we provide in a web browser, you have to add the custom URL scheme to your app's `Info.plist` file. For more info about how to do it, check the [iOS documentation](https://docs.contentsquare.com/en/ios/in-app-features/#1-add-the-custom-url-scheme-in-your-app-info). ### 2. Call the SDK when your app is opened with the custom URL Then, you will need to link your app with our SDK. When your application is started via a deeplink, a specific delegate function is called in your AppDelegate file. In order for us to be able to handle it, you will need to call a function of our API that will handle it. Call either the React Native or the iOS native API: #### Call the React Native API Follow this [guide ↗](https://reactnative.dev/docs/linking) to call the React Native API. * JavaScript ```javascript Linking.addEventListener('url', (event) => { Contentsquare.handleUrl(event.url); }); ``` * TypeScript ```typescript Linking.addEventListener('url', (event: { url: string }) => { Contentsquare.handleUrl(event.url); }); ``` ## Enable in-app features In-app features can be enabled in different ways: ### Scan the QR Code If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code displayed with your phone. Take a look at the native documentation for further information. ### Alternative methods We provide alternative methods to enable in-app features especially for iOS Simulator and Android Emulator. 📚 [Native Android SDK documentation for Enable in-app features](https://docs.contentsquare.com/en/android/in-app-features/) 📚 [Native iOS SDK documentation for Enable in-app features](https://docs.contentsquare.com/en/ios/in-app-features/) ## Debugging and Logging Contentsquare provides Logging capabilities that allow you to see the raw event data logged by your app. Use this for validation purposes during the instrumentation phase of development and can help you discover errors and mistakes in your analytics implementation and confirm that all events are being logged correctly. 📚 [Native Android SDK documentation for Debugging and Logging](https://docs.contentsquare.com/en/android/in-app-features/#debugging-and-logging) 📚 [Native iOS SDK documentation for Debugging and Logging](https://docs.contentsquare.com/en/ios/in-app-features/#debugging-and-logging) ## Screenshot capture To unlock the full data-visualization capabilities of Contentsquare, the SDK provides a way to capture screenshots of your app screens. These screenshots can only be taken by Contentsquare's users on their device. They are not captured from your end-users device. It means your Personal Data is safe, as long as you use a test user account. Warning For screenshot capture to work, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. 📚 [Native Android SDK documentation for Screenshot Capture](https://docs.contentsquare.com/en/android/in-app-features/#screenshot-capture) 📚 [Native iOS SDK documentation for Screenshot Capture](https://docs.contentsquare.com/en/ios/in-app-features/#screenshot-capture) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"In-app features","description":"Implement in-app features with the Contentsquare React Native bridge","url":"https://docs.contentsquare.com/en/react-native/in-app-features/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - React Native (classic) description: Learn how Contentsquare deals with Personal Data and related APIs lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/react-native/privacy/ md: https://docs.contentsquare.com/en/react-native/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). The Contentsquare React Native Bridge and SDKs are compliant with the **Play Store and App Store Privacy guidelines** and with the **EU General Data Protection Regulation (GDPR)**. Consult our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Handling User Consent Even though Contentsquare only collects usage data on your app, we will consider every new user to be opted-out. To start tracking, the Opt-in API must be called. Note If for some reason you think that securing user consent is not required for your app, discuss it during the Implementation process with your main contact. ## Opt-in Use the Opt-in API to get user consent. Calling this API will generate a user ID and initiate tracking. ```javascript import Contentsquare from "@contentsquare/react-native-bridge"; Contentsquare.optIn(); ``` ## Opt-Out **Permanently breaking the link and stopping all data collection.** When this API is called, tracking stops immediately, all settings are reset (session number, page number, user ID...) and all files related to Contentsquare tracking are deleted. Contentsquare will never track and collect any data from the user's phone unless the Opt-in API is called again. ```javascript import Contentsquare from "@contentsquare/react-native-bridge"; Contentsquare.optOut(); ``` ## Give me my data **We allow the client to provide to their users their Contentsquare user ID.** This ID is a non binding identifier which can be used to make a data request to Contentsquare. You are able to get an ID only if the user is not Opted-out. To do so, pass a callback as a parameter to the function. ```javascript import Contentsquare from "@contentsquare/react-native-bridge"; const [userId, setUserId] = useState("not retrieved yet"); // Contentsquare.getUserId(string => {}) Contentsquare.getUserId((newUserId) => { console.log(`Your Contentsquare UserID is ${newUserId}`); setUserId(newUserId); }); ``` ## Stop / Resume Tracking Although we do not gather any humanly readable text from the user's screens, we understand that there may be some areas that you want to completely exclude from tracking. For this reason, we also support stopping and resuming the complete tracking mechanism. ```javascript import Contentsquare from "@contentsquare/react-native-bridge"; // Stop tracking Contentsquare.stopTracking(); // Resume tracking Contentsquare.resumeTracking(); ``` Note As this mechanism stops the tracking, make sure that you call resume once your user exits the sensitive screen. Best practice would be to link these method calls to lifecycle events. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Learn how Contentsquare deals with Personal Data and related APIs","url":"https://docs.contentsquare.com/en/react-native/privacy/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Reliable Targets (iOS only) - React Native (classic) description: Reliable targets enables the analysis of data across various Screenshots from different dates and versions, including layouts or A/B testing variations lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/react-native/reliable-targets/ md: https://docs.contentsquare.com/en/react-native/reliable-targets/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). The identifier associated with each view in your app is the concatenation of the list of its ancestors in the React Native tree view. This means that if you have the following component: **basicComponent.js** ```javascript const basicComponent = () => { return ( <View> <Text>Hello world!</Text> <TextInput placeholder="Enter your name" /> </View> ); }; ``` You may always want to use the same id for this component, even if you publish a new version of the app in which it has been moved in the tree view. Having a reliable target for a view or a container of views enables the analysis of data across various Screenshots from different dates and versions, including layouts or A/B testing variations. Here are examples of how the reliable targets feature can be used: * Tracking elements that can dynamically move on a page (example: Customizable profile page). * Tracking elements that you want to monitor from one version to another, even if their position changes (example: Moving carousel position from top to bottom). * Tracking elements during A/B testing (example: Testing new and old Product page on the same version). * Tracking elements that can be used on multiple pages (example: Search bar). * Ensuring that a call to action has a unique identifier wherever it appears on a screen (example: AddtoCart button). The Contentsquare React Native SDK provides a `CSReliableTarget` component that can be used to wrap the component you want to track reliably. `CSReliableTarget` accepts a mandatory `name` prop that allows the identification of the component to track. **componentWithReliableTarget.js** ```javascript const componentWithReliableTarget = () => { return ( <CSReliableTarget name="MyComponentTracked"> <View> <Text>Hello world!</Text> <TextInput placeholder="Enter your name" /> </View> </CSReliableTarget> ); }; ``` Note Each target name must be unique to effectively use the feature. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Reliable Targets (iOS only)","description":"Reliable targets enables the analysis of data across various Screenshots from different dates and versions, including layouts or A/B testing variations","url":"https://docs.contentsquare.com/en/react-native/reliable-targets/","inLanguage":"en","dateModified":"2026-03-11T15:17:40+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Session Replay - React Native (classic) description: How to implement Session Replay with the Contentsquare React Native bridge lastUpdated: 07 August 2026 source_url: html: https://docs.contentsquare.com/en/react-native/session-replay/ md: https://docs.contentsquare.com/en/react-native/session-replay/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). Session Replay enables replaying real sessions to observe how users interact with your product, by capturing screen content - including text and images - as users navigate your mobile app. For more details, see [Introduction to Session Replay for Apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) in the Help Center. ## Starter guide ### Prerequisites #### Update to latest SDK version To enable Session Replay in your app and get the most stable version, it is required to [upgrade the SDK](https://docs.contentsquare.com/en/react-native/#install-the-sdk) to its latest version. #### Implement screen tracking Ensure screen tracking is implemented, since Session Replay collection starts at the first screenview event. See [Track screens](https://docs.contentsquare.com/en/react-native/track-screens/). #### Handle User consent Ensure user consent is handled for Contentsquare data collection, especially if you're implementing the SDK for the first time. See [Privacy](https://docs.contentsquare.com/en/react-native/privacy/) section. Note Mandatory data collection settings are configured by Contentsquare in your project parameters. [Learn more about Data collection configurations ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) on the Help Center. ### Configure Session Replay masking #### Masking behavior By default, the Contentsquare SDK is configured to mask all content displayed on the user interface (UI) to prevent unnecessary data collection. For more details, see what a fully masked screen looks like in [Masking mechanisms](#masking-mechanisms). **For testing purposes**, we advise you to unmask all the content by setting the [default masking](#default-masking) status to false. **For more granular control in deployment mode**, you can use the [SDK public masking APIs](#public-masking-apis) to fine-tune exactly which elements remain masked. Warning Always keep sensitive data masked to ensure compliance with privacy regulations and to protect users' personal data. ### Configure Webviews (optional) If your mobile app includes Webviews, specific implementation steps are required to ensure they are properly reflected in Session Replay: * Implement [Webview tracking](https://docs.contentsquare.com/en/webview-tracking-tag/) * Handle [personal data within WebViews](https://docs.contentsquare.com/en/webview-tracking-tag/session-replay/#personal-data-handling) ### Configure UIKit custom fonts - iOS only To ensure UIKit text elements are rendered in Session Replay exactly as they appear in your app, you can add fonts in `otf`, `ttf`, `woff`, or `woff2` formats directly from the player. See [Managing iOS Fonts In The Player ↗](https://support.contentsquare.com/hc/en-us/articles/37271807874577) in the Help Center documentation. ### Test your setup #### Enable Session Replay on your device If the Session Replay sampling rate is less than 100%, only a portion of sessions are collected. To ensure data collection on your device for testing and debugging purposes, you can force it from the In-app Features settings by following these steps: 1. [Enable in-app features](https://docs.contentsquare.com/en/react-native/in-app-features/) 2. Open in-app features settings with a long press on the screenshot button 3. Under "Session Replay", toggle "Enable Session Replay" on 4. Kill the app 5. Start app, a new session is starting with Session Replay enabled #### How do I know if Session Replay is enabled? * Android  There are 2 places where you can check if Session Replay is enabled: **In the logs:** The log `I/CSLIB|SessionReplay: Starting Session Replay.` will confirm that Session Replay is enabled. **In in-app features settings:** Below the "Enable "will start at next app start" *(see below [Access the replay](#access-the-replay))*, you will either see: * `No replay link available` which means Session Replay is not running for the current session * `Get Replay link` which means Session Replay is running for the current session * iOS  There are 2 places where you can check if Session Replay is enabled: **In the logs:** The log `Session Recording is starting.` will confirm that Session Replay is enabled. **In in-app features settings:** Below the "Enable "will start at next app start" *(see below [Access the replay](#access-the-replay))*, you will either see: * `No replay link available` which means Session Replay is not running for the current session * `Get Replay link` which means Session Replay is running for the current session #### Access the replay * Android The replay can be accessed by tapping on `Get replay link` button from the in-app features settings:  The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay your session up to the previous screenview if the session is still running. * iOS The session can be accessed by tapping on `Get replay link` button from the in-app features settings:  The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay your session up to the previous screenview if the session is still running. ## Personal Data Masking The Session Replay feature replays every interaction of your users with your app. To respect the user's right to privacy, the Contentsquare SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our [Masking rules](#masking-rules) Warning When using Contentsquare with React Native, if you decide to use unmasked elements leading to collection of new data or use already collected data but for a different purpose, it is up to you to update your app's privacy documentation accordingly. Here are some common examples of data collected via un-masked session Replay: Search history, Purchase history, Advertising data, etc. See [Types of data and purpose](https://docs.contentsquare.com/en/react-native/privacy/) already described in the Contentsquare iOS SDK Privacy Manifest. Contentsquare is not intended nor designed to collect sensitive personal data (such as health, financial, racial data). It is the customer's responsibility not to send any sensitive personal data to Contentsquare. ### Masking mechanisms Although the implementation is done once for both iOS and Android on React Native, the visual appearance of the masking itself will be different for each platform: * Android Every single UI element is converted into a highly pixelated image to reach a very low resolution. Text and images will appear very blurry so that the content cannot be identified. #### Original vs Replay fully masked  * iOS * Images are not collected, a placeholder is sent instead of the content; the "IMG" placeholder will be displayed in the frame of the element. * Text: text is replaced by "la" repeated as many times as needed to equal the original character count. White characters are preserved. For instance `the lazy fox` is collected as `lal lala ala`. All other visual properties are collected (text color, background color, alignment, etc.). * TextFields: same as Text * For all other types: no specific data is collected but visual properties are collected. If you think a specific element can reveal personal data from one of these properties mask it using one of the methods presented below. An efficient way to check how a view is rendered in replays is to navigate to the desired view with the CS SDK running then use the [quick replay link](#access-the-replay). #### Original vs Replay fully masked  ### Masking rules Masking rules can be applied in two ways: 1. **Through remote masking configuration in the CSQ Console (for admin users):** These configurations are managed directly in the Console and take effect for all sessions as soon as the app is restarted or brought to the foreground See [How to customize masking rules from the Data Masking tab ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) in the Help Center. 2. **Using public masking APIs in the SDK (for mobile application developers):** These configurations require developer implementation and will be applied only after the mobile app has gone through its release cycle. Masking rules set via the CSQ Console or the public APIs are applied according to different priorities, as described below. The SDK determines whether a view is masked by evaluating the rules in the order specified below. Once a rule is triggered, the state is set, and subsequent rules are not applied: | Priority | Rule | Configured via | | - | - | - | | 1 | The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2 | Remote Text or Image masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3 | A [component](#maskingunmasking-specific-component) is specifically masked or unmasked | API | | 4 | A [parent](#masking-and-unmasking-behaviors-on-a-parent-view) is specifically masked or unmasked | API | | 5 | Remote Text or Image unmasking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 6 | Otherwise the [default masking state](#default-masking) is applied | API | ### Public masking APIs #### Default masking All components are initially masked by default. To modify this default masking state, use the `setDefaultMasking` API, preferably within a `useEffect` in the root file (such as `App.js`). This ensures proper initialization and handling when the component mounts. If you choose to unmask the entire app using the `setDefaultMasking` API, be aware that you will need to individually mask all personal data within the app. Additionally, ensure that you consistently mask personal data on new screens in the future, if necessary. ```javascript /** * Set the default masking of all the views. * @param isMasking true mask all views by default. * false unmask all views by default. * The default value is true. */ Contentsquare.setDefaultMasking(boolean isMasking) ``` Note Even if you change the default masking state to `false`, the `TextInput` component will stay masked by default. #### Masking/Unmasking Specific Component To mask or unmask specific views or components you can use the `<CSMask isMasking={boolean}>` component. Control masking by setting the `isMasking` prop: * `isMasking={true}` (default, can be omitted): Masks all children components. * `isMasking={false}`: Unmasks all children components. In this example below, all children views inside `<CSMask>` will follow the rule of the closest parent prop `isMasking`. ```jsx // Masks or unmasks all child components based on isMasking prop <CSMask isMasking={true | false}> <View> <Text style={styles.title}>Buy my amazing merch!</Text> <Text> Hurry up! This offer won't be available tomorrow. Only $99.98 to get your hands on a wonderful, brand-new, life-changing item. </Text> </View> </CSMask> ``` #### Masking and Unmasking behaviors on a parent view The masking state of a parent view propagates to all nested views unless explicitly overridden by a nested `<CSMask>` component. This enables flexible masking and unmasking behaviors within complex component structures. ```jsx // Masks or unmasks all child components based on isMasking prop <CSMask isMasking={true}> <View> <Text>This content is masked.</Text> <CSMask isMasking={false}> <Text>This specific content is unmasked, despite the parent mask.</Text> </CSMask> </View> </CSMask> ``` In this example, the inner `<CSMask>` explicitly overrides the parent view's masking behavior. ### Implementation recommendations #### Avoid wrapping the Root Navigator `<CSMask>` should not wrap the Root Navigator it could cause unwanted results. If you want to set the default masking behavior for the whole application you should use `setDefaultMasking(boolean isMasking)`. `<CSMask>` should be used at component level. #### Avoid dynamically changing `isMasking` prop While `<CSMask>` supports toggling masking at the instance level, we do not recommend changing the `isMasking` prop dynamically based on conditions like this: ```jsx <CSMask isMasking={someCondition ? true : false}>...</CSMask> ``` This approach may lead to unexpected behavior, such as personal data leaks. Instead, structure your layout in a way that ensures predictable masking behavior without frequently modifying the `isMasking` prop dynamically. #### Keeping track of what is masked The SDK doesn't provide a list of what is currently masked. If you need to keep track of it, you probably will have to write your specific wrapper. ## Advanced features for Experience Monitoring Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. ### Send user identifier Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier: email, phone number, customer ID… As these values are typically personal data, from the moment the SDK is collecting the User Identifier, we immediately encode the value using a hashing algorithm so that the information is hidden and can never be accessed. Use the following code to send a user identifier: ```javascript import Contentsquare from "@contentsquare/react-native-bridge"; Contentsquare.sendUserIdentifier("any_identifier"); ``` When called, the SDK will log: * Android ```plaintext I/CSLIB: User identifier hashed sent {value} ``` * iOS ```plaintext CSLIB ℹ️ Info: User identifier hashed sent {value} ``` #### Sending a user identifier for each session You may want to send the user identifier for each session. While triggering the user identifier at app launch will cover most cases, it will not be enough. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See Session definition section for more information. That is why we also recommend sending the user identifier every time the app enters foreground. You can use [`AppState` API ↗](https://reactnative.dev/docs/appstate) to detect foreground and trigger a `sendUserIdentifier()`. #### Limitations * User identifier max length is 100 characters (if the limit is exceeded, the user identifier will not be handled and you will see an error message in the Console/Logcat) * Only the first 15 user identifiers per view will be processed on server side * The SDK will trim and lowercase user identifier * User identifier event are not visible in Log visualizer ## Integrations Contentsquare provides the ability to retrieve the link of the replay to be attached to other vendors such as Voice of Customer or Crash reporting tools. ### Subscribe to Session Replay Link changes Use `onSessionReplayLinkChange` to subscribe to Session Replay link updates (1). Then use the returned subscriber to remove the subscription when it is no longer needed. (2) ```jsx useEffect(() => { const subscriber = Contentsquare.onSessionReplayLinkChange((link) => { // 1 currentSessionReplaylink = link; }); return () => { if (subscriber) { // 2 subscriber.remove(); } }; }, []); ``` When a new link is created, the SDK will log: ```plaintext I/CSLIB: SessionReplay link: https://app.contentsquare.com/quick-playback/index.html?pid={projectId}&uu={userId}&sn={sessionNumber}&recordingType=cs ``` If you have a Contentsquare account, you can use this link to directly watch your current Session Replay on the Contentsquare Platform. The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay the session up to the previous screenview if the session is still running. ### Get current replay Link Deprecated `getCurrentSessionReplayLink` API is deprecated as of SDK version 4.3.0. Use `onSessionReplayLinkChange` instead. ```jsx const link = await Contentsquare.getCurrentSessionReplayLink(); ``` ## How Session Replay works ### Initialization Sessions can be collected for Session Replay if the Session Replay feature has been enabled for your project and the session matches the collection criteria. The following conditions will have an impact on which sessions will be collected: * **User consent**: The users have given their **consent** (if required) * **Collection rate**: The session is being **drawn for collection** (see Collection Rate below) * **Compatibility**: The **OS version** is supported. * **App version**: The **app version** is not part of the block list (see App version block list below) When Session Replay is turned off, no content specific to Session Replay is collected whatsoever. The standard Contentsquare analytics tracking remains unaffected by this. #### Collecting rate Session Replay collection is based on a percentage of the total sessions. By default Session Replay collection is disabled. During the early access phase, the percentage of collected sessions will be set to 1% at the beginning. It will then be adjusted according to: * The traffic on your app * The volume of collected sessions set in the contract #### Compatibility See [compatibility](https://docs.contentsquare.com/en/react-native/compatibility/). #### App version block list The Contentsquare team can add versions of your app in the block list to make sure Session Replay does not start on these versions. This is done when a problem is discovered on a specific version of your app, such as a Personal Data for which the masking was forgotten. This allows to keep Session Replay to work on the other app versions (especially the new ones with the fix). ### Collection The SDK monitors the application lifecycle events and the view hierarchy, and generates Session Replay data from the behavior of the app, the content of the screen and the interaction of the user. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. Tip Session collection will start at the 1st screenview event. ### Network and Storage By default, Session Replay data can be sent over **cellular network**. If the particular context of your app or users requires a very limited impact on cellular data consumption, **sending data over cellular network can be completely disabled**. Once disabled, data will be sent when the device is using Wi-Fi. Reach out to your Contentsquare contact that will make the adjustment in your project's configuration. #### Storage Before being sent, data is stored in local files on disk up to 30MB on iOS and 20MB on Android. If the limit is reached, Session Replay is stopped. It will restart at the next app launch, once the SDK has been able to send the data. ### Requests The maximum request size is 1Mbyte. #### Android Requests are sent: * Every 5 seconds * On screen change * When [Replay Link API](#access-the-replay) is called #### iOS Requests are sent: * Every 10 seconds * At app hide * When [Replay Link API](#access-the-replay) is called ## Performance impact ### Android #### Performance impact mitigation Most operations related to Session Replay are performed on dedicated background threads, for a minimal impact on the main thread. If CPU usage is too high for background tasks, some expensive calculations will be discarded. To make sure of this, we run performance tests on testing applications, along with the Android profiler. If too much time is spent on the main thread, the quality level will decrease automatically: from high to medium to low to a complete stop if required. Once conditions are back to normal, quality level will be changed back to the default value set in the configuration. We defined our network strategy to have the lesser impact on CPU, memory, and data consumption of the users devices. We measure these impacts, using the Android profiler and dedicated logging system, for each release of our SDK. You can reduce the quality level if you want to favor performance impact over quality. #### Performance test results We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. The performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | Pixel 5 | | Android version | 33 (Android 13) | | Quality level | High | | Default Masking State | Disabled | Note That the numbers provided below will vary depending on the user's device and Android version. | Property | Value | | - | - | | Total % on main thread (CPU Profiling) | < 10 % | | Memory overhead | 10 MB | | Session Replay data transmitted over network during 1 minute of use: | | | - with "High quality" level | < 300 kB | | - with "Medium quality" level | < 200 kB | | - with "Low quality" level | < 100 kB | ##### Additional info on performance test procedure **CPU Usage Test** We are profiling our Demo app with and without the SDK dependency by following the same use case. We are measuring the CPU peak for both versions of the app and we are computing the difference. **RAM Usage Test** We are profiling our Demo app with and without the SDK dependency by following the same use case. We are measuring the RAM usage peak for both versions of the app and we are computing the difference. **Memory Leak Test** We are profiling our demo app and we are using the ADB Monkey tool to create random user input events. During this time we are monitoring the RAM behavior for any anomaly. We are using the Memory Profiler to identify leaks. **Data consumption** We replay a predefined, repeatable, and automated user scenario on our demo app and all data sent is measured in kB/min. **JankStats** If you use the alpha library from Google to monitor the jank frames and you already have some jank frames in your application (main thread overwhelmed), you can expect an increase of 1% or 2% with Session Replay activated. Session Replay requires to perform tasks on the main thread (screen capture and view hierarchy inspection). ### iOS We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. #### Performance impact mitigation Most operations related to Session Replay are performed on background threads, for the impact on the main thread to be minimal. To make sure of this, we run performance tests on testing applications, using XCTMetric and Hitch Time Ratio measures. We also set up mechanisms that stop Session Replay if we detect the feature is using too much memory. We defined our network strategy to have the lesser impact on CPU and battery of the users devices. We measure these impacts, using Apple Dev Tools, for each release of our SDK. Session Replay will also stop if we use up to 30Mbytes of local storage. You can reduce the quality level if you want to favor performance impact over quality. #### Performance test results The following performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | iPhone 7 | | iOS version | 15.7.8 | | Test App built using Xcode version | 14.3.1 | | Test App built with Swift version | 5.8 | | Quality level | High | | Default Masking State | Disabled | We conducted the tests using a default `Master-Detail` app built using ad hoc distribution with no app thinning and with Swift symbols stripped. In the app, the SDK was making calls to the public APIs, running, and collecting data in its default state. Note The numbers provided below will vary depending on the user's device, iOS version, SDK version, and if you use Swift or not, which Swift version you use if you do, if you enabled bitcode or not and which options you used when building your IPA for App Store distribution. Note Screens built with SwiftUI produce, on average, 120% of the SR data produced by similar screens built with UIKit. | Property | Value | | - | - | | Max CPU overhead | <10% | | Max RAM usage | <5MB | | Session Replay data transmitted over network during 1 minute of use | | | - with "High quality" level | <2Mbytes | | - with "Medium quality" level | <1Mbytes | | - with "Low quality" level | <900Kbytes | ## Known limitations ### Discrepancy of the default iOS Font There is a discrepancy of the default iOS Font between devices and Session Replay. ### Incomplete Animations on iOS In some cases, animations may appear incomplete or cut off in Session Replay on iOS. ### Gradient and Masked View Limitations on iOS When using `react-native-linear-gradient` or `@react-native-masked-view/masked-view` libraries, elements may not be fully displayed in your Session Replays: * Background, border, and text elements can be missing during element recreation. * Results may differ depending on whether the default masking is set to `true` or `false`. ## Troubleshooting ### Requests are not sent from an Android emulator / iOS simulator If you struggle to watch a replay collection on an emulator/simulator, it may be due to some network constraints applied on your computer (VPN, company network restrictions, etc.). Check your configuration or use a real device. See following sections for more information about our endpoints and requests: * [Android - Requests are failing](https://docs.contentsquare.com/en/android/troubleshooting/#requests-are-failing) * [iOS - Requests are failing](https://docs.contentsquare.com/en/ios/troubleshooting/#requests-are-failing) ### Very long session on an Android emulator / iOS simulator It is important to remember that **an app kill does not end a session**. See [Session definition](https://docs.contentsquare.com/en/react-native/how-the-sdk-works/#session-definition) for more information. If you leave the simulator/emulator running with the app in foreground, the session will not end, even if you are inactive. To better reflect actual end user behavior and avoid unusually long sessions (last hours), put the app in background or kill it. ### Elements being unmasked when scrolling on Android If you encounter an issue where elements positioned above a ScrollView appear unmasked when scrolling, it may be due to the ScrollView clipping behavior. To resolve this, add the `removeClippedSubviews={true}` property to the ScrollView. This will ensure that only the visible subviews are rendered, helping prevent masking issues. ```javascript <View> <Image source={{ uri: image }} /> <ScrollView removeClippedSubviews={true}> {items.map(item => ( <ListItem key={item.id} item={item} /> ))} </ScrollView> <View> ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Session Replay","description":"How to implement Session Replay with the Contentsquare React Native bridge","url":"https://docs.contentsquare.com/en/react-native/session-replay/","inLanguage":"en","dateModified":"2026-08-07T10:11:06+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Security - React Native (classic) description: Data transfer and security information lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/react-native/security/ md: https://docs.contentsquare.com/en/react-native/security/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). The React Native SDK is designed with security and privacy in mind. ## Transmission and hosting All data is encrypted in transport over HTTPS. Our hosting solution is a PCI DSS Level 1 Service Provider. ## What is not collected * Passwords from password fields * Geo location information * Information from contacts, emails, or any other user identifiable information. * Text from labels, buttons, and any other widget which contains text * Accessibility information from any widget which the user interacts with * Labels printed on the screen of any kind. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Security","description":"Data transfer and security information","url":"https://docs.contentsquare.com/en/react-native/security/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track custom variables - React Native (classic) description: Track custom variables with the Contentsquare bridge for React Native lastUpdated: 02 June 2026 source_url: html: https://docs.contentsquare.com/en/react-native/track-custom-variables/ md: https://docs.contentsquare.com/en/react-native/track-custom-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). Custom variables attach additional information about the screen, user, or session to screenview events. For example, they can include information on the current layout of a screen, like day/night mode. ## Defining custom variables To define and send custom variables, follow this example: ```typescript import Contentsquare, { CustomVar } from "@contentsquare/react-native-bridge"; const cVar1: CustomVar = { index: 1, key: "CustomVarName1", value: "CustomVarValue1", }; const cVar2: CustomVar = { index: 2, key: "CustomVarName2", value: "CustomVarValue2", }; Contentsquare.send("ScreenName", [cVar1, cVar2]); ``` Warning The same (index, name) pair values should be used across the application to have consistent analytics results **Screen A** with CVAR: * `index` = 4 * `name` = `hero_banner_type` * `value` = "carousel" **Screen B** with CVAR: * `index` = 4 * `name` = `hero_banner_type` * `value` = `slider` ## Limits ### On the server side * It is possible to save up to 20 distinct custom variables per screenview. If more are received, only the first 20 custom variables, based on their `index` value, will be kept. * The `index` value of the custom variable is used to determine which custom variables to be kept. Only `index` values between 1 and 20 will be taken into account. ### On the SDK side * Every custom variable is composed of `index`, `name` and `value`. * If you are using the same `index` twice in the same screen, only the first (`name`, `value`) pair associated with the `index` will be kept. * It is possible to save up to 20 custom vars on the same screenview. * In case `name`(max. 512 characters) or `value`(max. 255 characters) maximum character length is reached, the SDK will automatically trim the exceeding characters. * If `name` or `value` are empty, the SDK will instead send the literal string `"cs-empty"`. * Use a consistent index for a given custom var within an application — for instance, if the "screen layout" is collected with an `index` of 3, use the slot 3 for this information on every screen of the application. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track custom variables","description":"Track custom variables with the Contentsquare bridge for React Native","url":"https://docs.contentsquare.com/en/react-native/track-custom-variables/","inLanguage":"en","dateModified":"2026-06-02T10:48:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track dynamic variables - React Native (classic) description: Track dynamic variables with the Contentsquare bridge for React Native lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/react-native/track-dynamic-variables/ md: https://docs.contentsquare.com/en/react-native/track-dynamic-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). Dynamic variables are additional information on the session that can be used to segment sessions. For example, they can include information on the A/B Test variations displayed to the current user. ## Defining dynamic variables To define and send a dynamic variable, you just need to use the following API. For each dynamic variable, we send: * Key (string, mandatory) * Value (string or integer, mandatory) if you send an integer as a value, it has indeed to be an integer. A null or a float will not be accepted as a valid parameter, and will result in an error. Also, in order for you to be able to handle such errors happening when we try to send the dynamic variable (see the constraints on keys and values in the [Limits](#limits) section above), you can also add, as a last parameter, a function that we will call so you can handle it gracefully. if you do not add that callback, we will log the error's message on the console whenever it happens. ```javascript import Contentsquare from "@contentsquare/react-native-bridge"; // alphanumeric value: Contentsquare.sendDynamicVar(string, string, ({ name, message, stack }: { name: string, message: string, stack: string }) => {} ?) Contentsquare.sendDynamicVar("my key", "my value 1"); Contentsquare.sendDynamicVar("my key", "my value 2", ({ message }) => { Toast.show(message, 0.3); }); // numeric value: Contentsquare.sendDynamicVar(string, number, ({ name, message, stack }: { name: string, message: string, stack: string }) => {} ?) Contentsquare.sendDynamicVar("my key", 10); Contentsquare.sendDynamicVar("my key", 5000, (errorObject) => { Console.log(errorObject.toString()); }); ``` **Type of the value** — The value can be either a `number` or a `string`. For each case, available features won't be the same in the Contentsquare app: * For **number**, you will be able to do some algebra. Example: *sessions with dynamic variable key = "numberOfFriends" and value >= 10* * For **string**, auto-completion and Regular Expression will be available. Example: *sessions with dynamic variable key = "accountType" and value is "Premium"* ## Sending a dynamic variable for each session You may want to send a dynamic variable for each session (like the user's country or store). While **triggering the dynamic variable at app launch will cover most cases, it will not be enough**. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See [Session definition](https://docs.contentsquare.com/en/react-native/how-the-sdk-works/#session-definition) section for more information. That is why we also recommend **sending such dynamic variable every time the app enters foreground**. You can use the [`AppState` API ↗](https://reactnative.dev/docs/appstate) to detect foreground and trigger a dynamic variable. ## Limits ### On the server side * It is possible to save up to 40 distinct dynamic variable keys per screen view. If more are received, only the first 40 keys will be kept. * If you are using the same key twice, the last value associated with the key will be collected. ### On the SDK side * Every dynamic variable is composed of a pair of key (max. 512 characters) and value (max. 255 characters string or number of type Long between 0 and 232 - 1). In case these maximums length are reached, the SDK will automatically trim the exceeding characters. * If key or value are empty, the SDK will instead send the literal string "cs-empty". ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track dynamic variables","description":"Track dynamic variables with the Contentsquare bridge for React Native","url":"https://docs.contentsquare.com/en/react-native/track-dynamic-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track screens - React Native (classic) description: Track screens with the Contentsquare bridge for React Native lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/react-native/track-screens/ md: https://docs.contentsquare.com/en/react-native/track-screens/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). Contentsquare aggregates user behavior and engagement at the screen level. To do so, it is required to track screen transitions by calling a dedicated API. When the API is called, the SDK logs a screenview event that identifies the new screen with the screen name provided. Warning Sessions without at least one screenview will be discarded. ```javascript import Contentsquare from "@contentsquare/react-native-bridge"; // Contentsquare.send(string); Contentsquare.send("ScreenName"); ``` ## Screen name handling The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side. ## Screenview after app in background The SDK triggers a screenview automatically after the app is put in background and foreground, as long as a screenview with a screen name has been triggered previously. It will use the last screen name set. ## Implementation recommendations From a functional standpoint, we expect a screenview to be sent: * When the screen appears * When a modal/pop-up is closed and the user is back on the screen * When the app is put in the foreground (after an app hide) ## How to name screens As a general rule, keep distinct screen names under 100. As they are used to map your app in Contentsquare, you will want something comprehensive. ### Separate words with space, dash, or underscore characters If you want to generate screen names including more than one word, it is best to separate them and to do so using space, dash, or underscore characters. Contentsquare handles automatically the formatting for them. **Example:** For a sub-category list of a retail app, use `Home & Living - Home Furnishings` instead of ~~`homeLivingHomeFurnishings`~~. ### Use screen template/layout names As a general recommendation, use names referring to the screen template/layout rather than referring to the specific content (data). This will help: * To keep the number of distinct screen names low and therefore make Contentsquare easier to use * Remove the risk of sending Personal Data to Contentsquare List of screen types falling into that category: *Product detail, Event detail, Conversation/Chat, User profile...* ### Screens with multiple states/layouts Screens can have different layouts or states depending on the user context. In this case, append its value to the screen name. **Home screen** | State | Screen name | | - | - | | App landing layout | `Home` | | Women products layout | `Home - Women` | | Men products layout | `Home - Men` | | Sales layout | `Home - Sales` | **Product Detail screen (PDP)** | State | Screen name | | - | - | | Users on a Top for Women PDP | `PDP - Clothing - Women - Tops` | | Users on a Microwave PDP | `PDP - Kitchenware - Electrics - Microwave` | | Users on a Hotel details screen | `PDP - Holiday type - Season - Board` | **User account screen** | State | Screen name | | - | - | | Overview | `My Account - Dashboard` | | Order history | `My Account - Order history` | | Returns | `My Account - Returns` | **Search screen** | State | Screen name | | - | - | | Search | `Search` | | Search results for "Skincare" products | `Search - Skincare` | | Search results error screen | `Search - Error` | **Cart screen** | State | Screen name | | - | - | | Empty cart | `Cart - Empty` | | Items have been added to the cart | `Cart - Populated` | | Issues with availability or pricing | `Cart - Error` | **Checkout screen** | State | Screen name | | - | - | | User provides name, surname, and date of birth | `Checkout - User Details` | | User provides shipping address | `Checkout - Shipping Details` | | User inputs their credit card information | `Checkout - Payment` | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track screens","description":"Track screens with the Contentsquare bridge for React Native","url":"https://docs.contentsquare.com/en/react-native/track-screens/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track transactions - React Native (classic) description: Track transactions with the Contentsquare bridge for React Native lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/react-native/track-transactions/ md: https://docs.contentsquare.com/en/react-native/track-transactions/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). To associate a user's session with their potential purchases (and corresponding revenue), you must send the transaction via a dedicated API. For each transaction, we send: * Price (number, mandatory) * Currency (Currency or string, mandatory) * Transaction ID (string, optional) ```javascript import Contentsquare, { Currency } from "@contentsquare/react-native-bridge"; // numeric currency: Contentsquare.sendTransaction(number, Currency, string?) Contentsquare.sendTransaction(10.99, Currency.USD); Contentsquare.sendTransaction(200.99, Currency.EUR, "my_transaction_1"); // alphanumeric currency: Contentsquare.sendTransaction(number, string, string?) Contentsquare.sendTransaction(10.99, "USD"); Contentsquare.sendTransaction(200.99, "eur", "my_transaction_2"); ``` Warning **Each transaction must only be sent once**. A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ## Currency The currency is conforming to the [ISO 4217 ↗](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) standard. Although the currency can be passed either as "alphanumeric code" or "numeric code", you should always prefer using the bridge's Currency object values. If you have to pass the ISO code as a string, capitalization is not a factor (`Currency.USD`, `"USD"`, `"Usd"` or `"usd"` will all be treated as the US Dollar). If the currency passed doesn't match our supported currencies, the SDK will send a currency value of "-1". It will be processed as the default currency of the project. ## Migrating from version 4.X.X to 5.X.X If you are migrating from a previous version of the Contentsquare React Native SDK, the `sendTransactionWithStringCurrency` method has been removed, and replaced by `sendTransaction`: ```javascript import Contentsquare, { Currency } from "@contentsquare/react-native-bridge"; Contentsquare.sendTransactionWithStringCurrencysendTransaction(10.99, "USD"); Contentsquare.sendTransactionWithStringCurrencysendTransaction(200.99, "eur", "my_transaction_2"); ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track transactions","description":"Track transactions with the Contentsquare bridge for React Native","url":"https://docs.contentsquare.com/en/react-native/track-transactions/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track WebViews - React Native (classic) description: Track webviews with the Contentsquare bridge for React Native lastUpdated: 23 April 2026 source_url: html: https://docs.contentsquare.com/en/react-native/track-webviews/ md: https://docs.contentsquare.com/en/react-native/track-webviews/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). WebView tracking links the Contentsquare SDK to the JavaScript tag running inside your WebViews to support analytics and Session Replay for web content displayed within your app. React Native compatibility Contentsquare only supports the [`react-native-webview` ↗](https://github.com/react-native-webview/react-native-webview) library for tracking WebView components in React Native apps. Contentsquare's implementation relies on `react-native-webview` internals and is not compatible with other WebView implementations. ## Enable tracking in WebViews ### Inject the Bridge between the CS Tag in WebView mode and the SDK To inject this JavaScript, you will use our `CSWebView` component to render your WebView, as detailed bellow. Here is a screen with a `react-native-webview` WebView component. ```jsx import { WebView } from "react-native-webview"; const WebviewWithTagScreen = () => { return ( <> <WebView source={{ uri: "https://www.mywebpage.com" }} /> </> ); }; export default WebviewWithTagScreen; ``` Let's walk through how we can inject it with a custom JavaScript interface. #### CSWebView component To inject your WebView with the Contentsquare JavaScript WebView interface you will need to wrap your original WebView with `CSWebView` component. `CSWebView` component will handle all. ```jsx import { WebView } from "react-native-webview"; const WebviewWithTagScreen = () => { return ( <> <CSWebView> <WebView source={{ uri: "https://www.mywebpage.com" }} /> </CSWebView> </> ); }; export default WebviewWithTagScreen; ``` ### Inject the CS Tag in WebView mode into your HTML page After doing all the above, in order for the implementation to be completed, you will need to make sure our **CS Tag in WebView mode** is injected on your pages. To do so, refer to 📚 [Mobile Apps WebView Tracking Documentation](https://docs.contentsquare.com/en/webview-tracking-tag/). ## Migrating from version 4.X.X to 5.X.X If you are migrating from a previous version of the Contentsquare React Native SDK, update your `CSWebView` implementation: ```jsx import React from "react"; import { WebView } from "react-native-webview"; import { CSWebView } from "@contentsquare/react-native-bridge"; const WebviewWithTagScreen = () => { return ( // This method is deprecated <CSWebView url="https://www.mywebpage.com" renderWebView={(onLayout, webViewUrl) => { return ( <WebView onLayout={onLayout} source={{ uri: webViewUrl }} /> ); }} /> <CSWebView> <WebView source={{ uri: "https://www.mywebpage.com" }} /> </CSWebView> ); }; export default WebviewWithTagScreen; ``` ## Validate WebView tracking To validate the tracking of WebViews, refer to the platform-specific instructions. * [📚 Android documentation](https://docs.contentsquare.com/en/android/track-webviews/#validating-the-implementation-on-the-web-side) * [📚 iOS documentation](https://docs.contentsquare.com/en/ios/track-webviews/#on-the-web-side) ## Known limitations For iOS only An issue has been identified with the `goBack()` method of the React Native WebView component. When this method is called, it may not be registered by Session Replay in some cases, leading to some webview pages not being replayed correctly. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track WebViews","description":"Track webviews with the Contentsquare bridge for React Native","url":"https://docs.contentsquare.com/en/react-native/track-webviews/","inLanguage":"en","dateModified":"2026-04-23T15:45:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Troubleshooting - React Native (classic) description: Need help? We share probable causes and recommended fixes lastUpdated: 29 July 2026 source_url: html: https://docs.contentsquare.com/en/react-native/troubleshooting/ md: https://docs.contentsquare.com/en/react-native/troubleshooting/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). When the SDK is not sending data as expected, use this page to identify probable causes and apply recommended fixes. ## Requests are failing In order for Contentsquare to work, you need to make sure the following endpoints are not blocked by your network (VPN): | Request | Endpoint | Detail | | - | - | - | | Config file | `https://mobile-production.content-square.net` | See [Configuration](../how-the-sdk-works/#configuration) | | Analytics data (EU) | `https://m.csqtrk.net` `https://m.ba.contentsquare.net` `https://m.aa.contentsquare.net` | See [Sending data](../how-the-sdk-works/#sending-data) | | Analytics data (US) | `https://m-aus1.contentsquare.net` `https://m.bf.contentsquare.net` `https://m.af.contentsquare.net` | See [Sending data](../how-the-sdk-works/#sending-data) | | Monitoring | `https://l.contentsquare.net` | Used by the SDK to send SDK monitoring analysis in JSON format over HTTPS. | | Session Replay data (EU) | `https://ka-aeu1.contentsquare.net` `https://ka.ba.contentsquare.net` `https://ka.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Session Replay data (US) | `https://ka-aus1.contentsquare.net` `https://ka.bf.contentsquare.net` `https://ka.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Screenshot (EU) | `https://s.contentsquare.net` `https://b.ba.contentsquare.net` `https://b.aa.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Screenshot (US) | `https://s-aus1.contentsquare.net` `https://b.bf.contentsquare.net` `https://b.af.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Resources manager (EU) | `https://srm.ba.contentsquare.net` `https://srm.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Resources manager (US) | `https://srm.bf.contentsquare.net` `https://srm.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | ## Known limitations ### React Native Webview goBack() Warning iOS only: When the `goBack()` method of the React Native WebView component is called, it may not be registered by Session Replay in some cases, leading to some webview pages not being replayed correctly. ### Use of PanResponder If you are using PanResponders in your app, a bug might appear on the element implementing it where it will only move for about a second and then freeze. This bug is caused by a conflict between the React Native SDK and our Bridge related to tracking swipe events. The workaround is to stop Contentsquare tracking when the pan gesture starts, and resume it as the gesture ends, as follows: ```javascript const panResponder = useRef( PanResponder.create({ [...] onPanResponderGrant: (evt, gestureState) => { Contentsquare.stopTracking(); [...] }, onPanResponderRelease: (evt, gestureState) => { Contentsquare.resumeTracking(); [...] }, [...] }) ).current; ``` Applying this workaround fixes the bug, but Contentsquare will no longer track swipes on views using the PanResponder. ### Long Screenshot Not Supported Long Screenshot is not currently supported in React Native. This feature captures and analyzes long scrollable screens such as product listing pages or user profiles for enhanced Zoning Analysis, and is only available in Flutter, iOS, and Android native SDKs. Warning If Long Screenshot has been enabled in your React Native project, expect limitations and inconsistencies in capturing extended scrollable views. Contact your Customer Success Manager to discuss mitigation strategies for your implementation. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Troubleshooting","description":"Need help? We share probable causes and recommended fixes","url":"https://docs.contentsquare.com/en/react-native/troubleshooting/","inLanguage":"en","dateModified":"2026-07-29T20:57:49+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Use Adobe Analytics - React Native (classic) description: Leverage our native integration to use Adobe Analytics segments in Contentsquare lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/react-native/use-adobe-analytics/ md: https://docs.contentsquare.com/en/react-native/use-adobe-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). Analyze your data from anywhere in the customer journey using your Adobe Analytics segments. Contentsquare allows you to use your Adobe Analytics segments in every Contentsquare feature (Journey Analysis, Page Comparator, Session Replay). Warning Sessions without at least one screenview will be discarded. You should implement your screen tracking plan first, to have your Adobe Analytics integration work. See [Track screens](../track-screens/). ## Prerequisites 1. Follow the instructions from [Adobe Analytics for mobile apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271665881745) 2. Add the [React Native AEP ↗](https://github.com/adobe/aepsdk-react-native) to your project ## Code implementation Note **Adobe SDK code requirements** On the native Android and iOS parts of your React Native project, make sure you have registered at least `Edge Network` and `Edge Identity` extension before starting `MobileCore`. Check [React Native AEP repository ↗](https://github.com/adobe/aepsdk-react-native) for the code to put in the Android and iOS native parts. **Why 30 minutes before sending a new csMatchingKey** * 30 minutes is Contentsquare default session duration. * Setting a value **higher** than 30 minutes would cause overlapping on our sessions, and would impact negatively the data import from Adobe. * Setting a value **lower** than 30 minutes would make you to send more data to Adobe. This could cause the variable to reach Adobe's threshold, causing Adobe to filter values, and potentially impact your billing. See [Low-traffic value in Adobe Analytics ↗](https://experienceleague.adobe.com/docs/analytics/technotes/low-traffic.html) Add the following code snippet in your application code. **adobe-analytics.js** ```javascript import { Edge, ExperienceEvent } from "@adobe/react-native-aepedge"; import Contentsquare from "@contentsquare/react-native-bridge"; // TODO: Use local storage you prefer here import AsyncStorage from "@react-native-async-storage/async-storage"; export async function sendCSMatchingKeyIfNeeded() { const csMatchingKeyRecord = await AsyncStorage.getItem("csMatchingKey_creation_ts"); if (!csMatchingKeyRecord) { await submitNewCsMatchingKey(); return; } const { timestamp } = JSON.parse(csMatchingKeyRecord); if (Date.now() - timestamp > 30 * 60 * 1000) { // if the key is not valid anymore, submit a new one await submitNewCsMatchingKey(); } // if the key is still valid, do nothing } async function submitNewCsMatchingKey() { // Generate the matching key and store it in the local storage const csMatchingKeyValue = `${Math.random()}_${Date.now()}`; const newCsMatchingKeyRecord = { csMatchingKey: csMatchingKeyValue, timestamp: Date.now(), }; await AsyncStorage.setItem("csMatchingKey_creation_ts", JSON.stringify(newCsMatchingKeyRecord)); // Submit the matching key to Contentsquare and Adobe Contentsquare.sendDynamicVar("csMatchingKey", csMatchingKeyValue); const xdmData = { eventType: "csMatchingKey_state" }; const data = { csMatchingKey: csMatchingKeyValue }; const experienceEvent = new ExperienceEvent(xdmData, data); Edge.sendEvent(experienceEvent); } ``` Add a call to the `sendCSMatchingKeyIfNeeded()` from within the `index.js` file of your project root folder when app state changes to 'active'. **index.js** ```javascript import { AppState } from "react-native"; import { sendCSMatchingKeyIfNeeded } from "./adobe-analytics.js"; // Listen for app state changes to foreground AppState.addEventListener("change", (nextAppState) => { if (nextAppState === "active") { sendCSMatchingKeyIfNeeded(); } }); ``` How to use deprecated React Native AEP Analytics Extension Deprecated For [React Native AEP Analytics Extension ↗](https://github.com/adobe/react-native-acpanalytics), on the native Android and iOS parts of your React Native project, make sure you have registered at least `ACPIdentity` and `ACPAnalytics` before starting `ACPCore`. Check [React Native AEP Analytics Extension repository ↗](https://github.com/adobe/react-native-acpanalytics/tree/main/sample/ACPAnalyticsSampleApp) for the code to put in the Android and iOS native parts. Add the following code snippet in your application code. Add a call to the `updateCsMatchingKey()` from within the `index.js` file of your project root folder. **adobe-analytics.js** ```javascript import { ACPCore } from "@adobe/react-native-acpcore"; import Contentsquare from "@contentsquare/react-native-bridge"; // TODO: Use local storage you prefer here import AsyncStorage from "@react-native-community/async-storage"; export async function updateCsMatchingKey() { const csMatchingKeyRecord = await AsyncStorage.getItem("csMatchingKey_creation_ts"); if (!csMatchingKeyRecord) { await submitNewCsMatchingKey(); return; } const { timestamp } = JSON.parse(csMatchingKeyRecord); if (Date.now() - timestamp > 30 * 60 * 1000) { // if the key is not valid anymore, submit a new one await submitNewCsMatchingKey(); } // if the key is still valid, do nothing } async function submitNewCsMatchingKey() { // Generate the matching key and store it in the local storage const csMatchingKeyValue = `${Math.random()}_${Date.now()}`; const newCsMatchingKeyRecord = { csMatchingKey: csMatchingKeyValue, timestamp: Date.now(), }; await AsyncStorage.setItem("csMatchingKey_creation_ts", JSON.stringify(newCsMatchingKeyRecord)); // Submit the matching key to Contentsquare and Adobe Contentsquare.sendDynamicVar("csMatchingKey", csMatchingKeyValue); ACPCore.trackState("csMatchingKey_state", { csMatchingKey: csMatchingKeyValue, }); } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Use Adobe Analytics","description":"Leverage our native integration to use Adobe Analytics segments in Contentsquare","url":"https://docs.contentsquare.com/en/react-native/use-adobe-analytics/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Use Google Tag Manager - React Native (classic) description: Leverage our native integration to send Google Tag Manager events to Contentsquare lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/react-native/use-google-tag-manager/ md: https://docs.contentsquare.com/en/react-native/use-google-tag-manager/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/). Integrate Google Tag Manager with Contentsquare in your React Native app to forward GTM events to the SDK. ## Prerequisite If you are following this Google Tag Manager integration process, you should already have followed the React Native Firebase setup. We will assume that you are using [the officially supported Firebase bridge ↗](https://rnfirebase.io/) the officially supported Firebase bridge. We will also assume that you have added the native GTM library to your iOS and Android project (following the [iOS documentation ↗](https://developers.google.com/tag-manager/ios/v5) and the [Android documentation ↗](https://developers.google.com/tag-manager/android/v5#add-gtm-to-project)). Before anything, you also need to integrate the Contentsquare Bridge ([see section: Add Contentsquare to your app](https://docs.contentsquare.com/en/react-native/#install-the-sdk)). ## Integration The whole integration will happen in the native part of your app, and in the GTM interface. Here is how it will work (you need to do these steps twice, once for iOS and once for Android): * You will first setup custom tag, trigger, and variables in your GTM interface. * Then, you will have to add a custom Tag class in your native project. * In your JavaScript/TypeScript code, or in your native code, you will use the Firebase Analytics library to send events, as explained thereafter. * As you have created a trigger for that specific type of event, it will trigger the code in your native custom Tag class, where you will be calling the native SDK function corresponding to that event, thus allowing Contentsquare to collect those events. ### Screenview events Screenview events will be triggered in the Firebase React Native bridge [by calling setCurrentScreen ↗](https://rnfirebase.io/analytics/screen-tracking). As the integration is exactly the same as the native ones, you can refer directly to the SDKs' explanation of the [iOS integration](https://docs.contentsquare.com/en/ios/use-google-tag-manager/#screenview-events) and [Android integration](https://docs.contentsquare.com/en/android/use-google-tag-manager/#screenview-events). You will have to do both to have a similar behavior across both platforms. ### Transaction events Transaction events will be triggered in the Firebase React Native bridge [by calling `logEvent` ↗](https://rnfirebase.io/analytics/usage#custom-events) with a purchase event (for example, `analytics().logEvent('purchase', { currency: 'USD', value: 99.99 })`). As the integration is exactly the same as the native ones, you can refer directly to the SDKs' explanation of the [iOS integration](https://docs.contentsquare.com/en/ios/use-google-tag-manager/#screenview-events) and the [Android integration](https://docs.contentsquare.com/en/android/use-google-tag-manager/#screenview-events). You will have to do both to have a similar behavior across both platforms. ### Dynamic variable events Dynamic variables are generally custom, and as such can be used with any type of event that can be boiled down to a key/value pair with value types that are valid for the Contentsquare SDK (a string or an unsigned integer). The most common event in that case will thus be a custom event, sent [by calling `logEvent` ↗](https://rnfirebase.io/analytics/usage#custom-events) with a custom event name and parameters. As the integration is exactly the same as the native ones, you can refer directly to the SDKs' explanation of the [iOS integration](https://docs.contentsquare.com/en/ios/use-google-tag-manager/#dynamic-variable-events)/[Android integration](https://docs.contentsquare.com/en/android/use-google-tag-manager/#dynamic-variable-events). You will have to do both to have a similar behavior across both platforms. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Use Google Tag Manager","description":"Leverage our native integration to send Google Tag Manager events to Contentsquare","url":"https://docs.contentsquare.com/en/react-native/use-google-tag-manager/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Artificial Pageviews - Web description: Artificial pageviews are to be used when the site uses AJAX, SPA, PWA, or re-routes users without refreshing the page lastUpdated: 25 June 2026 source_url: html: https://docs.contentsquare.com/en/web/artificial-pageviews/ md: https://docs.contentsquare.com/en/web/artificial-pageviews/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use artificial pageviews when: * An action completely changes the content displayed on the page without refreshing it and changing its URL (Ajax requests) * The site is built with a Single Page Application (SPA) and any related frameworks (React, Angular) * The user gets redirected to another step of a funnel without refreshing the page * The site re-routes all the URL changes without refreshing the page * The site is built as a Progressive Web App (PWA) * Important modal windows (sometimes called popups or popins) are displayed #### Modal tracking with artificial pageviews To track a modal opening and closing while the user navigates your site, use artificial pageviews. Send one artificial pageview when the modal is opened, and another one when the modal is closed. For example, this might be a click on the close button or a custom JavaScript event that fires when the modal is dismissed. For the close event, you can reuse the code snippet, updating the name or path parameter to indicate that this is a close event. #### Stable URLs - Modal windows and artificial pageviews tracking For tracking **modal windows or events that don't change the URL structure**, you'll need to use the Contentsquare **Trackpageview** functionality by following these methods and binding them to the correct action (button click/event trigger). #### Dynamic URLs - Single Page Applications and History Change In the event of the **URL structure being changed** on each view change, we can keep track of this by **firing the Main Tag again**: the tag will automatically detect that it was previously put in place on the site and fire a new pageview instead. ## Contentsquare Tag Configurator (CSTC) Use the [Contentsquare Tag Configurator ↗](https://support.contentsquare.com/hc/en-us/articles/37271878716433-CSTC-Template-Artificial-Pageview) to implement artificial pageviews through a visual interface. ## Google Tag Manager (Template) ### Stable URLs 1. Open your container and go to the **templates** section  2. Select **Search gallery**  3. Type in **`contentsquare`** and select the **Contentsquare - Artificial Pageview** option  4. Click **Add to workspace**  5. Confirm your choice by selecting **Add**  6. Go to the Tags section and click the **New** button to create a new tag  7. Configure it by selecting the top-right button  8. Type in **`contentsquare`** and select the **Contentsquare - Artificial Pageview** option  9. Select the tag and configure: * Select the Free text option and enter the value under `Artificial Pageview value`. * If there's a modal (sometimes called "popup") on your website and you need to deploy APV, then select `This is for the opening a popup` or `This is for the closing of a popup` in the drop-down. Note The value will be prefixed with `cs-popin-`. For instance `cs-popin-cart`, `cs-popin-wishlist`.  ### Dynamic URLs 1. Amend the Main tag configuration by **adding a new trigger** to it.  2. Create a new trigger  3. Select **"Choose a trigger type to begin setup..."**.  4. In the list, select the **"History Change"** trigger.  5. **Save** your trigger.  6. Select the **"Save"** button on the top right.  ## Google Tag Manager (Custom HTML) ### Stable URLs 1. Select **"Choose a tag type to begin setup..."**.  2. In the list, pick the **"Custom HTML"** tag.  3. Write the snippet to be fired in the **HTML field**. It should be similar to this: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push([ "setQuery", window.location.search + (window.location.search ? "&" : "?") + "cs-popin-dedicated_query_string", { lifespan: 'onNextPageviewOnly' } ]); window._uxa.push([ "trackPageview", window.location.pathname + window.location.hash.replace("#", "?__"), { lifespan: 'onNextPageviewOnly' } ]); </script> ```  4. Select **"Choose a trigger to make this tag fire..."**.  5. Create a new trigger to make this tag fire  6. Select **"Choose a trigger type to begin setup..."**.  7. In the list, pick the **"All Elements"** trigger.  8. Check **"Some Clicks"**  9. Select **"Click Element"**, **"matches CSS selector"** and enter a **valid CSS** filter corresponding to the element you want to track. For example the valid CSS for: ```html <button class="btn btn primary">Submit</button> ``` Will be: ```css .btn.btn.primary ```  ### Dynamic URLs 1. Amend the Main tag configuration by **adding a new trigger** to it.  2. Create a new trigger  3. Select **"Choose a trigger type to begin setup..."**.  4. In the list, select the **"History Change"** trigger.  5. **Save** your trigger.  6. Select the **"Save"** button on the top right.  ## Tealium ### Stable URLs **Assign the event** you might already have in place a custom HTML snippet and write the snippet to be fired in the HTML field. It should be similar to this: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push([ "setQuery", window.location.search + (window.location.search ? "&" : "?") + "cs-popin-dedicated_query_string", { lifespan: 'onNextPageviewOnly' } ]); window._uxa.push([ "trackPageview", window.location.pathname + window.location.hash.replace("#", "?__"), { lifespan: 'onNextPageviewOnly' } ]); </script> ``` ### Dynamic URLs Create (or select an already existing) event that occurs on each history change or view re-routing. Assign this event to the Contentsquare extension. ## Adobe Launch ### Stable URLs #### Artificial Pageviews When setting up the rule, **make sure to target the specific event or condition** needed. For instance, for an add to bag action, you could either follow the click route:  Or the custom event route:  Once you've chosen the desired event, you can select the Artificial Pageview tracking action from the Contentsquare extension.  Depending on the pageview you'd need to track, you can **either specify the query** to be passed to the Contentsquare servers:  **Or, leave the input field empty**, which will allow our script to capture the current URL automatically:  You can also use **Data Elements** as a query string for artificial pageviews.  ### Dynamic URLs In the event of a SPA implementation, if the path/query automatically changes on each re-routing, utilise the built-in history change event to fire the CS tag on each of these occurrences.  ## Commanders Act 1. To add a new event, go to the "EDIT" step, and click "ADD EVENT" (1):  A configuration window will appear, with several fields: * (1) "Name": Name of the event you wish to add * (2) "Id": The event's ID (to be completed only if you know it and want to trigger the event based on its ID; otherwise, leave the field empty, and it will be generated automatically by Commanders Act) * (3) JavaScript code: Area where the event's JavaScript code is entered * (4) "Use Tag Cleaner": Feature allowing you to "correct" the event (rewrites it to avoid JavaScript errors and makes it compatible with the container's code)  2. Click "ADD" to add your event to the container. 3. Go to the tag library. Once there: 1. Write "Event Injection" in the search engine 2. Select the tag 3. Add the tag  In case of tracking pageviews with Contentsquare, the code to be deployed should follow this guideline: ```javascript window._uxa = window._uxa || []; window._uxa.push(['trackPageview', <PATH_TO_SEND> ]); ``` (4) Go to your website; place the cursor on the element you wish to place an event on and do a right click. In the menu that opens up, select "Inspect Element". (5) In the console, once the element is highlighted, right-click again. (6) Choose "copy" from the menu. (7) > "Copy Selector". Note These actions on the site's CSS are applicable to the Google Chrome browser only.  (8) If you know the element's ID (starting with a #): copy and paste it in the #CSS\_PATH# field.  (9) If you do not know or cannot find the ID: copy and paste the element's information starting with "#" and replace `" > "` with a single space in the code line.  (10) Copy and paste the line in the interface's #CSS\_Path# field.  Now enter the ID of the event you wish to summon in the corresponding field. Proceed to the deployment step as you do with other tags. ## Shopify 1. Within the main menu, select **Online Store > Themes**, then click the **Actions** drop-down menu, and **Edit Code**.  2. Open the relevant Liquid file where you want to trigger an artificial pageview based on your own JavaScript logic. You can put this in the main `theme.liquid` file or in a specific Liquid file. Let's say you want to trigger this artificial pageview only when a certain action takes place like when an item is added to the cart. You would need to wrap this code inside your own condition, callback function, or event listener. 3. In the snippet below, replace `<PATH_TO_SEND>` with your unique path. ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(['trackPageview', <PATH_TO_SEND> ]); </script> ``` You either hard-code a static value for the path like `Added_to_cart` or use Shopify's [Liquid Objects ↗](https://shopify.dev/api/liquid/objects)/[Liquid Tags ↗](https://shopify.dev/api/liquid/tags) to grab the dynamic data from it like below: Tip Check out Shopify's [Liquid Object cheat sheet ↗](https://www.shopify.com/partners/shopify-cheat-sheet) ```html <script type="text/javascript"> // Contentsquare Send Artificial Pageviews document.getElementById("AddToCart").addEventListener('click', function() { window._uxa = window._uxa || []; window._uxa.push(["trackPageview", "Added_to_cart_" + {{ custom_tag.value}}]) }); </script> ``` 4. Insert this code after the main tracking tag block. The end result of adding this code into the Liquid file: ```html <!-- Contentsquare Tags Start --> <script type="text/javascript"> // Contentsquare Main Tracking Tag (function () { window._uxa = window._uxa || []; if (typeof CS_CONF === "undefined") { window._uxa.push([ "setPath", window.location.pathname + window.location.hash.replace("#", "?__") ]); var mt = document.createElement("script"); mt.type = "text/javascript"; mt.async = true; mt.src = "//t.contentsquare.net/uxa/769238b6e1309.js"; document.getElementsByTagName("head")[0].appendChild(mt); } else { window._uxa.push([ "trackPageview", window.location.pathname + window.location.hash.replace("#", "?__") ]); } }); </script> <script type="text/javascript"> // Contentsquare Send Artificial Pageviews document.getElementById("AddToCart").addEventListener('click', function() { window._uxa = window._uxa || []; window._uxa.push(["trackPageview", "Added_to_cart_" + {{ custom_tag.value}}]) }); </script> ``` 5. To modify the entire path that is sent, use the `setPath` command: ```html <script type="text/javascript"> // Contentsquare Send Artificial Pageviews document.getElementById("AddToCart").addEventListener('click', function() { window._uxa = window._uxa || []; window._uxa.push(["setPath", "Added_to_cart_" + {{ custom_tag.value }}]); window._uxa.push(["trackPageview"]); }); </script> ``` Note You don't need to supply a second parameter in the `trackPageview` command when it is set in the `setPath` command above it. For more information, see the [`setPath` command](https://docs.contentsquare.com/en/web/sending-pageviews/#modifying-the-path). 6. To modify only the query string, use the `setQuery` command: ```html <script type="text/javascript"> // Contentsquare Send Artificial Pageviews document.getElementById("AddToCart").addEventListener('click', function() { window._uxa = window._uxa || []; window._uxa.push(["setQuery", "Added_to_cart_" + {{ custom_tag.value }}]); window._uxa.push(["trackPageview"]); }); </script> ``` Note You don't need to supply a second parameter in the `trackPageview` command when it is set in the `setQuery` command above it. For more information, read about the [`setQuery` command](https://docs.contentsquare.com/en/web/sending-pageviews/#modifying-the-query-parameters). ## Custom HTML To send a pageview, use the `trackPageview` command: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(['trackPageview', <PATH_TO_SEND>]); </script> ``` `<PATH_TO_SEND>` is limited to 255 characters. Just the path The Tag prepends the domain and appends the query parameters. Do not include the domain or the `#` character since everything which comes after is erased. ### Stable URLs For instance, in case you wanted to keep track of the modal window appearing when adding an item to the cart: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push([ "setQuery", window.location.search + (window.location.search ? "&" : "?") + "cs-popin-dedicated_query_string", { lifespan: 'onNextPageviewOnly' } ]); window._uxa.push([ "trackPageview", window.location.pathname + window.location.hash.replace("#", "?__"), { lifespan: 'onNextPageviewOnly' } ]); </script> ``` ### Dynamic URLs #### With custom variables ```html <script> (function () { window._uxa = window._uxa || []; try { if (typeof dataLayer !== "undefined") { for (var i = 0; i < dataLayer.length; i++) { window._uxa.push([ "setCustomVariable", 1, "Sample Variable", dataLayer[i].sampleVariable, 3 ]); } } } catch (e) {} if (typeof CS_CONF === "undefined") { window._uxa.push([ "setPath", window.location.pathname + window.location.hash.replace("#", "?__") ]); var mt = document.createElement("script"); mt.type = "text/javascript"; mt.async = true; mt.src = "//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js"; document.getElementsByTagName("head")[0].appendChild(mt); } else { window._uxa.push([ "trackPageview", window.location.pathname + window.location.hash.replace("#", "?__") ]); } })(); </script> ``` #### Without custom variables ```html <script> (function () { window._uxa = window._uxa || []; if (typeof CS_CONF === "undefined") { window._uxa.push([ "setPath", window.location.pathname + window.location.hash.replace("#", "?__") ]); var mt = document.createElement("script"); mt.type = "text/javascript"; mt.async = true; mt.src = "//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js"; document.getElementsByTagName("head")[0].appendChild(mt); } else { window._uxa.push([ "trackPageview", window.location.pathname + window.location.hash.replace("#", "?__") ]); } })(); </script> ``` ### Tracking a modal opening To track a modal (or "popin") opening/closing during the user's navigation, use **artificial pageviews**. 1. A first artificial pageview needs to be sent when the modal is opened — the sent URL will be the current one, followed by a string of characters allowing you to identify the modal. ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push([ "setQuery", window.location.search + (window.location.search ? "&" : "?") + "cs-popin-dedicated_query_string", { lifespan: 'onNextPageviewOnly' } ]); window._uxa.push([ "trackPageview", window.location.pathname + window.location.hash.replace("#", "?__"), { lifespan: 'onNextPageviewOnly' } ]); </script> ``` 2. A second artificial pageview needs to be sent when the modal is closed. The sent URL will be the current one. ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push([ "trackPageview", window.location.pathname + window.location.hash.replace("#", "?__") ]); </script> ``` ### Single Page Application The Contentsquare Tracking tag sends only one pageview per full reload. In a Single Page Application (SPA), that would be only once per session. To handle this, **an [artificial pageview](https://docs.contentsquare.com/en/web/artificial-pageviews/#custom-html) on every page change** is needed — use the "History Change" event which is available in most Tag Management Systems. You can fire the following script on every page and on history change. It fires the main tag the first time and then sends an artificial pageview for each next call. ```html <script type="text/javascript"> window._uxa = window._uxa || []; /* First call */ if (typeof CS_CONF === "undefined") { window._uxa.push([ "setPath", window.location.pathname + window.location.hash.replace("#", "?__") ]); var mt = document.createElement("script"); mt.type = "text/javascript"; mt.async = true; mt.src = "//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js"; document.getElementsByTagName("head")[0].appendChild(mt); } else { /* Every next call */ window._uxa.push([ "trackPageview", window.location.pathname + window.location.hash.replace("#", "?__") ]); } </script> ``` ### Following a single page check-out If your checkout only fires one full reload, the main tag will be called just once, and only one natural pageview will be sent. We thus only collect: * `shop.com/checkout/` Instead of: * `shop.com/checkout/step1` * `shop.com/checkout/step2` * `shop.com/checkout/step3` * `shop.com/checkout/step4` To achieve this result, it is necessary to: 1. Change the natural pageview URL (the first that was sent) 2. Send an artificial pageview for every step Here is the corresponding code, which uses the [`setPath` function](https://docs.contentsquare.com/en/web/sending-pageviews/#modifying-the-path) and [artificial pageviews](https://docs.contentsquare.com/en/web/artificial-pageviews/#custom-html): ```javascript /* 1. Change the natural URL pageview, before loading the main tag */ window._uxa = window._uxa || []; window._uxa.push(["setPath", "checkout/step1"]); (function () { var mt = document.createElement("script"); mt.type = "text/javascript"; mt.async = true; mt.src = "//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js"; document.getElementsByTagName("head")[0].appendChild(mt); })(); /* ... Step Change Event ... */ /* 2. Send an artificial page for every step change*/ window._uxa = window._uxa || []; window._uxa.push(["trackPageview", "checkout/step" + n]); /* Repeat step 2 as much as required */ ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Artificial Pageviews","description":"Artificial pageviews are to be used when the site uses AJAX, SPA, PWA, or re-routes users without refreshing the page","url":"https://docs.contentsquare.com/en/web/artificial-pageviews/","inLanguage":"en","dateModified":"2026-06-25T11:10:14+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - Web description: The Contentsquare Tracking Tag changelog lastUpdated: 06 August 2026 source_url: html: https://docs.contentsquare.com/en/web/changelog/ md: https://docs.contentsquare.com/en/web/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. 📬 Stay updated! Which version of the Tag is deployed on my website? Check your Tag version with the Contentsquare Tracking Setup Assistant Chrome extension:  ## 15.240.2 - August 6th, 2026 **Features** * **Voice of Customer:** Emit survey lifecycle events as Custom Events to SingleStore. * **Core:** Update web-vitals to 6.0.1. * **Core:** Add platform specific requirement and visibility. * **Core:** Add WeakRef availability to the available-features metric. **Bug Fixes** * **Session Replay:** Use `recording-player` debug flag. * **Session Replay:** Derive collision-free document/window capture names. * **Session Replay:** Track reinserted stylesheets. * **Session Replay:** Minify the async wrapper and capture global variables as parameters. * **Session Replay:** Freeze scroll/view-timeline animations at captured progress. * **Core:** Remove implicit analytics/collection start-order race. * **Core:** Avoid duplicated transactions by subscribing to `webRecorder` exactly once. * **Core:** Send v (version) parameter on dvar requests. * **Core:** Stop checking prebuilt binary freshness when building past refs. * **Core:** Access natives through pristine accessors so protection survives cross-realm nodes. - **Product Analytics:** Make the Heap config side-load host region-aware. - **Product Analytics:** Stub Heap commands by own-property check instead of `typeof` lookup. * **Product Analytics:** Run implementation snippets in iframe children. ## 15.237.0 - July 30th, 2026 **Features** * **Experience Analytics:** Apply new page masking settings. * **Experience Analytics:** Load PTC in-process when `ClickTaleGlobal.loadPTC` is available. * **Experience Analytics:** Align Shopify tag collect state. * **WebView:** Add URL and domain blocklist setting. **Bug Fixes** * **Experience Analytics:** Reintroduce the salt within `Encryption.digest` method parameter. * **Experience Analytics:** Drop invalid targeting rule regex instead of aborting boot. * **Core:** Route observers through task scheduler. * **Core:** Log CSP-blocked verification requests as warnings. * **Session Replay:** Anonymize JWT/auth tokens in hash change event URL. * **Session Replay:** Fix radio group state updates. * **Session Replay:** Do not send userCertainlyLeft for navigation event. * **Session Replay:** Use `DocumentMutationObserver` to detect late `setAttribute` on scroll container. * **Product Analytics:** Apply event enrichers against hierarchy string and allow wildcards in selectors. * **Product Analytics:** Remove selector validation in event enrichers. * **Product Analytics:** Fix `heap.getIdentity()`. ## 15.235.3 - July 23rd, 2026 **Features** * **Core:** Apply new page masking settings. Default digit anonymization now masks all credit-card-like numbers, phone-number-like strings, and all numbers greater than 9. **Bug Fixes** * **Core:** Fix radio group state updates. * **Core:** Anonymize JWT/auth tokens in HASH\_CHANGE event URL. * **Core:** Reintroduce the salt within as Encryption.digest method parameter. * **Core:** Route observers through task scheduler in production build. * **Core:** Drop invalid targeting-rule regex instead of aborting boot. ## 15.234.2 - July 9th, 2026 **Features** * **Voice of Customer:** Pass product analytics IDs to bridge for UCH-routed VoC responses. * **Core:** Add project configuration for max logs. **Bug Fixes** * **Core:** Apply current timestamp on cached performance timing events. * **Core:** Fix logger type issue. * **Core:** Guard `scheduler.yield()` for worker environments. ## 15.230.40 - July 3rd, 2026 **Bug Fixes** * **Core:** Add protection for `Element.attributes` getter. * **Experience Analytics:** Avoid reading side-effecting validity getter on custom elements. ## 15.230.29 - June 25th, 2026 **Features** * **Core:** Support `attachInternals()` validity for form-associated custom elements. **Bug Fixes** * **Core:** Restore `anonymized-on-start` page anonymization metric. * **Core:** Fix cross-domain shared context hydration in `cs_crosswrites_heap` mode. ## 15.230.22 - June 18th, 2026 **Features** * **Core:** Support VoC new API when site ID is missing. **Bug Fixes** * **Core:** Prevent crash in pure component rendering. * **Core:** Use `localStorage` instead of `sessionStorage` for URL redirection. * **Core:** Guard `Object.defineProperty` with configurability check on `window._uxa`. * **Core:** Register session-expired callback before analytics pipeline can trigger renewal. * **Core:** Fix crosswrite missing shared context. * **Product Analytics:** Scope HeapLegacyCommands back to crosswrite only. * **Product Analytics:** Install stubs before running queued commands. ## 15.229.4 - June 4th, 2026 **Bug Fixes** * **Core:** Fix crosswrite query parameter. * **Experience Analytics:** Remove dependency from reverse path computation. ## 15.228.3 - May 28th, 2026 **Bug Fixes** * **Core:** Hydrate initial collect state from session on all cases. * **Core:** Handle invalid characters on match id parsing. * **Core:** Prevent cache drift in session refresh on multi-tab sessions. * **Session Replay:** Improve recorder processor scheduling. * **Product Analytics:** Store pageview URL before sending PA page view. ## 15.225.5 - May 14th, 2026 **Bug Fixes** * **Experience Analytics:** Replace `watchedElements` Set with WeakSet in `TextVisibilityProducer`. ## 15.225.1 - May 7th, 2026 **Features** * **Core:** Read session referrer from session context cookie. **Bug Fixes** * **Experience Analytics:** Align device audience targeting with numeric FOV values. * **Experience Analytics:** Correctly resolve `visit:isNew` audience field. ## 15.224.0 - April 30th, 2026 **Bug Fixes** * **Core:** Add user consent logic on Shopify tag to match page-level anonymization behavior. * **WebView:** Fix before page view trigger in webview. * **Product Analytics:** Fix pageview duplication in `extendSession`. * **Experience Analytics:** Send document height from `data-cs-scroll-container` in pageview. ## 15.214.2 - April 16th, 2026 **Features** * **Session Replay:** Manage consent for replay in all mode. **Bug Fixes** * **Core:** Avoid node type casting. ## 15.211.0 - April 8th, 2026 **Features** * **Session Replay:** Add support for Web Animations. * **Session Replay:** Avoid code and parser mismatch for CSS selectors. * **Session Replay:** Implement worker stringify mode. * **Session Replay:** Introduce patch and initial state compression. * **Session Replay:** Serialize VisualViewport zoom properties. * **Experience Analytics:** Support `data-cs-scroll-container` inside Shadow DOM. * **Experience Analytics:** Add Shopify DOM converter. * **Core:** Handle empty catch blocks. * **Metrics:** Add metric on transactions. **Bug Fixes** * **Session Replay:** Replace threshold flushing with periodic interval for Shopify. * **Session Replay:** Fix false shadow-root insertion for anchor elements with `href`. * **Session Replay:** Key animations cache by Document to handle cross-document elements. * **Session Replay:** Deduplicate added fragments with existing serialization ID. * **Session Replay:** Exclude non-primitive value types from element state serialization. * **Session Replay:** Narrow value type check to string only. * **Session Replay:** Guard against null `event.target` in DOM observer. * **Session Replay:** Fix initial DOM screenshot on Shopify checkout. * **Session Replay:** Send analytics batch periodically for Shopify. * **Session Replay:** Prevent stack overflow for large DOM trees. * **Session Replay:** Prevent re-virtualization of already visited shadow roots. * **Session Replay:** Introduce masked parent elements count. * **Core:** Disable collection when `collectionEnabled` is not defined in tag configuration. * **Core:** Avoid unhandled errors. * **Core:** Collect `problem+json` body responses. * **Core:** Deduplicate similar errors in worker logger. * **Core:** Update cross-domain iframe code. * **Core:** Include more details in `MisusedCommandError`. * **Core:** Make `@Throttle` decorator instance-scoped to prevent cross-instance interference. * **Core:** Validate API error schemes against HTTP protocols. * **Experience Analytics:** Improve `nextPageOnly` scope management. * **Static Resource Manager:** Strip non-compliant parameters from MIME types. * **Analytics:** Guard analytics stop when service was never started. * **Core:** Rename verification parameters from `hjVerify` to `csqVerify`. * **Voice of Customer:** Decouple Hotjar commands from VoC feature flag. * **Voice of Customer:** Enable Hotjar integration events outside VoC scope. ## 15.196.0 - March 12th, 2026 **Features** * **Experience Analytics:** Listen to commands and update page context. * **Session Replay:** Use Session Replay Masking on SVG image's `href`. * **Metrics:** Add metrics service to Shopify tag. ## 15.193.7 - March 5th, 2026 **Features** * **Core:** Enable support for inlined sourcemaps **Bug Fixes** * **Core:** Enable tree-shaking of FastDOM class when FASTDOM feature flag is disabled. * **Product Analytics:** Write and read Product Analytics cookies from the xdframe single domain. * **Identity:** Guard calls to `window.crypto` with hashing supported check. ## 15.188.4 - February 26th, 2026 **Features** * **Experience Analytics:** Add command to start in autonomous iframe. **Bug Fixes** * **Experience Analytics:** Increment pageview count correctly when session already exists in Shopify checkout. * **Metrics:** Report Tracking Tag startup errors. * **Product Analytics:** Write and read Product Analytics cookies from and to the xdframe-single-domain. ## 15.186.3 - February 20th, 2026 **Features** * **Experience Analytics:** Redact OAuth tokens in URL. * **Product Analytics:** Add experimental flag to use collectTargetText for disableTextCapture in `cs_sideloads_heap`. **Bug Fixes** * **Experience Analytics:** Do not throw on Salesforce check. * **Metrics:** Safer page load timing collection. ## 15.181.0 - February 12th, 2026 **Features** * **Experience Analytics:** Add check for Salesforce framework. * **Experience Analytics:** Capture ClickTale command calls. * **Experience Analytics:** Support collect state and targeting rules for Shopify. * **Metrics:** Improve INP contribution tracking. * **Metrics:** Track form-associated custom element feature usage. **Bug Fixes** * **Tag Configurator:** Change use closest to be false by default in 'Element Becomes Visible' trigger. * **Errors:** Handle Error object in `sendLog`. * **Session Replay:** Convert non-string attributes values to string. ## 15.176.1 - February 5th, 2026 **Features** * **Metrics:** Normalize outlier parameter names. * **Metrics:** Track metrics for dual collection status. * **Metrics:** Track metrics for network requests other than metric network requests. ## 15.174.2 - January 29th, 2026 **Features** * **Tag Configurator:** Remove unused CSTC submit command template. * **Experience Analytics:** Add missing commands in iframe mode. * **WebView:** Add check on file-served webviews. ## 15.169.0 - January 22nd, 2026 **Features** * **Product Analytics:** Change pageview request to POST and attach custom properties. * **Product Analytics:** Support Heap identity and user properties APIs for crosswriting. * **Experience Analytics:** Send Shopify customer ID as Dynamic Variable for GDPR compliance. **Bug Fixes** * **Experience Analytics:** Don't activate ElementBecomesVisibleTrigger on added child. * **Static Resource Manager:** Use the correct global context instead of hard coded `self`. ## 15.167.3 - January 13th, 2026 **Features** * **Experience Analytics:** Collect quirks mode for DOM analysis. * **Session Replay:** Capture LocalStorage errors with warning. * **Session Replay:** Add state cleanup processor. * **Product Analytics:** Support client-side Shopify source. * **Session Replay:** Implement shared context compression. **Bug Fixes** * **Core:** Fix XHR async configuration for Safari. * **Session Replay:** Ignore attributes with non-string values in masking processor. * **Product Analytics:** Prevent event ingestion after ShopifyProducer stops. * **Product Analytics:** Add missing `v` parameter on transaction call. * **Core:** Add default timeout for XHR POST requests. * **Product Analytics:** Fix cookie domain calculation to use root domain instead of subdomain. ## 15.163.0 - December 18th, 2025 **Features** * **Experience Analytics:** Enable shared context cookie by default. * **Product Analytics:** Update download-time and transfer-size metrics. * **Experience Analytics:** Improve error reporting. * **Session Replay:** Track custom input properties. * **Dual Collection:** Add support for state change API. * **Product Analytics:** Remove `submit_command` event. **Bug Fixes** * **Experience Analytics:** Move current URL to local storage in shared context. * **Experience Analytics:** Capture `previousUrl` in shared context collection only if hostname matches current hostname. * **WebView:** Disable local assets masking in `serializeWebview` command. ## 15.158.2 - December 11th, 2025 **Features** * **WebView:** Support custom properties. **Bug Fixes** * **Errors:** Do not send errors when the user session has expired. ## 15.154.4 - November 20th, 2025 **Features** * **WebView:** Add custom analysis event enhancer (Product Analytics Screenshots). * **Product Analytics:** Add custom pageview and event properties to analysis events. **Bug Fixes** * **Experience Analytics (Free and Growth)**: Fix a data collection issue when targeting rules are enabled. * **Session Replay:** Fix an issue with workers when Session Replay feature is enabled. * **Session Replay:** Fix an issue where CSS content is scanned for personal data. ## 15.150.0 - November 13th, 2025 **Bug Fixes** * **Analytics:** Fix an issue with `setPath` and `setQuery` override duration. **Features** * **Session Replay:** Remove worker for sending data to Contentsquare servers. * **Experience Analytics:** Collect loading performance metrics. * **Product Analytics:** Improve handling of Product Analytics commands misuses. * **Product Analytics:** Add custom analysis event enhancer (Product Analytics Screenshots). * **Session Replays:** Improve how session replays events are produced. * **Analytics:** Implement Manual Start Mode and Start and Stop data collection commands. ## 15.140.1 - October 23th, 2025 **Features** * **WebView:** Support for custom **Experience Analytics** events. **Bug Fixes** * **Voice of Customer:** Improved interoperability when running the Contentsquare Tag along with the legacy VoC Tag. * **Experience Analytics:** The [`_cs_s_ctx`](https://docs.contentsquare.com/en/web/cookies/#_cs_s_ctx) cookie is now properly removed when the [`optout`](https://docs.contentsquare.com/en/web/command-reference/#optout) command is used. * **WebView:** No more event types conflicting with the mobile events. ## 15.138.1 - October 16th, 2025 **Features** * **Session Replay:** Support new format for URL targeting rules. ## 15.137.4 - October 9th, 2025 **Bug Fixes** * **Experience Analytics:** Implement allow/block list for query parameters capture. **Features** * **Tag Configurator:** Add `setReferrer` command for tag configuration. * **Experience Analytics:** Compute `sr` and `mdh` parameters for analytics. ## 15.136.1 - October 2nd, 2025 **Features** * **API Errors:** Do not capture errors from `heap-api.com` and `heapanalytics.com`. **Bug Fixes** • **Experience Analytics:** Do not renew session on hidden page. • **Session Replay:** Late collected events are now associated with the correct page view. ## 15.134.1 - September 25th, 2025 **Features** * **Experience Analytics:** When crosswriting is enabled, use memory instead of cookie to store previousViewUrl. * **Experience Analytics:** When crosswriting is enabled, query parameters are not saved in cookie context to reduce cookie size. **Bug Fixes** * **Collect:** Restore filtering of programmatic user event. * **iframe:** Fix iframe tracking feature code removal when not enabled (tree-shaking). ## 15.133.3 - September 11th, 2025 **Bug Fixes** * **Session Replay:** Fix missing HTML mutations in rare cases due to an optimization. ## 15.133.3 - September 4th, 2025 **Features** * **Experience Analytics:** Implement crosswriting of custom events. * **Tag bundles**: WebWorker code use ES6 as minimum deployment target. **Bug Fixes** * **Analytics:** Truncate URLs of session context cookie (`_cs_s_ctx`) to 800 characters. ## 15.126.1 - August 28th, 2025 **Features** * **Experience Analytics:** Refine checks for enabling new usage based quota. **Bug Fixes** * **Session Replay:** Ignore nested data URLs inside CSS rules. ## 15.125.0 - August 21st, 2025 **Features** * **Experience Analytics:** Enhance verify installation feature. * **Analytics:** Add murmur3 hashed target for heatmap. * **Voice of Customer:** Add metric to track legacy features. **Bug Fixes** * **Voice of Customer:** Ensure exclusivity between the unified and legacy VoC modules. * **Onboarding:** Enable verify installation feature in multiple scenarios. ## 15.121.0 - August 14th, 2025 **Features** * **WebView:** Add support for hierarchy identify and addUserProperties. * **Experience Analytics:** Add shared context in analytics requests. * **Experience Analytics:** Create verify installation CSQ-Lite Free/Growth. * **Voice of Customer:** Enable VoC module in no tracking mode. * **Voice of Customer:** Enable required global objects in the unified VoC module. ## 15.115.0 - August 5th, 2025 **Features** * **Analysis**: Update [web-vitals ↗](https://github.com/GoogleChrome/web-vitals/blob/main/CHANGELOG.md) library to 5.0.1. ## 15.114.0 - July 31st, 2025 **Features** * **Visual Labeler:** Add EU pipeline support. * **Experience Analytics:** Decommission legacy quota service. **Bug Fixes** * **Logging:** Improve logs context collection. ## 15.111.0 - July 24th, 2025 **Features** * **Identify**: Add EU pipeline support. ## 15.109.0 - July 17th, 2025 **Features** * **Session Replay**: Support disabled stylesheet property changes. **Bug Fixes** * **Session Replay**: Handle timing edge cases for `InputEvent`. * **Analytics:** Escape cookie value delimiter when stringifying. * **Session Replay**: When collection is paused because of user inactivity, still allow API and JS errors to be sent. ## 15.107.2 - July 10th, 2025 **Features** * **Session Replay**: Add flag to mask media elements when page is matching text replacement rules. * **Session Replay**: Support disabled stylesheet property changes. **Bug Fixes** * **Commands**: Ensure queued commands run only after external component starts. ## 15.105.5 - July 3rd, 2025 **Bug Fixes** * **Session Replay**: Ensure added nodes reference the proper parent context to avoid being auto-masked. * **Session Replay**: Clear page events callbacks when tracking stops to avoid duplicate events. ## 15.105.1 - June 26th, 2025 **Bug Fixes** * **WebView, Session Replay:** Fix CSS Link URL serialization. ## 15.105.0 - June 19th, 2025 **Features** * **Analytics:** Implement Product Analytics visual labeler for crosswriting customers. **Bug Fixes** * **Tag Configurator:** Fix `elementBecomesVisible` trigger schema. * **Session Replay:** Add support for Google Fonts stylesheets that don't use the `.css` extension. ## 15.104.2 - June 12th, 2025 **Features** * **Metrics:** Add new metrics for name and phone auto-masking. * **Analytics:** Implement option to collect `TargetText` on every click/tap/submit event. * **Session Replay:** Implement CSS styling rule change observer. * **Product Analytics:** Integrate product analytics view id in pageviews. **Bug Fixes** * **Session Replay:** Improve the debouncing and throttling mechanisms. * **Voice of Customer:** Ensure VoC URLs are synchronized with pageview URLs. * **Voice of Customer:** Remove ETR for surveys. * **Experience Monitoring:** Better handling for `TimeoutError` in Experience Monitoring. * **WebView:** Update masking state after artificial pageviews. * **Logger:** Ensure the logger preserves the caller's `this` context. ## 15.99.2 - May 28th, 2025 **Features** * **Experience Monitoring:** Mask name in API and custom error URLs. **Bug Fixes** * **Experience Monitoring:** Do not raise an error on signal timeout. * **Voice of Customers:** Synchronize URL with artificial pageview. * **Integration:** `onRecordingContextChange` command returns cleanup function. ## 15.94.1 - May 22th, 2025 **Features** * **Session Replay:** Reduce initial text visibility throttling for faster detection of visible text. * **Session Replay:** Introduce an experimental field to opt out of using the protected (unpatched) `MutationObserver` retrieved via iframe. ## 15.92.1 - May 15th, 2025 **Features** * **Metrics:** Normalize tracking of command misuse. * **Metrics:** Track CSP web worker security errors. * **Session Replay:** Mask elements with `contenteditable` attribute. * **Experience Monitoring:** Mask more name variants in custom errors. **Bug Fixes** * **Voice of Customer:** Fix incorrect URL passed to the VoC widget. ## 15.85.1 - April 30th, 2025 **Features** * **Metrics:** Wrap all tag command usage and track misuse. * **Tag Configurator:** Add help center links for each CSTC templates. * **Tag Configurator:** Add best practice section for 'Network requests - Mask URLs' template. **Bug Fixes** * **WebView:** Add protection against bad override of FileReader browser API. ## 15.84.1 - April 15th, 2025 **Bug Fixes** * **Experience Analytics:** Solve the conflict with third-party `ping` events. * **Session Replay:** Support blank iframes. * **Metrics:** Change name of Tag Configurator metrics. * **Voice of Customer:** Send survey responses as internal events. * **Voice of Customer:** Set [survey cookie](https://docs.contentsquare.com/en/web/cookies/#_hjdonepolls) duration to 365 days. * **Voice of Customer:** Use milliseconds for survey cookie duration. ## 15.82.2 - April 8th, 2025 **Bug Fixes** * **Session Replay:** Support DST dates in replay targeting rules for Free and Growth plans. * **Metrics:** Avoid starting metrics in webview contexts due to missing APIs. **Features** * **Metrics:** Track usage of Tag Configurator triggers and templates. ## 15.81.3 - April 1st, 2025 **Bug fixes** * **Product Analytics:** Do not send the domain in `heap.setPath`. * **Experience Analytics:** Handle quota response when session expires. * **Voice of Customer:** Don't include VoC code in the tag if the VoC flag is disabled. **Features** * **Voice of Customer:** Introduce VoC only tracking. * **Metrics:** Implement command, encryption, and masking metrics. * **Metrics:** Toggle metrics collection system on. ## 15.76.0 - March 20th, 2025 **Bug fixes** * **Tag Configurator:** Fix `BeforePageview` trigger. **Features** * **Product Analytics:** Send Product Analytics context in pageviews. * **Product Analytics:** Hierarchy collection for click, change, and submit events. * **Metrics:** Introduce a metrics collection system. ## 15.72.6 - March 13th, 2025 **Bug fixes** * **Webviews:** SerializeWebview `withAssets` not depending on staticResourceUrlTracker anymore. * **Session Replay:** Update serializer to ignore children already serialized and include mutation of `movedNode` into new one. * **Session Replay:** Change a query parameter for targeting rules collection mode. * **Product Analytics:** Use masked URL instead of path in `heap.setPath`. * **Product Analytics:** Create new command `sendHeapContext` for `heap.js` v5. * **Voice of Customer:** Initialize VoC on artificial page views. * **Experience Analytics:** Improve typing for Dynamic and Custom Variables modules. **Features** * **Product Analytics:** Start data collection for `heap.js` v4. * **Tag Configurator:** Cleanup obsolete template/triggers properties. ## 15.70.8 - February 26th, 2025 **Bug fixes** * **Experience Analytics:** Add a validity check on descriptor parameter of FilterUntrustedEvent. * **Tag Configurator:** Change template BlockAllowListForSR name. * **Session Replay:** Add source to masked Personal Data logs. * **Session Replay:** Avoid monkey patching the same API multiple times. * **Session Replay:** Partial matching patterns support placeholder matching empty URL token (bis). * **Static Resource Manager:** Update online assets collection on pageview. * **Session Replay:** Handle added text nodes. **Features** * **Tag Configurator:** Cleanup obsolete template/triggers properties. * **Webviews:** Send Tag configuration to parent. * **Product Analytics:** Implement `identify` and `addUserProperties` commands from `heap.js`. * **Session Replay:** Check if URL arguments are empty. ## 15.67.2 - February 20th, 2025 **Bug fixes** * **Session Replay:** Disabling session capture in CSQ Free and Growth plans does not stop data collection for Session Replay. ## 15.66.2 - February 13th, 2025 **Bug fixes** * **Emerchandising:** Flush element source upon stop. * **Experience Analytics:** Do not stop tag performance tracker on artificial pageviews. * **Session Replay:** Fix mutation optimizer issue when removing nodes. **Features** * **Experience Analytics:** Pass disableTextCapture to trackPageview on artificial pageviews. * **Product Analytics:** Collect pageview from History changes and listen submit event. ## 15.65.0 - February 10th, 2025 **Bug fixes** * **API Errors:** Check the attribute value is not null or undefined. * **Session Replay:** Avoid collision with user defined selectors. * **Session Replay:** Check fetch request response on being undefined. * **Session Replay:** Move initialization of shadow root filter. **Features** * **Experience Analytics:** Do not start the tag when page is being pre-rendering (Chrome speculation API). * **Tag Configurator:** Support closest matching element in click trigger. * **Tag Configurator:** Support new condition operators. * **Tag Configurator:** Support tap in all snippets implementing the click trigger. * **Product Analytics:** Implement new command to send cross-product context. * **Session Replay:** Optimize number of mutation observers needed to track text visibility changes. ## 15.56.1 - January 30th, 2025 **Bug fixes** * **Session Replay:** Fix an issue on legacy masked rules from window after `startdatacollection` command. * **Session Replay:** Fix send initial input values on activity resume after the new initial DOM. * **Session Replay:** Fix on Static Resources Manager ensures online assets collection flag in iframes and nested iframes is correctly handled. * **Session Replay:** Fix ensures input events are sent after mutation on the element. * **Tag Configurator:** Fix filter untrusted events (events not triggered by visitor). **Features** * **Session Replay:** Manage added nodes to encrypted element. * **Session Replay:** Unify all Personal Data config modes. * **Tag Configurator:** New trigger on element becomes visible. ## 15.49.1 - January 9th, 2025 **Minor fixes** * **Session Replay:** Handle errors related to closed readable streams in the NetworkWorker. * **Session Replay:** Handle errors when `document.body` is not accessible in a cross-domain iframe. **Bug fixes** * **Session Replay:** Prevent data collection when the `optout` command is pushed before the Tag is injected or starts. * **Analytics:** Handle null values passed to the `trackError` command gracefully. **Features** * **Tag Configurator:** Restart implementation snippets on artificial page views and session renewal. * **Tag Configurator:** New implementation template for excluding and allowing URLs in Session Replay. * **Tag Configurator:** New implementation log level for logging warnings about broken implementations. * **Session Replay:** Add logs to track usage of Google's speculative rules API. * **Session Replay:** Unify the default element masking rules across all deployment modes. * **Session Replay:** Add validators and log warnings for the `setCapturedElementsSelector` command. ## 15.43.0 - December 18th, 2024 **Bug fixes** * **Session Replay:** Fix an issue which could cause text visibility events to be lost in some cases. * **Session Replay:** Fix an issue occurring when the zoom tracker was stopped before being started. * **Session Replay:** Fix the mutation serialization optimiser that was producing incorrect outputs in some edge cases. * **Session Replay:** Stop serializing script children. * **Session Replay:** Improve text visibility detection for inline elements. * **Integration:** Improve replay link format. * **Experience Monitoring:** Fix an issue where the `responseBody` was not collected in some cases. * **Experience Monitoring:** Fix an issue that caused an error to be thrown when getting the file name for JavaScript errors collection. **Features** * **Session Replay:** Update the validation of the format of the visitor cookie. * **Session Replay:** Mask by default text area content from appended text nodes in iframe context. ## 15.39.6 - December 12th, 2024 **Bug fixes** * **Session Replay:** Fixed the issue with Tag Download time parameter. * **Session Replay:** Restart VoC widgets on artificial page views. * **Session Replay:** Fixed video events race condition. * **Session Replay:** Mask emails only in `href` and `src` attributes. * **Session Replay (webview):** Set sensitive status at start. * **Experience Monitoring:** Catch abort when reading the response body. **Features** * **Session Replay:** Mask `href` and `src` attributes in specific nodes. * **Session Replay:** Optionally mask non-text elements using masking settings. * **Session Replay:** Remove phones from custom errors. ## 15.36.2 - November 20th, 2024 **Bug fixes** * **Session Replay:** Improve support of images by accepting alternate source elements. * **Session Replay:** Fix regression after a performance optimization linked to mutation processing. * **Experience Monitoring:** Limit JavaScript file names to 150 characters max. * **Experience Monitoring:** Replace script data URL by pageview URL. * **Experience Analytics:** Fix JS error thrown by `getCurrentOrientation` function during resize events. **Features** * **Personal Data:** Mask first and last names in error collection. ## 15.33.7 - November 13th, 2024 **Bug fixes** * **Session Replay:** Improve support of `data-cs-mask` with shadow DOM of masked elements. * **Session Replay:** Improve support of CSS inline rules during initial DOM serialization. * **Session Replay:** Avoid masking digits of node attributes when masking feature is enabled. * **Session Replay:** Preserve inputs radio name attribute when masking feature is enabled. * **Session Replay:** Fix `nextSibling` calculation to return `null` under certain conditions. * **Session Replay:** Mask `document.baseURI` attribute on initial DOM. **Performance Improvements** * **Tag Configurator:** Improve performance of element visibility trigger. **Features** * **Experience Analytics (Free and Growth)**: Integrate Targeting rules into data collection flow. * **Session Replay:** Capture nested elements added through DOM mutations with `data-cs-capture` and `setCapturedElementsSelector`. ## 15.28.0 - October 30th, 2024 **Bug fixes** * **Text Visibility:** Do not collect `<textarea>` text value. **Performance Improvements** * **Session Replay:** Increase batch size limit. **Features** * **Integrations:** Simplify Dynamic Variable format for CSQ Lite integrations. ## 15.26.2 - October 23th, 2024 **Bug fixes** * **Session Replay:** Do not mask CSS `href` values for CSQ Lite customers. * **Session Replay:** Handle bad `setPIISelectors` input. **Performance Improvements** * **Session Replay:** Throttle attribute/characterData mutations by 30ms. * **Session Replay:** Improve performance of SelectorObserver by retrieving shadow roots from DocumentMutationObserver. **Features** * **Experience Monitoring:** Implement partial URL masking patterns. * **Session Replay:** Collect play pause video events refactor. * **Session Replay:** Add ETR status. ## 15.23.3 - October 16th, 2024 **Bug fixes** * **Session Replay:** Fixed infinite loop on Safari. * **Session Replay:** Pipe text visibility events through masked text processor. **Performance Improvements** * **Session Replay:** Improve performance when too many ShadowRoots get disconnected at the same time. **Features** * **Experience Analytics:** Implement quota boot blocking. * **Ecommerce:** Handle `Transaction` and `addToCart` pushed before start. * **Project Configuration:** Introduce `clickedElementTextEnabled` feature. ## 15.21.0 - October 10th, 2024 **Bug fixes** * **Session Replay:** Protect `RegExp` from overwrites on sites. * **Session Replay:** Fix calculated `nextSibling` on node mutations within the same tick. **Features** * **Experience Analytics:** Collect link and button text on click and tap events. * **Experience Analytics (Free and Growth):** Mask emails on any node by default. * **Experience Analytics:** Log warnings when too many attribute/text mutations occur within a short threshold. ## 15.19.3 - October 2nd, 2024 **Bug fixes** * **Session Replay:** Clean encryption logs and dead code. * **Voice of Customer:** Send poll answer value as integer. * **Experience Analytics:** Check if `self` is overridden. * **Voice of Customer:** Deduplicate VoC dynamic variables. * **Session Replay:** Serialize children from 0 index on added nodes. **Features** * **Experience Analytics:** Support quick replay for Free and Growth plans. * **Personal Data:** Check `href` attribute on certain conditions. * **Experience Analytics:** Support retaker mode for Free and Growth plans. * **API Errors:** Support media type `text/javascript`. ## 15.16.5 - September 26th, 2024 **Bug fixes** * **Session Replay:** Fix calculated `nextSibling` on added node mutation. * **Session Replay:** Add experimental option to not observe shadow roots. * **Emerchandising:** Stop Emerchandising capture right before artificial pageview. * **Session Replay:** Fix the propagation of `data-cs-capture` to children and handle it by default. ## 15.16.0 - September 18th, 2024 **Bug fixes** * **Performance:** Fix performance logs format. * **Session Replay:** Fix an issue causing duplicated nodes in replays. * **Session Replay:** Fix last message requests when `Worker` is not available. * **Session Replay:** Fix performance issue when there are many mutations happening in the same tick. ## 15.13.0 - September 4th, 2024 **Features** * **Session Replay:** Support `CSSGroupingRule`. * **Product Analytics:** Do not load the `heap.js` Tag when it has already been injected in the page. **Performance Improvements** * Add function execution time metrics to our monitoring. ## 15.10.0 - August 28nd, 2024 **Features** * **Product Analytics:** Collect page title in pageviews. ## 15.9.0 - August 22nd, 2024 **Bug fixes** * **Session Replay:** Fix move mutation event. * **Session Replay:** Process new stylesheet rules. * **Session Replay:** Observe mutations on text nodes. * **Product Analytics:** Catch errors when retrieving metadata. **Features** * **Product Analytics:** Support sideloading. * **Experience Analytics:** End session 30 minutes after last user event. ## 15.7.0 - August 14th, 2024 * Tag code refactoring. No client-side impact expected. ## 15.6.4 - August 7th, 2024 **Bug fixes** * **Session Replay:** Add `isValidSelector` check in encrypted nodes identifier. * **Session Replay:** Backport support of Chinese and Japanese ideograms in Flashpoint. * **Session Replay:** Fix performance issue by protecting functions overridden by `ZoneJS`. * **Session Replay:** Use `arrayFlatMap` to avoid exceptions on older browsers. * **Session Replay:** Clear Element observer `tickSet` on disconnect. * **Analytics:** Listen to `navigation` event inside last events tracker. * **Product Analytics:** Rename feature flags. * **Session Replay:** Check if `csQueueMicrotask` is a function. * **Session Replay:** Mask text area value changed by inserted text node. **Features** * **Voice of Customer:** Add a feature flag for the VoC Events API. * **Voice of Customer:** Send events to the `v2/events` endpoint. * **Experience Analytics:** Merge `anonymizeDigits` and `anonymizeEmails` settings into project configuration. * **API Errors:** Increase `body` attribute value limit to 100 characters. * **Experience Analytics:** Call verify installation for Free and Growth plans. ## 15.1.7 - July 25th, 2024 **Bug fixes** * **Static Resource Manager:** Resolve events on error. * **Session Replay:** Fix encryption processor. * **Session Replay:** Improve ElementObserver performance by traversing the tree only once per tick. * **Session Replay:** Catch error thrown by the custom element producer when element name is invalid. * **Session Replay:** Check iframe before accessing `contentWindow`. * **Session Replay:** Avoid access denied error when checking `localStorage` support. * **Session Replay:** Missing object `cssRules` in REGISTER\_ADOPTED\_STYLE\_SHEET payload. * **Session Replay:** Add symbol back to node identifier. * **Session Replay:** Fix duplicated nodes. * **Session Replay:** Fix SVG masking issues. **Features** * **Session Replay**: DOM Events are managed with Flashpoint. * **Analytics**: Introduce identity mechanism. ## 14.22.1 - July 04th, 2024 **Bug fixes** * **Session Replay:** Use U+FF41 char instead of book ideogram for masking. * **Session Replay:** Improve shadow roots detection when added on existing shadow roots. * **Session Replay:** Fixed timestamp issues on events created by Static Resource Manager. **Features** * **API Errors**: Rely on body length instead of `Content-Length` header. ## 14.18.3 - June 12th, 2024 **Features** Voice of Customer and Product Analytics General Availability As of June 2024, customers can use the Voice of Customer and Product Analytics modules. For more information refer to the Help Center. ### Voice of Customer The tag will inject a `hotjar-{SITE_ID}.js` script which loads the survey widgets as needed If you are using [SRI](https://docs.contentsquare.com/en/web/sri/), reach out to your Contentsquare contact for more information. [Additional cookies](https://docs.contentsquare.com/en/web/cookies/#voice-of-customer-cookies), prefixed with `_hj`, are created. To use Voice of Customer, make sure to add `script-src 'unsafe-inline' *.contentsquare.net` to your [CSP configuration](https://docs.contentsquare.com/en/web/content-security-policy/). ### Product Analytics The Tag will inject a `heap_config.js` script loaded from `https://cdn.us.heap-api.com/config/<ENV_ID>/heap_config.js`, which loads the PA tag `heap.js`. If you are using [SRI](https://docs.contentsquare.com/en/web/sri/), reach out to your Contentsquare contact for more information. [Additional cookies](https://docs.contentsquare.com/en/web/cookies/#product-analytics-cookies), prefixed with `_hp*`, are created. If you enforce a Content Security Policy, make sure to add the following to your [CSP configuration](https://docs.contentsquare.com/en/web/content-security-policy/): ```http script-src 'unsafe-inline' 'unsafe-eval' https://cdn.heapanalytics.com https://heapanalytics.com; script-src 'unsafe-inline' *.contentsquare.net; img-src https://heapanalytics.com; style-src https://heapanalytics.com; connect-src https://heapanalytics.com; font-src https://heapanalytics.com; ``` **Bug fixes** * **Session Replay:** Reduce network details payload. ## 14.15.0 - June 5th, 2024 **Bug fixes** * **Session Replay:** Mask Chinese and Japanese characters using an ideogram instead of the character `A` to preserve `line-break` behavior. ## 14.13.0 - May 28th, 2024 **Bug fixes** * **API Errors:** Check if `subscriberId` and `responseType` exist before accessing `responseText`. **Features** * **Session Replay:** Add allowlist mechanism for some event types. * **Personal Data**: Add data-cs-mask for all project's deployment mode type. ## 14.11.0 - May 21st, 2024 **Bug fixes** * **Personal Data**: Fix processing of `data-cs-mask` attributes that were being ignored. ## 14.10.0 - May 6th, 2024 **Bug fixes** * **iFrames**: Do not access storage, cookie, or XHR in child mode. * **Session Replay**: Fix lost initial resize events. * **Session Replay**: Remove query parameters of network details events. * **WebViews**: Align webview behaviors on bridge injection. **Features** * **WebViews**: Process commands received before webview tracking ready and start events. ## 14.9.3 - April 29th, 2024 **Features** * **Logging**: Emit logs for all critical errors ## 14.4.0 - March 26th, 2024 **Bug fixes** * **Static Resource URL**: Fixed Static URL resource bug on quoted URLs **Features** * **Session Replay**: New inactivity mechanism. ## 14.3.1 - March 26th 2024 **Bug fixes** * **Session Replay**: Fix identification of default sensitive attributes. ## 14.1.2 - March 21st, 2024 **Bug fixes** * **Static Resource Manager**: Filter double quotes `nestedResource` URLs fixing 404 errors ## 14.1.1 - March 21st, 2024 **Bug fixes** * Fix how the initial DOM event is inserted in the Session Replay events in both `top` and `iframe` contexts. ## 14.1.0 - March 21st, 2024 **Features** * **API Errors**: Increase `responseBody` size limit from 2kb to 5kb. ## 14.0.0 - March 18th, 2024 **Features** * **Tag Commands**: Add `lifespan` option to the following Tag commands, to handle SPA use cases: * [`setPath`](https://docs.contentsquare.com/en/web/command-reference/#setpath), * [`setQuery`](https://docs.contentsquare.com/en/web/command-reference/#setquery), * [`trackPageview`](https://docs.contentsquare.com/en/web/command-reference/#trackpageview) ## 13.100.1 - March 14th, 2024 **Bug fixes** * **TagDownloadTime Service**: Retrieve [`document.currentScript` ↗](https://developer.mozilla.org/en-US/docs/Web/API/Document/currentScript). ## 13.99.9 - March 12th, 2024 **Bug fixes** * **API Errors**: Remove Content-Length check to track all API calls when using [Transfer-Encoding ↗](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding). ## 13.99.8 - March 12th, 2024 **Bug fixes** * WebView: Handle injected CSS to fix zone-level elements data ## 13.99.7 - March 11th, 2024 **Bug fixes** * Flush pending microtasks on artificial pageviews to fix user actions not shown in Session Replay. ## 13.99.5 - March 6th, 2024 **Bug fixes** * **Static Resource Manager**: * Changed an error to non-blocking so that further data can be sent, * Send a single request when the payload exceeds the limit, instead of two. ## 13.99.4 - March 6th, 2024 **Bug fixes** * **Session Replay**: Restart `PerformanceTimingResourceTracker` on artificial pageviews. ## 13.97.0 - February 26th, 2024 **Bug fixes** * **Tag Commands**: Add `decodeUri` option to the following Tag commands: * [`setPath`](https://docs.contentsquare.com/en/web/command-reference/#setpath), * [`setQuery`](https://docs.contentsquare.com/en/web/command-reference/#setquery), * [`trackPageview`](https://docs.contentsquare.com/en/web/command-reference/#trackpageview) ## 13.94.0 - February 22nd, 2024 **Features** * **Static Resource Manager**: Internal Service Migration. ## 13.93.0 - February 21st, 2024 **Features** * **Static Resource Manager**: Add `groupMicrotask` priority option. ## 13.92.0 - February 19th, 2024 **Features** * **WebView**: Synchronize start and stop commands. ## 13.89.2 - February 14th, 2024 **Features** * **Static Resource Manager**: Support `style` attribute in element in serialization or mutation attribute. ## 13.89.0 - February 14th, 2024 **Features** * **Analysis**: Update [web-vitals ↗](https://github.com/GoogleChrome/web-vitals/blob/main/CHANGELOG.md) library to 3.5.2. ## 13.88.0 - February 14th, 2024 **Features** * **Session Replay**: Remove workaround used to consider base64 images of a certain size to be sensitive. ## 13.85.0 - February 8th, 2024 **Features** * Add protection against session cookie corruption. ## 13.84.1 - February 6th, 2024 **Bug fixes** * **Static Resource Manager**: Avoid calling with same data collection state. ## 13.84.0 - February 2nd, 2024 **Features** * Manage all DOM events in event translator. ## 13.83.0 - January 30th, 2024 **Features** * **Session Replay**: Mask credit card numbers automatically. ## 13.82.0 - January 30th, 2024 **Features** * **Static Resource Manager**: Save hashes to avoid sending them again. ## 13.81.2 - January 25th, 2024 **Bug Fixes** * **Static Resource Manager**: Support non-base64 images. ## 13.81.0 - January 24th, 2024 **Features** * **WebView**: Add [`excludeURLforReplay`](https://docs.contentsquare.com/en/web/command-reference/#excludeurlforreplay) command support. ## 13.78.0 - January 22nd, 2024 **Features** * **Session Replay**: Improve `input` element handling. ## 13.77.3 - January 15th, 2024 **Bug Fixes** * **Session Replay**: Call `onEvent` on all trackers before starting them. ## 13.77.1 - January 9th, 2024 **Performance Improvements** * Improve `allowSubdomain` change performance. ## 13.77.0 - January 9th, 2024 **Features** * **WebView**: Add [`afterPageView`](https://docs.contentsquare.com/en/web/command-reference/#afterpageview) command support. ## 13.76.3 - January 4th, 2024 **Bug Fixes** * **Static Resource Manager**: Do not process URLs when the online assets option is disabled. ## 13.75.4 - December 13th, 2023 **Bug Fixes** * Ignore logs coming from a worker override. ## 13.75.1 - December 12th, 2023 **Bug Fixes** * Catch SRM errors and add logs. ## 13.75.0 - December 12th, 2023 **Bug Fixes** * Execute callback directly when adding `onRecordingStateChange` command. ## 13.74.1 - December 12th, 2023 **Bug Fixes** * Manage ETR triggered before collection starts. ## 13.73.0 - December 6th, 2023 **Features** * **Static Resource Manager**: handle attribute and character data mutations. ## 13.72.3 - December 6th, 2023 **Bug Fixes** * Collect all navigation timing events. ## 13.72.2 - December 5th, 2023 **Bug Fixes** * Change log level error to warn for `crossDomainSingleIframe`. ## 13.72.1 - December 5th, 2023 **Bug Fixes** * Handle undefined values in for Console Message tracking. ## 13.72.0 - December 5th, 2023 **Bug Fixes** * Check that `addEventListener` is a function. **Features** * **crossDomainSingleIframe**: Start the tag on iFrame timeout. ## 13.71.4 - December 5th, 2023 **Bug Fixes** * **Custom Errors**: Truncate attributes keys and values (30 characters max). ## 13.67.4 - November 16th, 2023 **Bug Fixes** * **Custom Errors**: Replace object in root object. ## 13.65.1 - November 13th, 2023 **Bug Fixes** * Update Static Resource Manager [command names](https://docs.contentsquare.com/en/web/command-reference/). ## 13.63.0 - November 13th, 2023 **Bug Fixes** * Remove references to [`URLSearchParams` ↗](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams). ## 13.61.1 - November 11th, 2023 **Bug Fixes** * **Custom Errors**: Resolve circular dependency on console message. ## 13.60.0 - November 6th, 2023 **Features** * Track [`touchcancel` ↗](https://developer.mozilla.org/en-US/docs/Web/API/Element/touchcancel_event) events. ## 13.59.1 - October 30th, 2023 **Bug Fixes** * Align Analytics and Session Replay pipelines behavior. ## 13.59.0 - October 30th, 2023 **Bug Fixes** * **Session Replay**: Fixed failure to export `PerformanceResourceTimings` from a web worker. **Features** * Make the SKU optional on [`addToCart`](https://docs.contentsquare.com/en/web/sending-an-add-to-cart/) command. ## 13.58.4 - October 30th, 2023 **Performance improvements** * Remove useless object assignment checks. ## 13.58.3 - October 30th, 2023 **Bug Fixes** * **Session Replay**: Add slot element and attribute to serialized DOM to fix replays without CSS. ## 13.58.0 - October 25th, 2023 **Features** * **Session Replay**: Add Static Resource Manager support for `srcset` attributes in `<image>` elements. ## 13.57.0 - October 25th, 2023 **Features** * **Emerchandising**: Support for Display ads analysis ## 13.56.1 - October 17th, 2023 **Bug Fixes** * **WebViews**: Remove items from transaction on mobile. ## 13.56.0 - October 16th, 2023 **Features** * **API Errors**: Collect non encrypted headers. ## 13.55.0 - October 16th, 2023 **Features** * **Session Replay**: Add `onRecordingStateChange` command to track when the replay state changes. ## 13.54.0 - October 11th, 2023 **Features** * **WebViews**: Collect API, JS, and Custom errors in WebViews. ## 13.53.0 - October 9th, 2023 **Features** * **Session Replay**: Update to Static Resource Manager v2 (including images, inline assets, base64 assets). ## 13.51.2 - October 5th, 2023 **Bug Fixes** * **Session Replay**: Do not send navigation timing on the artificial pageviews. * **Session Replay**: Fix CSS resource when link use a relative path. ## 13.51.0 - October 5th, 2023 **Features** * Collect `adoptedStyleSheet` events in Iframes and WebViews. ## 13.50.2 - September 28th, 2023 **Bug fixes** * Fix wrong module imports. ## 13.49.3 - September 22nd, 2023 **Features** * Manage CSS rules inserted before tag starts. ## 13.49.0 - September 19th, 2023 **Features** * Static Resource Manager supports SVG elements with links (for screenshots and Session Replay). ## 13.48.3 - September 19th, 2023 **Bug Fixes** * Remove Static Resource Manager debug logs. ## 13.48.2 - September 19th, 2023 **Bug Fixes** * **Session Replay**: Filter out static URLs containing credentials. ## 13.48.1 - September 18th, 2023 **Bug Fixes** * Fix `shadowRoot` observer bug. ## 13.48.0 - September 14th, 2023 **Features** * **Session Replay**: Introduction of the Static Resource Manager, which optimizes the management of static resources and assets (such as images or fonts). ## 13.46.0 - September 13th, 2023 **Features** * **Session Replay**: Use API error patterns for resource tracking. ## 13.45.0 - September 13th, 2023 **Features** * **Session Replay**: Watch for `resize` events of sensitive elements. ## 13.44.2 - September 6th, 2023 **Bug fixes** * **Session Replay**: Filter `<img>` tags with empty `src` attribute. ## 13.44.1 - September 5th, 2023 **Bug fixes** * **Serialization**: update `addedNodesInATick` when a mutation target is not identified. ## 13.44.0 - September 4th, 2023 **Features** * **WebViews**: Update the signature of `serializeWebview` command. ## 13.43.0 - August 31th, 2023 **Features** * **WebViews**: Add processor to serialize `adoptedStyleSheets`. ## 13.42.0 - August 31th, 2023 **Features** * **WebViews**: Restart Session Replay on artificial pageview. ## 13.41.0 - August 31th, 2023 **Features** * **WebViews**: Introduce `AssetTransformers` mode and API to dynamically update it. ## 13.40.6 - August 31th, 2023 **Bug Fixes** * Handle multi tab for browser events. ## 13.40.4 - August 29th, 2023 **Bug Fixes** * **Project Configuration**: When updating fields from the **Data collection for Zoning** panel in the console project settings, an empty value for **Matching Dynamic elements regex** would be saved as an empty string instead of null and propagated to the configuration export (`CS_CONF`) used by the Tag. Empty string values are now discarded. ## 13.40.3 - August 29th, 2023 **Bug Fixes** * **Events**: Watch for [`change` ↗](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) events inside Shadow DOM. ## 13.40.0 - August 24th, 2023 🕒 *Available in an upcoming release on Contentsquare* **Features** * **Session Replay**: Add [`PerformanceResourceTiming` ↗](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming) tracker. ## 13.39.0 - August 22nd, 2023 **Features** * **Session**: Add [`session:clear:visitor`](https://docs.contentsquare.com/en/web/extending-the-session-length/#clear-previous-visitors-data) command to clear information about previous visitors before initiating a new session. ## 13.37.0 - August 21st, 2023 🕒 *Available in an upcoming release on Contentsquare* **Features** * **Custom Errors**: Enable collecting console error messages. ## 13.36.1 - August 21st, 2023 **Bug fixes** * **WebView**: Minor improvements to WebView local assets management. ## 13.36.0 - August 21st, 2023 **Features** * **Session Replay**: Monitor and collect changes to selected/unselected elements such as radio buttons. ## 13.35.0 - August 17th, 2023 **Features** * **Webviews**: Collect local assets and pass them to the JavaScript bridge and SDKs. ## 13.34.0 - August 16th, 2023 **Features** * **Webviews**: Send `BasePath` and `rawPath` of assets to the JavaScript bridge and SDKs. ## 13.33.1 - August 10th, 2023 **Bug Fixes** * **DOM Serializer**: Collection of [`adoptedStyleSheets` ↗](https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptedStyleSheets) on main document is re-introduced. ## 13.33.1 - August 9th, 2023 **Features** * **Session Replay**: Add optional capability to start and stop a replay based on user consent approval/withdrawal (`replayConsentRequired` configuration property). Up until today, no visitor consent was required to start Session Replay: the value of `replayConsentRequired` is `0`. When visitor consent is required, the value is `1`. Use the `replay:consent:startForSession:granted` and `replay:consent:startForSession:withdrawn` commands to shift the consent based on the user answer. The [`afterPageView`](https://docs.contentsquare.com/en/web/third-party-integrations-and-implementation-examples/#afterpageview) command has been enhanced to return the `replayConsentRequired` and `replayConsent` return values: ```javascript { projectId: 194, sessionKey: '48531f4b-b184-a11a-cae1-10ee72ef4c10.110', pageNumber: 1, replayConsentRequired: 1 replayConsent: 0 } ``` ## 13.31.2 - August 3rd, 2023 **Bug Fixes** * **Session Replay**: Identify and prevent email addresses to be encoded twice in query parameters. Example: `james@cs.com` would be encoded to `james%40cs.com` (correct), and then again to `james%2540cs.com` (incorrect). ## 13.30.11 - August 1st, 2023 **Features** * **Tag bundles**: The Tracking Tag is now served as ES2019 JavaScript by default, if your browser allows it. ES2019 bundles come with critical patching, treeshaking, and live update on project configuration change. If your browser does not support ES2019, the Tag is still served in ES5 at the same URL: `https://t.contentsquare.net/uxa/{PROJECT_ID}.js` ## 13.30.2 - July 20th, 2023 **Bug fixes** * **Session Replay**: Manage masking when `history.pushState()` is used before session renewal. Use of the browser's back button after triggering `history.pushState()` with a page outside the masking rules could lead to sending unmasked pages in certain cases. ## 13.30.0 - July 19, 2023 **Features** * Treeshake accessibility module to optimize bundle size. ## 13.29.0 - July 12, 2023 **Features** * **Session management**: Add a [`session:start:newVisitor`](https://docs.contentsquare.com/en/web/extending-the-session-length/#create-a-new-visitor) command to start a new visitor. Use this command when multiple people are using devices in kiosks, for instance. ## 13.28.6 - July 12, 2023 **Bug fixes** * **Custom Errors**: Send Custom Errors to the Session Replay pipeline only if the maximum number hasn't been reached. ## 13.28.5 - July 10, 2023 **Bug fixes** * Fixed performance issue in `VisibilityObserver`. ## 13.28.0 - July 05, 2023 **Features** * Add the pageview type to the [`afterPageView`](https://docs.contentsquare.com/en/web/third-party-integrations-and-implementation-examples/#afterpageview) command's context. ## 13.27.0 - July 04, 2023 **Features** * **API Errors**: ignore case when matching body for [configurable API errors ↗](https://support.contentsquare.com/hc/en-us/articles/37271964822417). ## 13.26.4 - July 04, 2023 **Performance improvements** * Optimize Tag bootload time. ## 13.26.0 - June 29, 2023 **Features** * **WebView**: stringify assets before calling `sendAssets`. ## 13.25.0 - June 29, 2023 **Bug fixes** * **Session Replay**: do not serialize nodes not yet identified during initial serialization. **Features** * **Session Replay**: add replay link generator command. ## 13.24.2 - June 29, 2023 **Bug fixes** * **Session Replay**: catch exceptions thrown by `whenDefined` function. ## 13.24.1 - June 28, 2023 **Bug fixes** * **Session Replay**: improve sensitive content coverage. ## 13.24.0 - June 26, 2023 **Features** * **API Errors**: Configurable API errors support. ## 13.22.3 - June 26, 2023 **Bug fixes** * **`EnviromentChecker`**: check if `localStorage` is not `null`. ## 13.22.1 - June 23, 2023 **Bug fixes** * Check `localStorage` exists in `window`. ## 13.22.0 - June 22, 2023 **Performance Improvements** * **Emerchandising**: Optimize `getAllValidAnchors`. ## 13.21.3 - June 22, 2023 **Performance improvements** * Remove non essential `localStorage` check. ## 13.21.0 - June 15, 2023 **Features** * **WebView**: Migrate analytics events. ## 13.20.0 - June 15, 2023 **Features** * **WebView**: Support commands on `cs_wvt`. ## 13.19.7 - June 14, 2023 **Bug fixes** * Handle ES5 in the worker context. ## 13.19.3 - June 08, 2023 **Bug fixes** * Log errors thrown when creating the web worker. ## 13.19.2 - June 07, 2023 **Bug fixes** * Update GzipCompressor to only use native `CompressionStream` on Chromium. ## 13.19.0 - June 06, 2023 **Features** * **Ecommerce**: Add `trackTransaction` to commands. ## 13.18.0 - June 06, 2023 **Features** * **Replay**: add pageX, pageY in Tap replay events. ## 13.17.2 - June 1st, 2023 **Bug fixes** * **Analysis**: upgrade web-vitals library. ## 13.17.1 - May 31st, 2023 **Bug fixes** * Support different casing of the `Content-Type` header. ## 13.17.0 - May 31st, 2023 **Features** * Filter untrusted gesture events. ## 13.16.0 - May 30th, 2023 **Features** * **Session Replay**: Add regex operator condition. ## 13.15.8 - May 29th, 2023 **Bug fixes** * Avoid relying on the `Response.type` property. ## 13.15.7 - May 29th, 2023 **Performance Improvements** * Optimize inactivity tracker. ## 13.15.6 - May 29th, 2023 **Performance Improvements** * **Session Replay**: Optimize debounce. ## 13.14.4 - May 24th, 2023 **Bug fixes** * **Session Replay**: allow all small Base64 images. ## 13.14.3 - May 24th, 2023 **Bug fixes** * Catch `onArtificialPageViewEnd` errors to avoid stopping the artificial pageview. ## 13.13.9 - May 22nd, 2023 **Bug fixes** * **Session Replay**: Add support for `data-cs-scroll-container` attribute on initial scroll event. ## 13.13.4 - May 16th, 2023 **Bug fixes** * Send `SCREEN_RESIZE` event on artificial pageview. ## 13.13.3 - May 16th, 2023 **Bug fixes** * **Session Replay**: Mask attribute value of input type button or submit when attribute name is value. ## 13.13.1 - May 15th, 2023 **Bug fixes** * **Session Replay**: mask sensitive nodes removed during serialization. ## 13.12.4 - May 4th, 2023 **Bug fixes** * **Session Replay**: start `textVisibility` only when enabled. ## 13.11.3 - April 18th, 2023 **Bug fixes** * Stop using `CompressionStream` for Safari. ## 13.11.0 - April 25th, 2023 **Features** * Add Interaction to Next Paint (INP) support. ## 13.10.0 - April 18th, 2023 **Bug fixes** * Support non-utf8 data for Symmetric decryption. ## 13.8.6 - April 4th, 2023 **Bug fixes** * **Session Replay**: Add value attribute to replay request for `input[type=submit]`. ## 13.7.3 - March 31st, 2023 **Bug fixes** * **Session Replay**: Remove initial empty event. ## 13.7.1 - March 28th, 2023 **Performance Improvements** * Measure `RecordingBatch.addEvent`. ## 13.7.0 - March 28th, 2023 **Features** * Errors triggered by Contentsquare tag are properly caught by third-party monitoring tools. ## 13.6.1 - March 28th, 2023 **Performance Improvements** * Optimize `onStartTracking` event lifecycle. ## 13.6.0 - March 28th, 2023 **Features** * **Webview**: Add `ec:transaction:items:add` command for WebView in SDK. ## 13.5.0 - March 23th, 2023 **Features** * **IFrame**: Add support for `setEncryptionSelectors` in iframe context. ## 13.4.0 - March 22th, 2023 **Features** * Add task scheduler globally. ## 13.3.0 - March 20th, 2023 **Features** * **Iframe**: Allow Tag to start inside an iframe of type `srcdoc`. ## 13.2.7 - March 15th, 2023 **Bug fixes** * **Replay**: Do not set `mouseover` event listener on shadow roots for old iOS versions. ## 13.2.4 - March 15th, 2023 **Performance improvements** * Measure the execution duration of `ElementVisibility` tracker ## 13.2.1 - March 13th, 2023 **Bug fixes** * Handle `self` property overrides ## 13.2.0 - March 9th, 2023 **Features** * Stringify and send requests from worker ## 13.1.0 - March 9th, 2023 **Features** * **Session Replay**: Implement screen resize event tracker ## 13.0.2 - March 6th, 2023 **Performance improvements** * Improve DOM serialization performance. ## 13.0.1 - March 6th, 2023 **Bug Fixes** * **Session Replay**: Support parsing multiple values for the `rel` attribute for stylesheet linking. ## 13.0.0 - March 6th, 2023 **Features** * Add Session Replay support in WebViews **Breaking Changes** * `window._uxa.push(["setOption", "isWebView", true]);` will start the Tag in WebView mode. ## 12.6.1 - March 2nd, 2023 **Bug Fixes** * Remove warning logs for node without identifier ## 12.5.11 - March 1st, 2023 **Bug Fixes** * **Accessibility**: Fix issue when an artificial pageview is triggered before the initial collection is triggered ## 12.5.7 - February 24th, 2023 **Bug Fixes** * Handle null referrer ## 12.5.7 - February 23th, 2023 **Bug Fixes** * Text visibility events not sent when emerch is enabled ## 12.5.0 - February 15th, 2023 **Features** * Add `isRecording` command inside iframe context ## 12.4.4 - February 15th, 2023 **Bug fixes** * Fix extensions index out of bounds ## 12.4.3 - February 15th, 2023 **Bug fixes** * Logger should handle when property is undefined ## 12.4.2 - February 13th, 2023 **Bug fixes** * Mask API error library field ## 12.4.0 - February 8th, 2023 **Features** * Add browser accessibility features and extensions detection ## 12.3.0 - February 8th, 2023 **Features** * Refactored serialization objects **Performance Improvements** * Read visitor cookie only once ## 12.1.0 - February 1st 2023 **Features** * Mask JWT token ## 12.0.1 - January 27th, 2023 Version bump for the `@contentsquare/tracking-tag` package. ## 12.0.0 - January 26th, 2023 **Features** * Add data collection for Session Replay in iFrames ## 11.68.2 - January 17th, 2023 **Bug fixes** * Refactored eventQueueStream ## 11.68.1 - January 12th, 2023 **Bug fixes** * Fix race condition ## 11.68.0 - January 5th, 2023 **Features** * Improve text visibility performance * Remove dynamically generated numbers from element name in path computation ## 11.67.0 - January 2nd, 2023 **Features** * **Session Replay data collection**: added the `setEncryptionSelectors` command to encrypt sensitive data by a selector (continued) ## 11.66.0 - January 2nd, 2023 **Bug fixes** * **Custom Variables**: Ignore invalid custom variables that were injected in the [`_cs_cvars`](https://docs.contentsquare.com/en/web/cookies/#_cs_cvars) cookie. ## 11.65.0 - December 22th, 2022 **Features** * **Transformers**: Change JavaScript transformers to TypeScript transformers. ## 11.64.0 - December 20th, 2022 **Features** * **Emerch**: Add product exposure tracking. ## 11.63.1 - December 19th, 2022 Version bump for the `@contentsquare/tracking-tag` package. ## 11.63.0 - December 18th, 2022 **Features** * **Session Replay data collection**: added the `setEncryptionSelectors` command to encrypt sensitive data by a selector ## 11.62.0 - December 14th, 2022 **Bug Fixes** * **Emerch**: Keep request parameters upon session renewal ## 11.62.0 - December 13th, 2022 **Features** * Process DOM mutations in chunks to improve performance ## 11.61.1 - December 12th, 2022 **Bug Fixes** * **API Errors**: Clone Fetch Response before reading payload * **Session Replay data collection**: The `set_adopted_style_sheets` event must come after the target element is serialized ## 11.61.0 - December 12th, 2022 **Features** * **Iframe**: Collect emerch on trackPageview. * **Iframe**: Upgrade communication to Channel Messaging API. ## 11.60.1 - December 8th, 2022 **Bug Fixes** * Fix Text visibility issue ## 11.60.0 - December 8th, 2022 **Bug Fixes** * Fix most frequent errors ## 11.59.0 - December 07, 2022 **Features** * Support [`document.adoptedStyleSheets` ↗](https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptedStyleSheets) in Session Replay (continued). ## 11.57.9 - December 05th, 2022 **Bug Fixes** * Install listeners for composed events only on document. ## 11.57.7 - November 18th, 2022 **Bug Fixes** * **Serialization**: Duplication when moving a node inside a node added during the same tick. ## 11.57.6 - November 17th, 2022 Version bump for the `@contentsquare/tracking-tag` package. This version protects the `Image.src` setter against JavaScript overrides. ## 11.57.4 - November 15th, 2022 **Bug Fixes** * Added input element to selectors in serialization ## 11.57.3 - November 14th, 2022 **Bug Fixes** * Allowed synchronous compression when Worker creation fails (continued) ## 11.57.2 - November 14th, 2022 **Bug Fixes** * Allowed synchronous compression when Worker creation fails ## 11.57.1 - November 14th, 2022 Version bump for the `@contentsquare/tracking-tag` package. ## 11.57.0 - November 10th, 2022 Version bump for the `@contentsquare/tracking-tag` package. ## 11.56.2 - November 10th, 2022 **Performance Improvements** * Compute initial scroll position only for document instead of every HTML element. ## 11.56.1 - November 9th, 2022 **Features** * Text visibility revamp ## 11.56.0 - November 8th, 2022 **Bug fixes** * **Session Replay**: reduce the payload size by rounding mouse position coordinates. ## 11.55.1 - November 7th, 2022 **Bug fixes** * Fix intermittent JS error produced by the logger. ## 11.55.0 - November 7th, 2022 **Features** * Don't renew sessions on browser events that are not user events. ## 11.54.3 - November 3rd, 2022 **Bug fixes** * Fix throttling to only report actual target events * Filter untrusted click/mouse/pointer/touch events (continued) ## 11.54.2 - November 2nd, 2022 **Bug fixes** * Update Performance API management to fix incorrect session time duration * Filter untrusted click/mouse/pointer/touch events ## 11.54.1 - October 31st, 2022 **Bug fixes** * Reset pageview request index on session renewal. ## 11.54.0 - October 27th, 2022 **Features** * (Internal) Allow flush commands register for dev environments **Performance Improvements** * Miscellaneous performance improvements (including tag download time, caching, tree shaking) ## 11.53.1 - October 24th, 2022 Version bump for the `@contentsquare/tracking-tag` package. ## 11.53.0 - October 24th, 2022 **Features** * Add `referrer:` commands to mask Personal Data carried over by the referrer and sent to the tracking Tag on the next page. ## 11.52.0 - October 19th, 2022 **Features** * Use reliable selector to collect product path for Emerch. ## 11.51.0 - October 11th, 2022 **Bug fixes** * Use `cachedJsonStringify` on Error events. **Features** * Increase the number of events to and throttling time to send a Session Replay data collection request **Performance Improvements** * Implemented throttling on move events ## 11.50.0 - October 10th, 2022 **Bug fixes** * Fix serialization issues which resulted in broken screenshots ## 11.49.1 - October 05th, 2022 **Bug fixes** * Fix duplicates in collection by handling nodes removed and added within the same tick (event loop). ## 11.49.0 - October 05th, 2022 **Features** * Check `Map` and `Set` are supported in the browser before tracking. ## 11.48.0 - October 04th, 2022 **Features** * Retry data collection requests for Session Replay. **Bug fixes** * Fix Unplayable Replay rate by Wait for `initialDom` to be done before sending beacon requests. ## 11.47.0 - September 29th, 2022 **Bug fixes** * Reintroduce `CSPathComputation` global variable in built Tag. ## 11.46.0 - September 28th, 2022 **Features** * Support product exposure tracking for Emerch. ## 11.45.1 - September 26th, 2022 Version bump for the `@contentsquare/tracking-tag` package. ## 11.45.0 - September 26th, 2022 **Features** * Remove `mousemove`, `mousedown` and `mouseup` events collection ## 11.44.5 - September 22th, 2022 **Bug fixes** * Manage concurrent async serializations ## 11.44.4 - September 22th, 2022 **Bug fixes** * Catch Session Replay data collection recovery errors to avoid stopping the Tag boot. ## 11.44.3 - September 29th, 2022 **Bug fixes** * Prevent serializing twice nodes added in the same tick (event loop). ## 11.44.2 - September 15th, 2022 **Bug fixes** * Ignore attributes mutations that do not change the state of the DOM **Performance Improvements** * Improve duplicated `JSON.stringify` calls * Improved performance of Array-like operations ## 11.44.1 - September 14th, 2022 **Bug fixes** * Improve browser support check for Custom Elements registration in Session Replay * Fix page and session number on session renewal if multiple tabs are open ## 11.44.0 - September 13th, 2022 **Features** * **Add `pvt` query parameter to tell the pageview type**: artificial, natural, or session renewal. ## 11.43.0 - September 12th, 2022 **Features** * Throttle data collection for Session Replay requests to improve performance ## 11.42.0 - September 12th, 2022 **Features** * Protect `window.performance` against overrides (pageviews were not being fired). ## 11.41.0 - September 8th, 2022 **Bug fixes** * Improve sanitization of Personal Data CSS selectors which prevented collecting Session Replay data for sessions (continued) **Features** * Fix controlled exposure for HTML elements which generated blank screens ## 11.40.2 - September 7th, 2022 **Bug fixes** * Improve sanitization of Personal Data CSS selectors which prevented collecting Session Replay data for sessions ## 11.40.1 - August 29th, 2022 **Bug fixes** * Do not collect personal information in JS errors * Report errors when touch events are not supported ## 11.40.0 - August 24th, 2022 * Implementation touch events - Pinch and Spread support ## 11.39.0 - August 23rd, 2022 * Technical improvement on the serialization process ## 11.38.1 - August 22nd, 2022 * Collect touch events in Session Replay ## 11.38.0 - August 22nd, 2022 * Collect touch events in Session Replay ## 11.37.1 - August 18th, 2022 * Technical improvement ## 11.37.0 - August 17th, 2022 * Merchant info for add to cart and purchase ## 11.36.2 - August 9th, 2022 * **Bug fix**: Emerch module ## 11.36.2 - August 8th, 2022 * **Bug fix**: Emerch module ## 11.36.1 - August 8th, 2022 * Session Replay improvement ## 11.36.0 - August 3rd, 2022 * Implementation of Text errors ## 11.35.0 - August 3rd, 2022 * **Technical improvement**: Session duration ## 11.34.0 - August 3rd, 2022 * Cvar key maximum length increased to 512 characters. ## 11.33.3 - August 1st, 2022 * Performance improvement ## 11.33.2 - July 28th, 2022 * Internal improvement ## 11.33.1 - July 26th, 2022 * Support fix ## 11.33.0 - July 18th, 2022 * Update the pointer events with more arguments. ## 11.32.2 - July 13th, 2022 * Maximum length of Dvar key increased from 50 to 512 characters. ## 11.32.1 - July 12th, 2022 * Technical improvement ## 11.32.0 - July 12th, 2022 * New Scope for custom variables added ## 11.30.1 - July 6th, 2022 * Support fix ## 11.30.0 - July 5th, 2022 * New event tracking for input password and number in SR ## 11.29.0 - July 4th, 2022 * Add Swipe metrics in zoning ## 11.28.0 - July 4th, 2022 * Collect body ## 11.27.3 - June 28th, 2022 * Refactoring DOM serializer/ Async Map Processor introduction ## 11.27.2 - June 28th, 2022 * Support fix ## 11.27.1 - June 28th, 2022 * Scraper requests fix ## 11.27.0 - June 27th, 2022 * Collect swipe and long-press events ## 11.26.3 - June 16th, 2022 * Tag refactoring ## 11.26.1 - June 8th, 2022 * Support fix ## 11.26.0 - June 7th, 2022 * API errors - Collect Query parameters ## 11.25.2 - June 1st, 2022 * Bug fix ## 11.25.1 - May 31st, 2022 * Support fix ## 11.25.0 - May 24th, 2022 * Regex flags support ## 11.24.0 - May 17th, 2022 * Tag improvement ## 11.23.2 - May 9th, 2022 * Fix API call undefined when collecting headers ## 11.23.1 - May 9th, 2022 * Support ticket fix ## 11.23.0 - May 4th, 2022 * Manage lazy loaded products * Add query parameter in display requests to indicate if the payload is compressed or not ## 11.22.0 - May 3rd, 2022 * Collect custom/standard headers ## 11.21.0 - April 26th, 2022 * **Fix**: \[API Error] Collected wrong `error_time` ## 11.20.2 - April 25th, 2022 * Bug fix ## 11.20.0 - April 20th, 2022 * Support ticket fix ## 11.19.4 - April 14th, 2022 * Symmetric Encryption services into `cryptoWrapper` package ## 11.19.3 - April 13th, 2022 * Bug fix ## 11.19.2 - April 12th, 2022 * Bug fix ## 11.19.1 - April 11th, 2022 * Internal improvement ## 11.19.0 - April 11th, 2022 * Add `projectId` to the context object passed to the afterPageView callback ## 11.18.0 - April 7th, 2022 * Use fetch when available ## 11.17.0 - April 7th, 2022 * Reduce Tag size ## 11.16.0 - April 6th, 2022 * Internal change in logs * Bug fix ## 11.15.2 - April 5th, 2022 * Internal change in logs ## 11.15.1 - March 31st, 2022 * Bug fix ## 11.15.0 - March 30th, 2022 * Send encrypted user identifier to Session Replay ## 11.14.2 - March 30th, 2022 * Debounced scroll events attributed to the wrong pageview ## 11.14.1 - March 21st, 2022 * Session Replay improvement ## 11.14.0 - March 21st, 2022 * Bug fix ## 11.13.1 - March 21st, 2022 * Bug fix ## 11.13.0 - March 21st, 2022 * Internal update ## 11.12.0 - March 15th, 2022 * Internal logs set up ## 11.11.0 - March 14th, 2022 * `setOption` command usage for technical reason ## 11.10.1 - March 10th, 2022 * Events collection fix ## 11.10.0 - March 10th, 2022 * Core Web Vitals collection implementation * Minor improvement ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare Tracking Tag changelog","url":"https://docs.contentsquare.com/en/web/changelog/","inLanguage":"en","dateModified":"2026-08-06T16:34:19+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Collected data - Web description: Understand what data is collected by the Tag lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/web/collected-data/ md: https://docs.contentsquare.com/en/web/collected-data/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare collects comprehensive visitor interaction data while protecting personal information through email filtering and optional masking features. ## Personal Data You will find below an exhaustive list of all data being collected. In particular, **potential** Personal Data would be: 1. Into the **HTML content** that is sent for a small fraction of our visitors. Solutions to prevent this from happening: * Remove some sensitive content ([this chapter explains how](https://docs.contentsquare.com/en/web/personal-data-handling/#remove-contentpersonal-data-from-the-collected-html)) * Totally deactivate this for all users (some features may then be unavailable like Session Replay or retroactive background; ask your Account Manager) 2. Into **Custom Variables** sent to our servers (to prevent this from happening, make sure that the values that you wish to collect could not be linked to one individual) ## What is not collected * We don't collect the values of form fields * We don't collect what the user types in * We remove every email-looking string in URL, Custom Vars, Dynamic Vars and Session Replay before they are sent to our servers Warning This does not apply to Voice of Customer capabilities designed to collect user feedback. See [Voice of Customer](https://docs.contentsquare.com/en/web/voice-of-customer/). ## What is collected The Tag automatically collects the following data. Any values you explicitly send via [Custom Vars](https://docs.contentsquare.com/en/web/sending-custom-vars/) or [Dynamic Vars](https://docs.contentsquare.com/en/web/sending-dynamic-vars/) are also collected. | Data | Usage | Value example | | - | - | - | | User Agent | Device type (desktop/tablet/mobile) and browser detection | Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv.7.5) | | City Geolocation | Web users geolocation (based on the IP address; for more info on IP Addresses [see dedicated section](https://docs.contentsquare.com/en/web/ip-addresses/)) | Paris, France | | URL | Mappings: group pageviews on similar page templates | [https://en.wikipedia.org/ ↗](https://en.wikipedia.org/) | | Screen Resolution | Segments | 1600x900 | | Referer | Segments: traffic source detection | [https://google.com ↗](https://google.com) | | Clicks | Zoning Analysis | {target: "div#zone", t:1500} | | Clicked Element (button and link) | Segmentation, Funnels | {target: "button#checkout", t:1500, text: "Checkout"} | | Clicked Element (all elements) | Segmentation, Funnels | {target: "button#checkout", t:1500, text: "Checkout"} | | Hovers | Zoning Analysis | {target: "div#zone", t:1500} | | Scroll | Zoning Analysis (exposure metrics) | {top:0px, left: 0px; t:1500} | | Mouse move | Activity rate | {x:200, y:800, t:1500} | | Focus | Not used | {target: "div#zone", t:1500} | | E-commerce data (if applicable) | Value example | | - | - | | Transaction ID | 1234 | | Total (revenue) | 11.99 | | Currency | USD | | Product Total ([Merchandising](https://docs.contentsquare.com/en/web/sending-ecommerce-commands/#sending-a-transaction-for-merchandising) only) | 11.99 | | Product ID / SKU ([Merchandising](https://docs.contentsquare.com/en/web/sending-ecommerce-commands/#sending-a-transaction-for-merchandising) only) | 1234 | | Product name ([Merchandising](https://docs.contentsquare.com/en/web/sending-ecommerce-commands/#sending-a-transaction-for-merchandising) only) | Green shoes | | Product quantity ([Merchandising](https://docs.contentsquare.com/en/web/sending-ecommerce-commands/#sending-a-transaction-for-merchandising) only) | 1 | | Product category ([Merchandising](https://docs.contentsquare.com/en/web/sending-ecommerce-commands/#sending-a-transaction-for-merchandising) only) | Shoes | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Collected data","description":"Understand what data is collected by the Tag","url":"https://docs.contentsquare.com/en/web/collected-data/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Tag API reference - Web description: Tag commands reference including signature, parameter descriptions, and examples lastUpdated: 09 June 2026 source_url: html: https://docs.contentsquare.com/en/web/command-reference/ md: https://docs.contentsquare.com/en/web/command-reference/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Tag commands reference including signature, parameter descriptions, and examples. Which commands are available in my project? Contentsquare use [tree shaking ↗](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) techniques to optimize the Tag bundle size for every project. Specific commands can be unavailable when: * You haven't subscribed to the specified paying option or module * You are [self-hosted](https://docs.contentsquare.com/en/web/#self-hosting) and do not use a recent version of the Tag ## About this page ### iFrames When iframe tracking is enabled (`CS_CONF.iframesTracking = 1`), commands used in iframes or nested iframes that load a tag are sent to the top window tag which processes them like any other command. For example, using `window._uxa.push(["trackPageview", IFRAME_PATH]);` will trigger an artificial pageview in the top window. Commands supported in iframes while iframe tracking is enabled are specified with iframe. ### Webview Some commands can be run in webviews when webview tracking is enabled. This requires both `CS_CONF.webviewsTrackingEnabled = true` and `_uxa.push(["setOption", "isWebView", "true"])`. Commands that support webviews are marked with webview. ## Pageview The Tag can send 3 types of pageview: * **Natural** pageview: sent when the tracking tag initializes during the initial browser load. This is the standard trigger for traditional multi-page websites. * **Artificial** pageview: triggered via a manual command. This is essential for Single-Page Applications (SPAs), where the browser does not perform a full refresh as the user navigates between different states or views. * **Renewal** pageview: occurs when a visitor re-engages with a page after their previous session has expired. Since every session starts with a pageview, the system generates a renewal pageview to maintain session integrity without requiring a URL change. ### `trackPageview` iframe | webview | **Added in:** `1.1.0` Send an artificial pageview. ```javascript window._uxa.push(["trackPageview", path, options]); ``` If run before the loading of the tag, the command will behave as [`setPath`](#setpath). [Tag Configurator Template: Artificial Pageview](https://support.contentsquare.com/hc/en-us/articles/37271878716433-CSTC-Template-Artificial-Pageview)Learn how to use this command with the Contentsquare Tag Configurator. #### Parameters * #### path  string (optional, <= 255 chars)   The URL pathname to send. If not set, the current document `href` attribute is used instead. * #### options  object (optional)   Path options * #### options.decodeURI  boolean   Single attempt to decode the provided `path` using the [`decodeURI` ↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) native API. Since 13.97.0. * #### options.decodeURIDeep  boolean   Up to 10 attempts to fully decode the provided `path` using the [`decodeURI` ↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) native API. Since 13.97.0. * #### options.lifespan  integer or string   Specify the lifespan of the overridden path. If not set, the overridden path will persist all along the user session. Possible string values: `onNextPageviewOnly` (reset after this pageview). Possible integer values: `2`. ### `setPath` iframe | **Added in:** `2.0.0` Override the path to send within a pageview. ```javascript window._uxa.push(["setPath", path, options]); ``` #### Parameters * #### path  string   The path to send in place of the current URL pathname. * #### options  object (optional)   Path options * #### options.decodeURI  boolean   Single attempt to decode the provided `path` using the [`decodeURI` ↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) native API. Since 13.97.0. * #### options.decodeURIDeep  boolean   Up to 10 attempts to fully decode the provided `path` using the [`decodeURI` ↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) native API. Since 13.97.0. * #### options.lifespan  integer or string   Specify the lifespan of the overridden path. If not set, the overridden path will persist all along the user session. Possible string values: `onNextPageviewOnly` (reset after upcoming pageview). Possible integer values: `2`. #### Examples ##### Collect URL with custom decoded path URL is `https://www.company.es/specials/campañas-y-ofertas`. ```javascript window._uxa.push(["setPath", window.location.href, { decodeURI: true }]); ``` Using `decodeURI`, the URL in the next pageview request is collected without encoding: ```text https://www.company.es/specials/campañas-y-ofertas ``` instead of: ```text https://www.company.es/specials/campa%C3%B1as-y-ofertas ``` ### `setQuery` iframe | **Added in:** `7.16.0` Replace a URL query string containing personal data with a masked one. ```javascript window._uxa.push(["setQuery", queryString, options]); ``` #### Parameters * #### queryString  string   Masked query string. * #### options  object (optional)   Query string options * #### options.decodeURI  boolean   Single attempt to decode the provided `queryString` using the [`decodeURI` ↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) native API. Since 13.97.0. * #### options.decodeURIDeep  boolean   Up to 10 attempts to fully decode the provided `queryString` using the [`decodeURI` ↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) native API. Since 13.97.0. * #### options.lifespan  integer or string   Specify the lifespan of the overridden query. If not set, the overridden query will persist all along the user session. Possible string values: `onNextPageviewOnly` (reset after upcoming pageview). Possible integer values: `2`. #### Examples ##### Collect URL with custom decoded query string URL is `https://www.company.es/specials/ofertas?code=mañanas2024`. ```javascript window._uxa.push(["setQuery", window.location.search + "&cookies-popin=true", { decodeURI: true }]); ``` Using `decodeURI`, the query string URL in the next pageview request is collected without encoding: ```text https://www.company.es/specials/ofertas?code=mañanas2024&cookies-popin=true ``` instead of: ```text https://www.company.es/specials/ofertas?code=ma%C3%B1anas2024&cookies-popin=true ``` ### `referrer:maskUrl` iframe | **Added in:** `11.53.0` Allows to change the referrer URL (`dr` query parameter) that is sent in the next pageview request. The command can be called multiple times to mask different URL patterns. ```javascript window._uxa.push(["referrer:maskUrl", url]); ``` #### Parameters * #### url  string   URL containing parameters prefixed with a colon for masking purposes. #### Examples The referrer URL to be sent is: ```text https://web.com/users/123456/products/ABCDEF ``` By calling `referrer:maskUrl` with this URL: ```javascript window._uxa.push(["referrer:maskUrl", "https://web.com/users/:USER_ID/products/:PRODUCT_ID"]); ``` The referrer URL that is sent becomes: ```text https://web.com/users/CS_ANONYMIZED_USER_ID/products/CS_ANONYMIZED_PRODUCT_ID ``` ### `referrer:keepQueryString` iframe | **Added in:** `11.53.0` Reverts the action of [`referrer:removeQueryString`](#referrerremovequerystring) for the next pageview. ```javascript window._uxa.push(["referrer:removeQueryString"]); ``` #### Examples The referrer URL to be sent is: ```text https://hello?withQueryString=true ``` `referrer:keepQueryString` will keep the query string if `referrer:removeQueryString` was used: ```javascript window._uxa.push(["referrer:removeQueryString"]); // Referrer URL will be https://hello? window._uxa.push(["referrer:keepQueryString"]); // Referrer URL will be https://hello?withQueryString=true ``` #### Parameters * No parameters. ### `referrer:removeQueryString` iframe | **Added in:** `11.53.0` Remove all characters in the query string. ```javascript window._uxa.push(["referrer:removeQueryString"]); ``` #### Parameters * No parameters. #### Examples The referrer URL to be sent is: ```text https://hello?withQueryString=true ``` By calling `referrer:removeQueryString`: ```javascript window._uxa.push(["referrer:removeQueryString"]); ``` The referrer URL becomes: ```text https://hello? ``` ### `setCustomVariable` iframe | **Added in:** `1.1.0` Define a custom variable to add meta information to pageviews about the page, user, or the session. ```javascript window._uxa.push(["setCustomVariable", index, name, value, scope]); ``` A custom var can be deleted by calling the command with an empty string value. The index parameter must match the custom var to delete. If a custom var already exists with a given index, the new name and value will override the old one. [Tag Configurator Template: Custom Variable](https://support.contentsquare.com/hc/en-us/articles/37271895488401-CSTC-Template-Custom-Variable)Learn how to use this command with the Contentsquare Tag Configurator. #### Parameters * #### index  positive integer   Variable index (between 1 and 20). * #### name  string (<= 512 chars)   Variable name. * #### value  string (<= 255 chars)   Variable value. * #### scope  string or integer (optional)   Variable scope. If not set, defaults to visit and page. Possible string values: `visit`, `page`, or `nextPageOnly`. Possible integer values: `2`, `3`, or `4`. #### Examples ##### Setting a custom variable with the scope `visit` at index 5 ```javascript window._uxa.push(["setCustomVariable", 5, "cname", "cvalue", "visit"]); ``` ##### Setting and deleting custom variables with specific scopes Setting a custom var in both scopes (visit + page) at index 6 and named `cname` value `cvalue`: ```javascript window._uxa.push(["setCustomVariable", 6, "cname", "cvalue"]); ``` To delete the custom variable: ```javascript window._uxa.push(["setCustomVariable", 6, "cname", "", 2]); // from scope visit window._uxa.push(["setCustomVariable", 6, "cname", "", 3]); // from scope page window._uxa.push(["setCustomVariable", 6, "cname", ""]); // from both scopes by passing no value ``` ##### Setting a custom variable with the scope `nextPageOnly` ```javascript window._uxa.push(["setCustomVariable", 6, "cname", "cvalue", "nextPageOnly"]); // or window._uxa.push(["setCustomVariable", 6, "cname", "cvalue", "4"]); ``` Attach and send the custom variable to an specific artificial pageview: ```javascript window._uxa.push(["trackPageview", "/a-path"]); ``` After sending another artificial pageview: ```javascript window._uxa.push(["trackPageview", "/another-path"]); ``` The custom variable is automatically deleted. ### `hidePageTitle` iframe | Product Analytics | **Added in:** `15.10.0` Replace the page title by `****` in the next pageview or in all the next pageviews. ```javascript window._uxa.push(["hidePageTitle", scope]); ``` #### Parameters * #### scope  string   When `scope` equals to `onNextPageviewOnly`, the command only affects the next pageview. Otherwise, it affects all subsequent pageviews. #### Examples Consider the following HTML page: ```html <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Order #12345 for Jane Smith - Retail Store</title> </head> <body> ... </body> </html> ``` Calling `window._uxa.push(["hidePageTitle"]);` replaces "Order #12345 for Jane Smith - Retail Store" by `****` on all the next pageviews, until the tag is reloaded or if the `resetHidePageTitle` command is run. ### `resetHidePageTitle` iframe | Product Analytics | **Added in:** `15.10.0` Reverts the action of [`hidePageTitle`](#hidepagetitle) for the next pageviews. ```javascript window._uxa.push(["resetHidePageTitle"]); ``` #### Parameters * No parameters. ## eCommerce A transaction should be sent by implementation to track information about visitors transactions on the website. To send a transaction, use these commands in the following order: 1. [`ec:transaction:create`](#ectransactioncreate) to create a transaction which can contain items 2. [`ec:transaction:items:add`](#ectransactionitemsadd) to add an item to the previously created transaction (multiple items can be added by calling this command multiple times) 3. [`ec:transaction:send`](#ectransactionsend) to send the previously created transaction containing all the items ### `ec:transaction:create` iframe | webview | **Added in:** `11.5.0` Create transactions before adding items and sending them to Contentsquare. ```javascript window._uxa.push([ "ec:transaction:create", { id: TRANSACTION_ID, revenue: REVENUE_AMOUNT, currency: CODE }, ]); ``` #### Parameters * #### id  string   Transaction ID. * #### revenue  integer or string   Total cost of the transaction. * #### currency  string (optional, <= 10 characters)   Currency value. When no currency is supplied, the currency used in the one from the Contentsquare project settings. #### Examples ##### Creating a transaction in euros ```javascript window._uxa = window._uxa || []; window._uxa.push([ "ec:transaction:create", { id: "037333583343", revenue: 280, currency: "EUR" }, ]); window._uxa.push([ "ec:transaction:items:add", { id: "037333583343", name: "Men's Tree Dasher 2", sku: "AA000QM080", category: "Shoes", price: 140, quantity: 2 }, ]); window._uxa.push(["ec:transaction:send"]); ``` ### `ec:transaction:items:add` iframe | webview | **Added in:** `11.10.0` Add item to a transaction created with [`ec:transaction:create`](#ectransactioncreate). ```javascript window._uxa.push([ "ec:transaction:items:add", { id: TRANSACTION_ID, name: ITEM_NAME, price: ITEM_AMOUNT, quantity: ITEM_QUANTITY, sku: ITEM_SKU_CODE, category: ITEM_CATEGORY, merchant: MERCHANT_NAME }, ]); ``` #### Parameters * #### id  string   The Transaction ID. * #### name  string   Item name. * #### price  float   Item price. * #### quantity  integer   Number of items. * #### sku  string (optional)   A valid Stock Keeping Unit (SKU) code. * #### category  string (optional)   Item category. * #### merchant  string (optional)   The merchant name. #### Examples ##### Adding two items to a transaction ```javascript window._uxa = window._uxa || []; window._uxa.push([ "ec:transaction:create", { id: "037333583343", revenue: 280, currency: "EUR" }, ]); window._uxa.push([ "ec:transaction:items:add", { id: "037333583343", name: "Men's Tree Dasher 2", sku: "AA000QM080", category: "Shoes", price: 140, quantity: 2 }, ]); window._uxa.push(["ec:transaction:send"]); ``` ### `ec:transaction:send` iframe | webview | **Added in:** `10.5.0` Send a transaction containing items added with `ec:transaction:items:add` to later associate a user's session with their purchases. This command extends the session. ```javascript window._uxa.push(["ec:transaction:send"]); ``` #### Parameters * No parameters. #### Examples ##### Sending a transaction with two items ```javascript window._uxa = window._uxa || []; window._uxa.push([ "ec:transaction:create", { id: "037333583343", revenue: 280, currency: "EUR" }, ]); window._uxa.push([ "ec:transaction:items:add", { id: "037333583343", name: "Men's Tree Dasher 2", sku: "AA000QM080", category: "Shoes", price: 140, quantity: 2 }, ]); window._uxa.push(["ec:transaction:send"]); ``` ### `ec:cart:add` iframe | **Added in:** `10.5.0` Register an add to cart event. This command extends the session. ```javascript window._uxa.push([ "ec:cart:add", { merchant: MERCHANT_NAME, sku: SKU_CODE }, ]); ``` #### Parameters * #### merchant  string (optional)   The merchant name. * #### sku  string (optional)   A valid Stock Keeping Unit (SKU) code. Note Either `merchant` or `sku` is required. #### Examples ##### Sending an add to cart event (Merchandising customers) ```javascript window._uxa = window._uxa || []; window._uxa.push([ "ec:cart:add", { merchant: "Pixel patterns", sku: "DC126O0FX-L11" }, ]); ``` ## Session By default, a Tag session ends 30 minutes after the last event. These commands allow you to manage session behavior. ### `extendSession` iframe | **Added in:** `9.7.0` Extend session duration. ```javascript window._uxa.push(["extendSession"]); ``` This command automatically extends a session until: * The session duration reaches 4h00 * A new pageview (natural or artificial) is triggered To achieve the extension of the session, it will periodically, with a period of 29 minutes: * Update the session cookie [`cs_s`](https://docs.contentsquare.com/en/web/cookies/#_cs_s) and add 29 minutes. * Send a dynamic variable `session_expiry_update:Counter` where the counter begins with the value 1 and is incremented (+1) after each call. #### Parameters * No parameters. Commands extending the session The following commands also extend the session duration: * [identify](#identify) * [addUserProperties](#adduserproperties) * [ec:transaction:send](#ectransactionsend) * [ec:cart:add](#eccartadd) ### `optout` iframe | webview | **Added in:** `7.12.0` Opt out the current user from data collection. ```javascript window._uxa.push(["optout"]); ``` #### Parameters * No parameters. ### `session:start:newVisitor` iframe | **Added in:** `13.29.0` Start a new visitor and a new session. Running the command generates a new pageview. ```javascript window._uxa.push(["session:start:newVisitor"]); ``` #### Parameters * No parameters. ### `session:clear:visitor` iframe | **Added in:** `13.39.0` Clear all data linked to previous visitors. ```javascript window._uxa.push(["session:clear:visitor"]); ``` Warning The command must be called before the Tag is loaded. #### Parameters * No parameters. ## Dynamic variables Dynamic variables allow you to send key-value pairs that can be used for segmentation and analysis. Unlike custom variables which are attached to pageviews, dynamic variables are sent immediately when the command is called. Calling [`trackDynamicVariable`](#trackdynamicvariable) multiple times in the same tick will batch the dynamic variables into a single request. ### `trackDynamicVariable` iframe | webview | **Added in:** `5.19.0` Send a dynamic variable. ```javascript window._uxa.push(["trackDynamicVariable", { DYNAMIC_VARIABLE }]); ``` [Tag Configurator Template: Dynamic Variable](https://support.contentsquare.com/hc/en-us/articles/37271814927633-CSTC-Template-Dynamic-Variable)Learn how to use this command with the Contentsquare Tag Configurator. #### Parameters * #### DYNAMIC\_VARIABLE  object   The dynamic variable * #### key  string (<= 512 chars)   Dynamic variable key * #### value  number or string (<=255 chars)   Dynamic variable value #### Examples ##### Sending dynamic variables for A/B testing campaigns **First user** ```javascript window._uxa = window._uxa || []; window._uxa.push([ "trackDynamicVariable", { key: "AB_ABT_Label_Best_Price_PC", value: "With best price" }, ]); window._uxa.push([ "trackDynamicVariable", { key: "AB_ABT_Product_Show_Customer_Ratings", value: "Variation 1" }, ]); ``` **Second user** ```javascript window._uxa = window._uxa || []; window._uxa.push([ "trackDynamicVariable", { key: "AB_ABT_Label_Best_Price_PC", value: "Standard" }, ]); window._uxa.push([ "trackDynamicVariable", { key: "AB_ABT_Product_Show_Customer_Ratings", value: "Variation 2" }, ]); ``` ## Page events Page events allow you to track specific actions or states on a page. Once the command is called, a request is sent to the Contentsquare backend. If the session is collected, the page event is also sent to the Session Replay pipeline. ### `trackPageEvent` iframe | **Added in:** `9.5.0` Track a page event. ```javascript window._uxa.push(["trackPageEvent", eventName]); ``` [Tag Configurator Template: Page Event](https://support.contentsquare.com/hc/en-us/articles/37271705463185-CSTC-Template-Page-Event)Learn how to use this command with the Contentsquare Tag Configurator. #### Parameters * #### eventName  string (<= 255 chars)   The name of the event to collect. #### Examples ##### Collect when visitors save a property add for later consultation ```javascript window._uxa = window._uxa || []; window._uxa.push(["trackPageEvent", "SubscribedToPropertyButtonClick"]); ``` ##### Collect user identifiers for Session Replays **Added in:** `10.17.0` ```javascript window._uxa = window._uxa || []; window._uxa.push(["trackPageEvent", "@user-identifier@" + accountID]); ``` See [User Identifier](https://docs.contentsquare.com/en/web/personal-data-handling/#user-identifier). ## Custom events ### `trackEvent` webview | **Added in:** `15.116.0` Required configuration * `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` Track a custom event. ```javascript const event = { name: "purchase", properties: { dollars: 50, items: ["socks", "shoes", "shirt"] }, }; window._uxa.push(["trackEvent", event]); ``` #### Parameters * #### Event Object  object   Name and properties of the event to collect. * #### name  string (<= 1024 chars)   The name of the event. * #### properties  object (optional)   The properties of the event. * #### key  string (<= 512 chars)   The key of the property. * #### value  boolean, number, string, or array (<= 1024 chars)   The value of the property. ## Sending from submit Deprecated To track form [submit ↗](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event) events, implement a command that will add submit events to the analytics events collected. ### `submit` Deprecated | iframe | **Added in:** `11.8.0` Send the submit state to the Contentsquare Tag. ```javascript window._uxa.push(["submit", state, htmlElement]); ``` #### Parameters * #### state  string   Submit state. Possible values: `attempt`, `success`, or `failure`. * #### htmlElement  string   A CSS selector reference to a DOM element. ## Session Replay data collection Masking (also known as "auto-masking") is the process where text node content (text in a web page) is replaced by `aaa` strings. This feature is enabled or disabled per project through feature flags. For example, the string `Imagine this string in a textNode element` is replaced by `aaaaaaa aaa aaaaaa aa a aaaaaaaa aaaaaaa`. In addition to replacing text content, masking removes most element attributes except an allowlist and all attributes on SVG elements. The allowlist can be extended through the Tag configuration in the back-office. By design, replacing any string by "a" may result in altering the layout of the website because most websites do not use monospace fonts — any replacement may result in different placement of the text in replay. If this is a problem, disable masking and use [`setPIISelectors`](#setpiiselectors) to mask personal data on the website instead. ### `setCapturedElementsSelector` iframe | webview | **Added in:** `9.22.0` Capture elements' text data with Page Masking enabled. ```javascript window._uxa.push(["setCapturedElementsSelector", CSS_SELECTORS]); ``` Warning The command must be called before the Tag is loaded. In case of a [`trackPageview`](#trackpageview), this command should be called beforehand. [Tag Configurator Template: Element Unmasking](https://support.contentsquare.com/hc/en-us/articles/37271866118033-CSTC-Template-Element-Unmasking)Learn how to use this command with the Contentsquare Tag Configurator. #### Parameters * #### CSS\_SELECTORS  string   Comma-separated list of CSS selectors. ### `setPIISelectors` iframe | webview | **Added in:** `9.28.0` Mask Personal Data using specific selectors. ```javascript const PIIobject = { PIISelectors: [".to-mask, #mask-me"], Attributes: [ { selector: ".bar", attrName: "foo" } ] }; window._uxa.push(['setPIISelectors', PIIObject]); ``` Warning The command must be called before the Tag is loaded. In case of a [`trackPageview`](#trackpageview), this command should be called beforehand. [Tag Configurator Template: Element Masking](https://support.contentsquare.com/hc/en-us/articles/37271836678545-CSTC-Template-Element-Masking)Learn how to use this command with the Contentsquare Tag Configurator. #### Parameters * #### PIIObject  object   Elements and attributes to be masked in Session Replay. * #### PIISelectors  array (optional)   Comma-separated list of CSS selectors for elements to mask completely. * #### Attributes  array of objects (optional)   Attributes to mask * #### selector  string   CSS selector of the element * #### attrName  string   Attribute name to mask ### `setEncryptionSelectors` iframe | webview | **Added in:** `11.63.0` Encrypt sensitive data in elements matched by CSS selectors. An encryption key must be set using the Tag configuration in the Contentsquare console. ```javascript window._uxa.push(["setEncryptionSelectors", CSS_SELECTORS]); ``` Warning The command must be called before the Tag is loaded. In case of a [`trackPageview`](#trackpageview), this command should be called beforehand. #### Parameters * #### CSS\_selectors  string   Comma-separated list of CSS selectors ### `trackEventTriggerRecording` iframe | **Added in:** `9.5.0` Trigger Session Replay data collection after a specific event. When the collection mode is ETR (Event Triggered Replay), the Tag collects all sessions but only keeps those that trigger at least one ETR event. There are two ETR types: * **Session** (default): the pipeline keeps all pageviews of the session * **Page**: the pipeline keeps at least the current pageview To trigger a page-level ETR, prefix the event name with `@ETP@`. The `@ETS@` prefix is optional for session-level ETR. ```javascript // Session ETR (default) window._uxa.push(["trackEventTriggerRecording", eventName]); // Page ETR window._uxa.push(["trackEventTriggerRecording", "@ETP@" + eventName]); ``` #### Parameters * #### eventName  string (<= 255 chars)   The name of the event that triggers Session Replay data collection. Truncated if longer than 255 characters. Prefix with `@ETP@` for page-level ETR. ### `excludeURLforReplay` iframe | webview | **Added in:** `11.66.0` Specify a regular expression to exclude matching URLs from Session Replay data collection. ```javascript window._uxa.push(["excludeURLforReplay", regex]); ``` Call this command once, before the Tag is loaded. The regex is matched against the URL without the protocol. It is kept until the next page load. #### Parameters * #### regex  string   Regular expression string tested against the URL (without protocol) using a partial match — the pattern does not need to match the full URL. #### Examples ##### Exclude checkout and account pages across specific subdomains ```javascript window._uxa = window._uxa || []; window._uxa.push(["excludeURLforReplay", "(us|uk|de)\\.shoetune\\.eu/(checkout|account)"]); ``` This excludes the `/checkout` and `/account` sections on `us.shoetune.eu`, `uk.shoetune.eu`, and `de.shoetune.eu`, including deeper paths and query strings such as `us.shoetune.eu/checkout/step-2?promo=SPRING`. ### `replay:consent:unanonymized:granted` Personal Data Exposure When misused, this command can lead to the exposure of personal data in Session Replays. Make sure to only grant and withdraw consent when you are sure that no personal data will be collected in Session Replays. iframe | **Added in:** `13.33.0` Disable masking for the current browser when masking is enabled on the project. ```javascript window._uxa.push(["replay:consent:unanonymized:granted"]); ``` The consent is sticky for 13 months, stored in the [`_cs_c`](https://docs.contentsquare.com/en/web/cookies/#_cs_c) cookie. If masking is disabled on the project, this command has no effect. Note Before v13.33.0, this command was named `trackConsentGranted` (still supported). #### Parameters * No parameters. ### `replay:consent:unanonymized:withdrawn` Personal Data Exposure When misused, this command can lead to the exposure of personal data in Session Replays. Make sure to only grant and withdraw consent when you are sure that no personal data will be collected in Session Replays. iframe | **Added in:** `13.33.0` Re-enable masking for the current browser after consent was granted. ```javascript window._uxa.push(["replay:consent:unanonymized:withdrawn"]); ``` The withdrawal is sticky for 13 months, stored in the [`_cs_c`](https://docs.contentsquare.com/en/web/cookies/#_cs_c) cookie. If masking is disabled on the project, this command has no effect. Note Before v13.33.0, this command was named `trackConsentWithdrawn` (still supported). #### Parameters * No parameters. ### `replay:resourceManager:enableForOnlineResource:nextPageviewOnly` iframe | **Added in:** `13.66.0` Activates the collection of remote resources of the page by the Static Resource Manager for the next pageview. By default, the pipeline downloads resources (images, CSS, etc.) from their URLs. When resources require authentication or VPN access, enable this command so the Tag sends resource content directly instead. Should be used before a pageview containing protected resources starts. ```javascript window._uxa.push(["replay:resourceManager:enableForOnlineResource:nextPageviewOnly"]); ``` #### Parameters * No parameters. ### `replay:resourceManager:getStatus` **Added in:** `13.66.0` Returns information concerning the Static Resource Manager feature current state to help with implementation and troubleshooting. ```javascript window._uxa.push(["replay:resourceManager:getStatus"]); ``` The response schema from a command run is: ```json { "isStarted": boolean, "onlineAssets": { "activated": boolean, "enabledOnNextPageview": boolean, "enabledForChilddrenOnNextStart" boolean } } ``` #### Parameters * No parameters. ## API errors and network requests collection Masking commands for network request URLs that are collected. This affects URLs that are collected in the context of API Errors and Network Details. ### `networkRequest:maskUrls` iframe | webview | **Added in:** `15.24.0` Register patterns to mask URLs collected for API errors and network details. ```javascript window._uxa.push(["networkRequest:maskUrls", pattern]); ``` Compatibility with the api-errors:maskUrl command If a pattern registered by the [api-errors:maskUrl](https://docs.contentsquare.com/en/web/command-reference/#api-errorsmaskurl) command matches a URL, patterns supplied to `networkRequest:maskUrls` are not taken into account. [Tag Configurator Template: Network requests mask URLs](https://support.contentsquare.com/hc/en-us/articles/37271848447761-CSTC-Template-Network-requests-mask-URLs)Learn how to use this command with the Contentsquare Tag Configurator. #### Parameters * #### pattern  string or array of strings   One or several URL masking patterns. Patterns can match the full URL of the page or only a part of it. URL fragments to mask are prefixed by a colon. They are replaced by `CS_ANONYMIZED_{FRAGMENT}`. You can also call this command multiple times with different patterns each time to register multiple patterns. No patterns are overridden. #### Examples Supplying the following URL masking patterns: ```javascript window._uxa.push([ "networkRequest:maskUrls", ["contracts/:contract_id/clients/:client_id", "resources/:resource_id"], ]); ``` On the following URLs: ```txt https://host.com/contracts/123456/clients/llltgm/offers https://resources/56789/locations ``` Results in these masked URLs which are collected by Tag: ```txt https://host.com/contracts/CS_ANONYMIZED_CONTRACT_ID/clients/CS_ANONYMIZED_CLIENT_ID/offers https://resources/CS_ANONYMIZED_RESOURCE_ID/locations ``` ### `networkRequest:maskUrls:reset` iframe | webview | **Added in:** `15.24.0` Clear all patterns registered using the [`networkRequest:maskUrls`](https://docs.contentsquare.com/en/web/command-reference/#networkrequestmaskurls) command. ```javascript window._uxa.push(["networkRequest:maskUrls:reset"]); ``` #### Parameters * No parameters. ### `api-errors:maskUrl` iframe | webview | Deprecated | **Added in:** `10.8.0` Register patterns to mask URLs collected for API errors and network details. ```javascript window._uxa.push(["api-errors:maskUrl", url]); ``` #### Parameters * #### url  string   Full URL of the page. URL fragments to mask are prefixed by a colon. They are replaced by `CS_ANONYMIZED_{FRAGMENT}`. #### Examples ##### Mask order IDs ```javascript var urls = [ "https://api.net/order/:order_id/merge/:order_id", "https://api.net/order/:order_id/item", "https://www.api.nl/nl/ajax/nfs/account/cancelOrder/:order_id", ]; for (var i = 0; i < urls.length; i++) { window._uxa.push(["api-errors:maskUrl", urls[i]]); } ``` The URLs will be collected as: ```txt https://api.net/order/CS_ANONYMIZED_ORDER_ID/merge/CS_ANONYMIZED_ORDER_ID https://api.net/order/CS_ANONYMIZED_ORDER_ID/item https://www.api.nl/nl/ajax/nfs/account/cancelOrder/CS_ANONYMIZED_ORDER_ID ``` ## Custom Errors collection Experience Monitoring Web To send an error to Contentsquare without any JavaScript or API error triggered in the browser, it is possible to send a custom error. ### `trackError` iframe | webview | **Added in:** `11.36.0` Collect any text displayed on the user screen because of a specific action. ```javascript window._uxa.push(["trackError", message, { ERROR_CATEGORIES }]); ``` [Tag Configurator Template: Custom Error](https://support.contentsquare.com/hc/en-us/articles/37271813052817-CSTC-Template-Custom-Error)Learn how to use this command with the Contentsquare Tag Configurator. #### Parameters * #### message  string (<= 300 chars)   The text to collect. * #### ERROR\_CATEGORIES  object \[1...5] (optional)   An object containing up to 5 key/value pairs to categorize the errors. Keys and values must be up to 30 characters. When these limitations are not respected, the command is ignored. * #### \[key\_name]  string (<= 30 chars)   The key name * #### \[value\_name]  string (<= 30 chars)   The value name #### Examples ##### Send a custom error for incorrect user input ```javascript window._uxa.push([ "trackError", "140000 is not a valid postal code", { type: "formValidation", severity: "minor", lang: "english" }, ]); ``` ## Identity Product Analytics Identity commands allow you to attach a unique identity to the current user. For more information, see [Track User Identity ↗](https://developers.heap.io/docs/using-identify) Required configuration * `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` || * `CS_CONF.heapEnvironment?.heap_tag_status === cs_sideloads_heap` ### `identify` This command associates the current user with the provided identity string. If this command is called while the current user already has a **different** identity string associated with them, the current session will be reset, the user ID will be re-generated, and a new pageview of type renewal will be sent. Calling `identify` with the same identity does not reset the session. This command extends the session. * cs\_crosswrites\_heap iframe | webview | **Added in:** `15.69.0` ```javascript window._uxa.push(["identify", <identityString>, <options>]); ``` #### Parameters * #### identityString  string | number   The identity string that will be associated with the current user. * #### options  { hash: boolean }   With `{ hash: true }`, the identity string will be hashed before being sent to the server. * cs\_sideloads\_heap iframe | **Added in:** `15.1.0` ```javascript window._uxa.push(["identify", <identityString>]); ``` This command acts as a wrapper for the `heap.identify` command. See [https://developers.heap.io/reference/identify ↗](https://developers.heap.io/reference/identify) #### Parameters * #### identityString  string | number   The identity string that will be associated with the current user. #### Timing with `cs_sideloads_heap` Call identify after the tag has initialized This command wraps `heap.identify()` and requires `window.heap` to be defined. Commands pre-loaded into `_uxa` before the tag script runs are replayed as soon as the tag bootstraps. The `cs-sideloads-heap` module initializes slightly later, so `window.heap` may not be ready yet. Calling `identify` at that point silently does nothing. Avoid arbitrary `setTimeout` workarounds. Use [`afterPageView`](#afterpageview) (available since v7.7.0) instead: the callback runs after the tag's initial bootstrap, ensuring `window.heap` is defined. ```javascript window._uxa.push(["afterPageView", function(context) { // Only run on natural pageviews, not artificial or renewal ones if (context.pageViewType !== "n") return; window._uxa.push(["identify", <identityString>]); }]); ``` ### `resetIdentity` When called while the current user has an identity string associated with them, the current session will be reset, the user ID will be re-generated, and a new pageview of type renewal will be sent. If the user is not identified, this command has no effect. * cs\_crosswrites\_heap iframe | webview | **Added in:** `15.69.0` ```javascript window._uxa.push(["resetIdentity"]); ``` #### Parameters * No parameters. * cs\_sideloads\_heap iframe | **Added in:** `15.1.0` ```javascript window._uxa.push(["resetIdentity"]); ``` #### Parameters * No parameters. This command acts as a wrapper for the `heap.resetIdentity` command. See [https://developers.heap.io/reference/resetidentity ↗](https://developers.heap.io/reference/resetidentity) ### `getIdentity` This command is a helper command that determines whether the current user has an identity string associated with them. * cs\_crosswrites\_heap iframe | **Added in:** `15.69.0` ```javascript window._uxa.push(["getIdentity"]); ``` #### Parameters * No parameters. This command will not return the exact identity string but a hash computed from the identity string. * cs\_sideloads\_heap iframe | **Added in:** `15.1.0` ```javascript window._uxa.push(["getIdentity"]); ``` #### Parameters * No parameters. This command acts as a wrapper for the `heap.getIdentity` command. See [https://developers.heap.io/docs/api-reference#getidentity ↗](https://developers.heap.io/docs/api-reference#getidentity) ## User properties Product Analytics User properties command allows you to attach custom properties to the current user. For more information, see [Track User Identity ↗](https://developers.heap.io/docs/using-identify) Required configuration * `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` || * `CS_CONF.heapEnvironment?.heap_tag_status === cs_sideloads_heap` ### `addUserProperties` This command associates the current user with the given custom properties, overwriting any previously set values for the same properties. This command extends the session. * cs\_crosswrites\_heap iframe | webview | **Added in:** `15.69.0` ```javascript window._uxa.push(["addUserProperties", properties]); ``` #### Parameters * #### properties  Record\<string, string | number | boolean | bigint>   The custom properties to attach to the current user. * cs\_sideloads\_heap iframe | **Added in:** `15.31.0` ```javascript window._uxa.push(["addUserProperties", properties]); ``` #### Parameters * #### properties  Record\<string, string | number | boolean | bigint>   The custom properties to attach to the current user. This command acts as a wrapper for the `heap.addUserProperties` command. See [https://developers.heap.io/reference/adduserproperties ↗](https://developers.heap.io/reference/adduserproperties) ## Event properties Product Analytics Event properties commands allow you to attach custom properties to events. These properties will be included with all subsequent events until they are removed or cleared. Required configuration * `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` || * `CS_CONF.heapEnvironment?.heap_tag_status === cs_sideloads_heap` ### `customProperties:visit:add` Alias: `addEventProperties` This command adds custom properties that will be attached to all subsequent events. * cs\_crosswrites\_heap iframe | webview | **Added in:** `15.152.0` ```javascript window._uxa.push(["customProperties:visit:add", properties]); ``` #### Parameters * #### properties  Record\<string, string | number | boolean | bigint>   The custom properties to attach to all subsequent events. * cs\_sideloads\_heap iframe | **Added in:** `15.152.0` ```javascript window._uxa.push(["customProperties:visit:add", properties]); ``` #### Parameters * #### properties  Record\<string, string | number | boolean | bigint>   The custom properties to attach to all subsequent events. This command acts as a wrapper for the `heap.addEventProperties` command. See [https://developers.heap.io/reference/addeventproperties ↗](https://developers.heap.io/reference/addeventproperties) ### `customProperties:visit:remove` Alias: `removeEventProperty` This command removes a custom property from subsequent events. * cs\_crosswrites\_heap iframe | webview | **Added in:** `15.152.0` ```javascript window._uxa.push(["customProperties:visit:remove", property]); ``` #### Parameters * #### property  string   The name of the property to remove. * cs\_sideloads\_heap iframe | **Added in:** `15.152.0` ```javascript window._uxa.push(["customProperties:visit:remove", property]); ``` #### Parameters * #### property  string   The name of the property to remove. This command acts as a wrapper for the `heap.removeEventProperty` command. See [https://developers.heap.io/reference/removeeventproperty ↗](https://developers.heap.io/reference/removeeventproperty) ### `customProperties:visit:clear` Alias: `clearEventProperties` This command removes all custom properties from subsequent events. * cs\_crosswrites\_heap iframe | webview | **Added in:** `15.152.0` ```javascript window._uxa.push(["customProperties:visit:clear"]); ``` * cs\_sideloads\_heap iframe | **Added in:** `15.152.0` ```javascript window._uxa.push(["customProperties:visit:clear"]); ``` This command acts as a wrapper for the `heap.clearEventProperties` command. See [https://developers.heap.io/reference/cleareventproperties ↗](https://developers.heap.io/reference/cleareventproperties) ## Pageview properties Product Analytics Pageview properties commands allow you to attach custom properties to pageviews. These properties will be attached to the current pageview and all events that occur on that page. Required configuration * `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` ### `customProperties:page:add` iframe | webview | **Added in:** `15.69.0` This command adds custom properties to the current pageview and events on the page. ```javascript window._uxa.push(["customProperties:page:add", properties]); ``` #### Parameters * #### properties  Record\<string, string | number | boolean | bigint>   The custom properties to attach to the current pageview and subsequent events. ### `customProperties:page:remove` iframe | webview | **Added in:** `15.69.0` This command removes a custom property from subsequent events on the page. ```javascript window._uxa.push(["customProperties:page:remove", property]); ``` #### Parameters * #### property  string   The name of the property to remove. ### `customProperties:page:clear` iframe | webview | **Added in:** `15.69.0` This command clears all custom properties from the subsequent events on the current pageview. ```javascript window._uxa.push(["customProperties:page:clear"]); ``` ## Integrations Integration commands allow you to retrieve session information and register callbacks to be run after pageviews or when the data collection context changes. These are used for integrating Contentsquare data with other tools and systems. ### `getSessionKey` iframe | **Added in:** `5.15.0` Retrieves a unique Contentsquare session key. Returns the `sessionKey` string if the natural pageview has already been sent, otherwise `undefined`. A unique session identifier formatted as `<userId>.<sessionNumber>` (example: `123abc.789`) — `userId` is a unique anonymous ID generated by Contentsquare. ```javascript function callback(sessionKey) { const [userId, sessionNumber] = sessionKey.split("."); // do something with the session key } window._uxa = window._uxa || []; _uxa.push(["getSessionKey", { callback }]); ``` #### Parameters * #### options  object (optional)   Options object. * #### options.callback  function   Callback function which receives the `sessionKey` string. ### `afterPageView` iframe | webview | **Added in:** `7.7.0` Allows to run a callback function after a natural or artificial pageview. ```javascript window._uxa.push(["afterPageView", callback]); function callback(context) { const sessionKey = context.sessionKey; const pageNumber = context.pageNumber; const projectId = context.projectId; const pageViewType = context.pageViewType; const uxaDomain = context.uxaDomain; const isRecording = context.isRecording; const recordingConsentState = context.recordingConsentState; // ... } ``` #### Parameters * #### callback  function   Callback function which receives a context object. * #### context.sessionKey  string   A unique session identifier. A string that encodes `<userId>.<sessionNumber>` (example: `59e73d8b-2730u283i20-6712c43aaab3.3`) — `userId` is a unique anonymous ID generated by Contentsquare. * #### context.pageNumber  number   The page number * #### context.projectId  number   Your Contentsquare project ID. * #### context.pageViewType  string   Natural (n), Artificial (a), Renewal (r). * #### context.uxaDomain  string   The Contentsquare App domain. * #### context.isRecording  boolean   Whether Session Replay is on. * #### context.recordingConsentState  number   Indicates the visitor's choice regarding consent: * 1 = not required, * 2 = not expressed, * 3 = withdrawn, * 4 = granted The callback function is run after the natural pageview and after each `trackPageview`. You can register multiple callbacks by calling the command multiple times. #### Examples ##### Check visitor consent for Session Replay a on specific page ```javascript window._uxa = window._uxa || []; _uxa.push(["afterPageView", callback]); function callback(context) { if (context.recordingConsentState === 2 && context.pageNumber === 42) { displayConsentWidget(); } } ``` ### `replay:link:generate` iframe | **Added in:** `13.25.0` Generate a replay link. ```javascript window._uxa.push(["replay:link:generate", { withTimestamp: true }, onReplayLinkGenerated]); function onReplayLinkGenerated(context) { var isRecording = context.isRecording; var replayLink = context.replayLink; // ... } ``` #### Parameters * #### options  object   Replay link options * #### withTimestamp  boolean   Whether the replay link is generated with a timestamp * #### onReplayLinkGenerated  function   Callback function which receives a context object. * #### context.isRecording  boolean   Whether the data collection for Session Replay is in progress. * #### context.replayLink  string   The replay link of the session, optionally with a timestamp query parameter (`withTimeStamp`). ### `onRecordingContextChange` iframe | webview | **Added in:** `13.55.0` Note The command alias `onRecordingStateChange` is still compatible. Track changes to the data collection context to avoid false positives while generating replay links. ```javascript window._uxa.push(["onRecordingContextChange", onRecordingContextChange]); function onRecordingContextChange(context) { var isRecording = context.isRecording; var recordingStartTimestamp = context.recordingStartTimestamp; var etrState = context.etrState; var etrStatus = context.etrStatus; // ... } ``` #### Parameters * #### onRecordingContextChange  function   Callback function which receives a context object and called each time the data collection context changes. * #### context.isRecording  boolean   Whether the data collection for Session Replay is in progress. * #### context.recordingStartTimeStamp  number   Timestamp indicating when data collection for Session Replay started. * #### context.etrState  string   `0` (ETR is disabled) or `1` (ETR is enabled). * #### context.etrStatus  string   `0` (ETR is disabled), `1` (ETR is pending), `2` (ETR is triggered on **page**) or `3` (ETR is triggered on **session**). ## Webview mode When the Tag is integrated in a WebView where the tracking is managed by the app opening the WebView (for example Android, iOS, or Cordova), the Tag should not be in charge of managing the session but only report tracked events (click, DOM mutation) to the Contentsquare SDK installed in the iOS or Android app. It is necessary to enable the WebView mode for the Tag to enable this specific behavior. ### `setOption` **Added in:** `4.0.1` Enables webview mode when the Tag is managed by a mobile app opening the WebView. ```javascript window._uxa.push(["setOption", "isWebView", true]); ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Tag API reference","description":"Tag commands reference including signature, parameter descriptions, and examples","url":"https://docs.contentsquare.com/en/web/command-reference/","inLanguage":"en","dateModified":"2026-06-09T17:42:02+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - Web description: Tag compatible browsers, frameworks, and libraries lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/web/compatibility/ md: https://docs.contentsquare.com/en/web/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare Tracking Tag is compatible with modern browsers and works alongside common frameworks and libraries. ## Browsers Support Policy The Contentsquare Tracking Tag is designed to work on browsers that support features that were part of [Baseline by the end of 2019](https://web-platform-dx.github.io/web-features/supported-browsers/?targetYear=2019). This ensures compatibility with modern web APIs while maintaining broad browser support. The Tracking Tag may work on older browser versions, but they are not actively tested. Critical bugs affecting functionality or security will be addressed on a case-by-case basis, while non-critical issues may not be fixed. | Browser | Minimum Version | | - | - | | Android (Webview) | 66+ | | Chrome | 66+ | | Chrome for Android | 66+ | | Facebook In-App Browser | 169+ | | Firefox | 65+ | | Firefox for Android | 65+ | | Instagram In-App Browser | 42+ | | KaiOS Browser | 3+ | | Microsoft Edge | 18+ | | Opera | 53+ | | Opera Mobile | 47+ | | QQ Browser | 9+ | | Safari | 13+ | | Safari iOS | 13+ | | Samsung Internet | 9+ | | UC Browser | 13+ | | Yandex Browser | 18+ | ### Safari (macOS and iOS) * The Tracking Tag uses the Beacon API to send data when the user leaves the page (page load, close tab, close browser). * This feature is only supported on macOS 12.1+ and iOS 12.2+. * ITP 2.1 deletes all JavaScript cookies 7 days after the last visit on a website. ### In-app browsers and webviews * Tracking works as long as the app doesn't restrict required browser APIs, delete, or prevent cookies setup, or blocks local storage. * The Tracking Tag behavior has been validated (pageviews and events tracking, session data collection) on the following in-app browsers, on both iOS and Android: **Facebook, Facebook Messenger, Twitter, Instagram, LinkedIn, Slack, Snapchat, Pinterest, WeChat**. ## Frameworks The Contentsquare Tracking Tag is compatible with **all JavaScript frameworks** for single-page applications, including Angular, React, Vue, Ember... Note To make the reporting easier, some pages loading could require the sending of [artificial pageviews](https://docs.contentsquare.com/en/web/sending-pageviews/). ### Single Page Applications leaving inactive pages in the DOM Special care must be taken for **Single Page Applications** that leave inactive pages in the DOM, such as **Angular+Ionic**. In that case, avoid using [Page Masking](https://docs.contentsquare.com/en/web/personal-data-handling/#selectively-mask-pages-by-url) as it may leak some **personal data** into the **Session Replay**. Instead, use [Element Masking](https://docs.contentsquare.com/en/web/personal-data-handling/#remove-contentpersonal-data-from-the-collected-html). ## Iframes Contentsquare supports iFrames, including for Zoning and Session Replay. ### Implementation 1. Add the tag to the topmost window and inside each iframe down to and including the ones you want to track. Use the same Tag ID. ``` stateDiagram-v2 accTitle: Iframe tracking implementation accDescr: Shows the implementation of the tracking tag for iframes, with the top window and two nested iframes, all with the same Tag ID, and the flow of pageviews. state "Top window (Tag ID = 1111111111111)" as Top { state "Iframe 1 (Tag ID = 1111111111111)" as If1 { state "Iframe 2 (Tag ID = 1111111111111)" as If2 } } ``` 2. Your Contentsquare team enables the `iFrameTracking` tag setting to support iFrame tracking. When the flag is enabled, the tag inside the iFrames is not sending any natural pageview. 3. For Single Page Applications, trigger an [artificial pageview](https://docs.contentsquare.com/en/web/sending-pageviews/#sending-an-artificial-pageview) inside the iFrame with a condition to run only in this context to send a pageview. ```javascript if (window.self !== window.top) { window._uxa = window._uxa || []; window._uxa.push(["trackPageview", "PATH"]); } ``` ### Session Replay and iframes In **version `12.0.0` and later**, tracking of first and third-party iFrames in Session Replay is fully supported, and activated on demand by Contentsquare. ## Custom elements and shadow DOM The tracking Tag has two separate event trackers: **Session Replay** and **Analytics**. Both provide full support for [custom elements ↗](https://developer.mozilla.org/docs/Web/API/Web_components#custom_elements) and the [shadow DOM ↗](https://developer.mozilla.org/docs/Web/API/Web_components#shadow_dom). ## Partial support The following features have limited or partial support with the Tracking Tag. ### Web Animations API Since version `15.211.0` (see [changelog](https://docs.contentsquare.com/en/web/changelog/#152110---april-8th-2026)), Session Replay captures animations driven by the JavaScript [Web Animations API ↗](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API). Support is partial: animations started by the browser's CSS engine after an element is already being tracked are not replayed. #### What is supported * `Element.animate(keyframes, options)` * Changes made through the `Animation` interface: `play()`, `pause()`, `finish()`, `cancel()`, `reverse()`, `updatePlaybackRate()`, and the `currentTime` setter * Animation properties serialized in the replay: `playState`, `playbackRate`, `currentTime` (rounded to the nearest millisecond), and `id` * Keyframes resolved via `KeyframeEffect.getKeyframes()` (computed values) * Timing options resolved via `KeyframeEffect.getTiming()`: `duration`, `delay`, `endDelay`, `easing`, `iterations`, `iterationStart`, `direction`, `fill`; plus `KeyframeEffect` options: `composite`, `pseudoElement`, and `iterationComposite` * The initial set of animations on an element at the moment it is first serialized (including CSS animations already running on it), via `document.getAnimations()` #### What isn't supported * **CSS animations and CSS transitions started after an element is already tracked** — for example, a `@keyframes` animation or a `transition` triggered by toggling a CSS class. The class change itself is captured, but the animation playback isn't, so the animation may appear missing, frozen, or out of sync in Session Replay. * Mid-flight changes to a running animation via `Animation.startTime`, `KeyframeEffect.setKeyframes()`, `KeyframeEffect.updateTiming()`, or by replacing `animation.effect` * `Animation.commitStyles()` and `Animation.persist()` * Animations created directly with `new Animation(...)` (only `Element.animate()` is instrumented) * Scroll- and view-driven animations using `ScrollTimeline`, `ViewTimeline`, or any custom `AnimationTimeline` * Animations inside cross-origin iframes (general Session Replay limitation) #### Recommendation For animations that must be faithfully reproduced in Session Replay, prefer the JavaScript Web Animations API (`element.animate(...)`) over CSS-class-triggered `@keyframes` or `transition` declarations. ### HTML Canvas and WebGL The Tracking Tag attaches mouse listeners to `<canvas>` elements but cannot locate interactions inside the canvas. This limitation applies to any framework that renders its entire UI into a `<canvas>` element — most notably **Flutter Web** when using the [CanvasKit renderer ↗](https://docs.flutter.dev/platform-integration/web/renderers). #### What works on a canvas-rendered site * Session and visitor identification, consent, and opt-out * Page views, when the application exposes URL changes through the History API (for example, by configuring `PathUrlStrategy` in Flutter) * Any event sent explicitly through the JavaScript API (`_uxa.push(...)`): custom page views, custom variables, dynamic variables, ecommerce, and custom errors * API and JavaScript error monitoring (JavaScript errors require source maps for readable stack traces) #### What isn't supported * Zoning, click maps, scroll maps, and heatmaps — interactions can't be tied to specific UI elements * Automatic click, hover, form, and link tracking * Session Replay — canvas content can't be serialized * DOM-based personal data masking — no DOM text is exposed #### Recommendation for Flutter Web developers To get the most out of Contentsquare on a Flutter Web application: * Configure `PathUrlStrategy` so route changes produce trackable page views through the History API. * Send business events from Dart through `dart:js_interop` and `_uxa.push(...)`. * Build with source maps: `flutter build web --source-maps`. * Initialize accessibility semantics at startup by calling `SemanticsBinding.instance.ensureSemantics()` so the application is ready to benefit from upcoming canvas-related improvements. ## Not supported The following technologies and environments are **not supported** by the Contentsquare Tracking Tag. ### Partytown [Partytown ↗](https://partytown.qwik.dev/) is a generic all-purpose proxy that helps relocate resource intensive scripts into a web worker, and off of the main thread. The Tracking Tag is incompatible with Partytown. It relies on DOM mutations, querying, observations, and global variables — features that do not function properly when the Tag is loaded using Partytown. ### Websites overriding native JavaScript function and browser APIs The Contentsquare Tracking Tag uses common web browser APIs and native JavaScript API. Overriding any of these APIs can prevent the Tag from functioning normally. ### Google AMP - Accelerated Mobile Pages Contentsquare doesn't provide tracking capabilities for AMP yet. ### Offline browsing The Tracking tag doesn't verify if data was received by the server before deleting it locally. All events would be deleted at request signing attempt. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Tag compatible browsers, frameworks, and libraries","url":"https://docs.contentsquare.com/en/web/compatibility/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Content Security Policy (CSP) - Web description: List of directives, values, and domains required by the Tag lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/web/content-security-policy/ md: https://docs.contentsquare.com/en/web/content-security-policy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. If your website uses a Content Security Policy (CSP), you need to allow the sources the Contentsquare tag relies on so it can collect data. The required directives are broken down by product. Each section shows the full CSP policy for that product, building on the Experience Analytics base policy and highlighting the directives specific to it. ## Experience Analytics ### Base policy Base policy directives are the foundation of your Contentsquare setup. They allow the core tag to install and load, and they enable essential features such as data collection, Session Replay, and Static Asset Management: ```http Content-Security-Policy: script-src 'unsafe-inline' *.contentsquare.net; img-src *.contentsquare.net; connect-src *.contentsquare.net *.contentsquare.com ``` Wildcards The base policy uses the `*.contentsquare.net` and `*.contentsquare.com` wildcards. This covers all subdomains for features like Zoning, Session Replay, and Static Asset Management, while ensuring future compatibility. All are Contentsquare-controlled domains. If your security policy restricts wildcards, contact your Contentsquare representative for a project-specific host list based on your tag configuration. | Directive | What it allows | What breaks without it | | - | - | - | | `script-src *.contentsquare.net` | Loading the Contentsquare tag and the additional Contentsquare-hosted scripts it bootstraps at runtime (for example the Voice of Customer widget) | The tag does not load — nothing is collected | | `script-src 'unsafe-inline'` | Running the inline installation snippet and any custom implementation code you add in a `<script>` block (for example to trigger artificial pageviews, set custom variables, or push events) | The install snippet and your inline implementation code are blocked — the tag does not initialize | | `img-src *.contentsquare.net` | Sending collected data through pixel (image) requests | Collected data is not sent to Contentsquare | | `connect-src *.contentsquare.net *.contentsquare.com` | Sending data through `XMLHttpRequest`/`fetch`, plus tag verification (`*.contentsquare.com`) | Data is not sent, and tag verification fails | ### Why `script-src 'unsafe-inline'` is required The `'unsafe-inline'` directive is included in our base policy to accommodate how the tag is integrated into your website, rather than how it operates at runtime. The Contentsquare tag itself does not inject inline scripts or use inline event handlers. Instead, the requirement typically stems from two integration points: * **Installation snippet:** when the tag is added directly to your HTML as an inline `<script>` block. * **Custom implementation code:** when inline scripts handle custom events, trigger artificial pageviews, or set custom variables. #### Removing `'unsafe-inline'` for strict CSPs If your organization enforces a strict CSP and wants to remove `'unsafe-inline'`, either move the Contentsquare tag installation snippet and related implementation code to an external file or secure them with a CSP nonce. Because the best approach depends on your own website architecture and deployment tools, configuring it falls outside the scope of this documentation. You should review your site's deployment workflow with your engineering team to determine the best path forward. Implementing cross-domain tracking does not introduce an `'unsafe-inline'` requirement. Because the cross-domain iframe operates as a separate origin, it is governed by its own standalone security policy. To enable this feature, add the `frame-src` directive pointing to `csxd.<domain>`. ### Optional features Add these directives **only if you use the corresponding feature**: | Feature | Add to your CSP | What breaks without it | | - | - | - | | Cross-domain tracking | `frame-src csxd.<domain>` — one entry per cross-domain host, for example `frame-src csxd.domain1.com csxd.domain2.com`. If you use the single Contentsquare-hosted iframe, add `frame-src csxd.contentsquare.net` instead. | Sessions are not linked across your domains | | Zoning / screenshot from the Contentsquare app | `script-src app.contentsquare.com` | Contentsquare users cannot build a zoning or screenshot from the app. No impact on end-visitor data collection. | ## Voice of Customer Voice of Customer includes the base policy and `style-src 'unsafe-inline'`: ```http Content-Security-Policy: script-src 'unsafe-inline' *.contentsquare.net; img-src *.contentsquare.net; connect-src *.contentsquare.net *.contentsquare.com; style-src 'unsafe-inline' ``` | Directive | What it allows | What breaks without it | | - | - | - | | `style-src 'unsafe-inline'` | Voice of Customer applies styles inline when rendering a survey | Surveys render without their styling | ## Product Analytics Product Analytics introduces two integration components: * **Heap SDK** (`heap.js`): loaded on your pages by the Contentsquare tag when your project is configured to also load Heap, and served from `*.heap-api.com`. If your project is not configured to load the Heap SDK, these hosts are not required. * **Visual Labeler**: loaded only when your site is opened inside the Contentsquare app for event tagging, and served from `heapanalytics.com`. The Product Analytics policy includes the base policy and the following directives: * **`'unsafe-eval'`:** required only by the Visual Labeler for in-app event tagging — never by the core tag, and never for end-visitor data collection. It applies only while a Contentsquare user has your site open in the app. * **`app.contentsquare.com`:** the Visual Labeler runs inside the Contentsquare app, so the optional [`app.contentsquare.com` directive](#optional-features) also applies. - US ```http Content-Security-Policy: script-src 'unsafe-inline' *.contentsquare.net 'unsafe-eval' https://cdn.us.heap-api.com https://heapanalytics.com; img-src *.contentsquare.net https://heapanalytics.com; connect-src *.contentsquare.net *.contentsquare.com https://c.us.heap-api.com https://heapanalytics.com; style-src https://heapanalytics.com; font-src https://heapanalytics.com ``` | Directive | What it allows | What breaks without it | | - | - | - | | `script-src https://cdn.us.heap-api.com` | Loading the Heap configuration script `heap_config.js` and the Heap SDK script `heap.js` | The Heap SDK does not load | | `script-src https://heapanalytics.com` | Loading the Visual Labeler script | The Visual Labeler does not load | | `script-src 'unsafe-eval'` | Visual Labeler rendering | The Visual Labeler fails to render | | `img-src https://heapanalytics.com` | Loading the Visual Labeler image assets | Visual Labeler image assets do not load | | `connect-src https://c.us.heap-api.com` | Sending events through the Heap SDK | Heap SDK events are not sent | | `connect-src https://heapanalytics.com` | Fetching environment settings for the Visual Labeler | The Visual Labeler cannot fetch environment settings | | `style-src https://heapanalytics.com` | Loading the Visual Labeler stylesheets | The Visual Labeler renders without its styling | | `font-src https://heapanalytics.com` | Loading the Visual Labeler custom fonts | The Visual Labeler falls back to default fonts | - EU ```http Content-Security-Policy: script-src 'unsafe-inline' *.contentsquare.net 'unsafe-eval' https://cdn.eu.heap-api.com https://cdn.us.heap-api.com https://heapanalytics.com https://eu.heapanalytics.com; img-src *.contentsquare.net https://heapanalytics.com https://eu.heapanalytics.com; connect-src *.contentsquare.net *.contentsquare.com https://c.eu.heap-api.com https://heapanalytics.com https://eu.heapanalytics.com; style-src https://heapanalytics.com https://eu.heapanalytics.com; font-src https://heapanalytics.com https://eu.heapanalytics.com ``` | Directive | What it allows | What breaks without it | | - | - | - | | `script-src https://cdn.eu.heap-api.com` | Loading the Heap SDK script `heap.js` | The Heap SDK does not load | | `script-src https://cdn.us.heap-api.com` | Loading the Heap configuration script `heap_config.js` | The Heap SDK does not load | | `script-src https://heapanalytics.com https://eu.heapanalytics.com` | Loading the Visual Labeler script | The Visual Labeler does not load | | `script-src 'unsafe-eval'` | Visual Labeler rendering | The Visual Labeler fails to render | | `img-src https://heapanalytics.com https://eu.heapanalytics.com` | Loading the Visual Labeler image assets | Visual Labeler image assets do not load | | `connect-src https://c.eu.heap-api.com` | Sending events through the Heap SDK | Heap SDK events are not sent | | `connect-src https://heapanalytics.com https://eu.heapanalytics.com` | Fetching environment settings for the Visual Labeler | The Visual Labeler cannot fetch environment settings | | `style-src https://heapanalytics.com https://eu.heapanalytics.com` | Loading the Visual Labeler stylesheets | The Visual Labeler renders without its styling | | `font-src https://heapanalytics.com https://eu.heapanalytics.com` | Loading the Visual Labeler custom fonts | The Visual Labeler falls back to default fonts | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Content Security Policy (CSP)","description":"List of directives, values, and domains required by the Tag","url":"https://docs.contentsquare.com/en/web/content-security-policy/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Cookies - Web description: List of cookies and local storage items managed by the Contentsquare Tag lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/web/cookies/ md: https://docs.contentsquare.com/en/web/cookies/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. List of cookies and local storage items managed by the Contentsquare Tag. Contentsquare is only using first-party cookies for analytics purposes. Note Tools such as OneTrust may flag a cookie `_cs_nnnnnnnnnnnnn` as coming from Contentsquare, which is incorrect. In this context, `nnnnnnnnnnnnn` refers to an unknown pattern of numbers such as in `1083746253643` or `1111111111111`. Contentsquare is not setting any cookie with a name like `_cs_nnnnnnnnnnnnn` or `_cs_1083746253643`. | Name | Duration | Description | Applies to | | - | - | - | - | | [`_cs_id`](#_cs_id) | 13 months | Stores technical user data | All plans | | [`_cs_s`](#_cs_s) | 30 minutes | Stores session data | All plans | | [`_cs_c`](#_cs_c) | 13 months | Stores user consent on use of session data use within replays (not masked vs. full masked) | All plans | | [`_cs_s_ctx`](#_cs_s_ctx) | 30 minutes | Stores the Session context data | Product Analytics | | [`_cs_i`](#_cs_i) | 3 days | Stores the encryption result of the user identity string | Product Analytics | | [`_cs_cvars`](#_cs_cvars) | Session length | Stores the URL-encoded custom variables from the session | All plans | | [`_cs_ep`](#_cs_ep) | 13 months | Stores the visit-level custom properties as a JSON object | Product Analytics | | [`_cs_ex`](#_cs_ex) | 30 days | When set, the user is excluded from tracking | Enterprise | | [`_cs_optout`](#_cs_optout) | 13 months | When set, the user is opted-out from tracking | All plans | | [`_cs_t`](#_cs_t) | Immediately removed | Checks if the browser supports cookies and sets flags | All plans | | [`_cs_same_site`](#_cs_same_site) | Immediately removed | Checks if the browser supports the `SameSite` flag | All plans | | [`_cs_root-domain`](#_cs_root-domain) | Immediately removed | Stores the URI-encoded main domain name of the site | All plans | | [`_cs_debug`](#_cs_debug) | Session length | Enables/disables specific behavior of the Tag for debugging purposes | All plans | | [`_hjHasCachedUserAttributes`](#_hjhascacheduserattributes) | Session length | Specifies whether the data set in `_hjUserAttributes` local storage item is up to date or not | All plans | | [`_hjUserAttrbutesHash`](#_hjuserattributeshash) | 2 minutes, extended every 30 seconds | Specifies whether any user attribute has changed and needs to be updated | All plans | | [`_hjUserAttributes`](#_hjuserattributes) | No explicit expiration | Local storage item containing user attributes sent through the Identify API | All plans | | [`_hjClosedSurveyInvites`](#_hjclosedsurveyinvites) | 365 days | Ensures the same invite does not reappear if it has already been shown. Set when a user interacts with a Link Survey invitation modal. | All plans | | [`_hjDonePolls`](#_hjdonepolls) | 365 days | Ensures the same Survey does not reappear if it has already been filled in. | All plans | | [`_hjMinimizedPolls`](#_hjminimizedpolls) | 365 days | Ensures that the Survey stays minimized when the user navigates through your site. Set when a user minimizes an on-site Survey. | All plans | | [`_hp2_hld*`](#_hp2_hld) | Immediately removed | Used to determine which domain a cookie can be set on (since public suffix domains block setting cookies on the top level). May appear as numbered variants (such as `_hp2_hld1` or `_hp2_hld2`). | All plans | | [`_hp5_event_props.ENV_ID`](#_hp5_event_propsenv_id) | 13 months minus a day | Event properties cookie | All plans | | [`_hp5_let.ENV_ID`](#_hp5_letenv_id) | 13 months minus a day | Contains last event timestamp | All plans | | [`_hp5_meta.ENV_ID`](#_hp5_metaenv_id) | 13 months minus a day | Contains all metadata related to user/session | All plans | | [`_cs_mk_aa`](#_cs_mk_aa) | 30 minutes | Ensures Adobe Analytics dimensions and eVars are set only once every 30 minutes | All plans | | [`_cs_mk_ga`](#_cs_mk_ga) | 30 minutes | Ensures Google Analytics dimensions and eVars are set only once every 30 minutes | All plans | | [`_cs_mk_pa`](#_cs_mk_pa) | 30 minutes | Ensures Piano Analytics dimensions and eVars are set only once every 30 minutes | All plans | | [`_cs_rl_*`](#_cs_rl_) | 365 days | For integrations that require replay links to be stored into cookies. | All plans | | [`_cs_tld{nnnnnnnnnnnnn}`](#_cs_tldnnnnnnnnnnnnn) | Immediately removed | Cookies generated for Google Analytics and Adobe Analytics integrations which help determine the main domain on which to create integration cookies | All plans | ## Tag cookies Cookies required by the Contentsquare tag to collect reliable data. ### `_cs_id` #### Description Stores technical user data. Contains the following information separated by dots: * User ID, * User creation timestamp (seconds), * Number of visits, * Last pageview timestamp (seconds), * Last visit timestamp (seconds), * Timestamp of the last time this visitor was drawn, * Cookie expiration date, * Cookie `SameSite` attribute: * `None`: For cross-domain projects, * `Lax`: For projects that are not cross-domains, * `X`: When browsers that do not support the `SameSite` cookie attribute. * Cookie `Secure` attribute value: * `0`: cookie is not secure. Default for projects that are not cross-domain or if the browser doesn't support the `SameSite` cookie attribute, * `1`: cookie is secure, default for cross-domain projects. #### Lifetime 13 months, fixed. The cookie value is updated with every pageview. The cookie is recreated if the visitor can be tracked and no `_cs_id` cookie exists. #### Length Up to 103 characters. #### Example `5c8f99e9-46cc-a2cc-b049-031bfdb3d43b.1661526503.5.1661785703.1661785703.1.1695690503380` ### `_cs_s` #### Description Stores session data. Contains the following data separated by dots: * The number of pages viewed for the current session, * The Session Replay data collection state: * For the legacy Session Replay data collection pipeline: * `1` when not collected, * `3` when collected, * `5` when collected after a specific trigger. * For the main Session Replay data collection pipeline: * `0` when not collected, * `5` when collected. * The Replay consent state (internal use only, not relevant to customers), * The Event Triggered Replay (ETR) Status: * `3` (`ETR_SAVED_SESSION`) when the session is being saved by ETR, * `9` (`ETR_NOT_SAVED_SESSION`) when the session is not being saved by ETR. * The cookie expiry timestamp (Epoch time). When ETR is activated for the session, the 2nd value (Session Replay data collection state) is `0` (analytics only) and the 4th value (ETR Status) is `3`. #### Length Between 21 and 24 characters. The maximum number of characters depend on the number of pages seen during the session. #### Lifetime 30 minutes, renewed with every user action. #### Example `5.0.U.3.1773077954508` ### `_cs_c` #### Description Stores user consent on use of session data use within replays (not masked vs. full masked): * `1` (consent not expressed) — visitor session is fully masked. * `2` (consent granted) — visitor session is not fully masked even if the feature is enabled. * `3` (consent withdrawn) — visitor session is fully masked even if the feature is not enabled. * `0` (masking not required) — visitor session is not fully masked. Note The value `0` means that full masking was deactivated in your project configuration. This is applicable for projects having no sensitive data or having masked all their sensitive data. #### Lifetime 13 months, renewed when consent is updated. ### `_cs_s_ctx` #### Description Stores the Session context data. Contains a URL encoded stringified JSON object with the following data: * `firstViewTime`: The timestamp of the first pageview of the session. * `firstViewUrl`: The URL of the first pageview of the session. * `sessionReferrer`: The referrer of the first pageview of the session. #### Length Due to the nature of the data, the length of this cookie can vary significantly and can be problematic if you enforce a cookie size limitation on your servers. The following rules are applied to limit its length: 1. Each URL (`firstViewUrl`, `sessionReferrer`) is truncated to 800 characters. 2. The cookie is automatically compressed when its length exceeds 256 characters. #### Lifetime 30 minutes, renewed with every user action. #### Example Example of URL-decoded data: ```json { "firstViewTime":1753968212429, "firstViewUrl":"https://contentsquare.com/", "sessionReferrer":"https://www.google.com/" } ``` ### `_cs_i` #### Description Stores the result of the encryption of the user identity string when the user is currently associated with an identity string via the [identify](https://docs.contentsquare.com/en/web/command-reference/#identify) command. Stores as well the first 8 characters of the hash of the key used for its encryption and the user id: `_cs_i` = `<user_id>.<identity_string_encryption_result>.<encryption_key_hash>` #### Length The total length is 566. In details: 36 (`user_id`) + 1 (separator) + 512 (`identity_string_encryption_result`) + 1 (separator) + 16 (`encryption_key_hash`). #### Lifetime 3 days, renewed when the [identify](https://docs.contentsquare.com/en/web/command-reference/#identify) command is run. #### Example `7e845c32-0783-a6b4-cc0b-f995f4881782.YgQw555v3uL98tBy9qIjPvaZsPeauaCZzci67hWElRDuvfNqHyNHs6RbUDzIRYnGBWZHPxnw1wOydMzM8EXMjoi+Qn+z2hJPNwBaqoslRFuKSlI6OZljo9LEqzobQy0v4DZgUSy4ezhAKw8Om6FNAsgjNB+XPSG34EsDGWAhtCp2CKLOv2eHc5Secs+5STxATXM5J2dmzEonVyxSKX8pH4bCassn2SzSwyYcxyuhIv9ySgx6KI1ru2eMo5yUUUfsSQXsHf5VrqtX7P9n0M00M4jhA+m3gIuBk4yG4mjMJ7V7YKClbIjLYvvfVaGkPmkjlDmTa6f0vSJXeBXWL28Ikd2JJiwsT28WB8YBxvzNTvgXnzThAPREsipPSeA211RD/FVvgwOYpFfSbcZIjlRS8j6pTFyPxvRH64N1CNp7S7wJ8z6g2efH4w7PiLeulAQbGKthewCeiVfpmLJ9OWE5FHr9ahw8pFxTM3luLxrcDTuTfho0C9Jci+Nwlnk9z3Do.d5ae589256d3ff1c` ### `_cs_cvars` #### Description Includes the URL-encoded custom variables from the session. Used only when using custom vars in scope `visit` or without scope. #### Example This will store custom vars inside `_cs_cvars`: ```javascript window._uxa.push(["setCustomVariable", 5, "cvar_name", "cvar_value", "visit"]); ``` ```javascript window._uxa.push(["setCustomVariable", 5, "cvar_name", "cvar_value"]); ``` This will **not** store custom vars inside `_cs_cvars`: ```javascript window._uxa.push(["setCustomVariable", 5, "cvar_name", "cvar_value", "page"]); ``` #### Lifetime While the session lasts. Created when session-level custom variables are triggered. The value and expiration date are updated with each pageview. #### Length The minimum number of characters is 39. Length depends on how many custom variables are pushed and the length of the keys and values passed. ### `_cs_ep` Product Analytics #### Description Stores visit-level custom properties as a URL-encoded JSON object. Custom properties are set through the [`customProperties:visit:add`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitadd) Tag command and persist across pages for the duration of the cookie. Values are sanitized before storage: * Strings are stored as-is. * Numbers and booleans are converted to strings. * Arrays are joined with `||`. * Objects are dropped. #### Lifetime 13 months, renewed when custom properties are updated. The cookie is removed when the [`customProperties:visit:clear`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitclear) command is called or when the user opts out. #### Example URL-decoded value: ```json {"plan":"premium","country":"FR"} ``` ### `_cs_ex` Enterprise #### Description Contains the timestamp of the last time this visitor was drawn. Used to exclude visitors from being tracked when: * The Sample Rate defined for the project is below 100%. * The user is not selected to be tracked (generated number for user < Sample Rate). #### Lifetime 30 days, renewed on Tag run. ### `_cs_optout` #### Description When set, the user is opted-out from tracking. The cookie is set when you implement and run the `optout` Tag command, for users who [do not consent to data collection](https://docs.contentsquare.com/en/web/send-the-users-decisions-about-data-collection/#users-who-refuse-data-collection). #### Lifetime 13 months, fixed. ### `_cs_t` #### Description Whether the browser supports cookies. If so, the Tag sets the `SameSite` flag to `None` and the `Secure` flag to `Yes`. Always `1`. #### Lifetime Immediately removed. ### `_cs_same_site` #### Description Used to check if the browser supports the `SameSite` flag. The value is always `Test same site`. #### Lifetime Immediately removed. ### `_cs_root-domain` #### Description Stores the URI-encoded main domain name of the site. #### Lifetime Immediately removed. #### Example `https%3A%2F%2Fusps.com` for the domain `usps.com`. ### `_cs_debug` #### Description Enables/disables specific behavior of the Tag for debugging purposes. Danger You can only use this cookie to inspect the uncompressed payload content, not to perform complete end-to-end data collection tests. Requests with uncompressed payloads are filtered out by our Session Replay pipeline. You will **not** be able to replay **any** session collected with the `compressionDisabled` flag on. Supported flags: * `compressionDisabled`: disables payload compression for inspection in the browser. #### Lifetime Session duration. To be created and deleted manually. #### Length N/A #### Example N/A ## Voice of Customer cookies ### `_hjHasCachedUserAttributes` Voice of Customer Specifies whether the data set in `_hjUserAttributes` local storage item is up to date or not. #### Lifetime Session duration. #### Example `true` ### `_hjUserAttributesHash` Voice of Customer Specifies whether any user attribute has changed and needs to be updated. #### Lifetime 2 minutes, extended every 30 seconds. #### Example `5fc3d78656281a4f251d087894032eaa` ### `_hjUserAttributes` Voice of Customer Local storage item containing user attributes sent through the Identify API. #### Lifetime No explicit expiration. #### Example `eyJhdHRyaWJ1dGVzIjp7InRlc3QiOiJ0ZXN0In0sInVzZXJJZCI6bnVsbH0` ### `_hjClosedSurveyInvites` Voice of Customer A list of Survey IDs, URL encoded. Ensures the same invite does not reappear if it has already been shown. Set when a user interacts with a Link Survey invitation modal. #### Lifetime 365 days. #### Example `840982%2C841051%2C733219%2C155923%2C853559%2C859932%2C866639%2C898685%2C896429%2C899130%2C921824%2C951201%2C788909` ### `_hjDonePolls` Voice of Customer A list of Survey IDs, URL encoded. Ensures the same Survey does not reappear if it has already been filled in. #### Lifetime 365 days. #### Example `840982%2C841051%2C733219%2C155923%2C853559%2C859932%2C866639%2C898685%2C896429%2C899130%2C921824%2C951201%2C788909` ### `_hjMinimizedPolls` Voice of Customer A list of Survey IDs, URL encoded. Ensures that the Survey stays minimized when the user navigates through your site. Set when a user minimizes an on-site Survey. #### Lifetime 365 days. #### Example `840982%2C841051%2C733219%2C155923%2C853559%2C859932%2C866639%2C898685%2C896429%2C899130%2C921824%2C951201%2C788909` ## Product Analytics cookies ### `_hp2_hld` Product Analytics #### Description Used to determine the highest-level domain a cookie can be set on (since public suffix domains block setting cookies on the top level). During this domain detection process, numbered variants such as `_hp2_hld1`, `_hp2_hld2`, or `_hp2_hld3` may be created temporarily — one per subdomain tested. All variants are immediately removed after the check completes. Note Tools such as OneTrust may flag multiple `_hp2_hld*` entries. You can configure OneTrust to use the wildcard `_hp2_hld*` to cover all variants. #### Lifetime Immediately removed. ### `_hp5_event_props.ENV_ID` Product Analytics #### Description Event properties cookie. #### Lifetime 13 months minus a day. ### `_hp5_let.ENV_ID` Product Analytics #### Description Contains last event timestamp. #### Lifetime 13 months minus a day. #### Example ```txt 1736522139241 ``` ### `_hp5_meta.ENV_ID` Product Analytics #### Description Contains all metadata related to user/session. #### Lifetime 13 months minus a day. #### Example ```json { "setPath": {}, "userId": "6491850061908711", "sessionId": "6327163630185553", "lastEventTime": 1717426613532, "sessionProperties": { "time": 1717426613532, "referrer": "", "id": "6327163630185553", "search_keyword": "", "utm": { "source": "", "medium": "", "term": "", "content": "", "campaign": "" }, "initial_pageview_info": { "time": 1717426613532, "id": "8208811256027992", "title": "Landing page", "url": { "domain": "user.host.io", "path": "/pa-cs/page1.html", "query": "", "hash": "" }, "source_properties": { "screen_height": 874, "screen_width": 621 }, "properties": {} } } } ``` ## Integration cookies Cookies used when third-party integrations are enabled. ### `_cs_mk_aa` #### Description Ensures Adobe dimensions and eVars are set only once every 30 minutes. Stores the value of the `csMatchingKey` which is a random number plus timestamp in milliseconds. #### Lifetime 30 minutes. #### Example `0.004432816788423777_1593783518901` ### `_cs_mk_ga` #### Description Ensures Google dimensions and eVars are set only once every 30 minutes. Stores the value of the `csMatchingKey` which is a random number plus timestamp in milliseconds. #### Lifetime 30 minutes. #### Example `0.004432816788423777_1593783518901` ### `_cs_mk_pa` #### Description Ensures Piano dimensions and eVars are set only once every 30 minutes. Stores the value of the `csMatchingKey` which is a random number plus timestamp in milliseconds. #### Lifetime 30 minutes. #### Example `0.004432816788423777_1593783518901` ### `_cs_rl_*` #### Description For integrations that require replay links to be stored into cookies. #### Lifetime 1 year. Updates on every pageview. #### Example `https://app.contentsquare.com/quick-playback/index.html?pid=2887&uu=022d47a4-ef01-a959-f9df-be7b104e2762&sn=5&pvid=1` ### `_cs_tld{nnnnnnnnnnnnn}` #### Description Cookies generated for Google Analytics and Adobe Analytics integrations which help determine the main domain on which to create integration cookies. `{nnnnnnnnnnnnn}` is the timestamp. #### Lifetime Immediately removed. #### Example `_cs_tld1670937307564` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Cookies","description":"List of cookies and local storage items managed by the Contentsquare Tag","url":"https://docs.contentsquare.com/en/web/cookies/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Core concepts - Web description: Core concepts to learn about when implementing the Tag lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/web/core-concepts/ md: https://docs.contentsquare.com/en/web/core-concepts/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare provides all indicators necessary to precisely analyze web user experience. It requires the setting up of the Contentsquare Tracking Tag to collect data. Learn the main concepts behind the Contentsquare collection tool, how the library works, and the available commands. ## Account and project identifier Your subscription to a Contentsquare contract gives you access to a **tag ID** composed of 13 characters. Each ID is a tag instance for which are notably setup: * The authorized domains (and subdomains if authorized), * IP addresses to exclude from the collection, * The visitors' inclusion percentage for every collected data. A project ID corresponds to only one instance on this configuration. Consequently, if you want different inclusion percentages following sections of the site, you will need several tag IDs, meaning that data will be aggregated in several accounts separated on the Contentsquare interface. ### Several domains It is possible to associate several domains on the same account. **By default, a browsing session on a domain doesn't continue on another domain.** For example, a web user going from `domain.com` to `otherdomain.com` will be identified as a "site exit" on `domain.com` and identified as a "new visitor" on `otherdomain.com`. This is because Contentsquare doesn't use third-party cookies. #### Activating Cross-domain analysis Warning Cross-domain tracking does not work on Safari and Firefox. Note Cross-domain tracking will only work if HTTPS is enabled. It is possible to configure the tag so that a session started on a domain stays alive on another one. This is **cross-domain tracking**. There are two possible implementations of cross-domain tracking: * iFrames hosted on customer domains * iFrame hosted on Contentsquare domain #### iFrames hosted on customer domains The Tracking Tag will retrieve Contentsquare cookies on every domain configured for the project. It uses all iFrames to read cookies from the customer domains. **Example:** Consider a project with 2 domains `weballwin.com` and `weballwin.net`. When loaded on `weballwin.com`, the Tag opens an iFrame on `csxd.weballwin.net`. This specific `csxd.`sub-domain redirects the browser to an HTML page served by Contentsquare which allows to read Contentsquare's cookie on `weballwin.net`. The Tag uses the most up-to-date cookies, from `weballwin.com` or `weballwin.net`, and which contain session data. **Setup**: Every domain's `csxd.*` subdomain must be redirected to Contentsquare servers with a DNS entry, and associated with an SSL certificate. If using foreign SSL certificates isn't allowed by your IT Policy, a self-hosted alternative can be set up. Restrictions for iFrames hosted on customer domains This feature can link **up to 5 domains** to ensure good performance. It does **not** work on Safari or Firefox. #### iFrame hosted on Contentsquare domain The Tracking Tag will read and write a copy of its cookies on a Contentsquare domain using a single iFrame. **Example:** Consider a project with 2 domains `weballwin.com` and `weballwin.net`. When loaded on `weballwin.com`, the Tag opens an iFrame on `contentsquare.net` to read cookies present for this project; if cookies are present, the Tag uses the most up-to-date cookies, from `weballwin.com` or `weballwin.net`, and which contain session data. The Tag then writes new, up-to-date cookies on `contentsquare.net`. This approach does not require any setup from your part, except if you use a Content Security Policy (CSP): you must add `frame-src csxd.contentsquare.net` to your CSP directive. See [Content Security Policy](https://docs.contentsquare.com/en/web/content-security-policy/#experience-analytics) for details. Restriction for the iFrame hosted on Contentsquare domain It does **not** work on Safari or Firefox. ### One domain, several accounts If you are using different Contentsquare accounts for the same main domain, you may encounter this behavior: * A visitor enters a part of the domain tracked by an account. * The same visitor navigates to a part of the domain tracked by another account. As Contentsquare doesn't use third-party cookies, going back and forth between accounts may alter data accuracy. Some transactions may be collected on the wrong account for instance. ### Multinational domains If your site hosts multiple versions of the same content under a single domain, you can either choose to assign a separate tag to each different country or to bundle them all together under one single tag. #### One tag, One country This approach will allow you to split the analysis by country, making the Contentsquare account configuration quicker. We advise to follow this path if there are separate teams working on separate countries/sections that don't need to compare cross-country data. #### One tag, Multiple countries This approach will allow you to tag the whole site with just one **tag id**, making the Contentsquare implementation quicker. However, when configuring the Contentsquare account you will need to separate the different sites and create ad-hoc segments to analyze each different site/country. ## Pageviews A **pageview** is a page visit by a web user. It includes, among other things, the current URL of the page, the screen size, the window size and the size of the document. It is sent automatically. [Detailed information here...](https://docs.contentsquare.com/en/web/sending-pageviews/) When a web user is included in the analysis, **pageviews** are sent: * When the main tag is called, meaning every time a page fully loads ("full reload") but not during Ajax loading, * The `trackPageview` command is called, * From every frame loading the tag if the `iFrameTracking` tag has been activated by Contentsquare and the `trackPageview` command is called within the iFrame. [Learn more about the population included in the analysis...](https://docs.contentsquare.com/en/web/who-is-included-in-the-analysis/) [Learn more about sending pageviews...](https://docs.contentsquare.com/en/web/sending-pageviews/) ## Transaction To link a web user's visit with their potential purchases, meaning the corresponding revenue, it is necessary to send the transaction via a dedicated command which includes, among other things, the reference of the purchase, its amount, which articles were bought, etc. [Learn more about transaction sending...](https://docs.contentsquare.com/en/web/sending-ecommerce-commands/) ## Events When the main tag is loaded, our solution will collect and transmit **most interactions** happening on the page: mouseovers and clicks will thus be processed to give you UX indicators on the elements composing the page. Only the population included in the analysis is studied. the tag itself does not collect nominative information on visitors. [Learn more about the included population in the analysis...](https://docs.contentsquare.com/en/web/who-is-included-in-the-analysis/) [Learn more about collected data...](https://docs.contentsquare.com/en/web/collected-data/) ## Custom data ### Custom vars In addition to information automatically integrated in pageviews, it is possible to add data which will ease websites mapping and segmentation. To do so, you can add up to **20 personalized variables** ("custom vars") which will be sent along with pageviews. [Learn more about sending custom vars...](https://docs.contentsquare.com/en/web/sending-custom-vars/) ### Dynamic Vars Dynamic vars are additional information on the session that can be used to segment users like A/B Test variations displayed to the current user. It can be fired at any point in time up to 40 per pageview. [Learn more about sending dynamic vars...](https://docs.contentsquare.com/en/web/sending-dynamic-vars/) ### Page events A page event or a custom page event is a value (an element or an event) triggered during a session on a specific page. Each page event is unique. They are created to answer a client request, thus they are very varied. [Learn more about sending custom page events...](https://docs.contentsquare.com/en/web/custom-page-events/) ### Page events vs Custom Vars vs Dynamic Vars | Custom Vars | Dynamic Vars | Page events | | - | - | - | | Fired at pageview | Fired at any point in time | Fired at any point in time | | Up to 20 Custom Vars per pageview | Up to 40 Dynamic Vars per pageview | Up to 40 page events per pageview | | Keys of 512 chars. max and values of 255 chars. max | Key of 50 chars. max and values of 255 chars. max | String, values of 255 chars. max | #### Examples of use cases * **Custom Vars** are used for page template/category. * **Dynamic Vars** are commonly used for A/B testing. * **Page events** are used to trigger ETR (example: VoC form submission) and Custom Visitor Identification (example: Customer ID or Order number) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Core concepts","description":"Core concepts to learn about when implementing the Tag","url":"https://docs.contentsquare.com/en/web/core-concepts/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Custom Page Events - Web description: A page event or a custom page event is a value (an element or an event) triggered during a session on a specific page lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/web/custom-page-events/ md: https://docs.contentsquare.com/en/web/custom-page-events/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Custom page events are named signals you send from JavaScript to mark specific user actions, which can then be used for segmentation and as triggers for Event Triggered Replay. ## General principles ### Use Custom page events are additional information on the session that can be used to segment sessions. Similar to dynamic vars, custom page events can be sent at any time during a session. Custom pages events are used when we want to segment based on a specific visitor (`action` or `onload`) event. They are as flexible as anything you can do with JavaScript on a web page. For instance, VoC events triggered (3 stars only, smiley face emoji…), specific messages and validation errors and even things like if page took more than x seconds to load, visitor's status, such as **"is the user logged in?"**,option selected in drop-down menu. And many more..., up to your imagination. Furthermore, it can also be used as a trigger for Event Triggered Replay (ETR) where the full user session or specific pageview is collected. ### Limits * It is possible to save up to 40 page events per pageview. If more are received, only the first 40 will be kept. * The maximum size is 255 characters. ## Contentsquare Tag Configurator (CSTC) Use the [Contentsquare Tag Configurator ↗](https://support.contentsquare.com/hc/en-us/articles/37271705463185-CSTC-Template-Page-Event) to implement page events through a visual interface. ## Google Tag Manager (Template) 1. Open your container and go to the **templates** section.  2. Select **Search Gallery**.  3. Type in **`contentsquare`** and select the **Contentsquare - Page Events** option.  4. Click **Add to workspace**.  5. Confirm your choice by selecting **Add**  6. Go to the Tags section and click the **New** button to create a new tag.  7. Configure it by selecting the top-right button.  8. Search for **`contentsquare`** and select the **Contentsquare - Page Events** template that you've previously added to your container.  9. Give a title to the tag and input your Tag ID in the dedicated field. 10. Enter the event name. 11. (Optional) If needed, add additional page events.  12. Select the trigger. 13. Save your changes and go back to your container. You should now see both the template and the newly created tag.  ## Adobe Launch Prerequisite You have installed the [Contentsquare extension](https://docs.contentsquare.com/en/web/#installing-the-contentsquare-extension). 1. Within Tag properties, select **Rules** > **Add Rule**. 2. Specify a name, events, and conditions. 3. Add an Action with the following settings: * Extension: `Contentsquare`, * Action Type: `Page Events`, * Name: `Contentsquare - Page Event`. 4. On the right-hand side, enter the event name.  5. Select **Keep Changes** > **Save**. ## Custom HTML ### Defining page Event To define a page Event which will be automatically sent right away, use the `trackPageEvent` command: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(["trackPageEvent", eventName]); </script> ``` For example, here's how to collect a click event: ```javascript window._uxa = window._uxa || []; window._uxa.push(["trackPageEvent", "SubscribedToPropertyButtonClick"]); ``` Or how to collect a user identifier to filter Session Replays, with the `@user-identifier@` prefix: Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(["trackPageEvent", "@user-identifier@USER_IDENTIFIER"]); </script> ``` [See User Identifiers](https://docs.contentsquare.com/en/web/personal-data-handling/#user-identifier-implementation) ## Verifying the sending of page events Our [Contentsquare Tracking Setup Assistant Chrome Extension ↗](https://chrome.google.com/webstore/detail/contentsquare-tracking-se/pfldcnnaiaiaogmpfdjjpdkpnigplfca) displays each page event sent. ### Inspecting the payload If you can't use our Chrome extension, use the [`_cs_debug`](https://docs.contentsquare.com/en/web/cookies/#_cs_debug) cookie. 1. From the browser console, run this command to create the cookie: ```plaintext document.cookie = "_cs_debug=compressionDisabled" ``` Note Sessions collected with the `compressionDisabled` flag on are filtered out from the Session Replay pipeline. 2. Reload the page. 3. In the Network tab, search for `pageEvent`, select the request, and check the value of the `value` parameter. ### Checking the requests To check the actual request that is sent for transactions, follow GET requests sent to `//c.contentsquare.net/pageEvent`, with these parameters. | Name | Description | Type | | - | - | - | | `value` | Page Event (compressed) | String | | `pid` | Project ID | Integer | | `r` | A random digit to avoid request caching | Integer | | `uu` | Unique user ID | String | | `pn` | Page number (each pageview increments of 1) | Integer | | `sn` | Session number | Integer | | `isETR` | Identifies the page Event has ETR or not | Boolean | | `v` | Tracking tag version | String | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Custom Page Events","description":"A page event or a custom page event is a value (an element or an event) triggered during a session on a specific page","url":"https://docs.contentsquare.com/en/web/custom-page-events/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Dynamic Variables Tag - Web description: Dynamic vars are additional information on the session that can be used to segment users lastUpdated: 12 December 2025 source_url: html: https://docs.contentsquare.com/en/web/dynamic-variables-tag/ md: https://docs.contentsquare.com/en/web/dynamic-variables-tag/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Dynamic vars are additional information on the session that can be used to segment users. For example, they can include information on the A/B Test variations displayed to the current user. Unlike custom vars, dynamic vars can be sent at any time during a session and do not require to send a pageview. For more information, see [Dynamic Vars](https://docs.contentsquare.com/en/web/sending-dynamic-vars/). ## Contentsquare Tag Configurator (CSTC) Use the [Contentsquare Tag Configurator ↗](https://support.contentsquare.com/hc/en-us/articles/37271814927633-CSTC-Template-Dynamic-Variable) to implement dynamic variables through a visual interface. ## Google Tag Manager (Template) 1. Open your container and go to the **templates** section.  2. Select **Search Gallery**.  3. Type in **`contentsquare`** and select the **Contentsquare - Dynamic variables** option.  4. Click **Add to workspace**.  5. Confirm your choice by selecting **Add**  6. Go to the Tags section and click the **New** button to create a new tag.  7. Configure it by selecting the top-right button.  8. Search for **`contentsquare`** and select the **Contentsquare - Dynamic variables** template that you've previously added to your container.  9. Give a title to the tag and input your Tag ID in the dedicated field. For each dynamic variable, enter: * The key * The value * The type - `Number` or `String`.  10. Select the trigger: `All Pages` or `DOM Ready` (when data layer has been fully loaded). 11. Save your changes and go back to your container. You should now see both the template and the newly created tag.  ## Adobe Launch Prerequisite You have installed the [Contentsquare extension](https://docs.contentsquare.com/en/web/#installing-the-contentsquare-extension). 1. Within Tag properties, select **Rules** > **Add Rule**. 2. Specify a name, events, and conditions. 3. Add an Action with the following settings: * Extension: `Contentsquare`, * Action Type: `Dynamic Variables`, * Name: `Contentsquare - Dynamic Variable tracking`. 4. On the right-hand side, select `Add New Variable`. 5. For each dynamic variable, enter: * The key * The value * The type - `Number` or `String`.  6. Select **Keep Changes** > **Save**. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Dynamic Variables Tag","description":"Dynamic vars are additional information on the session that can be used to segment users","url":"https://docs.contentsquare.com/en/web/dynamic-variables-tag/","inLanguage":"en","dateModified":"2025-12-12T22:25:41+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Error Analysis - Web description: Error Analysis enables you to quantify, prioritize and visualize errors occurring on your site lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/web/error-analysis/ md: https://docs.contentsquare.com/en/web/error-analysis/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Error Analysis enables you to quantify, prioritize, and visualize errors occurring on your site. This section covers all the information you need to enable proper error collection within Contentsquare. Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. ## JavaScript errors When displaying JavaScript errors in the Error Analysis module, the top error might be "Script error". Contentsquare collects errors via web browser, however the majority of browsers don't share the details of an error coming from another domain (function name, file) unless they are allowed to. That's why, for some errors, Contentsquare can only report "Script Error", as it is a setting coming from the browser and the hosting server. ### Scripts to unmask Start by mapping out JavaScript errors that your team struggle to reproduce and fix. Create a spreadsheet to list your third-party party providers and keep track of which scripts have been unmasked with the [`crossorigin` ↗](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) attribute. Bear in mind that some third-parties such as Google, Meta, or Adobe can't be unmasked. ### Unmasking script errors 1. Add `Add Access-Control-Allow-Origin` HTTP header on the script and a wildcard (`*`). ```http Access-Control-Allow-Origin: * ``` 2. Add `crossorigin=anonymous` on the script tag: ```javascript <script src="http://another-domain.com/app.js" crossorigin="anonymous"></script> ``` This instructs the browser to fetch the file anonymously so that no sensitive data is forwarded via cookie or HTTP authentication. ### Unmasking script errors locally Even though Contentsquare can't access any specific details about local errors, you can try to reproduce the error to know more which errors to unmask first. 1. Open your website on a page that consistently produces errors. 2. Open the browser console to view a full unmasked log of errors on this page. 3. Enter the following code to check what the Tag has access to when this error occurs: ```javascript window.onerror = function (errorName, file, lineNo, colNo, errStack) { debugger; }; ``` ### Masking script errors permanently 1. Choose the scripts to unmask The more scripts you unmask, the more errors you can collect. Start by prioritizing the scripts to unmask: * Ask among the website developers team * Select scripts from the Error Analysis module: some "Script Errors" point to a specific file * Ask third-party providers to do the same: their JavaScript libraries will be added to your watch list. Note The process of unmasking script errors applies globally, meaning you do not need to wait for new errors to be generated. This process unmasks all JS errors. 2. Add a cross-origin HTTP header on the server for these scripts: ```http Access-Control-Allow-Origin: * ``` 3. Add a `crossorigin="anonymous"` attribute on these scripts: ```javascript <script src="http://another-domain.com/app.js" crossorigin="anonymous"></script> ``` After 3 hours, the script errors should start being replaced by the actual details of the scripts in Error Analysis. ## API Errors API error collection helps you monitor site performance and user experience over time. You have the ability to collect additional information surrounding API Errors, about your analysis needs. ### Mask API errors URLs To ensure safe error collection, you may need to configure for Personal Data to be masked. See [Removing Personal Data in API errors](https://docs.contentsquare.com/en/web/personal-data-handling/#removing-personal-data-in-api-errors). ### Advanced troubleshooting API Errors Advanced Troubleshooting configuration enables you to create rules to collect more information about API errors (headers, request/response body content), and collect API errors with a status code, not only in the 4XX-5XX range, so you can troubleshoot errors faster. Use API Errors Advanced Troubleshooting to: * Setup collection of API errors for network requests where the HTTP status code is below 400. * See the following types of additional API error details in the Event Stream of Session Replay: * The HTTP headers of the request and the response * The body (the data sent by the request or received in the response) * The body elements (specific elements of the request/response body) * The query parameters of the request endpoint (of the URL of the information you request for). * Leverage unencrypted response body elements in Errors Dashboard and Alerts and Analysis Context to monitor, identify, and quantify errors based on response body content. For more information, see [Configuring API Error Collection Rules ↗](https://support.contentsquare.com/hc/en-us/articles/37271885035537-How-to-configure-API-error-collection-rules) ### Why CSP errors can reference `uxa.js` When API Errors tracking or Network Details is turned on for a project, the Tag patches browser network APIs (`fetch` and `XMLHttpRequest`) to collect request metadata. Because network requests made via these patched APIs pass through the Tag wrappers, `uxa.js` can appear in the call stack for requests started by other scripts that call `fetch` or `XMLHttpRequest`. If a request initiated via `fetch` or `XMLHttpRequest` is blocked by Content Security Policy (CSP), browser console logs can reference `uxa.js` in the stack. This does not mean the Tag is the origin of the blocked request. To identify the source of the CSP issue, inspect the blocked URL, the CSP directive, and the request initiator chain in browser DevTools. ## Custom errors With the Custom Errors feature, collect any text displayed on the user screen because of a specific action such as: * Filling a form, * Loading a product list, * Log in to a website, * A request failing to get the remaining stock quantity on a product page. Custom errors can be located inside alert banners, pop-up windows, or inline in a form. ### Sending custom errors You can send a maximum of 20 custom errors per page. [Tag Configurator Template: Custom Error](https://support.contentsquare.com/hc/en-us/articles/37271813052817-CSTC-Template-Custom-Error)Use the Tag Configurator to implement custom error tracking through a visual interface. To collect custom error messages, use the `trackError` command: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push([ "trackError", "<MESSAGE>", {key: value, key: value, ...} ]) </script> ``` where: * `<MESSAGE>` is a `string` which contains the text displayed to end-users (max. 300 characters). * (optional) - A JavaScript object with **up to 5 key/value pairs** to categorize the errors. Both the key and value should be `string` and can be up to 30 characters. **Examples** Send a custom error for a failing request, typed as an error from the system: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(["trackError", "Could not get stock quantity", { type: "systemError" }]); </script> ``` Send a custom error for incorrect user input with multiple attributes (type, severity, language): ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push([ "trackError", "140000 is not a valid postal code", { type: "formValidation", severity: "minor", lang: "english" }, ]); </script> ``` ### Verifying the sending of custom errors Use the [Contentsquare Tracking Setup Assistant Chrome Extension ↗](https://chrome.google.com/webstore/detail/contentsquare-tracking-se/pfldcnnaiaiaogmpfdjjpdkpnigplfca) to track custom errors that are sent.  ### Errors collection in Contentsquare Console Information retrieved from console messages can help developers understand what is happening behind the scenes, debug issues, and catch exceptions that don't usually block script execution. ## Console messages collection As a project administrator or Contentsquare implementation manager, configure the console messages collection: 1. Log into [https://console.contentsquare.com/ ↗](https://console.contentsquare.com/). 2. Within your project, navigate to `Advanced errors troubleshooting` > `Console messages`, and select `Add log levels`. 3. Select the levels and click `Apply`. It takes about one hour to see the analysis for console messages in the Error Analysis module. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Error Analysis","description":"Error Analysis enables you to quantify, prioritize and visualize errors occurring on your site","url":"https://docs.contentsquare.com/en/web/error-analysis/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: The E-commerce tag - Web description: The e-commerce tag is used to keep track of the e-commerce transactions happening on the site and empower analysis with revenue-related metrics lastUpdated: 18 June 2026 source_url: html: https://docs.contentsquare.com/en/web/ecommerce-tag/ md: https://docs.contentsquare.com/en/web/ecommerce-tag/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The e-commerce tag is used to keep track of the e-commerce transactions happening on the site and empower analysis with revenue-related metrics. It needs to be **fired a single time on the confirmation page**, after the transaction has been finalised, and needs the following **mandatory parameters** to function: * Transaction ID, which is the unique identifier for that transaction * Revenue, which is the total amount of the purchase You can also include the following **optional** parameters: * Currency, which is the currency used for the purchase and also in our platform for a potential conversion. [Full technical documentation firing the e-commerce tag...](https://docs.contentsquare.com/en/web/sending-ecommerce-commands/) ## Google Tag Manager (Template) 1. Open your container and go to the **templates** section  2. Select **Search gallery**  3. Type in **`contentsquare`** and select the **Contentsquare - E-commerce data** option  4. Click **Add to workspace**  5. Confirm your choice by selecting **Add**  6. Go to the Tags section and click the **New** button to create a new tag  7. Configure it by selecting the top-right button  8. Search for **`contentsquare`** and select the **Contentsquare - E-commerce data** template that you've previously added to your container.  9. Give a title to the tag and add your **GTM Variables** to the **Transaction IDs** and **Revenue** fields. Make sure to select a trigger that fires only on the confirmation page, or on all the pages that are needed to keep track of transactions, on which **your variables are going to be populated**.  10. If you would like to send Contentsquare the **currency** value as well, fill in the **optional parameters** section.  11. Save your changes and go back to your container. You should now see both the template and the newly created tag. ## Google Tag Manager (Custom HTML) 1. Create a new tag and paste the following code in the **HTML field**: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push([ "ec:transaction:create", { id: "{{YOUR ID HERE}}", revenue: "{{YOUR REVENUE HERE}}", currency: "{{CURRENCY ISO CODE HERE}}" }, ]); window._uxa.push(["ec:transaction:send"]); </script> ``` 2. Inside the script, **replace all the placeholder variables** with your GTM values (using the double brace notation: `{{transaction id}}`, `{{transaction revenue}}`). These variables must be available in the "Variables" section of Google Tag Manager. 3. In the trigger list, select the "Confirmation page", or create one if it doesn't exist. * Select the "+" on the top right, * Select "Choose a trigger type to begin setup..." * Pick "Window Loaded" * You don't want this to be trigger on every page, so choose "Some Window Loaded Events" * Add a condition to match only the confirmation page — for instance, `"Page URL" contains "checkout/confirmation"` * Save and name your trigger "Confirmation page" ## Tealium The Tealium extension will **automatically fire the Contentsquare transaction code** as soon as the transaction values defined have been populated in your `utag` datalayer. ## Adobe Launch Navigate to **Rules**, and open an existing rule or create a new one. ### Event Configuration The E-commerce tag **needs to be fired once on the confirmation page**, after a transaction has been made and needs to be tracked. to do so, **specify the path or the event** to be used as a trigger. For example, if you want to target the confirmation page, you could use a similar condition:  If you have chosen the event+condition route, your setup should look similar to this:  ### Action Configuration Select the **Contentsquare** extension and then **Ecommerce Transactions** as the action type.  You will then be prompted to fill in the required information by using either strings or Data Elements.  Given the dynamic nature of transaction details, **it is required to have previously setup Data Elements with the requested information**.  ## Commanders Act 1. Add a new tag to your container by choosing "Contentsquare (Builder)".  2. Set the right Contentsquare template selecting **Ecommerce**.  3. Fill in all required fields with your Commanders Act variables.  4. (Optional) If your transactions have different currencies, send Contentsquare the currency value.  5. (Optional) If you are a merchandising customer, add items. 6. Select a trigger/perimeter that fires only on the confirmation page, and click **Save**. Your Tag is ready to be deployed. ## Shopify The Contentsquare Shopify app automatically collects e-commerce transaction data during the checkout flow, eliminating the need for manual tagging. After you install the app, map each checkout domain to the matching Contentsquare Tag ID in Shopify. Transaction data (order ID, revenue, and currency) is automatically captured on checkout completion for mapped domains. For installation instructions, see [Shopify app installation](https://docs.contentsquare.com/en/web/#shopify). ### Transaction gaps with redirect-based payment methods Contentsquare tracks Shopify transactions by listening to the [`checkout_completed` ↗](https://shopify.dev/docs/api/web-pixels-api/standard-events/checkout_completed) Web Pixels event, which provides the order ID, amount, and currency. Some payment methods redirect the user to an external payment page before returning them to the "Thank You" page (for example, PayPal). In these cases, Shopify may not emit the `checkout_completed` event. As Shopify [documents ↗](https://shopify.dev/docs/api/web-pixels-api/standard-events/checkout_completed), if the page where the event is supposed to fire fails to load, the event is not triggered at all. **What you may observe:** Sessions with a "Checkout" page view followed by a "Thank You" page view can appear in the **Sessions without Transactions** segment even though the user completed a purchase. This results in fewer collected transactions in Contentsquare. Note This is not a Contentsquare implementation issue. The Contentsquare Shopify tag processes the `checkout_completed` event whenever Shopify emits it. ## Custom HTML Supply the transaction ID, revenue, and currency ISO code as parameters to the [`ec:transaction:create`](https://docs.contentsquare.com/en/web/command-reference/#ectransactioncreate) command, then run [`ec:transaction:send`](https://docs.contentsquare.com/en/web/command-reference/#ectransactionsend) to send the transaction to Contentsquare. ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(['ec:transaction:create', { 'id': {{TRANSACTION_ID}}, // String - unique transaction identifier 'revenue': {{TRANSACTION_REVENUE}}, // Number - transaction total (49.99) 'currency': {{CURRENCY_ISO_CODE}} // String - ISO 4217 currency code ('USD') }]); window._uxa.push(['ec:transaction:send']); </script> ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"The E-commerce tag","description":"The e-commerce tag is used to keep track of the e-commerce transactions happening on the site and empower analysis with revenue-related metrics","url":"https://docs.contentsquare.com/en/web/ecommerce-tag/","inLanguage":"en","dateModified":"2026-06-18T16:54:41+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: ETR Event Tag - Web description: The ETR event tag allows to trigger ETR events to save the collected session of the visitor lastUpdated: 12 December 2025 source_url: html: https://docs.contentsquare.com/en/web/etr-event-tag/ md: https://docs.contentsquare.com/en/web/etr-event-tag/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Note **Event-triggered Replay (ETR)** is a paid option which requires specific implementation. The ETR event tag allows to trigger ETR events to save the collected session of the visitor. For more information, see [Events Handling](https://docs.contentsquare.com/en/web/events-handling/). ## Google Tag Manager (Template) 1. Open your container and go to the **templates** section.  2. Select **Search Gallery**.  3. Type in **`contentsquare`** and select the **Contentsquare - ETR Event** option.  4. Click **Add to workspace**.  5. Confirm your choice by selecting **Add**  6. Go to the Tags section and click the **New** button to create a new tag.  7. Configure it by selecting the top-right button.  8. Search for **`contentsquare`** and select the **Contentsquare - ETR Event** template that you've previously added to your container.  9. Give a title to the tag and input your Tag ID in the dedicated field. 10. Enter the event name. 11. Select the event type: `Page Level` or `Session Level`.  12. Select the appropriate trigger to fire this tag only when you wish for the collection of Session Replay to be started. 13. Save your changes and go back to your container. You should now see both the template and the newly created tag.  ## Adobe Launch Prerequisite You have installed the [Contentsquare extension](https://docs.contentsquare.com/en/web/#installing-the-contentsquare-extension). 1. Within Tag properties, select **Rules** > **Add Rule**. 2. Specify a name, events, and conditions. 3. Add an Action with the following settings: * Extension: `Contentsquare`, * Action Type: `ETR Event`, * Name: `Contentsquare - ETR Event`. 4. On the right-hand side, enter the event name. 5. Select the event type: `Page Level` or `Session Level`.  6. Select **Keep Changes** > **Save**. ## Custom HTML To trigger an ETR event for the Event Triggered Replay feature, use the `trackEventTriggerRecording` command: **At Session level** ```html <script type="text/javascript"> window._uxa.push(["trackEventTriggerRecording", "@ETS@vocSubmit"]); </script> ``` **At Page level** ```html <script type="text/javascript"> window._uxa.push(["trackEventTriggerRecording", "@ETP@formError"]); </script> ``` Note Under the advanced recorder all legacy events are by default considered as Event Triggered Replay on Session if no prefix is specified. ```html <script type="text/javascript"> window._uxa.push(["trackEventTriggerRecording", "formError"]); </script> ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"ETR Event Tag","description":"The ETR event tag allows to trigger ETR events to save the collected session of the visitor","url":"https://docs.contentsquare.com/en/web/etr-event-tag/","inLanguage":"en","dateModified":"2025-12-12T22:25:41+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Extending the session length - Web description: How the Tag works with sessions lastUpdated: 25 June 2026 source_url: html: https://docs.contentsquare.com/en/web/extending-the-session-length/ md: https://docs.contentsquare.com/en/web/extending-the-session-length/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The session lifecycle is handled by the Tracking Tag on the browser side. The session ends 30 minutes after the last user event. ## Session initialization To manage the session, the Tag creates a session cookie called `_cs_s` which has its expiration date set to 30 minutes after its initialization. When the tag is executed, it checks for the `_cs_s` cookie: * If the cookie does not exist, it will increment the session number (stored in the `_cs_id` cookie) and will create the session cookie `_cs_s` * If the cookie already exists, it will only update the expiration date (now +30 minutes). ## Session update When a **pageview event** (natural or artificial) or a **user event** is triggered, the `_cs_s` cookie expiration date is updated (+30 minutes). ## Extending the session To artificially extend the session duration, use the `extendSession` command: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(["extendSession"]); </script> ``` When this command is called the Tag starts a process which: * **Updates the expiration date of the session cookie** `_cs_s` to 30 minutes after the process is run * **Sends a dynamic variable** with the key `session_expiry_update` and the process iteration number as value so that the Contentsquare data pipeline knows that the session should not be closed (example `{session_expiry_update: 2}`). This process will run every 29 minutes: * As long as the session length has not reached 4 hours (maximum duration of a session), counting from the beginning of the session, not the moment the command executed. * Until a new **pageview event** is triggered (natural or artificial). The process is then stopped and the session management goes back to its normal behavior. Thanks to this process, **the command only has to be called once per pageview.** ## Clear previous visitors data Use the `session:clear:visitor` command to clear all data linked to previous visitors: * Cvars * Consent * Exclusion * Visitor ID * Page number * Session number The command must be pushed **before the Tag starts**: ```html <script type="text/javascript"> (function () { window._uxa = window._uxa || []; window._uxa.push(["session:clear:visitor"]); var mt = document.createElement("script"); mt.type = "text/javascript"; mt.async = true; mt.src = "//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js"; document.getElementsByTagName("head")[0].appendChild(mt); })(); </script> ``` ## Create a new visitor Use the `session:start:newVisitor` command to trigger the creation of a new visitor. The `session:start:newVisitor` command: 1. Creates a new visitor by deleting and replacing the [`_cs_id`](https://docs.contentsquare.com/en/web/cookies/#_cs_id) cookie value. 2. Creates a new session for this visitor which deletes and recreates the [`_cs_s`](https://docs.contentsquare.com/en/web/cookies/#_cs_s) cookie. 3. Deletes all information, session, and cookies linked such as custom vars, consent cookie [`_cs_c`](https://docs.contentsquare.com/en/web/cookies/#_cs_c). 4. Triggers a new pageview. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Extending the session length","description":"How the Tag works with sessions","url":"https://docs.contentsquare.com/en/web/extending-the-session-length/","inLanguage":"en","dateModified":"2026-06-25T11:10:14+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Events handling - Web description: How the Tag handles browser events lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/web/events-handling/ md: https://docs.contentsquare.com/en/web/events-handling/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. **Reminder:** When the main tag has loaded, our tool will collect and transmit **most interactions** happening on the page: hovers and clicks will thus be treated to give you **UX indicators** on elements composing the page. ## Events handling - General principles ### Setup Events are automatically and systematically collected as soon as: * The main tag has loaded, * That the web user has been included in the analysis, * And the content is loaded (`DOMContentLoaded` event). ### Collected events The main Tag collects the following events: * Clicks — `click`, `pointerdown`, `pointerup`, `tap` on all elements * Hovers — `mouseover`, `mouseout` on `<a>`, `<button>`, `<select>`, `<input>`, `<textarea>` elements * Focus — `focus`, `blur`, `change` on `<input>`, `<textarea>`, `<select>` elements * Resize — `window.resize` * Mouse moves — `scroll`, `pointermove` on all elements It associates every element to a timestamp and a page block (meaning an HTML marker). ### How is the marker identified To target a block in the DOM, our tool reads through all parents chain of the element until finding the first **marker with an id** (if it has not been ignored, see below). If no IDs are found in the parent chain, it goes up to the `<html>` tag. It then goes back down counting the position of the tag within identical markers each time.  Elements taken into account for targeting are underlined. In these two examples, the two highlighted blocks will be identified as identical, and interaction data will be assimilated. ### Ignored "id"s #### Multiple occurrences of the same ID The Tracking Tag applies the W3C spec: *"id must be unique per webpage DOM tree"*. If an ID is not unique, the tag **will ignore all its occurrences**. #### Multiple IDs for the block Some websites use dynamic ids of which the value changes according to the pages within just one template. This stops us from combining data on those elements in the application. Also, markers that we want to analyze separately can be placed under the same "id". To answer those two issues, we exclude: * Ids with 4 consecutive digits, * Elements with a `data-cs-override-id` attribute with an empty value (see paragraph below),  > Elements taken into account for targeting are underlined. > > On this example, the id "product2134" is ignored; its parent will be considered instead. > > Original target: `div#products2134>p>img` => does not allow data combination > > Target with dynamic id detected: `div#wrap>div>p>img` => allows data combination ## Ignore, override, or add an "id" If you need to differentiate a block among others in the solution, you can define an ID that will be used by our tracking events mechanism. Just use the `data-cs-override-id` attribute, with a valid ID value (authorized characters are `a` to `z`, `A` to `Z`, `0` to `9`, `-` and `_`). Make sure this value is static and doesn't change from one URL to another (no dynamic ID). This attribute can be added to any HTML tag: `<div>`, `<p>`, `<form>`, `<a>`. It must be added to the HTML code, either in the original code or after the "DOM Ready" (`DOMContentLoaded`) event in JavaScript. ```html <div class="cta"></div> <div class="main_cta" data-cs-override-id="main_cta"></div> <div class="cta"></div> <div class="cta"></div> ``` You can also signify that an ID must be ignored because the ID differentiates blocks when they are, however, of the same nature. ```html <div class="product"></div> <div class="product" id="<IDENTIFIER_TO_IGNORE>" data-cs-override-id></div> <div class="product"></div> <div class="product"></div> ``` ## Get Page height and Scroll Rate on a specific HTML element The Tracking Tag listens to scroll events on the document and get the document height to compute **Page height**, **Scroll Rate** and **Zone Exposure** metrics. These metrics will be wrong on pages for which: * The document height equals the window height * And the scroll is happening within a HTML element with a height bigger than the document. To get accurate metrics, add the `data-cs-scroll-container` attribute to the specific HTML element handling the scroll events. It can be added to the original HTML code or after the "DOM Ready" (`DOMContentLoaded`) event in JavaScript. When binding event handlers, the Tracking Tag will detect the presence of an element in the DOM with the attribute `data-cs-scroll-container`. If such element is found, the Tracking Tag will not listen to the scroll events and page height on document anymore, but on that specific HTML element instead. It will use its height (and its `padding-top`) to compute the page height, scroll rate and exposure metrics. Note If multiple elements in the DOM with the `data-cs-scroll-container` attribute are present, the Tracking Tag will only take into account the first one. ```html <html> <head> ... </head> <body> <div>...</div> <div class="main"> <div class="scrollable" data-cs-scroll-container>...</div> </div> </body> </html> ``` ## Which HTML code is compatible? The solution is made to work on **all "normally" developed websites**. Here are some rules; they are for the most part derived from standard development. * Start each page with the DOCTYPE `<!DOCTYPE html>`. * Use only one "id" per page, to designate a functional block. * If an id or a class contains more than one word, use valid separators (`-`, `_`) or camel case: use `addToCart` or `add-to-cart` instead of `addtocart` and `addtoCart`. * Do not use random "id" or "id" that can change according to the contents or sessions. * Use valid "id": no space, no "quote". * Use a consistent hierarchy of information: within the same tag, only put elements of the same nature: ```html <div class="category"> <div class="list"> <div class="product"></div> <div class="product"></div> <div class="product"></div> </div> <div class="paging"></div> </div> ``` * Close every opened tag; do not close the parent element's tag before closing the children. * To facilitate the sending of "pageviews", it is advisable to change the URL with every major UI update. ## Verifying the sending of events ### Storage and performance So as not to alter display performance, interactions are not sent bit by bit. We stock all interactions in memory on the web user's browser and then send the collected events by packets. ### Sent request You will regularly notice GET requests to `//c.contentsquare.net/events` which will be sent to an encoded version of the latest events. Event requests are sent when: * The number of events in memory reaches 50 * The page is reloaded * The user "leaves" the page by either being redirected to another page, closing/switching tab, closing browser, switching to another app, lock screen, etc. *(triggers may vary depending on browsers and device type)* ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Events handling","description":"How the Tag handles browser events","url":"https://docs.contentsquare.com/en/web/events-handling/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Impact on performance - Web description: How the Tag impacts your site performance lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/web/impact-on-performance/ md: https://docs.contentsquare.com/en/web/impact-on-performance/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare Tracking Tag is designed to have minimal impact on your site's performance through optimized file size, asynchronous loading, and efficient network requests. ## What is the file size of the tag? The standard version of the Contentsquare tag is compressed to 148.7 KB, and transferred from the Contentsquare CDN to the browser, compressed by gzip. The size of the tag increases with the number of options that you enable, yet Contentsquare always optimizes the bundle size of your tag. Additional, custom integrations with other third-party services can also increase the file size. ## How long is the tag cached for? The Contentsquare tag is cached locally on a customers browser for 15 minutes, meaning that it should only be loaded once during the life of a typical browsing session. However, if it passes the 15 minute mark in a session, the only time the tag will be downloaded again is if a new version of the tag is deployed to the CDN. ## How will it impact page performance? The Contentsquare tag should be run just after the Document Object Model (DOM) is ready. Our recommended approach is to put the tag in the `<head>` element of your HTML page, with a `defer` attribute; this will make the browser download the tag asynchronously while it continues to parse the HTML, and once the DOM is ready, it will run the tag. This also means the Contentsquare tag should never impact any "paint" metrics, such as Time to First Byte (TTFB), First Contentful Paint (FCP) or Largest Contentful Paint (LCP). The only metrics that the Contentsquare tag should have any impact on would be Total Blocking Time (TBT), Time to Interactive (TTI) and Interaction to Next Paint (INP). How much impact the tag has, depends entirely on how large the DOM is, and how often the DOM is "mutated" when the page is interacted with. A page with a moderately sized DOM, where moving around the page doesn't change the HTML (aka "mutate") too much, will mean the impact on Total Blocking Time should be very minimal. Examples would be: * Desktop device with good processing power, good broadband connection, modern browser - the tag would have an impact of between 0ms and 50ms. * Mobile device with average processing power, 4G connection, modern browser - the tag would have an impact of between 25ms and 100ms. If the Total Blocking Time impact from synthetic testing is showing higher than these examples, then it may be due to: * The Document Object Model (DOM) being large, over 2000 nodes * Mutation of the DOM being excessive, creating lots of network requests and thereby increasing load on the CPU * Device being tested on is very old and has minimal processing power * The synthetic test is on an old simulated mobile device (such as `Moto G4`), and is exaggerating the impact of JavaScript converting "short tasks" into "long tasks" that wouldn't correlate to a real-world scenario. ## What does this mean for Core Web Vitals? The only Core Web Vital that would be affected by the Contentsquare tag is First Input Delay. This is a real user metric that relates to the synthetic metric Total Blocking Time. You can track Core Web Vital scores via Google's public BigQuery database, and viewed from a Google Data Studio dashboard. Follow the instructions on this link to set it up for your website: [https://g.co/chromeuxdash ↗](https://g.co/chromeuxdash) ## Which performance metrics can the tag impact? The Contentsquare tag will only impact metrics after it has loaded, parsed, and run. This means that it will not impact any paint metrics such as FCP, LCP, or Speed Index. It will also not affect stability metrics such as Cumulative Layout Shift (CLS). Here is a table that shows which metrics can be impacted by the Tag. | Metric Name | Impacted by CS Tag? | | - | - | | Time to First Byte (TTFB) | No | | First Meaningful Paint (FMP) | No | | Largest Contentful Paint (LCP) | No | | Speed Index | No | | Cumulative Layout Shift (CLS) | No | | Time to Interactive (TTI) | Yes | | Total Blocking Time (TBT) | Yes | | Interaction to Next Paint (INP) | Yes | ## How many requests will the tag make? The number of requests the Contentsquare tag will make depends on how many features are activated. If Session Replay is live, then there will be several requests made as the customer navigates around the website. These are batched up and sent as small HTTP POST or GET requests. If the Document Object Model (DOM) is being changed in any way while the user browses around the page then this can trigger more requests. Additionally, if the tag is also enabled for capturing errors, then this will trigger a new request per error occurrence on the page. ## How big are the requests that are posted by Contentsquare? The requests posted to Contentsquare's API vary depending on the information sent. However, the majority are tiny, typically under 500 bytes. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Impact on performance","description":"How the Tag impacts your site performance","url":"https://docs.contentsquare.com/en/web/impact-on-performance/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Personal data handling - Web description: Understand how Contentsquare handles Personal Data lastUpdated: 29 July 2026 source_url: html: https://docs.contentsquare.com/en/web/personal-data-handling/ md: https://docs.contentsquare.com/en/web/personal-data-handling/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare tag masks Personal Data before it leaves the browser and offers configurable commands, HTML attributes, and encrypted-collection modes to control what is sent and stored. ## At a glance Personal Data handling on the Contentsquare tag relies on three layers: 1. **Automatic Personal Data Redaction** — the tag detects common patterns (emails, JWTs, OAuth tokens, credit card numbers) and redacts them before any data leaves the browser. See [Automatic Personal Data Redaction](#automatic-personal-data-redaction). 2. **Masking features** you configure — commands and HTML attributes to mask or strip Personal Data from URLs, API error URLs, DOM content, and clicked element text. See [Masking features](#masking-features). 3. **Controlled Exposure** — collect and encrypt selected values client-side so Contentsquare cannot see them, and decrypt only with your private key when reviewing replays. See [Controlled Exposure](#controlled-exposure). Some data is **sent as-is** and is not automatically masked — most notably identity strings (`identify`), user properties, event names, event/pageview properties, and ecommerce item data. You are responsible for ensuring these do not contain Personal Data. See [Data sent as-is](#data-sent-as-is-not-automatically-masked). ## Automatic Personal Data Redaction The Contentsquare tag automatically detects and replaces certain types of personal data **before** any information leaves the browser. This happens without any configuration. The types of personal data that are detected depend on the data channel. ### What is detected | Personal data type | Replacement token | How it is detected | | - | - | - | | Email addresses | `CS_ANONYMIZED_EMAIL` | Pattern matching of email addresses, including URL-encoded forms (`%40`, `%2540`) | | JWT tokens | `CS_ANONYMIZED_JWT` | Structural match on the standard JWT format (`eyXxx.eyXxx.Xxx` — three base64-encoded segments) | | OAuth token values | `CS_ANONYMIZED_TOKEN` | Query parameters named `id_token`, `access_token`, `refresh_token`, or `auth_token`, regardless of the token format | | Credit card numbers | `CS_ANONYMIZED_PII` | 16-digit Visa/Mastercard number patterns, validated with a Luhn checksum | ### Where each type is masked Not every detection applies everywhere. The table below shows exactly which personal data types are masked in each data channel. | Data channel | Emails | JWT tokens | OAuth tokens | Credit cards | | - | - | - | - | - | | [**URLs**](https://docs.contentsquare.com/en/web/sending-pageviews/) (page URL, referrer) | ✅ | ✅ | ✅ | — | | [**HTML / DOM content**](#personal-data-handling-in-the-html-in-session-replay) (Session Replay) | ✅ | — | — | ✅ | | [**JavaScript error**](https://docs.contentsquare.com/en/web/error-analysis/) messages | ✅ | — | — | — | | [**JavaScript error**](https://docs.contentsquare.com/en/web/error-analysis/) filenames | ✅ | ✅ | ✅ | — | | [**API error**](https://docs.contentsquare.com/en/web/error-analysis/) URLs | ✅ | ✅ | ✅ | — | | [**Custom error**](https://docs.contentsquare.com/en/web/error-analysis/) messages | ✅ | — | — | — | | [**Custom error**](https://docs.contentsquare.com/en/web/error-analysis/) messages (embedded URLs) | ✅ | ✅ | ✅ | — | | [**Custom Variables**](https://docs.contentsquare.com/en/web/sending-custom-vars/) (name and value) | ✅ | — | — | — | | [**Dynamic Variables**](https://docs.contentsquare.com/en/web/sending-dynamic-vars/) (name and string value) | ✅ | — | — | — | | [**Ecommerce transactions**](https://docs.contentsquare.com/en/web/sending-ecommerce-commands/) (transaction id) | ✅ | — | — | — | Also, the following data-specific protections are always applied: * [**JavaScript errors**](https://docs.contentsquare.com/en/web/error-analysis/): form field values (patterns like `value="..."`) are redacted in error messages. * [**Custom errors**](https://docs.contentsquare.com/en/web/error-analysis/): phone numbers and name patterns (for example `firstName=`, `lastName=`, `userName:"..."`) are also redacted in error messages. * [**API errors**](https://docs.contentsquare.com/en/web/error-analysis/): the query string is stripped entirely from the collected URL, in addition to the masking listed above. * **Clicked element text**: if the text of a clicked button or link contains an email address or a credit card number, the entire text is dropped and not collected. Note Form field values (`<input>`, `<textarea>`) and editable content (`<div contenteditable="true|false">`) are never collected — they are replaced by dots before the HTML is sent. ### Data sent as-is (not automatically masked) The following data is transmitted without any Automatic Personal Data Redaction. If these channels may contain personal data, you are responsible for ensuring it is removed before sending it to Contentsquare. | Data channel | Details | | - | - | | [**`identify` identity string**](https://docs.contentsquare.com/en/web/track-users/) | The identity string is sent as-is. Use the [`{ hash: true }` option](https://docs.contentsquare.com/en/web/track-users/#best-practices) to hash it client-side before sending. | | [**User properties**](https://docs.contentsquare.com/en/web/command-reference/#adduserproperties) (`addUserProperties`) | Keys and values are sent as-is (only truncated to 255 characters) | | [**Visit properties**](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitadd) (`customProperties:visit:add`) | Keys and values are sent as-is | | [**Pageview properties**](https://docs.contentsquare.com/en/web/command-reference/#custompropertiespageadd) (`customProperties:page:add`) | Keys and values are sent as-is | | [**Page events**](https://docs.contentsquare.com/en/web/custom-page-events/) (`trackPageEvent`) | The event name string is sent verbatim | | [**Custom events**](https://docs.contentsquare.com/en/web/command-reference/#trackevent) (`trackEvent`) | The event name string is sent verbatim | | **External events** | The event name string is sent verbatim | | [**Custom errors**](https://docs.contentsquare.com/en/web/error-analysis/) — name and attributes (`trackError`) | Only the error *message* is filtered; the error name and attributes are sent as-is | | [**Ecommerce item data**](https://docs.contentsquare.com/en/web/sending-ecommerce-commands/) (`ec:transaction:items:add`) | Item names, SKUs, categories, and other attributes are sent as-is | | **Dynamic Variable integer values** | Integer values are not processed for anonymization | | **Non-email Personal Data in Custom/Dynamic Variable strings** | Credit card numbers, phone numbers, JWT tokens, and other sensitive data (other than emails) are not detected in Custom or Dynamic Variable values | ## Masking features Beyond [Automatic Personal Data Redaction](#automatic-personal-data-redaction), Contentsquare provides several commands and HTML attributes to mask or strip Personal Data from specific channels. This section lists every available feature and explains how and where to use them. ### Command cheatsheet The following commands and attributes are available to control Personal Data collection. Each is detailed in the corresponding section below or in the [Command Reference](https://docs.contentsquare.com/en/web/command-reference/). | Scope | Command / attribute | Purpose | | - | - | - | | URL path | [`setPath`](https://docs.contentsquare.com/en/web/command-reference/#setpath) | Rewrite the URL path before it is collected | | URL query string | [`setQuery`](https://docs.contentsquare.com/en/web/command-reference/#setquery) | Rewrite the URL query string before it is collected | | Referrer | [`referrer:maskUrl`](https://docs.contentsquare.com/en/web/command-reference/#referrermaskurl) | Mask Personal Data in the referrer path | | Referrer | [`referrer:removeQueryString`](https://docs.contentsquare.com/en/web/command-reference/#referrerremovequerystring) | Drop the referrer query string | | API error URLs | [`networkRequest:maskUrls`](https://docs.contentsquare.com/en/web/command-reference/#networkrequestmaskurls) | Mask Personal Data in collected API error URLs | | Session Replay (DOM) | [`setPIISelectors`](https://docs.contentsquare.com/en/web/command-reference/#setpiiselectors) | Mask DOM elements matching CSS selectors | | Session Replay (DOM) | `data-cs-mask` attribute | Mask the content of a specific HTML element | | Session Replay (DOM, Page Masking on) | [`setCapturedElementsSelector`](https://docs.contentsquare.com/en/web/command-reference/#setcapturedelementsselector) | Expose specific elements on a masked page via CSS selectors | | Session Replay (DOM, Page Masking on) | `data-cs-capture` attribute | Expose a specific element on a masked page | | Session Replay (page-level) | [`excludeURLforReplay`](https://docs.contentsquare.com/en/web/command-reference/#excludeurlforreplay) | Disable Session Replay collection for matching pages | | Controlled Exposure | [`setEncryptionSelectors`](https://docs.contentsquare.com/en/web/command-reference/#setencryptionselectors) | Collect the content of matching elements in encrypted form | | Controlled Exposure | `data-cs-encrypt` attribute | Collect the content of a specific element in encrypted form | | Identity | [`identify` with `{ hash: true }`](https://docs.contentsquare.com/en/web/track-users/#best-practices) | Hash the identity string client-side before sending it | | Identity | [`resetIdentity`](https://docs.contentsquare.com/en/web/command-reference/#resetidentity) | Clear the identity string (for example, on logout) | ### In identity and user attributes The tag exposes several commands to attach identity or attributes to a user. **None of these values are automatically masked** — what you pass is what is sent and stored. * [`identify`](https://docs.contentsquare.com/en/web/track-users/): associates an identity string with the current user. The value is sent as-is unless you use the `{ hash: true }` option, which hashes it client-side. Prefer non-directly-identifying values (UUIDs, account numbers) over emails or phone numbers. See [Track Users → Best practices](https://docs.contentsquare.com/en/web/track-users/#best-practices) for the trade-offs of client-side hashing. * [`resetIdentity`](https://docs.contentsquare.com/en/web/command-reference/#resetidentity): clears the identity associated with the current user. Use it on logout so a subsequent user on the same device does not inherit the previous identity. * [`addUserProperties`](https://docs.contentsquare.com/en/web/command-reference/#adduserproperties), [`customProperties:visit:add`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitadd), [`customProperties:page:add`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiespageadd): attach custom properties to the user, visit, or pageview. Keys and values are sent verbatim — do not pass Personal Data in either. For the full API, see [Track Users](https://docs.contentsquare.com/en/web/track-users/). ### Personal Data handling in the HTML (in Session Replay) Sessions will be collected for Session Replay if: * The `Session Replay` feature has been enabled for your account * The threshold set by the `Session Replay Collection Rate` is not exceeded For the HTML content to be sent, all these conditions must be true: * The user hasn't opted out * The session is being tracked * The browser is [compatible](https://docs.contentsquare.com/en/web/compatibility/) * The session has been flagged as "Collected for Session Replay", using the [`_cs_s`](https://docs.contentsquare.com/en/web/cookies/#_cs_s) cookie Warning If Session Replay is turned off, the HTML text/content of the page **is not** collected during the session. You must ensure that your URLs do not contain Personal Data or that they are masked by [modifying the sent URL](https://docs.contentsquare.com/en/web/sending-pageviews/#modifying-the-sent-url). #### Session Replay data collection options If Session Replay is turned on and data collection is active for the session, the HTML content of the page is sent **after every pageview** (both natural and artificial) and **every DOM change** (only the updated elements are sent). Note If you have a Success Manager, ask them to check your approach to masking. The Page Masking setting controls how much of the page content is collected. Page Masking (Automasking) Depending on whether Page Masking is activated, the resulting replay will differ and you will have to carry out additional masking tasks. ##### With Page Masking off The following protections apply regardless of Page Masking state: Contentsquare never collects the actual text typed into any `<input>` or `<textarea>` field. * The content of `<input>` elements with type `text`, `email`, `password`, `search`, `tel`, `url` or `<input>` elements without a `type` attribute are replaced with bullets before the HTML is sent * Every figure of `<input>` elements with type `number` are replaced by 0 * The `value` attribute is stripped from every `<input>` element, regardless of its type (including `checkbox`, `radio`, `hidden`, `range`, and others) * The content `<textarea>` elements is replaced with bullets before the HTML is sent * The content inside any element with a defined `contenteditable` property is replaced with bullets before the HTML is sent * The content of `<script>` elements is emptied * Except for the items listed previously, all the HTML content is sent, including `<head>` * The content of every element marked with the data attribute `data-cs-mask` is removed (see the [Tagging DOM elements](#tagging-dom-elements) section) CSS rules that depend on input values Because the `value` attribute is stripped from every `<input>` element, CSS selectors that target a specific value — for example `[name="filter"][value="12"]:checked ~ article` — will not produce the expected result in Session Replay. Content shown or hidden by such rules may appear incorrectly in the replay. Note Dropdowns are usually coded with the `<select>` element, which is collected by default by Contentsquare. If you show any Personal Data in these elements, apply the `data-cs-mask` data attribute. ##### With Page Masking on The following protections apply regardless of Page Masking state: Contentsquare never collects the actual text typed into any `<input>` or `<textarea>` field. * The content of `<input>` elements with type `text`, `email`, `password`, `search`, `tel`, `url` or `<input>` elements without a type are replaced with bullets before the HTML is sent * Every figure of `<input>` elements with type `number` are replaced by 0 * The `value` attribute is stripped from every `<input>` element, regardless of its type (including `checkbox`, `radio`, `hidden`, `range`, and others) * The content `<textarea>` elements is replaced with bullets before the HTML is sent * The content inside any element with a defined `contenteditable` property is replaced with bullets before the HTML is sent * The content of `<script>` elements is emptied * The content of every element marked with the data attribute `data-cs-mask` is removed (see the [Tagging DOM elements](#tagging-dom-elements) section) * The content of every element marked with the data attribute `data-cs-capture` is collected and shown unless it falls under the excluded elements listed above (`<input>`, `<textarea>`) * **Every character of the text content included in the elements sent is replaced by "A"** * Attributes unrelated to layout are removed. Only `id`, `class`, `style`, `src`, `srcset`, `href`, `rel`, and `type` are kept ##### Selectively mask pages by URL In case your site displays Personal Data only on a specific set of pages, **you can decide to run the Page Masking process only on a pre-defined set of pages**, so that you won't have to apply the masking across the whole site. These can only be configured by your dedicated Success Manager. There are two available options: * **Mask all pages except**: All pages will be masked except the ones defined by a Regex Pattern agreed with your Success Manager. * **Unmask all pages except**: All pages will be collected with clear content except from the ones defined by a Regex pattern agreed with your Success Manager #### Block data collection for specific pages (Session Replay) Use the `excludeURLforReplay` command to block data collection on pages based on their URL. Use cases include: * Personal data has been exposed * Exclude whole parts of your website from being collected for Session Replay * Some page replays for Session Replay cause performance issues (when the page contains many images or videos, for instance) — you can block these pages until the problem is fixed ```javascript window._uxa = window._uxa || []; window._uxa.push(["excludeURLforReplay", "URL_REGEX"]); ``` This command is scoped to the current pageview and must be rerun every time the tag loads. Using this command does not block pageviews for the given pages — it only blocks data collection for Session Replay. #### Remove content/Personal Data from the collected HTML There are two methods to remove content from the collected HTML: 1. Using the Contentsquare Personal Data Selector 2. Tagging DOM Elements ##### Personal Data Selector Each DOM element to be masked is identified by its CSS selector, and those selectors are pushed to the API via a JavaScript object. The content of the identified element is removed from the replay. [Tag Configurator Template: Element Masking](https://support.contentsquare.com/hc/en-us/articles/37271836678545-CSTC-Template-Element-Masking)Use the Tag Configurator to implement Element Masking through a visual interface. Note In case of CSS selectors being changed or removed, the masking will be removed as well. Push the following object containing CSS selectors for text and attributes to the API, **before firing the main tag**: ```javascript window._uxa = window._uxa || []; window._uxa.push(['setPIISelectors', PIIObject]); ``` The structure of the `PII` Object is as follows: * `PIISelectors`: Comma-separated list of CSS selectors which allow the **matching DOM elements to be masked by the tag.** * `Attributes`: Using this key, you can **remove the defined attributes of the DOM elements from the elements matching the CSS selectors.** You can use an array of attribute names as shown in the example above. Keep in mind that using both `PII Selectors` and `Attributes` is optional, meaning you can use either full element selectors, specific attribute selectors or both in the same object: ```javascript { PIISelectors: [".css-selector, selector"], // DOM elements to be masked Attributes: [ { selector: "select#month option, select#year option", // CSS selector(s) attrName: 'id' // Attribute name you want to mask }, { selector: ".link-page-7", // CSS selector(s) attrName: ['href','name'] // Array attribute names you want to mask } ] }; ``` ##### Tagging DOM elements To exclude content from being collected, use the `data-cs-mask` attribute on selected elements: ```html Content before <p data-cs-mask>emailaddress@sentitivedata.com</p> Content after ``` Their content is removed in the browser before it is sent to Contentsquare: ```html Content before <p data-cs-mask>emailaddress@sentitivedata.com</p> Content after ``` You can also add the `data-cs-mask` attribute with JavaScript provided you do it before any pageview is sent. **Events on removed HTML** — [Events](https://docs.contentsquare.com/en/web/events-handling/) (click, hover, etc.) will still be collected and sent to our servers even if they are targeting removed HTML elements. They will be visible in the application using Live Resources (as named in the platform). Warning Using comments within the HTML is not supported (`<!-- MousetestSensitiveStart -->...<!-- MousetestSensitiveEnd -->`). #### Display content in a fully masked HTML page There are two methods to display content in a masked HTML page: 1. Using the Contentsquare Personal Data Selector 2. Tagging DOM Elements ##### Personal Data Selector Each DOM element to be displayed is identified by its CSS selector, and those selectors are pushed to the API via a JavaScript object. The content of the identified element is displayed in Session Replay. [Tag Configurator Template: Element Unmasking](https://support.contentsquare.com/hc/en-us/articles/37271866118033-CSTC-Template-Element-Unmasking)Use the Tag Configurator to implement Element Unmasking through a visual interface. Note In case of CSS selectors being changed or removed, the element will be masked by default. The string which contains comma-separated CSS selectors for text and for attributes must be pushed to the Contentsquare API, **before firing the main tag**, as follows: ```javascript window._uxa = window._uxa || []; window._uxa.push(["setCapturedElementsSelector", "#capture-me, .show-me"]); ``` ##### Tagging DOM elements To display an HTML element in a masked page, add the `data-cs-capture` attribute to the HTML elements: ```html Sensitive Content before <p data-cs-capture>some piece of text that is not sensitive</p> Sensitive Content after ``` Content that is part of the tagged element is captured as is: ```html AAAA AAAA AA <p data-cs-capture>some piece of text that is not sensitive</p> AAA AAA AA ``` It can also be added with JavaScript, but attributes must be added before any pageview is sent. #### Session Replay Testing ##### Prerequisites * Have Google Chrome installed * Download the [Contentsquare Tracking Setup Assistant ↗](https://chrome.google.com/webstore/detail/contentsquare-tracking-se/pfldcnnaiaiaogmpfdjjpdkpnigplfca) Chrome Extension * Mask elements from the replay using [CSS selectors](https://docs.contentsquare.com/en/web/personal-data-handling/#personal-data-selector) or the [`data-cs-mask` attribute](https://docs.contentsquare.com/en/web/personal-data-handling/#tagging-dom-elements) — `<input>` elements are not captured by default, except dropdowns which still need masking * Activate full session masking * If you have already provided us with a list of your internal/office IPs for us to add to our exclusion list, inform your Contentsquare Success Manager to temporarily pause that exclusion list. Otherwise, sessions run from such an IP will not be collected by Contentsquare ##### Testing 1. Start a journey on your website, featuring the elements to be masked. 2. In the Contentsquare Tracking Setup Assistant extension, select `Turn off automasking` to prevent 'AAA' masking from affecting your local session.  3. Select `Collected for Session Replay` to enable Session Replay data collection for your session.  Direct link to replay A **Play** button appears next to the page URL. Click the icon and leave the tab open. The resulting replay will be available at this link 30 minutes after the end of your tests. 4. Select `Trigger testing pageEvent` to create the `SR Testing` page event which identifies your current session.  5. Make sure that the elements to be masked are visible as you progress along your testing journey. If required, fill out any test personal information. You will be able to check this information has been masked in the resulting replay. 6. Once you are done testing, close your session by either closing the session's tab or deleting your cookies.  Replay availability The replay is available 30 minutes later: * At the link generated above accessible via the **Play** button.  * On the [Contentsquare platform ↗](https://app.contentsquare.com/), by filtering replays containing the `SR Testing` page event.  7. Watch the replay and look for all the areas where Personal Data could appear: * ❌ If Personal Data is visible, update your masking and test again. * ✅ If there were no Personal Data, you are covered in terms of Privacy compliance. ##### What's next? If you are in the initial implementation phase of your project, inform your Success Manager about the results so they can double-check and then turn Page Masking off for you to use full Session Replay. If you are not in implementation and your tests are successful, you can update the Page Masking rules directly from the Console in Contentsquare if you are an Admin, by going to the **Page Masking** tab. For instructions, see the [Help Center article ↗](https://support.contentsquare.com/hc/en-us/articles/360017105259#01H7ZAF8S5FZ70HGHV036TXF18). ##### Following Session Replay requests HTML content is sent via requests to one of the endpoints listed below, based on where data is stored for your project: * `https://k.aeu1.contentsquare.net/{apiVersion}/recording` * `https://k.aus1.contentsquare.net/{apiVersion}/recording` * `https://k.eu1.az.contentsquare.net/{apiVersion}/recording` * `https://k.us1.az.contentsquare.net/{apiVersion}/recording` * `https://k.ba.contentsquare.net/{apiVersion}/recording` * `https://k.bf.contentsquare.net/{apiVersion}/recording` * `https://k.aa.contentsquare.net/{apiVersion}/recording` * `https://k.af.contentsquare.net/{apiVersion}/recording` The request is sent when the 2nd value of the [`_cs_s`](https://docs.contentsquare.com/en/web/cookies/#_cs_s) cookie (Session Replay data collection state) is `3` (collected) or `5` (collected after a specific trigger) or when ETR is enabled on the project. The request contains all the DOM. Note The tag serializes image elements containing base64 data. To mask such images in replays, use the [`setPIISelectors` command](https://docs.contentsquare.com/en/web/command-reference/#setpiiselectors): ```javascript const PIIobject = { PIISelectors: ["[src^='data:image']"] }; window._uxa.push(['setPIISelectors', PIIobject]); ``` Inspect data sent for Session Replay Use the [`_cs_debug`](https://docs.contentsquare.com/en/web/cookies/#_cs_debug) cookie inspect the decoded data: Sessions collected with the `compressionDisabled` flag on are filtered out from the Session Replay pipeline. 1. From the browser console, run this command to create the cookie: ```plaintext document.cookie = "_cs_debug=compressionDisabled" ``` 2. Reload the page. 3. In the Network tab, search for `https://k-*.contentsquare`, select the request, and check the payload. ### Blocking Personal Data in URLs Personal data appears in more places than just the HTML content. For a given page, you also need to mask Personal Data found in: * [The path of the current page](#masking-personal-data-in-the-url-path) * [The query string parameters of the current page](#masking-personal-data-in-url-query-string-parameters) * [The referrer of the next visited page](#masking-personal-data-in-the-referrer) Unmasked data could be exposed in the Error Analysis module. #### Masking Personal Data in the URL path To remove Personal Data in the URL of the current page, rewrite the URL of the pageview before the tag collects it, using the `setPath` command. The `setPath` command takes as a parameter the exact new path to collect as a URL. ```javascript window._uxa = window._uxa || []; window._uxa.push([ 'setPath', <NEW_PATH_TO_COLLECT> ]); ``` Call this command on **every page where the URL contains Personal Data, before the main Tracking tag is loaded**. Only the path is to be configured, not the whole URL. ##### Example ```javascript window._uxa = window._uxa || []; window._uxa.push(["setPath", "/users/CS_ANONYMIZED_USER_ID"]); ``` | URL before masking | URL after masking | | - | - | | `https://www.contentsquare.com/users/jon.snow` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID` | | `https://www.contentsquare.com/cartpage/users/jon.snow` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID` | #### Masking Personal Data in URL query string parameters When Personal Data can be found in the query parameters of an URL, use the `setQuery` command to replace the query string within the URL with a new masked one. ```javascript window._uxa = window._uxa || []; window._uxa.push([ 'setQuery', <ANONIMYZED_QUERY_STRING> ]); ``` The `setQuery` command takes as a parameter the exact new query string to display within the URL. This command instructs the tag to replace the part of the URL after the `?` with masked values. Call this command on **all pages where the URL contains Personal Data, and before the main tag is loaded**. Only the query string is to be configured, not the whole URL. ##### Example ```javascript window._uxa = window._uxa || []; window._uxa.push(["setQuery", "?user_id=CS_ANONYMIZED_USER_NAME&address=CS_ANONYMIZED_ADDRESS"]); ``` | URL before masking | URL after masking | | - | - | | `https://www.mysite.com/us/makeup/valentines-day/?user_id=jon.snow&address=castle.black` | `https://www.mysite.com/us/makeup/valentines-day/?user_id=CS_ANONYMIZED_USER_NAME&address=CS_ANONYMIZED_ADDRESS` | | `https://www.mysite.com/us/makeup/valentines-day/?campaign=valentinesday_feb_2021&user_id=jon.snow&address=castle.black` | `https://www.mysite.com/us/makeup/valentines-day/?user_id=CS_ANONYMIZED_USER_NAME&address=CS_ANONYMIZED_ADDRESS` | Customize the masked term according to the type of the parameter to replace, so that the result is explicit: * `CS_ANONYMIZED_USER_ID` * `CS_ANONYMIZED_EMAIL` * `CS_ANONYMIZED_ADDRESS` ...and more. Note The `setPath` and `setQuery` commands are already often used during the initial implementation phase, for other purposes than removing Personal Data in the Error Analysis module. If this is the case, amend the initial command with the new parameters to avoid collision. #### Masking Personal Data in the referrer Even when you have masked Personal Data in URLs and query parameters on a page, they propagate to the next visited page through the [`referrer` ↗](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer). To handle this use case, use the `referrer:` commands below. ##### In the URL Consider this journey: 1. Users navigate from `https://www.example.com/users/123456/products/ABCDEF` to `https://www.example.com/`. 2. A pageview is sent on `https://www.example.com/`. 3. The referrer value in both the browser and in the pageview request is `https://www.example.com/users/123456/products/ABCDEF`. To mask Personal data in the URL within the referrer, use the `referrer:maskUrl` command: ```javascript var referrers = [ "https://www.example.com/users/:USER_ID/products/:PRODUCT_ID", "https://www.example.com/account/cancelOrder/:ORDER_ID", "https://www.example.com/order/:ORDER_ID/merge/:ORDER_ID", ]; window._uxa = window._uxa || []; for (var i = 0; i < referrers.length; i++) { window._uxa.push(["referrer:maskUrl", referrers[i]]); } ``` The referrer value in the pageview request for `https://www.example.com/` will be: * `https://www.example.com/users/CS_ANONYMIZED_USER_ID/products/CS_ANONYMIZED_PRODUCT_ID` * `https://www.example.com/account/cancelOrder/CS_ANONYMIZED_ORDER_ID` * `https://www.example.com/order/CS_ANONYMIZED_ORDER_ID/merge/CS_ANONYMIZED_ORDER_ID` Note Use the `referrer:maskUrl` command as many times as needed, for example to deal with all URL patterns on your site at once. ##### Within query parameters Consider this journey: 1. Users navigate from `https://www.example.com/confirmation?firstname=jon&lastname=snow` to `https://www.example.com/`. 2. A pageview is sent on `https://www.example.com/`. 3. The referrer value in both the browser and in the pageview request is `https://www.example.com/confirmation?firstname=jon&lastname=snow`. To mask Personal data in the query string part of the referrer, use the `referrer:removeQueryString` command: ```javascript window._uxa = window._uxa || []; window._uxa.push(["referrer:removeQueryString"]); ``` The referrer value in the pageview request for `https://www.example.com/` will be: `https://www.example.com/?` Note To revert the behavior of the `referrer:removeQueryString` command, use `referrer:keepQueryString`. Use this command in the context of a multi-step funnel for a single page, where you run `referrer:removeQueryString` before the natural pageview and then need to pass query string parameters to subsequent artificial pageviews. ### Removing Personal Data in API errors Use the `networkRequest:maskUrls` command to rewrite the URL before the tag collects the API error URL. [Tag Configurator Template: Network requests mask URLs](https://support.contentsquare.com/hc/en-us/articles/37271848447761-CSTC-Template-Network-requests-mask-URLs)Use the Tag Configurator to implement network request URL masking through a visual interface. The command takes as parameter one or several masking patterns to apply to URLs containing Personal Data. Patterns can match the full URL of the page or only a part of it. ```javascript window._uxa = window._uxa || []; window._uxa.push([ 'networkRequest:maskUrls', <PATTERN> ]); ``` Patterns include the URL fragments to mask as variables prefixed by a colon. Such variables are replaced by `CS_ANONYMIZED_{FRAGMENT}`: * `:user_id` becomes `CS_ANONYMIZED_USER_ID` * `:address` becomes `CS_ANONYMIZED_ADDRESS` * `:email` becomes `CS_ANONYMIZED_EMAIL` Call this command **on all pages containing Personal Data which call the Contentsquare API, and before the main tag is loaded**. #### Example ```javascript window._uxa.push([ "networkRequest:maskUrls", ["order/:order_id/merge/:order_id", "order/:order_id/item", "cancelOrder/:order_id"] ]); ``` | URL before masking | URL after masking | | - | - | | `https://api.net/order/:order_id/merge/:order_id` | `https://api.net/order/CS_ANONYMIZED_ORDER_ID/merge/CS_ANONYMIZED_ORDER_ID` | | `https://api.net/order/:order_id/item` | `https://api.net/order/CS_ANONYMIZED_ORDER_ID/item` | | `https://www.api.nl/nl/ajax/nfs/account/cancelOrder/:order_id` | `https://www.api.nl/nl/ajax/nfs/account/cancelOrder/CS_ANONYMIZED_ORDER_ID` | ### Removing Personal Data in Clicked Element When clicked element collection is turned on and data collection is active for the session, the tag collects the text payload of the buttons and links being clicked as part of other analytics payloads (see `/events` [request](https://docs.contentsquare.com/en/web/requests/#events)). #### With Page Masking off The clicked element will be collected except if it is masked by `data-cs-mask`. #### With Page Masking on The clicked element will not be collected except if `data-cs-capture` is present on the clicked button or link. Note You can enable Page Masking on [specific URLs](https://docs.contentsquare.com/en/web/personal-data-handling/#selectively-mask-pages-by-url). You can also mask specific elements on the webpage. This masking takes priority over Page Masking configuration. For more information, see [personal data selector section](#personal-data-selector-1). ## Controlled Exposure Note This feature is only available to Experience Monitoring customers. Contact your Success Manager to inform them about your implementation of controlled exposure as they'll need to activate that feature for your project. The Contentsquare Tracking Tag does not collect any text typed into `input` or `textarea` fields. If you need to display the personal data of a user, such as shipping/delivery addresses, names, phone numbers, email addresses, or text inputs in a form field, use the collect and encrypt mode. With the collect and encrypt mode, you can collect, store, and display text in `input`, `textarea` fields, or any other element within a page that is usually masked by the tag, before it is sent to Contentsquare's servers. Encryption vs Masking Encrypting data is incompatible with element level masking such as tagging DOM elements with the [`data-cs-mask`](#tagging-dom-elements) attribute or through the [Personal Data Selector](#personal-data-selector) using the `setPIISelectors` API. This means that: * Both attributes `data-cs-mask` and `data-cs-encrypt` should never be used on the same HTML element * The `data-cs-mask` attribute should not be used on a container element that would target indirectly another element to be encrypted * If you already have a personal data masking method implemented on your project, check that no element with a `data-cs-encrypt` attribute is targeted by these methods, taking the DOM nesting rules into account * If you wish to mask an element by default but be able to encrypt it and expose it in Session Replays, you should **only** have the `data-cs-encrypt` attribute on this element at the most granular level rather than `data-cs-mask` ### Collect and encrypt personal data from the collected HTML There are two methods to collect and encrypt personal data from the collected HTML: * Using the Contentsquare Encryption Selector * Tagging DOM Elements #### Encryption Selector Each DOM element to be collected and encrypted is identified via its CSS selector. These selectors are pushed to the API via a JavaScript object. The content of the identified element is then encrypted and collected for Session Replays. Note In case of CSS selectors being changed or removed, the encryption and collection will be removed as well. The following object that contains CSS selectors for text should be pushed to the API as follows, before firing the main tag: ```javascript window._uxa = window._uxa || []; window._uxa.push(["setEncryptionSelectors", "#cart, .total-items"]); ``` #### Tagging DOM elements The `data-cs-encrypt` attribute can be added on an input field, `textarea` field, or any other element. Instead of being masked, the text in the tagged element is encrypted, stored, and made available for exposing under specific conditions. The encryption process happens on the `innerText` property of the tagged element. It does not apply on nested elements: the text of the nested element won't be masked nor encrypted. Make sure to add the `data-cs-encrypt` attribute on the most granular elements that must be collected. ```html <h2 class="welcoming"> Welcome back <span class="user_name" data-cs-encrypt>John Doe</span> </h2> ``` You can also add the `data-cs-encrypt` attribute with JavaScript provided you do it before any pageview is sent. Warning During the encryption process, the value of the text is truncated after 90 characters. Choose carefully the HTML elements to expose: try to avoid `textarea` or long text inputs. ### Data Encryption To use Controlled Exposure, obtain a combination of encryption keys: * Public key: used by the Tracking Tag to encrypt the data * Private key: used by the app for decryption Note You must generate the pair of keys, Contentsquare will never have access nor store the private key. ### How to generate the key pair #### Option 1: With a Google chrome script 1. Copy the following script: ```javascript function arrayBufferToString(buffer) { const byteArray = new Uint8Array(buffer); let byteString = ""; for (let i = 0; i < byteArray.byteLength; i += 1) { byteString += String.fromCodePoint(byteArray[i]); } return byteString; } crypto.subtle .generateKey( { name: "RSA-OAEP", hash: "SHA-256", modulusLength: 4096, publicExponent: new Uint8Array([1, 0, 1]), }, true, ["encrypt", "decrypt"], ) .then((keysObject) => { crypto.subtle.exportKey("pkcs8", keysObject.privateKey).then((result) => { const privateKey = btoa(arrayBufferToString(result)); console.log(`Private key: `, privateKey); }); crypto.subtle.exportKey("spki", keysObject.publicKey).then((result) => { const publicKey = btoa(arrayBufferToString(result)); console.log(`Public key: `, publicKey); }); }); ``` 2. Paste the script in the Chrome console. 3. Press enter on the keyboard. #### Option 2: With OpenSSL or OpenSSH On linux/Mac, you can use OpenSSL: ```plaintext openssl genpkey -out mykey.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096 openssl rsa -in mykey.pem -pubout > mykey.pub ``` On Windows you will need to [install WSL ↗](https://docs.microsoft.com/en-us/windows/wsl/install). #### How to add a public key 1. Go to the Contentsquare Console > Choose the account > Choose the project > "Encryption management" tab. 2. Select "Store public key". 3. Paste your preferred public key. 4. Select "Store key". Note It can take up to 30 minutes before the key is activated. ### Unmask on-screen text in Contentsquare 1. Select the key icon and select Unmask on-screen text 2. Enter in the private key and select decrypt (all replays will be exposed) ## User identifier Note This feature is only available to Experience Analytics customers on Pro and Enterprise plans, with a 50% Global Replay Sampling rate. 100% is highly recommended: the higher the sampling rate, the more likely you are to find the related replays. Always contact your Success Manager to inform them about your implementation of user identifier: this feature must be activated for your project. With the **User Identifier** feature, you can search for replays belonging to specific users using a unique identifier. You can search and access all sessions associated with a specific user, for example `john@gmail.com`, within the selected date range. Use this feature in the case of user feedback or complaints. The user identifier can be any value which uniquely identifies a user such as a username, an account number, email address, phone number, CRM ID, or loyalty system ID. It is immediately hashed and encoded in a one-way format before it is sent to Contentsquare. When filtering Session Replays with a user identifier in Contentsquare, the same hashing algorithm is used and both hashes are compared to match the user identifier with its associated replays. ### User identifier implementation 1. **Choosing the right User Identifier**: Opt for a unique identifier like the email address, username, or account number that is available on the front-end. 2. **Collecting User Identifiers**: To collect the user identifier, you need to send a page event using the [`trackPageEvent`](https://docs.contentsquare.com/en/web/custom-page-events/#defining-page-event) command, with the prefix `@user-identifier@`: ```javascript window._uxa = window._uxa || []; window._uxa.push(["trackPageEvent", "@user-identifier@user_email"]); ``` Or if you pull the identifier from the data layer: ```javascript window._uxa = window._uxa || []; window._uxa.push(["trackPageEvent", "@user-identifier@" + dataLayer.Name]); ``` The user identifier value is limited to 100 characters. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Personal data handling","description":"Understand how Contentsquare handles Personal Data","url":"https://docs.contentsquare.com/en/web/personal-data-handling/","inLanguage":"en","dateModified":"2026-07-29T20:06:11+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: IP Addresses - Web description: How Contentsquare uses IP addresses lastUpdated: 01 June 2026 source_url: html: https://docs.contentsquare.com/en/web/ip-addresses/ md: https://docs.contentsquare.com/en/web/ip-addresses/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare uses the visitor's IP address for the following purposes only: * Determining the visitor's geolocation, down to the city level * Blocklisting unwanted sessions (bots, internal employee traffic, etc.) * Short-term logging (up to 3 days) and replay troubleshooting purposes. The IP address is subsequently purged from our systems. ## Blocklist for analytics tools other than Contentsquare Contentsquare staff may generate some traffic on your site during the implementation phase or to perform some tests. This traffic is negligible, but you can filter it out by blocking the following IPs in your tools: * 213.41.77.105 * 5.50.90.43 * 176.175.236.35 * 95.178.109.249 * 212.114.25.152 * 62.23.207.242 * 82.163.197.242 * 65.209.26.84 * 50.228.63.242 * 160.72.153.180 * 212.235.51.193 * 84.110.158.42 * 83.135.182.254 * 79.148.101.36 * 80.32.138.162 * 2.139.157.177 * 62.57.159.45 * 80.28.196.106 * 82.163.210.26 * 213.208.255.250 * 202.128.197.138 * 202.128.193.138 * 148.109.0.162 ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"IP Addresses","description":"How Contentsquare uses IP addresses","url":"https://docs.contentsquare.com/en/web/ip-addresses/","inLanguage":"en","dateModified":"2026-06-01T14:44:25+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Product Analytics - Web description: What to expect when Product Analytics is activated — new Tag commands, features, and cookies lastUpdated: 05 June 2026 source_url: html: https://docs.contentsquare.com/en/web/product-analytics/ md: https://docs.contentsquare.com/en/web/product-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Heap App users This section only applies to customers with the Contentsquare tracking tag. If you're using the Heap tag, refer to the [Heap Web tracking docs ↗](https://developers.heap.io/docs/web). Product Analytics (PA) captures and visualizes user interactions across web, mobile, and other platforms, providing insights into user behavior and engagement. This data helps you identify user preferences, pain points, and behavior patterns so you can improve and optimize the digital experience. For more information, see [our product ↗](https://contentsquare.com/platform/product-analytics/) and [pricing ↗](https://contentsquare.com/pricing/) pages. ## CSP If you enforce a Content Security Policy, see [Content Security Policy](https://docs.contentsquare.com/en/web/content-security-policy/) for the directives required by the Contentsquare Tag. No additional CSP directives are required for the PA features described on this page. ## Privacy Masking and encrypted elements defined in the Contentsquare tracking tag are also enforced for PA data collection. See [Personal Data Handling](https://docs.contentsquare.com/en/web/personal-data-handling/). For projects with IP-less mode active, IP processing is also disabled for PA data collection. ### Page title masking You can keep page titles out of PA collection with the following commands: | Command | Description | | - | - | | [`hidePageTitle`](https://docs.contentsquare.com/en/web/command-reference/#hidepagetitle) | Replaces the page title with `****` in the next or all next pageviews. | | [`resetHidePageTitle`](https://docs.contentsquare.com/en/web/command-reference/#resethidepagetitle) | Reverts `hidePageTitle` for the next pageviews. | ## PA Tag commands Activating Product Analytics unlocks the following groups of Tag commands. All PA commands are called through `window._uxa.push(...)`, the same interface used for standard Tag commands. See [Command reference](https://docs.contentsquare.com/en/web/command-reference/) for full syntax and examples. ### Custom event commands Product Analytics Custom event commands let you send your own named events, enriched with custom properties, alongside the interactions Contentsquare captures automatically. | Command | Description | | - | - | | [`trackEvent`](https://docs.contentsquare.com/en/web/command-reference/#trackevent) | Sends a custom event with a name and optional properties. | ### Identity commands Product Analytics Identity commands let you attach a unique identifier to the current user for cross-device and cross-session analysis. | Command | Description | | - | - | | [`identify`](https://docs.contentsquare.com/en/web/command-reference/#identify) | Associates the current user with the provided identity string. If a different identity is already set, the session is reset: the user ID is regenerated and a renewal pageview is sent. | | [`resetIdentity`](https://docs.contentsquare.com/en/web/command-reference/#resetidentity) | Detaches the identity string from the current user and resets the session. | | [`getIdentity`](https://docs.contentsquare.com/en/web/command-reference/#getidentity) | Returns whether the current user has an identity string associated with them. | For more information on user identification, see [Track Users](https://docs.contentsquare.com/en/web/track-users/). ### User property commands Product Analytics User property commands let you attach custom key-value properties to the current user. These properties are associated with all future events for that user. | Command | Description | | - | - | | [`addUserProperties`](https://docs.contentsquare.com/en/web/command-reference/#adduserproperties) | Attaches custom properties to the current user, overwriting any previously set values for the same properties. | ### Event property commands Product Analytics Event property commands let you attach custom key-value properties to all subsequent events in the current visit. | Command | Description | | - | - | | [`customProperties:visit:add`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitadd) | Adds custom properties to all subsequent events. Alias: `addEventProperties`. | | [`customProperties:visit:remove`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitremove) | Removes a specific custom property from subsequent events. Alias: `removeEventProperty`. | | [`customProperties:visit:clear`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitclear) | Removes all custom properties from subsequent events. Alias: `clearEventProperties`. | ### Pageview property commands Product Analytics Pageview property commands let you attach custom key-value properties to the current pageview and all events on that page. | Command | Description | | - | - | | [`customProperties:page:add`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiespageadd) | Adds custom properties to the current pageview and its events. | | [`customProperties:page:remove`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiespageremove) | Removes a specific custom property from the current pageview. | | [`customProperties:page:clear`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiespageclear) | Clears all custom properties from the current pageview. | ## Element hierarchy collection To power interaction analysis, the Tag enriches `click`, `tap`, `change`, and `submit` events with the **element hierarchy**: the chain of ancestor elements from the interacted element up to the document root. Each level collects the tag name and a limited set of attributes. Hierarchy collection respects your project's masking settings. Attributes that commonly hold sensitive or non-semantic data are never collected, including: * Password manager attributes (for example, 1Password's `data-com.onepassword.iv`). * Library attributes that can hold personal data (for example, `data-initial-value` from v-mask). * Inline scripts and styles (`onclick`, `onsubmit`, `style`). * Framework-internal attributes with no analytical value (for example, `data-reactid`). ## Session context collection Most PA reporting relies on **session-level context** — when a visit started and where it came from — being attached to every event, not just the first pageview. The Tag persists this context client-side in the [`_cs_s_ctx`](https://docs.contentsquare.com/en/web/cookies/#_cs_s_ctx) cookie and replays it as request parameters on each subsequent pageview and event: | Stored value | Sent as | Purpose | | - | - | - | | `firstViewTime` | `fvt` | When the session started. | | `firstViewUrl` | `fvurl` | The session's landing page. | | `sessionReferrer` | `fpvurl` | The session's traffic source. | This cookie is created **only** when Product Analytics is active on the project. It has no effect on Experience Analytics features such as Session Replay or heatmaps. ### Impact of blocking `_cs_s_ctx` If `_cs_s_ctx` is blocked or stripped — by a WAF rule, a cookie allowlist, or a Consent Management Platform — the Tag cannot restore session context after the first pageview. Landing page, traffic source, and session-start time are then missing from every later event, which degrades attribution and the overall quality of PA reporting for the affected sessions. To avoid this, add `_cs_s_ctx` to any cookie filter you enforce — see [Server configuration](#pa-cookies) below. ## PA cookies When Product Analytics is activated, the following cookies are created in addition to the standard Tag cookies: | Cookie | Duration | Description | | - | - | - | | [`_cs_s_ctx`](https://docs.contentsquare.com/en/web/cookies/#_cs_s_ctx) | 30 minutes | Stores session context data (first pageview time, URL, and referrer). | | [`_cs_i`](https://docs.contentsquare.com/en/web/cookies/#_cs_i) | 3 days | Stores the encrypted user identity string set via the `identify` command. | | [`_cs_ep`](https://docs.contentsquare.com/en/web/cookies/#_cs_ep) | 13 months | Stores visit-level custom event properties set via `customProperties:visit:add`. | ### Server configuration These cookies are **new** when Product Analytics is activated and are not present in a standard Tag deployment. If you have an existing cookie filter, update it before activating PA features. If you enforce a cookie allowlist — through a Consent Management Platform (CMP), a WAF, or server-side filtering rules — add `_cs_s_ctx`, `_cs_i`, and `_cs_ep` to that list. Blocking any of them prevents Product Analytics from collecting data correctly. `_cs_ep` grows with the number of custom event properties set. Combined with `_cs_s_ctx`, the total `Cookie` request header size can exceed limits enforced by reverse proxies or web servers. If your infrastructure enforces a header size limit, make sure it accommodates at least 4 KB for cookies. For more information, see [Cookies](https://docs.contentsquare.com/en/web/cookies/#tag-cookies). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Product Analytics","description":"What to expect when Product Analytics is activated — new Tag commands, features, and cookies","url":"https://docs.contentsquare.com/en/web/product-analytics/","inLanguage":"en","dateModified":"2026-06-05T11:05:10+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Requests - Web description: The list of Tag requests and responses lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/web/requests/ md: https://docs.contentsquare.com/en/web/requests/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare tracking tag sends HTTP requests to several endpoints to collect pageviews, events, transactions, and Session Replay data. ## Pageview **Endpoint** `https://c.contentsquare.net/pageview` **Trigger** Tag execution and when the trackpageview command is called **Method** `GET` **Protocol** `HTTP/2` **Type** `gif` **Additional information** [See dedicated section for more details](https://docs.contentsquare.com/en/web/sending-pageviews/#verifying-the-sending-of-pageviews) ## Events **Endpoint** `https://c.contentsquare.net/events` **Trigger** [See dedicated section for more details](https://docs.contentsquare.com/en/web/events-handling/#verifying-the-sending-of-events) **Method** `GET` and `POST` **Protocol** `HTTP/2` **Type** `gif` **Additional information** [See dedicated section for more details](https://docs.contentsquare.com/en/web/events-handling/#verifying-the-sending-of-events) ## Quota **Endpoint** * `https://k-aeu1.contentsquare.net/quota` (Europe) * `https://q-aus1.contentsquare.net/quota` (US) **Trigger** For projects using the advanced session data collection pipeline, when a session is randomly selected for Session Replay, a POST request to the Quota Service is sent at the beginning of the session. The goal of the request is to check if the project still has credits to collect the current session. **Method** `POST` **Protocol** `HTTP/2` **Type** `xhr` **Additional information** There are no request parameters for quota request. ## Transaction **Endpoint** `https://c.contentsquare.net/transaction` **Trigger** When the `ec:transaction:send` command is called **Method** `GET` **Protocol** `HTTP/2` **Type** `gif` **Additional information** [See dedicated section for more details](https://docs.contentsquare.com/en/web/sending-ecommerce-commands/#verifying-the-sending-of-transactions) ## Dynamic variable **Endpoint** `https://c.contentsquare.net/dvar` **Trigger** When the `trackDynamicVariable` command is called **Method** `GET` **Protocol** `HTTP/2` **Type** `gif` **Additional information** [See dedicated section for more details](https://docs.contentsquare.com/en/web/sending-ecommerce-commands/#verifying-the-sending-of-transactions) ## Page Event **Endpoint** `https://c.contentsquare.net/pageEvent` **Trigger** When the `trackPageEvent` command is called **Method** `GET` **Protocol** `HTTP/2` **Type** `gif` **Additional information** [See dedicated section for more details](https://docs.contentsquare.com/en/web/custom-page-events/#verifying-the-sending-of-page-events) ## Session Replay Data Collection **Endpoint** * Projects on Advanced Data Collection Pipeline: * `https://k-aeu1.contentsquare.net/v2/recording` (Europe) * `https://k-aus1.contentsquare.net/v2/recording` (US) **Trigger** When session data collection is enabled according to ratio defined in the settings **Method** `POST` **Protocol** `HTTP/2` **Type** `xhr` **Additional information** [See dedicated section for more details](https://docs.contentsquare.com/en/web/personal-data-handling/#session-replay-testing) ## Non publicly accessible resources collection The collection of data URL, non-public, or remote resources by the Tag triggers these requests during session data collection. **Endpoint** * `https://srm.ba.contentsquare.net/exist` (Europe/AWS) * `https://srm.ba.contentsquare.net/putTag` (Europe/AWS) * `https://srm.aa.contentsquare.net/exist` (Europe/Azure) * `https://srm.aa.contentsquare.net/putTag` (Europe/Azure) * `https://srm.bf.contentsquare.net/exist` (US/AWS) * `https://srm.bf.contentsquare.net/putTag` (US/AWS) * `https://srm.af.contentsquare.net/exist` (US/Azure) * `https://srm.af.contentsquare.net/putTag` (US/Azure) **Trigger** When data URL resources or resources behind authentication are found on the website. **Method** `POST` **Protocol** `HTTP/2` **Type** `fetch` ## E-Merchandising **Endpoint** `https://c.contentsquare.net/display` **Trigger** When the E-merchandising tracking is enabled for the project. **Method** `POST` **Protocol** `HTTP/2` **Type** `xhr` **Additional information** 1 request per pageview ## JS Errors **Endpoint** `https://c.contentsquare.net/errors` **Trigger** When JS Error tracking is enabled for the project. At each pageview. **Method** `POST` **Protocol** `HTTP/2` **Type** `xhr` **Additional information** 1 request per error with a maximum of 20 requests per pageview ## Custom Errors **Endpoint** `https://c.contentsquare.net/custom-errors` **Trigger** Collected with the [`trackError`](../command-reference/#trackerror) command. **Method** `POST` **Protocol** `HTTP/2` **Type** `xhr` **Additional information** Maximum of 20 custom errors collected per pageview ## API Errors **Endpoint** `https://c.contentsquare.net/api-errors` **Trigger** When API errors tracking is enabled for the project. **Method** `POST` **Protocol** `HTTP/2` **Type** `xhr` **Additional information** Maximum of 20 API Errors collected per pageview ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Requests","description":"The list of Tag requests and responses","url":"https://docs.contentsquare.com/en/web/requests/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Security - Web description: Contentsquare Tag and Security lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/web/security/ md: https://docs.contentsquare.com/en/web/security/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare is committed to the **confidentiality, data privacy, and security of its clients and their end-users**. We will continue to invest extensive resources towards maintaining the highest level of data protection, privacy, and security standards. ## Cloud architecture Contentsquare leverages cloud technology, and benefits from the **stringent standards** of cloud security maintained by our Cloud provider. These include: * Compliance with leading industry certifications, regulations, and frameworks (ISO 27001, PCI-DSS, SOC 2) * Physical and environmental security (24-hour manned security, biometric access control, CCTV, environmental control systems with no single point of failure) * Disaster Recovery infrastructure ## Product security Contentsquare follows a series of **security best practices** to ensure the availability, confidentiality, and integrity of your data: * Code development is done through a documented SDLC process which includes guidance on how code is tested, reviewed, and promoted to production. * Code is peer-reviewed before being committed and analyzed with static code analysis tool targeting injection flaws, input validation and other potential defects. * Yearly third-party penetration tests are performed against Contentsquare applications and public-facing environments. * Monthly automated security scans are performed in-house on all our public-facing endpoints. * Contentsquare leverages Datadog as an additional layer of protection of its web applications. * Contentsquare has set-up a private bug-bounty program to reward relevant feedback from the ethical hacking community ## Data security encryption Sensitive data in storage and in transit is **encrypted using state-of-the-art algorithms**: * Data in transit is secured from the user's browser to the application via TLS. Contentsquare TLS strength is ranked A by Qualys SSlabs. * Technical administrative access from Contentsquare is secured with SSH (RSA 4096 bits key) over a VPN channel. * Applicative user passwords are secured using bcrypt with salting and high cost factor by default, and physically encrypted at rest (AES-256). * At-rest data are encrypted with AES-256 ## Corporate security As any enterprise, Contentsquare maintains a **security program to ensure that security** is central to all corporate processes. * Contentsquare has a dedicated security officer responsible for security across the organization. * Contentsquare maintains an Information Security Management System that is certified against ISO/IEC 27001, 27017, 27018, and 27701. * Risk management program is monitored through Key Performance Indicators that are shared with all internal stakeholders. * Security starts with the people Contentsquare employs. New employees must sign an NDA as part of their work contract and must complete Security Awareness and Data Privacy training as part of the onboarding into the organization. All employees are also reminded of best practices through internal communications. * Contentsquare has put in place a vendor management program to ensure that third-parties and their supply chain of providers comply with its security requirements and standards. * Contentsquare also maintains an incident response policy and procedures that lay out clear communication channels and escalation paths. ## Tag integrity Contentsquare runs its own Tag checker service on all projects to make sure no tag file is compromised. Every 10 minutes, this service checks that the SHA-512 checksum of Tag files served at `//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js` by our public CDN matches the checksum stored in our databases. In the event of a compromised Tag, Contentsquare is alerted immediately. Contentsquare Tag Checker versus Subresource Integrity We don't recommend implementing [Subresource Integrity (SRI) ↗](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). If you implement SRI, you need to update to a newer version of the Tag yourself and are more dependent on Contentsquare support. For more information, see [SRI](https://docs.contentsquare.com/en/web/sri/). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Security","description":"Contentsquare Tag and Security","url":"https://docs.contentsquare.com/en/web/security/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Send the users' decisions about data collection - Web description: Track whether users accept data collection lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/web/send-the-users-decisions-about-data-collection/ md: https://docs.contentsquare.com/en/web/send-the-users-decisions-about-data-collection/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Implement user consent by running the opt-out command to prevent Contentsquare data collection for users who decline tracking. ## Users who refuse data collection To have a cookie attesting that the user completely refuse data collection (no pageviews, no transactions will be sent), you need to run the following code: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(["optout"]); </script> ``` We do recommend for you to add this to your privacy policy page: ```html Contentsquare is a solution which provides the website owner with digital visitor behavior analytics to enhance visitor experience. To be excluded from the collection of data by Contentsquare on this website, <a href="javascript:window._uxa.push(['optout']);">click here</a>. ``` On the current domain, this command will add a `_cs_optout` cookie and remove all the other Contentsquare cookies already there. **Command by URL** — If the opt-out mechanism is handled by a third-party tool such as Evidon, you can use a link to the targeted domain including `_cs_optout` in the query parameters or in the anchor. On the page, the tag will run the same code as above to exclude the user from tracking and add the opt-out cookie. * `www.mydomain.com/?_cs_optout` * `www.mydomain.com/#_cs_optout` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Send the users' decisions about data collection","description":"Track whether users accept data collection","url":"https://docs.contentsquare.com/en/web/send-the-users-decisions-about-data-collection/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Sending custom vars - Web description: Send custom vars from your web page lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/web/sending-custom-vars/ md: https://docs.contentsquare.com/en/web/sending-custom-vars/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Custom vars let you attach additional context to pageviews, users, or sessions for use in segmentation and analysis. ## General principles Note Custom vars are sent when a pageview event is triggered. There is no command to send them specifically. ### Use **Custom vars** are additional information on the page, the user or the session, sent along with pageviews. They generally include datalayer information, such as: * Page type, * Product category, * The user's language or region, * The A/B test variant applied to the page This information enables visitor segmentation or page grouping, for which the URL would not be enough. ### Limits Each custom var is composed of a key (max. 512 characters) and value (max. 255 characters). You are limited to 20 custom vars per project. You can update up to 20 cvars on the same page. Each custom var holds a unique index, strictly between 1 and 20. Custom vars with indexes outside this range are **not sent**. Indexes are available for users to select within Contentsquare. Use a consistent index for a given custom var within a project — for instance, if the "page template" is collected with an index of 3, use the slot 3 for this information on every page of the website. Saving a custom variable creates a URI-encoded cookie which contains a stringified JSON of the stored information. This string may contain all URI [allowed characters ↗](https://en.wikipedia.org/wiki/Percent-encoding). Warning Make sure there is no security limitation on your server which blocks site entry with URI-encoded cookies, or any regex test that could target Contentsquare cookies. ## Defining custom vars [Tag Configurator Template: Custom Variable](https://support.contentsquare.com/hc/en-us/articles/37271895488401-CSTC-Template-Custom-Variable)Use the Tag Configurator to implement custom variables through a visual interface. To define a custom var, use the `setCustomVariable` command: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(["setCustomVariable", index, name, value, scope]); </script> ``` This means that you have to add an array to the `_uxa` object, containing: * `index` is a integer > 0 and <= 20 * `name` is a string of 512 characters max (if longer the Tag will truncate it) * `value` is a string of 255 characters max (if longer the Tag will truncate it) * `scope` (optional) defines the custom var scope and behavior * No `scope` specified (**default**): * In scopes `visit` and `page`. * `2` or `visit`: * In scope `visit`. * `3` or `page`: * In scope `page`. * Deleted after a Natural pageview. * `4` or `nextPageOnly`: * In scope `nextPageOnly`. * Deleted after a Natural pageview, or an Artificial pageview with the next `trackPageview` command. Once defined, custom vars are sent automatically with the next pageview (natural or artificial). Defining a custom var with an index that already exists overrides its name and value. ### Examples Defining a custom var in scope `visit` at index `5` with name `cname` and value `cvalue`. ```html <script type="text/javascript"> window._uxa.push(["setCustomVariable", 5, "cname", "cvalue", 2]); </script> ``` Defining a custom var in scopes `visit` and `page` at index `6` with name `cname` and value `cvalue`. ```html <script type="text/javascript"> window._uxa.push(["setCustomVariable", 6, "cname", "cvalue"]); </script> ``` Defining a custom var with the scope `nextPageOnly`. ```html <script type="text/javascript"> // either window._uxa.push(["setCustomVariable", 6, "cname", "cvalue", 4]); // or window._uxa.push(["setCustomVariable", 6, "cname", "cvalue", "nextPageOnly"]); </script> ``` ### Delete custom var command * A custom var can be deleted by calling the command with an empty string value. The index parameter must match the custom var to delete. * Custom vars with scope `nextPageOnly` are automatically deleted when the next natural or artificial page view is sent. #### Examples Deleting the custom var of name `cname`. ```html <script type="text/javascript"> window._uxa.push(["setCustomVariable", 5, "cname", ""]); </script> ``` Deleting custom var of name `cname` from scope `visit`. ```html <script type="text/javascript"> window._uxa.push(["setCustomVariable", 6, "cname", "", 2]); </script> ``` Deleting custom var of name `cname` from both scopes `page` and `visit` with an empty `scope` value. ```html <script type="text/javascript"> window._uxa.push(["setCustomVariable", 6, "cname", ""]); </script> ``` ## Verifying the sending of custom vars To verify that **custom vars** have been sent, check the **`cvarp` parameter of the corresponding pageview**. [Learn more about pageviews](https://docs.contentsquare.com/en/web/sending-pageviews/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Sending custom vars","description":"Send custom vars from your web page","url":"https://docs.contentsquare.com/en/web/sending-custom-vars/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Sending an add to cart - Web description: Send an add to cart event from your web page lastUpdated: 30 September 2025 source_url: html: https://docs.contentsquare.com/en/web/sending-an-add-to-cart/ md: https://docs.contentsquare.com/en/web/sending-an-add-to-cart/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Add to cart event is available with **Experience Analytics Web** and **Merchandising**. The event is not available in **Experience Analytics Mobile**. For **Experience Analytics Web**: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(["trackPageEvent", "addToCart"]); window._uxa.push([ "ec:cart:add", { merchant: window.location.hostname }, ]); </script> ``` For **Merchandising**, specify an SKU value identical to the value in the Product Catalogue: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push([ "ec:cart:add", { sku: "SKU_added_to_cart" /* mandatory */, merchant: window.location.hostname }, ]); </script> ``` You can also implement an add to cart in Google Tag Manager using the "Tracking Customization" tag: select `Add to cart` as Action type and supply the SKU. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Sending an add to cart","description":"Send an add to cart event from your web page","url":"https://docs.contentsquare.com/en/web/sending-an-add-to-cart/","inLanguage":"en","dateModified":"2025-09-30T15:39:12+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Sending dynamic vars - Web description: Send dynamic vars from your web page lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/web/sending-dynamic-vars/ md: https://docs.contentsquare.com/en/web/sending-dynamic-vars/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Dynamic vars let you send real-time contextual data alongside pageviews for use in segmentation and zone-level analysis. ## General principles ### Use Dynamic vars are additional information on the session that can be used to segment users. For example, they can include information on the A/B Test variations displayed to the current user. Unlike custom vars, dynamic vars can be sent at any time during a session and do not require to send a pageview. ### Limits #### On the server side It is possible to save up to 40 distinct dynamic variables per pageview. If more are received, only the first 40 distinct keys will be kept. If multiple dynamic variables using the same key are fired per pageview, only the last value associated with the key will be kept #### On the Tracking Tag side Every dynamic variable is composed of a pair of key (max. 512 characters) and value (max. 255 characters string or integer from 0-4294967296). The key and value are truncated by the Tracking Tag before they are sent. ## Defining dynamic vars [Tag Configurator Template: Dynamic Variable](https://support.contentsquare.com/hc/en-us/articles/37271814927633-CSTC-Template-Dynamic-Variable)Use the Tag Configurator to implement dynamic variables through a visual interface. To define and send a dynamic var at once, use the `trackDynamicVariable` command: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(["trackDynamicVariable", { key: my_key, value: my_value }]); </script> ``` Allowed values are `number` or `string` — there are specific capabilities for each in the Contentsquare app: * For values of type **number**, you can use operators (more than, less than, etc.). * For values of type **string**, auto-completion and regular expressions are available. ## Verifying the sending of dynamic vars Our [Contentsquare Tracking Setup Assistant Chrome Extension ↗](https://chrome.google.com/webstore/detail/contentsquare-tracking-se/pfldcnnaiaiaogmpfdjjpdkpnigplfca) displays each dynamic var sent. ### Inspecting the payload If you can't use our Chrome extension, use the [`_cs_debug`](https://docs.contentsquare.com/en/web/cookies/#_cs_debug) cookie. 1. From the browser console, run this command to create the cookie: ```plaintext document.cookie = "_cs_debug=compressionDisabled" ``` Note Sessions collected with the `compressionDisabled` flag on are filtered out from the Session Replay pipeline. 2. Reload the page. 3. In the Network tab, search for `dvar`, select the request, and check the value of the `dv` parameter. ### Checking the requests To check the actual request that is sent for each dynamic vars package (several dynamic vars pushed at the same time bundled together in a single network request), follow GET requests sent to `//c.contentsquare.net/dvar`, with these parameters. | Name | Description | Type | | - | - | - | | `dv` | Dynamic vars (compressed) | String | | `pid` | Project ID | Integer | | `r` | A random digit to avoid request caching | Integer | | `uu` | Unique user ID | String | | `pn` | Page number (each pageview increments of 1) | Integer | | `sn` | Session number | Integer | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Sending dynamic vars","description":"Send dynamic vars from your web page","url":"https://docs.contentsquare.com/en/web/sending-dynamic-vars/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Sending ecommerce commands - Web description: Send ecommerce transactions from your web page lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/web/sending-ecommerce-commands/ md: https://docs.contentsquare.com/en/web/sending-ecommerce-commands/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Reminder: To associate a web user's visit with their potential purchases (and corresponding revenue), you need to send the transaction information to Contentsquare using a dedicated command. This command will send Contentsquare the order reference, its amount, bought items, etc. ## Sending a transaction (without Merchandising) To send transaction information to Contentsquare, run the following command each time a visitor to your website completes a purchase (and populate the values below accordingly for the ID, the revenue and the currency) Note Only send this information when the order is fully completed ```html <script type="text/javascript"> window._uxa = window._uxa || []; // Push transaction info into CS global object window._uxa.push([ "ec:transaction:create", { id: "123" /* Transaction ID (string, up to 40 characters) */, revenue: "9.99" /* Transaction's total amount paid (integer or string, up to 12 digits and 2 decimals - extra decimals are truncated) */, currency: "usd" /* Currency value (string - numeric or alphanumeric ISO 4217 value) (optional) */, }, ]); </script> ``` Followed by: ```html <script type="text/javascript"> // Send the information to Contentsquare window._uxa.push(["ec:transaction:send"]); </script> ``` Assuming no additional merchandising information needs to be sent, you could include the `ec:transaction:send` command inside the same `<script>` tag: ```html <script type="text/javascript"> window._uxa = window._uxa || []; // Push transaction info into CS global object window._uxa.push([ "ec:transaction:create", { id: "123" /* Transaction ID (string, up to 40 characters) */, revenue: "9.99" /* Transaction's total amount paid (integer or string, up to 12 digits and 2 decimals - extra decimals are truncated) */, currency: "usd" /* Currency value (string - numeric or alphanumeric ISO 4217 value) (optional) */, }, ]); // Send the information to Contentsquare window._uxa.push(["ec:transaction:send"]); </script> ``` Note You can send different transactions with different currencies: Contentsquare handles multi-currency by default. In the Contentsquare application, transaction amounts and metrics are displayed in the [single currency set by each user ↗](https://support.contentsquare.com/hc/en-us/articles/37271851275921) in their profile. ### Multiple transactions You can send several transactions to Contentsquare but with different IDs: * If multiple transactions are sent with an identical transaction ID on the same session, only the last one received is inserted in the database, * If multiple transactions are sent with different transaction IDs (even on the same session), all of them will be on the database. ## Sending a transaction (for Merchandising) Note This section applies to Merchandising customers only. When implementing the ecommerce tracking for our Merchandising product, you would be required to specify what products were purchased in each transaction, in addition to the regular transactional information already mentioned above. For each product purchased, the following script should be triggered, in addition to the generic transaction information explained above, followed by the command `ec:transaction:send`: ```html <script type="text/javascript"> // Push individual product info into CS global object window._uxa.push([ "ec:transaction:items:add", { id: "123" /* Transaction ID (string, up to 40 characters) */, sku: "123ABC" /* Product code (string, up to 20 characters) */, price: "9.99" /* Product unit price actually paid by the visitor; Not the nominal price (integer or string, up to 6 digits and 2 decimals - extra decimals are truncated) */, quantity: "1" /* Quantity (whole number between 1 and 32766) */, name: "Black scarf" /* Product name (string, up to 50 characters) */, category: "Scarves" /* optional - Product category (string, up to 20 characters) */, }, ]); </script> ``` Thus, the code for a full transaction for Merchandising should look something like below: ```html <script type="text/javascript"> window._uxa = window._uxa || []; // Push transaction info into CS global object window._uxa.push([ "ec:transaction:create", { id: "123" /* Transaction ID (string, up to 40 characters) */, revenue: "9.99" /* Transaction's total amount paid (integer or string, up to 12 digits and 2 decimals - extra decimals are truncated) */, currency: "usd" /* Currency value (string - numeric or alphanumeric ISO 4217 value) (optional) */, }, ]); // Push individual product info into CS global object (to be repeated per each product) window._uxa.push([ "ec:transaction:items:add", { id: "123" /* Transaction ID (string, up to 40 characters) */, sku: "123ABC" /* Product code (string, up to 20 characters) */, price: "9.99" /* Product unit price actually paid by the visitor; Not the nominal price (integer or string, up to 6 digits and 2 decimals - extra decimals are truncated) */, quantity: "1" /* Quantity (whole number between 1 and 32766) */, name: "Black scarf" /* Product name (string, up to 50 characters) */, category: "Scarves" /* optional - Product category (string, up to 20 characters) */, }, ]); // Send the information to Contentsquare window._uxa.push(["ec:transaction:send"]); </script> ``` Here is an example of a complete transaction (including individual products for Merchandising) with transactional information taken from the datalayer: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push([ "ec:transaction:create", { id: dataLayer.ecommerce.transactionId, revenue: dataLayer.ecommerce.totalRevenue, currency: dataLayer.ecommerce.currency, }, ]); for (var i = 0; i < dataLayer.ecommerceItems.length; i++) { window._uxa.push([ "ec:transaction:items:add", { id: dataLayer.ecommerce.transactionId, name: dataLayer.ecommerceItems[i].name, sku: dataLayer.ecommerceItems[i].sku, category: dataLayer.ecommerceItems[i].category, price: dataLayer.ecommerceItems[i].finalPrice, quantity: dataLayer.ecommerceItems[i].quantity }, ]); } window._uxa.push(["ec:transaction:send"]); </script> ``` ### Orders or products without any amount Every order must have an amount. To pass those transactions anyway in your conversion rate, you can add an amount of `0`; anyhow, be careful of the consequences on the average cart (the same goes for the pricing of a cart product). ## Verifying the sending of transactions Our [Contentsquare Tracking Setup Assistant Chrome Extension ↗](https://chrome.google.com/webstore/detail/contentsquare-tracking-se/pfldcnnaiaiaogmpfdjjpdkpnigplfca) will display each transaction sent with its parameters. ### Checking the requests To check the actual data sent for transactions, follow GET requests to `//c.contentsquare.net/transaction`, with the following parameters: | parameter | definition | type | | - | - | - | | `pid` | project ID | Integer | | `id` | transaction identifier | String | | `revenue` | order amount | Double | | `items` (optional) | order's products list | JSON | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Sending ecommerce commands","description":"Send ecommerce transactions from your web page","url":"https://docs.contentsquare.com/en/web/sending-ecommerce-commands/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Sending pageviews - Web description: Send natural and artificial pageviews from your web page lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/web/sending-pageviews/ md: https://docs.contentsquare.com/en/web/sending-pageviews/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. **Reminder:** ー A **pageview** is when a web user visits a page. Notably, it automatically contains the current URL of the page, the screen size, the window size and the size of the document. ## How pageviews are sent Two instructions can be responsible for the launch of a pageview. ### Natural pageview A pageview is automatically and compulsorily sent when the main tag has loaded. It is not possible to prevent this sending but it is possible to modify the sent URL. the URL which is sent does not include the hash (meaning the elements appearing after the `#`). [Modify the sent URL](#modifying-the-sent-url) ### Artificial pageview A JavaScript instruction can be run to send an artificial pageview via the `trackPageview` command. Use this command when the page changes without provoking a full reload, meaning a new loading of the main tag: * AJAX loading, * Popin opening, * Tabs changing,... ## Sending a natural pageview You just have to load the main tag. [Learn more about the main tag...](https://docs.contentsquare.com/en/web/#custom-html) ## Sending an artificial pageview See [Artificial pageviews](https://docs.contentsquare.com/en/web/artificial-pageviews/#custom-html). ## Modifying the sent URL Contentsquare provides commands to modify the URL to be sent automatically by the Tag. Use cases include passing information after the '#' sign, or removing Personal Data. Personal Data and URLs For a checklist on Personal Data in URLs, jump to the [dedicated section](https://docs.contentsquare.com/en/web/personal-data-handling/#blocking-personal-data-in-urls). ### Modifying the path To override the path, use the `setPath` command: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(['setPath', <PATH_TO_SEND>]); </script> ``` The domain will be automatically added before, and the query after. Note For a natural pageview, make sure to use it **before calling the tag** so the new value is set before the pageview is triggered. #### Recommendations and limits * The value passed should be 255 characters maximum. * Do not add "#", since **fragments** are considered to be anchors and **all that comes after will be erased in the Contentsquare pipeline**. * Don't use this command to push query parameters. If you do and the initial URL already has query parameters, you will end up having a badly formed URL: * Initial URL: `https://www.domain.com/path?initial=1` * Sent URL: `https://www.domain.com/overridenPath?overriden=0?initial=1` #### Example Let's take the example of a Single Page Application that is using the **fragment** instead of the **path** to define the page identifier: * The initial URL of the page is: `https://www.domain.com/en#dynamic-app-path/in-the-fragment?query=param` * The URL inserted in the Contentsquare database would be: `https://www.domain.com/en` * To fix that, we need to replace the `#` by something else (`/__`): `window._uxa.push(['setPath', window.location.pathname + window.location.hash.replace('#','/__')]);` * Resulting URL: `https://www.domain.com/en/__dynamic-app-path/in-the-fragment?query=param` ### Modifying the query parameters To override the query parameters, use the following command: ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(['setQuery', <QUERY_PARAMETERS_TO_SEND>]); </script> ``` The domain and path will be automatically added before. Note For a natural pageview, make sure to use it **before calling the tag** so the new value is set before the pageview is triggered. #### Recommendations and limits * The value passed should be 255 characters maximum. * Do not add "#", since **fragments** are considered to be anchors and **all that comes after will be erased in the Contentsquare pipeline**. #### Example Let's take the example of a page that could be loaded with a popin displayed and we want to be able to identify it: * The initial URL of the page is: `https://www.domain.com/mypage?existingQueryParam=all` * Using `setQuery`: `window._uxa.push(['setQuery', window.location.search + '&cookies-popin=true']);` * Resulting URL: `https://www.domain.com/mypage?existingQueryParam=all&cookies-popin=true` ## Verifying the sending of pageviews The [Contentsquare Tracking Setup Assistant Chrome Extension ↗](https://chrome.google.com/webstore/detail/contentsquare-tracking-se/pfldcnnaiaiaogmpfdjjpdkpnigplfca) will display each pageview sent with its URL and Custom vars. ### Checking the requests To check the actual request that is sent, follow GET requests sent to `//c.contentsquare.net/pageview`, with these query parameters: | Name | Description | Type | | - | - | - | | `url` | Page URL | String | | `cvarp` | Custom vars defined for this page | JSON — **optional** | | `pid` | Project ID | Integer | | `r` | A random digit to avoid request caching | Integer | | `uu` | Unique user ID | String | | `pn` | Page number (each pageview increments of 1) | Integer | | `lv` | Last visit | Timestamp | | `hd` | Hit Date | Timestamp | | `lhd` | Last hit date | Timestamp | | `sn` | Session number | Integer | | `re` | Collection | 1 (standard), 3 (replay) or 5 (triggered replay) | | `dw` | Document width | Integer | | `dh` | Document height | Integer | | `la` | User's browser language | String | | `dr` | Previous page URL (referrer) | String | | `sw` | Screen width | Integer | | `sh` | Screen height | Integer | | `ww` | Window width | Integer | | `wh` | Window height | Integer | | `cvars` | Session's custom vars | JSON — **optional** | | `cvaru` | User's custom vars | JSON — **optional** | | `v` | Contentsquare Tag version | String | | `pvt` | Pageview type | "a" (artificial), "r" (renewal), or "n" (natural) | | `ex` | Indicates if the pageview can be included in a replay | SR (not included) or empty (can be included) | | `uc` | User Consent | 0 (Not required), 1 (Not expressed), 2 (Granted) or 3 (Withdrawn) | | `uxt` | Ongoing UXT tests, where required | JSON — **optional** | | `uxtv` | Testing tag version, where required | String — **optional** | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Sending pageviews","description":"Send natural and artificial pageviews from your web page","url":"https://docs.contentsquare.com/en/web/sending-pageviews/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Sub-resource integrity (SRI) - Web description: Implement the Tag using sub-resource integrity (SRI) lastUpdated: 12 February 2026 source_url: html: https://docs.contentsquare.com/en/web/sri/ md: https://docs.contentsquare.com/en/web/sri/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Subresource Integrity (SRI) provides an additional layer of security by ensuring that the files your web application or web document fetches (from a CDN or anywhere) have been delivered without a third-party having injected any additional content into those files — and without any other changes of any kind at all having been made to those files. The files will be rejected by the browser if any changes are detected. (SRI protects against attacks such as CDN hijacking and "man-in-the-middle" attacks). The browser will calculate the hash according to a specified algorithm upon fetching it from the CDN, compare said hash with the hash specified in the integrity attribute of the script tag, and reject the request if no match is found. In addition to the security benefits of this approach, it also ensures that none of the changes/updates (periodical or ad-hoc) on the Contentsquare side propagate to the Contentsquare tag running on your web application/document, unless the code is updated on your end. ## Setting It Up To set up Contentsquare SRI on your web application, a tag similar to the below will be provided to you by your Contentsquare team (note the addition of the integrity attribute and the source path changes compared to the "regular" version of the tag). The path will use a project-specific ID that matches your Contentsquare project and the version of the screenshot being used. ```html <script type="text/javascript"> (function () { var mt = document.createElement("script"); mt.type = "text/javascript"; mt.async = true; mt.integrity = "sha512-NEWHASH"; mt.crossOrigin = "anonymous"; mt.src = "//t.contentsquare.net/ss/<ID>/<VERSION>/uxa.js"; document.getElementsByTagName("head")[0].appendChild(mt); })(); </script> ``` ## Version update procedure Each version of the tag is manually generated by your Contentsquare team using the SRI deployment method. You can define the updates frequency with your dedicated Contentsquare team. This means that every time we will generate a new version of your tag we will communicate: * New tag URL with the right version. * The SRI hash matching the version. * The changes introduced since the latest version shared with you. By changing it, **you will benefit from**: * Latest tag improvements and new features. * Potential customizations. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Sub-resource integrity (SRI)","description":"Implement the Tag using sub-resource integrity (SRI)","url":"https://docs.contentsquare.com/en/web/sri/","inLanguage":"en","dateModified":"2026-02-12T15:16:10+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Static assets scraping - Web description: Options to enable static assets scraping for Zoning and Session Replay lastUpdated: 23 July 2026 source_url: html: https://docs.contentsquare.com/en/web/static-assets-scraping/ md: https://docs.contentsquare.com/en/web/static-assets-scraping/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare uses two complementary methods to collect static resources for Session Replay and Zoning: **Static Resource Scraper** and **Static Resource Manager (SRM)**. The Scraper is the primary and always-active collector, but requires configuration to access your resources. SRM can then be configured to collect any resources the Scraper can't access. How Scraper and SRM work together * **SRM enabled** (default): The Scraper collects resources, SRM collects base64 images * **SRM explicitly enabled for online resources on a specific pageview**: SRM replaces the Scraper for that pageview (requires [explicit tag command](#remote-resources-authenticated-assets)) * **SRM disabled**: Only the Scraper collects resources ## Static Resource Scraper The Scraper runs automatically and asynchronously downloads publicly accessible resources (CSS, images, fonts) from your website: * It operates every 6 hours for frequently accessed pages * Falls back to live scraping when resources aren't cached * Requires [IP allowlisting](#allowing-ip-addresses) **or** [custom header configuration](#using-a-custom-static-header-alternative) * Stores resources securely for 13 months **Limitations:** * Assets must be accessible from Contentsquare's IP addresses. * Assets behind authentication or VPN are not accessible. * Resources that change frequently (cache-busted URLs) may become outdated. To enable the Scraper, allow Contentsquare to access your assets using one of the following: * [Allowing IP addresses (recommended)](#allowing-ip-addresses) * [Using a custom static header (alternative)](#using-a-custom-static-header-alternative) ### Allowing IP addresses (recommended) The Scraper needs explicit permission to access your website through your proxy, firewall, or server configuration. IP allowlisting is the recommended method as it's simpler to implement and maintain. **Why this is needed:** Your firewall or security systems may block automated requests. By allowlisting Contentsquare's IP addresses, you allow our Scraper to download static resources without triggering security alerts or rate limiting. Allow ports `80` (HTTP) and `443` (HTTPS) and the following IP addresses to prevent your proxy, firewall, or server configuration from blocking the scraper. ```plaintext 52.18.162.157 20.75.90.236 100.24.76.90 34.192.98.148 20.67.250.109 54.247.44.196 52.51.9.12 35.72.153.38 35.73.99.41 34.192.240.128 ``` Performance * The scraper checks if resources were already downloaded within the last 6 hours before fetching again * Only publicly accessible resources are downloaded * The scraper identifies itself via user-agent headers ### Using a custom static header (alternative) If you cannot allowlist by IP, you can use a custom header-based approach. **Security benefit:** This method allows you to verify requests are legitimately from Contentsquare by validating the custom header value. **When to use this approach:** * IP allowlisting is restricted by security policy * You need more granular control over scraper access * You want to monitor and log scraper requests separately When selecting this option, Contentsquare adds a custom header to the project settings. ```json { "headers": { "my-new-header-key": "myKeyValue" } } ``` You can then validate that scraper requests contain the specific header and value. ```javascript receivedHeaderExample = "myKeyValue"; const CONTENTSQUARE_CUSTOM_HEADER = "myKeyValue"; if (receivedHeaderExample === CONTENTSQUARE_CUSTOM_HEADER) { // } ``` ### Validation To verify scraping is working correctly: 1. Check your Session Replays render with correct styling and images 2. Review server logs for successful requests from Contentsquare IPs Contact support if replays show missing resources after configuration. ## Static Resource Manager (SRM) For resources the Scraper can't access, the **Static Resource Manager (SRM)** collects them directly from the visitor's browser and uploads them to Contentsquare servers. SRM is enabled by default for all projects. When SRM is needed: * Resources behind authentication or login * VPN-protected or private network resources * Assets requiring specific user cookies or headers * Dynamically generated, or user-context-dependent content * Base64-encoded data URLs How SRM works: * The user's browser downloads the resource during the user session * The tag computes a unique hash and checks if Contentsquare already has it * If new, the tag uploads the resource directly to Contentsquare servers * Resources are deduplicated across sessions using hash-based identification To enable SRM, note how it handles the two types of resources: * [Data URLs (base64 images)](#data-urls-base64-images): Collected automatically — no implementation required * [Remote resources (authenticated assets)](#remote-resources-authenticated-assets): Must be explicitly enabled for each pageview using a tag command **Limitations:** * **Missing or restrictive cache policies**: If resources don't have a `Cache-Control` header that allows browser caching, SRM makes additional requests to the resource server for every session. This also occurs when resources return 404 errors (for example, when the page references assets the server can't find). * **CORS restrictions**: Resources with incompatible Cross-Origin Resource Sharing (CORS) policies can't be fetched by the browser, preventing SRM from collecting them. * **Lazy loading not respected**: SRM downloads every resource it finds as soon as it discovers it in the DOM or in the CSS, regardless of lazy loading implementation. This may defeat your lazy loading strategy and cause all resources to load immediately. If your site relies on lazy loading for performance, avoid enabling online resource collection with SRM. SRM availability When these limitations cause excessive server load or repeated failures, Contentsquare may disable SRM for your project. You can [check your project configuration](#how-to-check-if-srm-is-enabled-for-your-project) to confirm whether it's enabled or not. ### Data URLs (base64 images) When SRM is enabled for your project, the Contentsquare tag automatically collects base64-encoded data URLs found in the DOM. This ensures that embedded images appear correctly in Session Replay. No additional implementation is required for data URLs. ### Remote resources (authenticated assets) For remote resources that are behind authentication or not accessible to the Scraper, you must explicitly enable online asset collection **for each pageview** using a tag command. Push the following command **before** the pageview starts: ```javascript window._uxa.push(["replay:resourceManager:enableForOnlineResource:nextPageviewOnly"]); ``` Timing is important This command must be pushed **before** the pageview starts. For the first pageview after the tag loads, push the command before the tag starts. For subsequent pageviews using `trackPageview`, push the command before calling `trackPageview`. **Example with `trackPageview`:** ```javascript // Enable SRM for the next pageview window._uxa.push(["replay:resourceManager:enableForOnlineResource:nextPageviewOnly"]); // Then track the pageview window._uxa.push(["trackPageview", location.pathname + location.search + location.hash]); ``` ### How to check if SRM is enabled for your project To check the current state of the Static Resource Manager, use the following command: ```javascript window._uxa.push(["replay:resourceManager:getStatus"]); ``` This returns: ```javascript { isStarted: true, onlineAssets: { activated: false, enabledOnNextPageview: false, enabledForChildrenOnNextStart: false } } ``` | Property | True if | | - | - | | `isStarted` | SRM is enabled for the project and the browser supports it | | `onlineAssets.activated` | The current pageview has online resources collection enabled | | `onlineAssets.enabledOnNextPageview` | The next pageview will have online resources collection enabled | | `onlineAssets.enabledForChildrenOnNextStart` | New iframes will have online resources collection enabled | ## Troubleshooting If resources are not Appearing in Replays, **check these common issues:** 1. **IP not allowlisted**: Verify all Contentsquare IPs are allowed on ports 80 and 443 2. **Authentication required**: Resources behind login cannot be scraped automatically * Solution: Consider using SRM for authenticated resources (contact support) 3. **VPN or private network**: Resources on internal networks are not accessible * Solution: Use SRM for internal resources (contact support) 4. **Geographical restrictions**: Resources with geo-blocking may not be accessible * Solution: Configure region-specific proxy settings (contact support) 5. **Rate limiting**: Your server may be throttling scraper requests * Solution: Allowlist our IPs in your rate limiting configuration ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Static assets scraping","description":"Options to enable static assets scraping for Zoning and Session Replay","url":"https://docs.contentsquare.com/en/web/static-assets-scraping/","inLanguage":"en","dateModified":"2026-07-23T17:08:07+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Third-party integrations - Web description: Resources to learn more about Contentsquare and third-party integrations lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/web/third-party-integrations-and-implementation-examples/ md: https://docs.contentsquare.com/en/web/third-party-integrations-and-implementation-examples/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare integrates with major analytics and A/B testing platforms; find connector documentation and implementation examples below. ## Google Analytics 360 connector Read the [related documentation ↗](https://support.contentsquare.com/hc/categories/360002508439). ## Adobe Analytics connector Read the [related documentation ↗](https://support.contentsquare.com/hc/categories/360002508439). ## A/B Testing solutions You can send the variants from A/B Testing solution (ABTasty, Kameleoon, Monetate, Google Optimize, Dynamic Yield, Qubit, VWO, Optimizely, Usabilla, Maxymiser, Adobe Test and Target...) Read the [related documentation ↗](https://support.contentsquare.com/hc/categories/360002508439). ## Adblock detection If you want to detect if the user is using Adblock, you could send this information using a custom var. The following code is an example on how to do it: ```javascript (function () { var test = document.createElement("div"); test.innerHTML = " "; test.className = "adsbox"; document.body.appendChild(test); window._uxa = window._uxa || []; if (test.offsetHeight === 0) window._uxa.push(["setCustomVariable", 1, "isAdblock", true]); else window._uxa.push(["setCustomVariable", 1, "isAdblock", false]); test.remove(); })(); ``` ## Get Contentsquare session context (for integrations) ### getSessionKey The `getSessionKey` command allows for retrieving a unique Contentsquare session key. It's a string that encodes both a `userId` and a `sessionNumber`, in the form `<userId>.<sessionNumber>` (example: `"59e73d8b-2730u283i20-6712c43aaab3.3"`). You can also provide a callback function: ```javascript function csCallback(sessionKey) { const [userId, sessionNumber] = sessionKey.split("."); // do something with the session key } window._uxa = window._uxa || []; _uxa.push(["getSessionKey", { callback: csCallback }]); ``` ### afterPageView The `afterPageView` command allows for executing a `callback` after the "natural" pageview or "artificial" pageview (`trackPageview` command). **You don't need to wait for the Contentsquare tag to be fired to send this command.** If the command is called after the natural pageview, the callback is executed immediately and then after each `trackPageview`. You can register multiple callbacks by calling the command multiple times. The `callback` is called with a `context` which contains: * `projectId` * `sessionKey` * `pageNumber` * `replayConsentRequired` * `replayConsent` `context.sessionKey` is a unique session identifier. It's a string that encodes both a `userId` and a `sessionNumber`, in the form `<userId>.<sessionNumber>` (example: `"59e73d8b-2730u283i20-6712c43aaab3.3"`). `userId` is a unique anonymous ID generated by Contentsquare. `sessionNumber` is the position of the session in all the sessions tracked by Contentsquare for the same user (based on cookie tracking). So if `sessionNumber` is 3, it means that it's the third session tracked for this user. Here's an example which shows how to get the session context and use it in your callback: ```javascript function csCallback(context) { const projectId = context.projectId; const [userId, sessionNumber] = context.sessionKey.split("."); const pageNumber = context.pageNumber; // do something with the session context } window._uxa = window._uxa || []; _uxa.push(["afterPageView", csCallback]); ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Third-party integrations","description":"Resources to learn more about Contentsquare and third-party integrations","url":"https://docs.contentsquare.com/en/web/third-party-integrations-and-implementation-examples/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Testing your implementation - Web description: Test your implementation using the Contentsquare Tracking Setup Assistant to make sure pageviews are sent to Contentsquare servers, on every page lastUpdated: 03 June 2025 source_url: html: https://docs.contentsquare.com/en/web/testing-your-implementation/ md: https://docs.contentsquare.com/en/web/testing-your-implementation/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Make sure that data is sent correctly to our server with the following steps: 1. Download our Chrome Extension [Contentsquare Tracking Setup Assistant ↗](https://chrome.google.com/webstore/detail/contentsquare-assistant/pfldcnnaiaiaogmpfdjjpdkpnigplfca).  2. Browse your website and, looking at the extension, make sure that: * A pageview is sent on every page, or major UI change, * You are sending the desired custom vars, * If needed, a transaction is sent. Otherwise, look at our [Troubleshooting section](https://docs.contentsquare.com/en/web/troubleshooting/#my-data-is-not-being-sent). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Testing your implementation","description":"Test your implementation using the Contentsquare Tracking Setup Assistant to make sure pageviews are sent to Contentsquare servers, on every page","url":"https://docs.contentsquare.com/en/web/testing-your-implementation/","inLanguage":"en","dateModified":"2025-06-03T16:27:32+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track Users - Web description: Link activities to consistent IDs, enabling cross-device analysis and unified user experience insights beyond cookie limitations lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/web/track-users/ md: https://docs.contentsquare.com/en/web/track-users/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Note This feature is only available for customers of the [User Lifecycle Extension ↗](https://support.contentsquare.com/hc/en-us/articles/37271864562961-Introduction-to-the-User-Lifecycle-extension) or Contentsquare Product Analytics. Understand your users' complete journey by connecting their interactions across different devices and sessions. By implementing the identify API, move beyond cookie limitations and gain a unified view of individual user behavior: * **Holistic user understanding:** link user activity across desktops, mobile devices, and over time, providing a true, unified view of their digital experience. * **Enriched analysis & segmentation:** associate your internal user identifiers (like user IDs, hashed emails, account IDs) with Contentsquare's rich behavioral data. This allows for deeper segmentation and analysis based on your known user attributes. * **Audience activation:** connect Contentsquare's behavioral insights with your CRM, marketing automation, and other tools by using a consistent user identity across all your tools. This enables precise and effective audience targeting. * **Privacy-focused flexibility:** you have control over the user identities you send. Use UUIDs, hashed emails, or other data to maintain users' privacy while still achieving a unified view. ## Why use Identify? Imagine a user who starts a session on your website using their laptop, then switches to their mobile device. ### Without identify Contentsquare sees two separate users. Analysis of their complete journey is impossible.   ### With identify You use the identify API with their user identity (for example, their UUID from your CRM). Contentsquare links their activity on both the laptop and the mobile to their identity, providing a complete picture of their behavior.   ## Identifying users The `identify` command associates the current user with a unique identifier you provide. ```javascript window._uxa.push(["identify", <identityString>, <options>]); ``` For example, you can identify users with: * A User ID from your CRM ```html <script type="text/javascript"> window._uxa = window._uxa || []; // crmUserID = 145612124 window._uxa.push(["identify", crmUserID]); </script> ``` * A hashed user email address ```html <script type="text/javascript"> window._uxa = window._uxa || []; // hashedEmail = bfuKr7A9WgrhAgm2:C2YFJWcfN1yXzUnPfMrv6JivXJvYw== window._uxa.push(["identify", hashedEmail]); </script> ``` Session reset Calling `identify` for a user who is already identified with a different identity resets the current session, generates a new user ID, and sends a renewal pageview. Calling `identify` for a user who is already identified with the same identity does **not** reset the session. ```html <script type="text/javascript"> window._uxa.push(["identify", crmUserID1]); // Contentsquare user ID = 123 // Identity = uuid1 // ... window._uxa.push(["identify", crmUserID2]); // Contentsquare user ID = 456 // Identity = uuid2 // Session reset, new user ID and renewal pageview // ... window._uxa.push(["identify", crmUserID2]); // Contentsquare user ID = 456 // Identity = uuid2 // No session reset </script> ``` ## Best practices Be mindful of user privacy and avoid directly identifying identifiers such as name, surname, email addresses but instead to use identifiers such as a customer number or UUID. If an identifier is directly identifying a data subject, the `identify` command provides a way to hash the identity string client-side, using the `{ hash: true }` option. ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(["identify", emailAddress, { hash: true }]); </script> ``` While hashing client-side provides an extra layer of privacy, it's crucial to understand that Contentsquare will store the **hashed value**, which will not match the original identifiers in your CRM or marketing platform. This makes it significantly more difficult to: * Join Contentsquare data with data from those systems for comprehensive analysis, * Activate Contentsquare audiences in external platforms for targeted campaigns. In most cases, you should send an identifier available in your other tools to maximize data integration and activation capabilities. For enhanced control and consistency, perform hashing on your server-side or within a centralized data processing pipeline, rather than relying on the client-side `{ hash: true }` option. This approach ensures that hashing is applied uniformly across all data sources and allows you to manage the hashing process according to your specific security and data governance policies. ## Related identity commands ### `resetIdentity` Removes any currently associated identity string from the user. This also resets the current session and generate a new anonymous user ID. ```javascript window._uxa.push(["resetIdentity"]); ``` ### `getIdentity` Checks if the current user has an identity string associated with them. It does not return the exact identity string but a hash of it. ```javascript window._uxa.push(["getIdentity"]); ``` ## Adding user properties The `addUserProperties` command associates the current user with the given custom properties, overwriting any previously set values for these properties. ```html <script type="text/javascript"> window._uxa = window._uxa || []; // hashedEmail = bfuKr7A9WgrhAgm2:C2YFJWcfN1yXzUnPfMrv6JivXJvYw== window._uxa.push(["identify", hashedEmail]); // userProperties = { "accountType": "Premium", "membershipLevel": 3 } window._uxa.push(["addUserProperties", userProperties]); </script> ``` ## Next steps By using the identify API, you unlock a deeper understanding of your users and their digital experiences. Once you've implemented the identify API, you can leverage the associated user data for: * Creating advanced segments in Contentsquare based on your user attributes, * Analyzing user journeys across different devices, * Integrating Contentsquare insights with your other business intelligence tools or audience activation tools. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track Users","description":"Link activities to consistent IDs, enabling cross-device analysis and unified user experience insights beyond cookie limitations","url":"https://docs.contentsquare.com/en/web/track-users/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Voice of Customer - Web description: Requirements to use the Voice of Customer module lastUpdated: 27 April 2025 source_url: html: https://docs.contentsquare.com/en/web/voice-of-customer/ md: https://docs.contentsquare.com/en/web/voice-of-customer/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. As of Fall 2024, Contentsquare users can take advantage of Voice of Customer capabilities. Voice of Customer gives context to quantitative data and helps you understand what users are thinking. The Voice of Customer module enables you to create surveys to capture user feedback using a variety of question types and customization options. For more information on Voice of Customer, see this article [Help Center ↗](https://contentsquare.com/platform/voice-of-customer/). For more information about how Voice of Customer combines with Experience Analytics, refer to our [plans and pricing ↗](https://contentsquare.com/pricing/). ## Requirements and impacts on the Tag ### CSP To use Voice of Customer, make sure your [CSP configuration](https://docs.contentsquare.com/en/web/content-security-policy/) includes: ```plaintext script-src 'unsafe-inline' *.contentsquare.net ``` ### Dedicated script The Tag will inject a `hotjar-{SITE_ID}.js` script which loads the survey widgets. Impacts on SRI If you are using [SRI](https://docs.contentsquare.com/en/web/sri/), reach out to your Contentsquare contact for more information. ### Cookies The Tag will create [additional cookies](https://docs.contentsquare.com/en/web/cookies/#voice-of-customer-cookies), prefixed with `_hj`. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Voice of Customer","description":"Requirements to use the Voice of Customer module","url":"https://docs.contentsquare.com/en/web/voice-of-customer/","inLanguage":"en","dateModified":"2025-04-27T18:55:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Troubleshooting - Web description: Frequently asked questions about data that is sent lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/web/troubleshooting/ md: https://docs.contentsquare.com/en/web/troubleshooting/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use this page to diagnose common issues with data collection and metric discrepancies between Contentsquare and other analytics tools. ## My data is not being sent Using the Chrome extension [Contentsquare Tracking Setup Assistant ↗](https://chrome.google.com/webstore/detail/contentsquare-assistant/pfldcnnaiaiaogmpfdjjpdkpnigplfca), use the checklist below.  * Is the **main tag loaded**? (Marker "1" above). If not: * Make sure the call is done by your Tag Management System or in your template. * Make sure that no Cross-origin Resource Sharing (CORS) rules is preventing the call to be made. * Is the **tag active**? (Marker "2" above, the "Status" should be "active". — Otherwise, contact us) * Is the **domain authorized**? (The current domain should be listed here, on marker "2" above — Otherwise, contact us.) * Is the current **session tracked**? (Marker "3" — Otherwise, update this dropdown menu.) ## My CS metric is different from other Analytics tool The current web analysis technology is dependent on different browsers, operating systems and screen resolution. These different components can affect the quality of the data of all analytical tools. When you compare Contentsquare data with other analytical tools, you can see differences between major metrics. There are several factors to consider depending on the tool and the indicators you are comparing. *Other analysis definitions.* — The following measurement definitions have been extracted from the official Adobe Analytics and Google Analytics documentation. For additional troubleshooting assistance, refer to the corresponding tabs. ### Sessions vs Visits metrics #### Definitions ##### Contentsquare The number of **unique visits** that happened within the selected analysis context. A visit ends after 30 minutes of inactivity. ##### Google Analytics **Total number of Sessions (not unique)** within the date range. A session is the period of time a user is actively engaged with your website, app, etc. All usage data (Screen Views, Events, Ecommerce, etc.) is associated with a session. ##### Adobe Analytics A sequence of page views in a sitting. The visits metric is commonly used in reports that display the number of user sessions within the selected time period. The visit metric is always associated with a time period, so you know whether to count a new visit if the same visitor returns to your site. A session starts when the user first arrives on your site, and ends under one of the following scenarios: * 30 minutes of inactivity: Almost all sessions end in this manner. If more than 30 minutes have elapsed between image requests, a new visit begins. * 12 hours of consistent activity: If a user fires images requests without a 30+ minute gap for 12 hours, a new visit automatically starts. * 2500 hits: If a user generates many hits without starting a new session, a new visit is counted after 2500 image requests. * 100 hits in 100 seconds: If a visit consists of more than 100 hits that occur in fewer than 100 seconds, the visit automatically ends. This behavior typically indicates bot activity, and this limitation is enforced to prevent these processing-intensive visits from increasing latency and increasing the time it takes to generate reports. Note The definition of a visit can be shortened for a report suite if specifically requested, but it cannot be lengthened. Have one of your organization's supported users contact Customer Care to request this change. **A visit does not necessarily coincide with a browser session.** #### Troubleshooting suggestions A major discrepancy in the visits/sessions can be due to multiple factors: * Different metric definition, as per the information shared above * The **Tag firing method**, which might come in place too late, hence allowing the users to bounce before tracking their visit. * The **trigger chosen** might not be the same used for your other analytics tool, hence creating a major difference. ### Bounce and Bounce rate metrics #### Definitions ##### Contentsquare The ratio between the visitors who entered the site and left it **without having seen a second page** and all visitors, **regardless of the amount of actions taken on that single page**. ##### Google Analytics A bounce is a single-page session on your site. Bounce rate is single-page sessions divided by all sessions, or the percentage of all sessions on your site in which **users viewed only a single page and triggered only a single request to the Analytics server**. These single-page sessions have a session duration of 0 seconds since there are no subsequent hits after the first one that would let Analytics calculate the length of the session. #### Adobe Analytics **Bounces** A visit that consists of a single server call. For example, a single page visit is a bounce if a visitor does not interact with the page in a way that sends data to Adobe, such as clicking a link or a video start. Note If more than a single hit is received in a visit, a Bounce is not counted. **Bounce Rate** Shows the percentage of visits that contain a single hit. Bounce rate uses the Bounces metric and is calculated as: Bounces divided by Entries. Bounce Rate does not include visits where multiple actions occurred on a single page. Note Existing implementations can sometimes contain a calculated metric that differs from the Analytics default metric. Check the calculated metric definition to make sure there are no differences. #### Troubleshooting suggestion When facing a major discrepancy with bounce and bounce rate, **the Contentsquare definition of bounce rate** takes into account visitors who viewed only a single page, regardless of the amount of events/actions they took. ### Pageviews metrics #### Definitions ##### Contentsquare Total number of pages viewed. This takes into account all the artificial pageviews triggered by the **trackpageview** function. ##### Google Analytics Pageviews is the total number of pages viewed. **Repeated views of a single page are counted.** ##### Adobe Analytics A Page View is counted for each server call that is sent. This metric represents total instances of Page View. **TrackLink calls are not counted** as page views and do not increment the Page Views metric. #### Troubleshooting suggestions A major discrepancy in the pageviews count can be due to multiple factors, such as: * The **events** that you're tracking with your other analytics tool might not be accounted for as Pageview. * If most of your site is running on a SPA framework, Contentsquare tracks each re-routing as a new pageview. ### Transactions vs Conversions metrics #### Definitions ##### Contentsquare The number of sessions during which visitors completed an Ecommerce transaction. An E-commerce transaction is defined by firing the Contentsquare E-commerce tag. ##### Google Analytics Transactions is the total number of completed purchases on your site. ##### Adobe Analytics **Conversions** Note The conversion and conversion rate are defined as custom reports, hence the configuration comparison is key when checking for data inaccuracy. Custom Conversion reports are based on eVars (conversion variables). Conversion variables can persist beyond the page view and be associated with metrics within its specified expiration. The reports' default metrics are revenue. All standard eCommerce metrics can be used: Revenue, Orders, Units, Carts, Cart Views, Checkouts, Cart Additions, Cart Removals. For further reference: [https://experienceleague.adobe.com/docs/analytics/technotes/ga-to-aa/reports/conversions-reports.html?lang=en ↗](https://experienceleague.adobe.com/docs/analytics/technotes/ga-to-aa/reports/conversions-reports.html?lang=en) **Orders** The number of orders made on your website during the selected time period. #### Troubleshooting suggestions When facing major discrepancies with the transactions count, if you have **different confirmation pages**, make sure to fire our ecommerce tag on all of them. ### Conversion rate #### Definitions ##### Contentsquare The number of sessions with Ecommerce transactions divided by the total number of sessions throughout the selected period. ##### Google Analytics The percentage of sessions that resulted in an e-commerce transaction. ##### Adobe Analytics See the conversions point above. #### Troubleshooting suggestions When comparing conversion rate between different tools, do the Contentsquare **conversion rate** is based on the ratio between **the number of visits with a transaction and the total number of visits**. This definition might differ depending on the other analytics tool you're using. ### Revenue metrics #### Definitions ##### Contentsquare Total purchase amount of all sessions. ##### Google Analytics The total revenue from web ecommerce or in-app transactions. Depending on your implementation, this can include tax and shipping. ##### Adobe Analytics Revenue is captured on the purchase event, and is defined as the total dollar amount for the sum of the order for each product. This value comes from the purchase event. #### Troubleshooting suggestions A major discrepancy in the revenue can be due to multiple factors: * Contentsquare only takes into account the amount set as 'revenue' in the e-commerce tag when calculating **the total revenue displayed** * If you need to **exclude shipping and taxes** from the total revenue, you would need to do so before sending the transaction. * If you have a returns policy, do Contentsquare does not support **negative values** in the transactions, so this won't be tracked. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Troubleshooting","description":"Frequently asked questions about data that is sent","url":"https://docs.contentsquare.com/en/web/troubleshooting/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Who is included in the analysis? - Web description: Understanding who the targeted users are and on what conditions lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/web/who-is-included-in-the-analysis/ md: https://docs.contentsquare.com/en/web/who-is-included-in-the-analysis/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. A visitor is included in the analysis only when the tag is called, the session matches the sampling rate, and the user has not been excluded by consent or bot detection.  ## (1) Tag call conditions The tag installation is completely on your end: you can install it either by "hard coding" or by using a Tag Management System (TMS). * Make sure to call the Tag in **every page**. * Call it **as soon as possible**; It only takes a few seconds to lose a user. ## (2) Pageviews and transactions sending conditions As soon as the tag is called, the pageview (or transaction) are sent if all conditions below are fulfilled: * The **tag configuration** display it as "active". to check the setting, the variable `CS_CONF.status` must be 1. * The **current domain** is the one that has been configured for the tag called. To check the setting, the current domain must be mentioned in the variable `CS_CONF.hostnames`. If you navigate through a sub domain, check if the variable `CS_CONF.allowSubdomains` is equal to 1. * The visitor has allowed cookies and JavaScript; is using a [supported browser](https://docs.contentsquare.com/en/web/compatibility/). **95% of all users** matches these conditions. * The visitor is not excluded from the analysis by the presence of the **`cs_ex` cookie**. (See below) * When the "Cross-domain" feature is activated, matching DNS must be installed. ### The `_cs_ex` cookie The [`_cs_ex`](https://docs.contentsquare.com/en/web/cookies/#_cs_ex) cookie appears in **2 cases**: * If the tag does not collect 100% of visits, people who were not drawn will be excluded by the cookie. The Session Replay percentage is included in the `CS_CONF.sampleRate` variable. * If Contentsquare A/B testing tool's "Preview" mode is used, this cookie is automatically used. To **force exclusion**, you must add a `_cs_ex` cookie with the value `1`. ## (3) Accounting conditions of pageviews and transactions The pageview (or transaction) received is stored in our database with the following conditions: * The visitor does not have an **optout** cookie. * The user's IP address is not in our exclusion list for this Contentsquare account (for more info on IP Addresses [see dedicated section](https://docs.contentsquare.com/en/web/ip-addresses/)). * We did not identified the user **as a bot** (the assumption can come from the IP address used, the browser, the behavior...). This can be applied to 2% of the visitors but sometimes more. ## Differences between analytics Differences between two analytics can be due to implementation or data issues. ### Implementation differences * The Tag may **not be called** on the same pages (example: omitted subdomain, 404 page missed). * The Tag is called **later or earlier** (each second may increase the gap by about 3 points). ### Differences in scopes * **Bot exclusion rules** differ between tools or they are not shared. * **Calculation methods** for session, time spent, and bounce rate are different between tools. [More information on the Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/360011787554). * The **time zone** impacts daily displayed data (Contentsquare data are saved in UTC). * **[Compatible browsers](https://docs.contentsquare.com/en/web/compatibility/)** may be different from one tool to another. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Who is included in the analysis?","description":"Understanding who the targeted users are and on what conditions","url":"https://docs.contentsquare.com/en/web/who-is-included-in-the-analysis/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Collected Data - WebView description: What's collected by the WebView Tracking Tag lastUpdated: 14 January 2026 source_url: html: https://docs.contentsquare.com/en/webview-tracking-tag/collected-data/ md: https://docs.contentsquare.com/en/webview-tracking-tag/collected-data/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Once communication is established, the tag will start tracking the following events and pass them over to the SDK: * **Pageviews** manually triggered (with the dedicated command) * **Transactions** manually triggered (with the dedicated command) * **Dynamic variables** manually triggered (with the dedicated command) * **Gestures** automatically detected: *tap, long press, scrolls and swipes (with finger direction)* * **HTML DOM** and **DOM Mutation** when Session Replay is activated * **HTML DOM** when a screenshot of the screen is triggered by the SDK *(see Enable Screenshot Mode in iOS and Android docs)*. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Collected Data","description":"What's collected by the WebView Tracking Tag","url":"https://docs.contentsquare.com/en/webview-tracking-tag/collected-data/","inLanguage":"en","dateModified":"2026-01-14T10:09:04-08:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Wrapping it up - Web description: Solicit your Contentsquare contact for more feedback on your data collection tests, and explore third-party integration capabilities lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/web/wrapping-it-up/ md: https://docs.contentsquare.com/en/web/wrapping-it-up/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Once all the appropriate tags have been implemented, your site will start sending data to Contentsquare. You will see data in your account **3 hours after setup**. ## Going further Refer to the "Guides" section of the documentation. If you need additional help with implementation, reach out to your Customer Success Manager. ## Connecting with third parties You can connect Contentsquare to a wide variety of **3rd party analytics tools** and **A/B testing platforms**. See the full list in [Help Center ↗](https://support.contentsquare.com/hc/en-us/categories/36055091278993). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Wrapping it up","description":"Solicit your Contentsquare contact for more feedback on your data collection tests, and explore third-party integration capabilities","url":"https://docs.contentsquare.com/en/web/wrapping-it-up/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Error Analysis - WebView description: How to use Contentsquare Error Analysis in webviews within your mobile app lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/webview-tracking-tag/error-analysis/ md: https://docs.contentsquare.com/en/webview-tracking-tag/error-analysis/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. Contentsquare allows you to collect similar error types as in a web project: JS errors, API errors and Custom errors. ## WebView error tracking prerequisites To collect WebView errors, Error Analysis needs to be set up on the native side. See the dedicated documentation: [iOS](https://docs.contentsquare.com/en/ios/error-analysis/) and [Android](https://docs.contentsquare.com/en/android/error-analysis/). ## How WebView error tracking works Similar to analytics events and Session Replay, once set in WebView mode, the web tracking tag will collect errors and pass them to the native SDK, which will then send them to the dedicated Apps project. Each error type has a collection setting that needs to be enabled by your Contentsquare Implementation manager. ## JS errors Similar to web context, JS errors are collected out of the box if the collection is enabled in the web project associated with the tracking tag loaded in the page. Find more information on how Contentsquare handles JS errors in our [JavaScript errors Help Center article ↗](https://support.contentsquare.com/hc/en-us/articles/37271820978449). ## API errors Similar to web context, API errors are collected out of the box if the collection is enabled in the web project associated with the tracking tag loaded in the page. Find more information on how Contentsquare handles API errors in our [Analyzing API errors Help Center article ↗](https://support.contentsquare.com/hc/en-us/articles/37271807561873). ### Removing Personal Data in request URL path By default, the API errors feature collects the URL path of the failed API requests. To prevent the collection of Personal Data in the URL path, you can rewrite the request URL path. Follow the web documentation dedicated section: [Removing Personal Data in API errors](https://docs.contentsquare.com/en/web/personal-data-handling/#removing-personal-data-in-api-errors). ### API Troubleshooting Details Note This is an on-demand feature. Reach out to your Contentsquare contact to enable it. API errors troubleshooting details enables you to collect more information about API errors so you can troubleshoot errors faster. With this feature you will be able to see three types of additional API error details in the Event Stream of Session Replay. * The HTTP headers of the request and the response. * The body (the data sent by the request or received in the response). * The query parameters for the URL of the requested endpoint. #### Where to configure API troubleshooting details Similar to the collection settings, the Tag loaded in WebView mode will apply the API troubleshooting details rules inherited from the configuration defined in the associated web project. See [API Troubleshooting Details ↗](https://support.contentsquare.com/hc/en-us/articles/37271885035537) for more details. Warning The encryption used for WebView API errors will be the one from the mobile project. ## Custom errors Follow the web documentation section to implement custom error collection: [Sending custom errors](https://docs.contentsquare.com/en/web/error-analysis/#sending-custom-errors). Find more information on how Contentsquare handles Custom errors in our [Custom errors Help Center article ↗](https://support.contentsquare.com/hc/en-us/articles/37271964822417). ## Validate WebViews error collection If in-app features are enabled, you will be able to see the WebView errors collected as events in the SDK Logs and Log Visualizer. See [iOS Debugging and Logging](https://docs.contentsquare.com/en/ios/in-app-features/#debugging-and-logging) and [Android Debugging and Logging](https://docs.contentsquare.com/en/android/in-app-features/#debugging-and-logging) sections for more details about debugging and logging. ### WebView errors in SDK Logs Check out SDK logs to validate WebView errors are properly collected: * Android ```kotlin CSLIB: API Error (from WebView) - GET 401 https://api.client.com CSLIB: JS Error (from WebView) - <Error name> - <Message> CSLIB: Custom Error (from WebView): <Message> - Attributes: [key:value, key:value...] ``` * iOS ```swift CSLIB ℹ️ Info: API Error (from WebView) - GET 401 https://api.client.com CSLIB ℹ️ Info: JS Error (from WebView) - <Error name> - <Message> CSLIB ℹ️ Info: Custom Error (from WebView): <Message> - Attributes: [key:value, key:value...] ``` ### WebView errors in Log Visualizer Use [Log Visualizer ↗](https://support.contentsquare.com/hc/en-us/articles/37271699876625) from the Experience Analytics project to validate WebView errors are properly collected and received. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Error Analysis","description":"How to use Contentsquare Error Analysis in webviews within your mobile app","url":"https://docs.contentsquare.com/en/webview-tracking-tag/error-analysis/","inLanguage":"en","dateModified":"2026-04-14T17:33:10+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - WebView description: Learn how Contentsquare deals with Personal Data and related APIs lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/webview-tracking-tag/privacy/ md: https://docs.contentsquare.com/en/webview-tracking-tag/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Manage user consent for WebView tracking using opt-in and opt-out APIs to respect user privacy preferences. ## Handling User Consent Collecting user consent By default, user consent should be handled through the SDK. If your application context requires to collect user consent from the WebView, follow the instructions below. Our mobile SDK considers every new user to be opted-out by default. You are responsible for creating the UI asking users for their consent and allowing them to manage their privacy settings and then calling the appropriate Contentsquare following methods (`optin` or `opt-out`). If you think securing user consent is not required for your app, discuss it during the implementation process with your main Contentsquare contact. ## Opt-in Note This command is available starting with iOS SDK `4.13.0`, Android SDK `4.10.0`, Flutter plugin `2.3.0`, React Native Bridge `3.0.0`. Use the Opt-in API to get user consent. Calling this API generates a user ID and initiates tracking. ```javascript window._uxa = window._uxa || []; window._uxa.push(["optin"]); ``` ## Opt-Out Note This command is available starting with iOS SDK `4.13.0`, Android SDK `4.10.0`, Flutter plugin `2.3.0`, React Native Bridge `3.0.0`. When this API is called, tracking stops immediately, all settings are reset (Session number, Page number...) and all files and directories regarding Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track or collect any data from the user's phone unless the Opt-in API is called again. ```javascript window._uxa = window._uxa || []; window._uxa.push(["optout"]); ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Learn how Contentsquare deals with Personal Data and related APIs","url":"https://docs.contentsquare.com/en/webview-tracking-tag/privacy/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Migration from the legacy WebView Tracking Tag - WebView description: How to migrate from the legacy WebView Tracking Tag lastUpdated: 25 June 2026 source_url: html: https://docs.contentsquare.com/en/webview-tracking-tag/migrate-from-the-legacy-tag/ md: https://docs.contentsquare.com/en/webview-tracking-tag/migrate-from-the-legacy-tag/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To migrate from the legacy WebView Tracking Tag to the latest, follow these steps: 1. **Update the Tag** ```javascript <script type="text/javascript"> (function() { window._uxa = window._uxa || []; var mt = document.createElement("script"); mt.type = "text/javascript"; mt.async = true; mt.src = "//t.contentsquare.net/wvt/web-view.js"; mt.src = "//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js"; document.getElementsByTagName("head")[0].appendChild(mt); window.cs_wvt = window.cs_wvt || []; })(); </script> ``` `YOUR_TAG_ID` refers either to a new project or an existing Web project. 2. **Update pageview tracking** ```javascript window.cs_wvt.push(["trackPageview", "My Custom Page Title"]); window._uxa.push(["trackPageview", "My Custom Page Title"]); ``` 📚 See [`trackPageview`](https://docs.contentsquare.com/en/web/command-reference/#trackpageview). 3. **Update the tracking of transactions** ```javascript window.cs_wvt.push([ "trackTransaction", window._uxa.push([ "ec:transaction:create", { value: 1000, currency: "EUR", id: "my-transaction-id" } ]); window._uxa.push(["ec:transaction:send"]); ``` 📚 See [`ec:transaction:create`](https://docs.contentsquare.com/en/web/command-reference/#ectransactioncreate) and [`ec:transaction:send`](https://docs.contentsquare.com/en/web/command-reference/#ectransactionsend). Warning [Sending purchased products](https://docs.contentsquare.com/en/web/sending-ecommerce-commands/) is not supported when tracking VebViews. If you call it, the command is ignored. 4. **Update the dynamic variable tracking** ```javascript window.cs_wvt.push(["trackDynamicVariable", window._uxa.push(["trackDynamicVariable", { key: "AB_ABT_Label_Best_Price_PC", value: "With best price" } ]); ``` 📚 See [`trackDynamicVariable`](https://docs.contentsquare.com/en/web/command-reference/#trackdynamicvariable). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Migration from the legacy WebView Tracking Tag","description":"How to migrate from the legacy WebView Tracking Tag","url":"https://docs.contentsquare.com/en/webview-tracking-tag/migrate-from-the-legacy-tag/","inLanguage":"en","dateModified":"2026-06-25T11:10:14+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Session Replay - WebView description: How to include WebViews in replays lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/webview-tracking-tag/session-replay/ md: https://docs.contentsquare.com/en/webview-tracking-tag/session-replay/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To have WebViews in the replays, Session Replay tracking needs to be set up on the native side. See [iOS](https://docs.contentsquare.com/en/ios/session-replay/#configure-webviews) and [Android](https://docs.contentsquare.com/en/android/session-replay/#configure-webviews) docs for prerequisites. ## How Session Replay WebView tracking works Similar to analytics events, once set in WebView mode, the Tag will collect Session Replay data and pass it to the native SDK, which will then send it to the dedicated Apps project. ## Personal Data Handling WebView personal data masking is entirely handled on the web side. Follow the web documentation section to implement personal data handling: [Personal Data Handling](https://docs.contentsquare.com/en/web/personal-data-handling/). ### About (remote) Session Replay data collection options [Session Replay data collection options](https://docs.contentsquare.com/en/web/personal-data-handling/#session-replay-data-collection-options) are also applied in WebView mode: * [Clear content with masked Personal Data](https://docs.contentsquare.com/en/web/personal-data-handling/#with-page-masking-off) VS [Auto-masked content with AAA masking](https://docs.contentsquare.com/en/web/personal-data-handling/#with-page-masking-on) * [Selectively mask pages by URL](https://docs.contentsquare.com/en/web/personal-data-handling/#selectively-mask-pages-by-url) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Session Replay","description":"How to include WebViews in replays","url":"https://docs.contentsquare.com/en/webview-tracking-tag/session-replay/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Product Analytics - WebView description: Product Analytics capabilities made available for users of the CSQ SDK within WebViews lastUpdated: 06 May 2026 source_url: html: https://docs.contentsquare.com/en/webview-tracking-tag/product-analytics/ md: https://docs.contentsquare.com/en/webview-tracking-tag/product-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The following Product Analytics capabilities are available in WebViews **only if** you use the CSQ SDK. If you are running the Contentsquare or Heap SDK, upgrade to the CSQ SDK first: * [From Contentsquare SDK (iOS)](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/) * [From Heap SDK (iOS)](https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-from-heap-core-sdk/) * [From Contentsquare SDK (Android)](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/) * [From Heap SDK (Android)](https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-from-heap-core-sdk/) * [From Contentsquare SDK (Android)](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/) * [From Heap SDK (Android)](https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-from-heap-core-sdk/) ## Track users Required configuration * `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` Link a user's activity across all devices and sessions with a consistent internal identifier (like a User ID or hashed email), effectively moving beyond cookie restrictions. This creates a single, unified view of the customer journey, enabling deep cross-device analysis, enhanced segmentation based on known user attributes, and seamless audience activation by integrating behavioral data with external tools like your CRM. The `identify` command associates the current user with a unique identifier you provide. ```javascript window._uxa.push(["identify", <identityString>, <options>]); ``` For example, you can identify users with: * A User ID from your CRM ```html <script type="text/javascript"> window._uxa = window._uxa || []; // crmUserID = 145612124 window._uxa.push(["identify", crmUserID]); </script> ``` * A hashed user email address ```html <script type="text/javascript"> window._uxa = window._uxa || []; // hashedEmail = bfuKr7A9WgrhAgm2:C2YFJWcfN1yXzUnPfMrv6JivXJvYw== window._uxa.push(["identify", hashedEmail]); </script> ``` Session reset Calling `identify` for a user who is already identified with a different identity resets the current session, generates a new user ID, and sends a renewal pageview. Calling `identify` for a user who is already identified with the same identity does **not** reset the session. ```html <script type="text/javascript"> window._uxa.push(["identify", crmUserID1]); // Contentsquare user ID = 123 // Identity = uuid1 // ... window._uxa.push(["identify", crmUserID2]); // Contentsquare user ID = 456 // Identity = uuid2 // Session reset, new user ID and renewal pageview // ... window._uxa.push(["identify", crmUserID2]); // Contentsquare user ID = 456 // Identity = uuid2 // No session reset </script> ``` ## Add user properties Required configuration * `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` Attach properties to users to allow contextual, cross-device, and cross-platform analysis such as finding users with the payment plan X in the past month. User properties can be attached to both anonymous and identified users. ```html <script type="text/javascript"> window._uxa = window._uxa || []; // hashedEmail = bfuKr7A9WgrhAgm2:C2YFJWcfN1yXzUnPfMrv6JivXJvYw== window._uxa.push(["identify", hashedEmail]); // userProperties = { "accountType": "Premium", "membershipLevel": 3 } window._uxa.push(["addUserProperties", userProperties]); </script> ``` ## Reset identity Resets the current session and generate a new user ID if the user has an identity string associated with them. ```html <script type="text/javascript"> window._uxa = window._uxa || []; // user identity = 9fae2d84-37e7-4321-9b26-793d1665e887 window._uxa.push(["resetIdentity"]); // new user identity = 4b5c6e21-2f4a-4c3d-8f1e-8b9d7e5c3a1f </script> ``` ## Track custom events Required configuration * `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` Send custom events from a WebView to power Product Analytics dashboards. Each event has a required `name` and an optional `properties` object whose values are primitives (string, number, boolean) or arrays of primitives. ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(["trackEvent", { name: "purchase_completed", properties: { item_id: "SKU-123", price: "49.99" } }]); </script> ``` Events without properties are also valid: ```javascript window._uxa.push(["trackEvent", { name: "page_loaded" }]); ``` For the full signature and constraints, see [`trackEvent`](https://docs.contentsquare.com/en/web/command-reference/#trackevent). ## Add event properties Required configuration * `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` Attach properties to all subsequent events sent from the WebView, including autocaptured interactions and custom events sent with [`trackEvent`](#track-custom-events). ```html <script type="text/javascript"> window._uxa = window._uxa || []; window._uxa.push(["addEventProperties", { plan: "premium", region: "EU" }]); </script> ``` `addEventProperties` is an alias for the canonical [`customProperties:visit:add`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitadd) command. ## Remove event properties Required configuration * `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` Remove a single event property, or clear them all, from subsequent events. ```html <script type="text/javascript"> window._uxa = window._uxa || []; // Remove a specific property window._uxa.push(["removeEventProperty", "plan"]); // Clear every property added with addEventProperties window._uxa.push(["clearEventProperties"]); </script> ``` `removeEventProperty` and `clearEventProperties` are aliases for [`customProperties:visit:remove`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitremove) and [`customProperties:visit:clear`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitclear). Neither command affects events that were already sent. ## Hierarchies Required configuration * `CS_CONF.collectHierarchy === true` Hierarchies identify an event's origin within the current screen. They help understanding how users interact with different parts of your website, such as product categories, blog sections, or service pages. Hierarchies are collected automatically within WebViews. Considering the following component: ```jsx const PinView = (props) => { return ( <View> <Button title="1" rounded /> <Button title="2" rounded /> ... </View> ); }; ``` Tapping the button "1" would generate the hierarchy: `PinView Button[title=1][rounded=true]`. ## Target text Required configuration * `CS_CONF.collectTargetText === 2` Target text is the automatic collection of text content of an element a user interacts with. It captures the actual text displayed within clickable elements like buttons, links, and similar UI components. For example, if a user clicks on a button that says "Sign Up", the Target Text property would capture "Sign Up" as the value. This can be enabled in one of two ways: * Collect text of buttons or links: A button or a link text that users have or have not clicked on. * Collect text of all elements: Any element containing text that users have or have not clicked on (includes buttons and links). This applies to `tap`, `click`, and `submit` events. Target text is collected up to 100 characters. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Product Analytics","description":"Product Analytics capabilities made available for users of the CSQ SDK within WebViews","url":"https://docs.contentsquare.com/en/webview-tracking-tag/product-analytics/","inLanguage":"en","dateModified":"2026-05-06T13:28:50+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track dynamic variables - WebView description: Track dynamic variables in your apps using the Web Tracking Tag lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/webview-tracking-tag/track-dynamic-variables/ md: https://docs.contentsquare.com/en/webview-tracking-tag/track-dynamic-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Dynamic variables are additional information on the session that can be used to segment sessions. For example, they can include information on the A/B Test variations displayed to the current user. ## Defining dynamic variables To define and send a dynamic variable, directly use the key and String/Long value **once a first screenview has been triggered**: ```javascript window._uxa = window._uxa || []; window._uxa.push(["trackDynamicVariable", { key: my_key, value: my_value }]); // key is a string // value is either a string or an integer ``` **Type of the value** — The value can be either a **whole number** or a **string**. For each case, available features won't be the same in the Contentsquare app: * For **whole numbers**, you will be able to do some algebra. Example: *sessions with dynamic variable key = "numberOfFriends" and value >= 10* * For **strings**, auto-completion and Regular Expression will be available. Example: *sessions with dynamic variable key = "accountType" and value = "Premium"* ## Limits ### On the server side * It is possible to save up to 40 distinct dynamic variable keys per screenview. If more are received, only the first 40 keys will be kept. * If you are using the same key twice on the same screenview, the last value associated with the key will be collected. ### On the SDK side * Every dynamic variable is composed of a pair of key (max. 50 characters) and value (max. 255 characters string or number of type `Long` between 0 and 232 - 1). In case these maximum lengths are reached, the SDK will automatically trim the exceeding characters. * If key or value are empty, the SDK will instead send the literal string "cs-empty". ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track dynamic variables","description":"Track dynamic variables in your apps using the Web Tracking Tag","url":"https://docs.contentsquare.com/en/webview-tracking-tag/track-dynamic-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track Pageviews - WebView description: Track pageviews in your apps using the Web Tracking Tag lastUpdated: 09 May 2025 source_url: html: https://docs.contentsquare.com/en/webview-tracking-tag/track-pageviews/ md: https://docs.contentsquare.com/en/webview-tracking-tag/track-pageviews/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To aggregate user behavior and engagement at the screen/page level, track page transitions by calling the [`trackPageview`](https://docs.contentsquare.com/en/web/command-reference/#trackpageview) command. ```javascript window._uxa = window._uxa || []; window._uxa.push(["trackPageview", "PAGE_TITLE_OR_URL"]); ``` The Tag logs a pageview event that identifies the new page with the page title that you provide. ## Track pageviews differences (with vs without WebView mode) Tracking Pageviews has different rules depending if the Tag is loaded in WebView mode or not. ### `trackPageview` command differences | Webview mode | Web context | | - | - | | The Tag will not generate any natural pageview, you have to manually track all your screens. | The Tag will generate a natural pageview when loaded. | | The value you set is the one that will be seen in the Contentsquare platform. | The tag will prepend the value with the domain and append it with the query parameters. | | If no value (second array element) is provided, no default value will be provided | The tag will set the path as default value | ### Note on pageview tracking in WebView mode When set in WebView mode, the CS Tag will not trigger [natural pageviews](https://docs.contentsquare.com/en/web/sending-pageviews/#natural-pageview). If you rely on natural pageviews when the page is loaded from a web browser, make sure to use `trackPageview` as the page is fully loaded, as soon as possible. To do so, use the following code to call the `trackPageview` API as the DOM is ready: ```javascript document.addEventListener("DOMContentLoaded", function () { window._uxa = window._uxa || []; window._uxa.push(["trackPageview", "PAGE_TITLE_OR_URL"]); }); ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track Pageviews","description":"Track pageviews in your apps using the Web Tracking Tag","url":"https://docs.contentsquare.com/en/webview-tracking-tag/track-pageviews/","inLanguage":"en","dateModified":"2025-05-09T12:09:00+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track transactions - WebView description: Track transactions in your apps using the Web Tracking Tag lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/webview-tracking-tag/track-transactions/ md: https://docs.contentsquare.com/en/webview-tracking-tag/track-transactions/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To associate a user's session with their potential purchases (and corresponding revenue), you must send the transaction via a dedicated API. For each transaction, we send: * Transaction ID * Revenue * Currency ```javascript window._uxa = window._uxa || []; window._uxa.push([ "ec:transaction:create", { id: "123" /* Transaction ID (string, up to 40 characters) */, revenue: "9.99" /* Transaction's total cost (integer or string, up to 12 digits and 2 decimals - extra decimals are truncated) */, currency: "usd" /* Currency value (string less than 10 characters or numeric/alphanumeric ISO 4217 value) */, }, ]); window._uxa.push(["ec:transaction:send"]); ``` Warning **Each transaction must only be sent once**. A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ## Currency The currency is conforming to the [ISO 4217 ↗](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) standard. The currency must be passed as an "alphanumeric code". If the currency doesn't match the supported currencies, the SDK sends a currency value of `-1`. It will be processed as the default currency of the project. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track transactions","description":"Track transactions in your apps using the Web Tracking Tag","url":"https://docs.contentsquare.com/en/webview-tracking-tag/track-transactions/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Authentication - APIs description: How to authenticate to use the Enrichment API lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/api/enrichment/authentication/ md: https://docs.contentsquare.com/en/api/enrichment/authentication/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare APIs authenticate via server-to-server OAuth 2.0 credentials generated from the Contentsquare console. Warning **Since April 30th, 2024, API keys are no longer supported**. You must use OAuth credentials instead to authenticate on our APIs, and migrate your existing applications using API keys. ## OAuth2 authentication The Contentsquare APIs use the server-to-server OAuth 2.0 standard for authentication, also know as 2-legged OAuth or OAuth 2LO. The flow basically consists in calling an authentication endpoint with a pair `client_id` / `client_secret` to retrieve an access token that remains valid for 1 hour. This JWT token should then be used as a Bearer token in the headers of your HTTPS requests (in the form `Authorization: Bearer YOUR_API_KEY`). the API call to the authentication endpoint will also dynamically return the right base URL that you must use. This base URL depends on which cloud the target project is installed on. You can refer below to a [detailed example](#example-of-authentication-flow) of the overall flow to retrieve a token and a base URL, and use those to query the Data Export API. You can generate a pair `client_id` / `client_secret` from the Contentsquare [console ↗](https://console.contentsquare.com), as a Contentsquare administrator. You can find how to generate these credentials in our Help Center documentation. You can create OAuth credentials either: * At the Project level, to request access resources from a specific project only * At the Account level: to request access for any project of the account Warning Your OAuth credentials carry many privileges, so make sure to keep them secure! Do not share them in publicly accessible areas such as GitHub, client-side code, and so forth. ## Refresh your access token Once you get a JWT access token (see the [authentication endpoint](#authentication-endpoint) below), it's valid for 1 hour. If you try to query the Contentsquare APIs with access to token that has expired, you will receive a `401 Unauthorized` error with the error code `JWT_EXPIRED`, in the form: ```json { "success": false, "errorMessage": "Auth token is expired.", "errorCode": "JWT_EXPIRED" } ``` In that case, you should first use your OAuth credentials (your pair `client_id` / `client_secret`) to query a new access token. The OAuth credentials expire after 1 year. See [How to regenerate OAuth credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593-How-to-create-API-credentials#section4). ## Authentication endpoint POST [https://api.contentsquare.com/v1/oauth/token ↗](https://api.contentsquare.com/v1/oauth/token) ### Request parameters * #### client\_id  string  Required The OAuth `client_id` generated from the Contentsquare console. * #### client\_secret  string  Required The OAuth `client_secret` generated from the Contentsquare console. * #### grant\_type  string  Required Always set it to `"client_credentials"`, as required by the OAuth 2.0 standard. * #### scope  string  Required You should use `"enrichment"`. You **cannot** combine this scope with any other scopes (for example: `data-export enrichment` will return an error). * #### project\_id  integer   Required only if you use account-level OAuth credentials, to specify which project of the account you want to target. * #### integration\_id  integer  Required Required only if you use the `enrichment` scope. This is the ID of the target integration. This ID is provided by Contentsquare when installing the [integration](https://docs.contentsquare.com/en/api/enrichment/definitions/#integration) on a project. ### Request example ```shell curl --location 'https://api.contentsquare.com/v1/oauth/token' \ --header 'Content-Type: application/json' \ --data '{ "client_id": "c3133d76-a768-4f5a-XXX", "client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX", "grant_type": "client_credentials", "scope": "enrichment", "project_id": 42, "integration_id": 123, }' ``` ### Response example ```json { "access_token": "eyJhbGciOiJSIsImtpY5MTXXX.CNTcKWAUb2mTp2cZyiDRYYOtGCKXXX", // to be used as bearer token to query the APIs "token_type": "bearer", "expires_in": 3600, "scope": "enrichment", "project_id": 42, "endpoint": "https://api.eu-west-1.production.contentsquare.com" // this is the base URL you should use to query the Data Export API endpoints - the provided URL depends on the cloud the project is installed on } ``` ## Example of authentication flow Below is a sample of JavaScript code to show a complete API call flow that first retrieves an access token and then use it to retrieve the list of export jobs on a project: ```javascript const clientId = "<your_client_id>"; const clientSecret = "<your_client_secret>"; const authEndpoint = "https://api.contentsquare.com/v1/oauth/token"; const authRequestOptions = { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ client_id: clientId, client_secret: clientSecret, grant_type: "client_credentials", scope: "data-export", project_id: 42, integration_id: 123, }), }; const authResponse = await fetch(authEndpoint, authRequestOptions); const authJsonData = await authResponse.json(); // Below are the access token and base URL that must be used to query the Data Export API endpoints const accessToken = authJsonData.access_token; const baseURL = authJsonData.endpoint; // Using the access token and endpoint to push data to the enrichment API await fetch(`${baseURL}/...`); ``` ## OAuth credentials information endpoint POST [https://api.contentsquare.com/v1/oauth/me ↗](https://api.contentsquare.com/v1/oauth/me) ### Request parameters * #### client\_id  string   The OAuth `client_id` generated from the Contentsquare console. * #### client\_secret  string   The OAuth `client_secret` generated from the Contentsquare console. ### Request example ```shell curl --location 'https://api.contentsquare.com/v1/oauth/me' \ --header 'Content-Type: application/json' \ --data '{ "client_id": "c3133d76-a768-4f5a-XXX", "client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX", }' ``` ### Response example ```json { "scopes": "metrics data-export session-replay symbolicator", "permissions": { "projects": [ { "id": 42, "name": "UX ANALYTICS" } ] } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Authentication","description":"How to authenticate to use the Enrichment API","url":"https://docs.contentsquare.com/en/api/enrichment/authentication/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Creating integrations - APIs description: Creating integrations with the Enrichment API lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/api/enrichment/creating-integrations/ md: https://docs.contentsquare.com/en/api/enrichment/creating-integrations/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Get in touch with your Contentsquare contact to provide the required information: * A data schema, in the form of a JSON object * A name, logo, and description of what the integration does and related use cases to be listed in the Contentsquare integrations catalog. ## Schema format ```json { "fields": [ // the list of fields { "name": "FIELD_NAME_1", // max 50 bytes "type": "STRING", // either "DATETIME", "INT", "FLOAT", "STRING" or "BOOL" "optional": true, // either true or false to make this field optional or not "label": "Field 1", // a business name that can be used in user interfaces "description": "A first field" // a business description that can be displayed in documentation pages and user interfaces }, { "name": "FIELD_NAME_2", "type": "INT", "optional": false, "label": "Field 2", "description": "Another field" } ] } ``` Note When registering a new schema, Contentsquare will provide you with a corresponding `integrationVersion` (will be 1 by default for the first schema that is created and will be incremented by 1 for each new version). Then [when pushing enrichments](https://docs.contentsquare.com/en/api/enrichment/sending-enrichment-data-batches-cs/#sending-data-to-the-enrichment-endpoint), you will need to specify for which `integrationVersion`. Tip Using different integration versions, you can safely update and version an integration while avoiding to break enrichments flows relying on a previous schema. See [the dedicated section](https://docs.contentsquare.com/en/api/enrichment/update-an-integration-schema/) to see how to manage an integration schema update. ### Data types An enrichment field can be of one of the following types: | Type | Constraints | | - | - | | `"STRING"` | 0–50 bytes | | `"INT"` | `-2147483648` to `2147483647` | | `"FLOAT"` | `-1.79769e+308` to `1.79769e+308` | | `"BOOL"` | `true` or `false` | | `"DATETIME"` | `YYYY-MM-DDThh:mm:ssZ` (example: "2022-07-26T14:47:35Z") | ## Limitations * A schema cannot include more than 10 fields of each type (so there can be up to 10 strings, 10 integers, 10 booleans etc.) * Key names length is limited to 30 bytes * Strings are limited to 50 bytes Tip Try to keep your key names as short as possible to optimize performance. ## Example An example schema for a provider sending phone call data could look like this: ```json { "fields": [ { "name": "answered", "type": "BOOL", "optional": true, "label": "Call answered", "description": "Whether the call was answered (true) or not (false)" }, { "name": "call_duration", "type": "INT", "optional": false, "label": "Call duration", "description": "The call duration in milliseconds" }, { "name": "call_client_rating", "type": "FLOAT", "optional": true, "label": "Client rating", "description": "The call rating left by the client after the call if any" }, { "name": "call_center_name", "type": "STRING", "optional": false, "label": "Call center name", "description": "The name of the call center that made the call" }, { "name": "call_datetime", "type": "DATETIME", "optional": false, "label": "Call date and time", "description": "The date and time at which the call started" } ] } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Creating integrations","description":"Creating integrations with the Enrichment API","url":"https://docs.contentsquare.com/en/api/enrichment/creating-integrations/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Definitions - APIs description: Enrichment API resources definition lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/api/enrichment/definitions/ md: https://docs.contentsquare.com/en/api/enrichment/definitions/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This page defines the core resources used by the Enrichment API. ## Provider A provider is the entity (usually a technology partner) that will enrich the data. A provider is identified by a unique `providerId` by Contentsquare. A provider will create [integrations](#integration) to be able to send data to Contentsquare. ## Integration An integration is created by a [provider](#provider) to declare what data will be sent to Contentsquare. It is represented by a data schema provided by the provider, in the form of a JSON object. When data will be sent to Contentsquare, a specific integration will be authenticated and Contentsquare will check that enrichments abide by the schema of the integration. An integration is identified by a unique `integrationId` by Contentsquare. An integration can have multiple [integration versions](#integration-version). ## Integration version An integration can have multiple schema versions, to allow for updating and versioning an [integration](#integration) while avoiding to break enrichments flows relying on a previous schema. See [the dedicated section](https://docs.contentsquare.com/en/api/enrichment/update-an-integration-schema/) to see how to manage an integration schema update. ## Enrichment An enrichment is a data instance that matches an [integration](#integration) schema. It is the data sent by the provider to enrich Contentsquare sessions. If an enrichment does not meet the specified [integration version schema](#integration-version), it will be rejected. As several enrichments can be sent to enrich the same Contentsquare [session](#session), each enrichment for a specific session is indexed with an [enrichment number](#enrichment-number). ## Enrichment number Each new [enrichment](#enrichment) for a specific session is indexed to be differentiated from the previous enrichments received for the same session. No more than 3 enrichments can be sent per session, so enrichments will be indexed with a number from 1 to 3 included. The enrichment number should be specified by the provided but if not, it will be considered as being 1 by default. The enrichment number can be used to update an existing enrichment: if for a session, an enrichment is pushed with the same index as a existing enrichment, it will get updated with the last enrichment received. See [the dedicated section](https://docs.contentsquare.com/en/api/enrichment/update-an-enrichment/) to see how to manage an enrichment update. ## Enrichment field An enrichment field is a specific key in an [enrichments](#enrichment) data object. ## Enrichment batch An enrichment batch is a collection of [enrichments](#enrichment), in the form of an array of JSON objects. Enrichments are sent in batch to the Enrichment API endpoint. Of course, nothing prevents the provider from sending a batch of one enrichment only. For security purposes, if an enrichment gets rejected, the full batch will be rejected. ## Session A session is a visit of a user on a website or mobile app. The purpose of the Enrichment API is to enrich Contentsquare sessions data. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Definitions","description":"Enrichment API resources definition","url":"https://docs.contentsquare.com/en/api/enrichment/definitions/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Installing integrations - APIs description: Using the Enrichment API to install integrations lastUpdated: 23 February 2026 source_url: html: https://docs.contentsquare.com/en/api/enrichment/installing-integrations/ md: https://docs.contentsquare.com/en/api/enrichment/installing-integrations/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Once an integration has been created by a [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) and is available in the Contentsquare integrations catalog, from there customers can install the integration. When they go through the installation flow, customers are provided with a **project ID** and **OAuth credentials** (a pair `client_id` / `client_secret`) in the Contentsquare UI. Those 2 elements have to be provided to the technology partner so that the latter can know which project to send data for, and how to authenticate. Note It means that on the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) side, there should be some kind of configuration user interface prompting the customer for the Contentsquare project ID and OAuth credentials. Tip The scope of one customer "project" in the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) definition may correspond to several projects in the Contentsquare definition. In such a case, and if data should be sent to multiple Contentsquare projects, then several integrations will have to be installed and a list of (project ID, OAuth credentials) pairs will need to be stored in the configuration of the technology partner. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Installing integrations","description":"Using the Enrichment API to install integrations","url":"https://docs.contentsquare.com/en/api/enrichment/installing-integrations/","inLanguage":"en","dateModified":"2026-02-23T15:16:21+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Sending enrichment data batches to Contentsquare - APIs description: How to send enriched data with the Enrichment API lastUpdated: 09 May 2025 source_url: html: https://docs.contentsquare.com/en/api/enrichment/sending-enrichment-data-batches-cs/ md: https://docs.contentsquare.com/en/api/enrichment/sending-enrichment-data-batches-cs/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Once the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) has collected the required Contentsquare session identifiers, they can start enriching the Contentsquare data with their own data. Sending a batch of enrichment data falls into 2 steps: * Authenticating and retrieving the right enrichment endpoint dynamically * Sending the enrichment data to this endpoint with a valid JWT ## Authentication See the dedicated [Authentication section](https://docs.contentsquare.com/en/api/enrichment/authentication/). ## Sending data to the enrichment endpoint ### Prerequisites * Step 3: the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) must have the knowledge of which Contentsquare project ID and sessions the data will enrich * Step 4.1: the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) must have a valid JWT and base URL for the enrichment endpoint * All the enrichments of a batch sent to the enrichment endpoint have to match the schema version of the integration provided in the request (if an enrichment gets rejected, then the full batch will be rejected) ### HTTP Request #### Request * **Endpoint** (returned by the authentication call in step 4.1):\ `https://enrichment-api.{cloud}.contentsquare.com/v1/enrichments` * **Method**: `POST` * **Header**: `Authorization: Bearer {JWT access token}` * **Body**: ```json { "integrationVersion": 1, // required, provided by Contentsquare when creating a new schema "projectId": 1, // retrieved in step 3 "enrichments": [ { "userId": "{USER_ID}", // string, retrieved in step 3 "sessionNumber": {SESSION_NUMBER}, // integer, retrieved in step 3 "enrichmentNumber": 1, // integer, max 3, optional (will be 1 if not specified) "enrichment": { "field1": "Some string", "field2": 42, "field3": 3.14, "field4": "2022-03-23T00:10:30Z", "field5": true } } ] } ``` * `integrationVersion`: **a schema version for the integration must be specified** so that Contentsquare can know which schema the data must match. Every time a new schema is created, Contentsquare provides the provider with a new integration version. The [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) must take care of sending data that match the right schema version. If the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) has only one schema registered, then the `integrationVersion` should remain `1` by default. * `enrichmentNumber`: as a Contentsquare session can be enriched with up to 3 enrichments, each enrichment must be indexed so that it can potentially be updated later (see the [dedicated section](https://docs.contentsquare.com/en/api/enrichment/update-an-enrichment/) on how to update an enrichment). **Index should start at 1 and can be max 3**. If no enrichment number is specified by the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider), it will be considered as `1` by default (meaning that if the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) never specifies any enrichment number, any new enrichment for a session will overwrite the previous one and there will be only 1 enrichment per session - with index `1`) #### Response **Success `200`** (Empty body) #### Errors ##### Unauthorized: `401`: invalid JWT token ```json { "message": "Unauthorized" } ``` ##### Bad request `400`: data validation failed ```json { "message": "enrichments don't match expected payload" } ``` ##### Bad request `400`: bad integration version ```json { "message": "bad integration version" } ``` ### Example #### Request ```shell curl --location --request POST 'https://enrichment-api.ba.contentsquare.com/v1/enrichments' \ --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IktJRCJ9.eyJpc3MiOiJlbnJpY2htZW50SW50ZWdyYXRpb24iLCJpYXQiOiJJQVQiLCJleHAiOiJFWFAiLCJ2ZXJzaW9uIjoiMSIsInByb2plY3RJZCI6MTYyLCJpbnRlZ3JhdGlvbklkIjoxMDB9' \ --data-raw '{ "integrationVersion": 1, "projectId": 162, "enrichments": [ { "userId": "aaa-aaa-aaa", "sessionNumber": 5, "enrichmentNumber": 1, "enrichment": { "has_called": true, "call_duration": 3532, "call_client_rating": 4.5, "call_center_name": "RENNES", "call_date": "2022-01-01T20:02:22Z" } }, { "userId": "aaa-aaa-aaa", "sessionNumber": 5, "enrichmentNumber": 2, "enrichment": { "has_called": true, "call_duration": 2293, "call_client_rating": 2, "call_center_name": "RENNES", "call_date": "2022-01-01T18:09:54" } } ] }' ``` #### Response **Success `200`** ### Limitations * EnrichmentNumber: * Min: 1 * Max: 3 * Number of enrichments per batch: max 200 * Sessions that started more than 7 days ago cannot be enriched (enrichment for those sessions will not be rejected but no data will be available in the Contentsquare platform in the end) Note For security purposes, if any enrichment gets rejected, then the full enrichment batch it belongs to will be rejected. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Sending enrichment data batches to Contentsquare","description":"How to send enriched data with the Enrichment API","url":"https://docs.contentsquare.com/en/api/enrichment/sending-enrichment-data-batches-cs/","inLanguage":"en","dateModified":"2025-05-09T12:09:00+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Retrieving Contentsquare session identifiers from the customer's website - APIs description: How to retrieve User Identifiers with the Enrichment API lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/api/enrichment/retrieving-cs-session-ids-from-customers-website/ md: https://docs.contentsquare.com/en/api/enrichment/retrieving-cs-session-ids-from-customers-website/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Once an integration has been installed, the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) should start collecting Contentsquare session identifiers during web visits on the common customer's website. These identifiers will be used to attach the enrichment data to the right Contentsquare sessions when data will be received from the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider). Those identifiers are: * The **project ID**: identifies the Contentsquare project ID where the data is stored * The **user ID**: identifies the Contentsquare anonymous user ID for the user visiting the website * The **session number**: identifies a specific session (as an ordered index) of the user ID. For example, if Contentsquare has tracked 4 different sessions of the same anonymous user, the last session number will be 4. Note The combination of a user ID and session number makes a unique session identifier. ## How to get those Contentsquare session identifiers? ### Web During a visit on a website, you can interact with Contentsquare's tag to pull those identifiers via the [`afterPageView`](https://docs.contentsquare.com/en/web/third-party-integrations-and-implementation-examples/#afterpageview) command. A JavaScript code using that command should look like this: ```javascript const yourCallback = (context) => { const projectId = context.projectId; const [userId, sessionNumber] = context.sessionKey.split("."); // store these Contentsquare session identifiers in your backend }; window._uxa = window._uxa || []; _uxa.push(["afterPageView", yourCallback]); ``` By calling this function you will get the project ID, user ID and session number of each session that are required to identify the Contentsquare sessions to be enriched. Tip We advise [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) to group the data by project ID as each project ID will require specific OAuth credentials to authenticate. ### Android native You can call the Contentsquare public API on the Android SDK to retrieve these identifiers at any time. ```kotlin val projectId = Contentsquare.getProjectId() val sessionNumber = Contentsquare.getSessionNumber() // store these Contentsquare session identifiers in your backend ``` Tip We advise [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) to group the data by project ID as each project ID will require specific OAuth credentials to authenticate. ### iOS native You can call the Contentsquare public API on the iOS SDK to retrieve these identifiers at any time. ```swift let projectID = Contentsquare.projectID let sessionNumber = Contentsquare.sessionNumber // store these Contentsquare session identifiers in your backend ``` Tip We advise [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) to group the data by project ID as each project ID will require specific OAuth credentials to authenticate. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Retrieving Contentsquare session identifiers from the customer's website","description":"How to retrieve User Identifiers with the Enrichment API","url":"https://docs.contentsquare.com/en/api/enrichment/retrieving-cs-session-ids-from-customers-website/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Update an enrichment - APIs description: Updating an enrichment using the API lastUpdated: 27 April 2025 source_url: html: https://docs.contentsquare.com/en/api/enrichment/update-an-enrichment/ md: https://docs.contentsquare.com/en/api/enrichment/update-an-enrichment/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. If the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) wants to update a specific enrichment, it can be done thanks to the `enrichmentNumber` key. While incrementing this key represents a whole new "event" for the target session, sending an enrichment with an enrichment number already used for that session will overwrite the enrichment that was sent previously with the same enrichment number. Use this to update the data that was sent previously based on some new information the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) processed for the same event. ## Example In a scenario where the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) is a company that tracks phone calls, it might happen that some data related to the call gets processed after the original enrichment for this call was sent (for example, a conversion occurred following the call but was not materialized yet the first time the call data was sent to Contentsquare). In such a case, as it's still related to the same phone call, the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) can update the enrichment later instead of sending a whole new enrichment. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Update an enrichment","description":"Updating an enrichment using the API","url":"https://docs.contentsquare.com/en/api/enrichment/update-an-enrichment/","inLanguage":"en","dateModified":"2025-04-27T18:55:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Authentication - APIs description: How to authenticate to use the Metrics API lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/api/metrics/authentication/ md: https://docs.contentsquare.com/en/api/metrics/authentication/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare APIs authenticate via server-to-server OAuth 2.0 credentials generated from the Contentsquare console. Warning **Since April 30th, 2024, API keys are no longer supported**. You must use OAuth credentials instead to authenticate on our APIs, and migrate your existing applications using API keys. ## OAuth2 authentication The Contentsquare APIs use the server-to-server OAuth 2.0 standard for authentication, also know as 2-legged OAuth or OAuth 2LO. The flow basically consists in calling an authentication endpoint with a pair `client_id` / `client_secret` to retrieve an access token that remains valid for 1 hour. This JWT token should then be used as a Bearer token in the headers of your HTTPS requests (in the form `Authorization: Bearer YOUR_ACCESS_TOKEN`). the API call to the authentication endpoint will also dynamically return the right base URL that you must use. This base URL depends on which cloud the target project is installed on. You can refer below to a [detailed example](#example-of-authentication-flow) of the overall flow to retrieve a token and a base URL, and use those to query the Metrics API. You can generate a pair `client_id` / `client_secret` from the Contentsquare [console ↗](https://console.contentsquare.com), as a Contentsquare administrator. You can find how to generate these credentials in our Help Center documentation. You can create OAuth credentials either: * At the Project level, to request access resources from a specific project only * At the Account level: to request access for any project of the account Warning Your OAuth credentials carry many privileges, so make sure to keep them secure! Do not share them in publicly accessible areas such as GitHub, client-side code, and so forth. ## Refresh your access token Once you get a JWT access token (see the [authentication endpoint](#authentication-endpoint) below), it's valid for 1 hour. If you try to query the Contentsquare APIs with access to token that has expired, you will receive a `401 Unauthorized` error with the error code `JWT_EXPIRED`, in the form: ```json { "success": false, "errorMessage": "Auth token is expired.", "errorCode": "JWT_EXPIRED" } ``` In that case, you should first use your OAuth credentials (your pair `client_id` / `client_secret`) to query a new The OAuth credentials expire after 1 year. See [How to regenerate OAuth credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593-How-to-create-API-credentials#section4). ## Authentication endpoint POST [https://api.contentsquare.com/v1/oauth/token ↗](https://api.contentsquare.com/v1/oauth/token) ### Request parameters * #### client\_id  string  Required The OAuth `client_id` generated from the Contentsquare console. * #### client\_secret  string  Required The OAuth `client_secret` generated from the Contentsquare console. * #### grant\_type  string  Required Always set it to `"client_credentials"`, as required by the OAuth 2.0 standard. * #### scope  string  Required You should use `"metrics"`. If needed, you can specify a list of several scopes to get a token that can query several APIs (for example "data-export metrics" if you want your token to cover both the [Data Export API](https://docs.contentsquare.com/en/api/export/) and Metrics API scopes). The only scope that cannot be combined with other scopes is `enrichment`. * #### project\_id  integer   Required only if you use account-level OAuth credentials, to specify which project of the account you want to target. ### Request example ```shell curl --location 'https://api.contentsquare.com/v1/oauth/token' \ --header 'Content-Type: application/json' \ --data '{ "client_id": "c3133d76-a768-4f5a-XXX", "client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX", "grant_type": "client_credentials", "scope": "metrics", "project_id": 42 }' ``` ### Response example ```json { "access_token": "eyJhbGciOiJSIsImtpY5MTXXX.CNTcKWAUb2mTp2cZyiDRYYOtGCKXXX", // to be used as bearer token to query the APIs "token_type": "bearer", "expires_in": 3600, "scope": "metrics", "project_id": 42, "endpoint": "https://api.eu-west-1.production.contentsquare.com" // this is the base URL you should use to query the Metrics API endpoints - the provided URL depends on the cloud the project is installed on } ``` ## Example of authentication flow Below is a sample of JavaScript code to show a complete API call flow that first retrieves an access token and then use it to retrieve the list of segments on a project: ```javascript const clientId = "<your_client_id>"; const clientSecret = "<your_client_secret>"; const authEndpoint = "https://api.contentsquare.com/v1/oauth/token"; const authRequestOptions = { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ client_id: clientId, client_secret: clientSecret, grant_type: "client_credentials", project_id: 42, scope: "metrics", }), }; const authResponse = await fetch(authEndpoint, authRequestOptions); const authJsonData = await authResponse.json(); // Below are the access token and base URL that must be used to query the Metrics API endpoints const accessToken = authJsonData.access_token; const baseURL = authJsonData.endpoint; // Using the access token and base URL to query the Metrics API endpoints and get the segments in this example const metricsApiEndpointResponse = await fetch(`${baseURL}/v1/segments`, { headers: { Authorization: `Bearer ${accessToken}` }, }); const metricsApiEndpointauthJsonData = await metricsApiEndpointResponse.json(); const segments = metricsApiEndpointauthJsonData.payload; ``` ## OAuth credentials information endpoint POST [https://api.contentsquare.com/v1/oauth/me ↗](https://api.contentsquare.com/v1/oauth/me) ### Request parameters * #### client\_id  string  Required The OAuth `client_id` generated from the Contentsquare console. * #### client\_secret  string  Required The OAuth `client_secret` generated from the Contentsquare console. ### Request example ```shell curl --location 'https://api.contentsquare.com/v1/oauth/me' \ --header 'Content-Type: application/json' \ --data '{ "client_id": "c3133d76-a768-4f5a-XXX", "client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX", }' ``` ### Response example ```json { "scopes": "metrics data-export session-replay symbolicator", "permissions": { "projects": [ { "id": 42, "name": "UX ANALYTICS" } ] } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Authentication","description":"How to authenticate to use the Metrics API","url":"https://docs.contentsquare.com/en/api/metrics/authentication/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Date Ranges - APIs description: How to manage Metrics endpoints date ranges lastUpdated: 25 April 2025 source_url: html: https://docs.contentsquare.com/en/api/metrics/date-ranges/ md: https://docs.contentsquare.com/en/api/metrics/date-ranges/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. For metrics endpoints, you need to specify the date range you want to query. On the Contentsquare platform, you cannot query more than 92 days of data for at once (this is to guarantee reliability and performance). If a date range exceeds 92 days or is out of the project data retention period, the API will return an error message indicating that the range is out of bounds. In terms of format, dates must respect one of the following ISO formats: * 2021-08-13T12:32.000Z (`YYYY-MM-DDThh:mm:ss.sssZ`) for a date in UTC. * 2021-08-13T12:32(`YYYY-MM-DDThh:mm:ss`), equivalent to 2021-08-13T12:32.000Z. * 2021-08-13T12(`YYYY-MM-DDThh:mm`), equivalent to 2021-08-13T12:32.000Z. * 2021-08-13 (`YYYY-MM-DD`), equivalent to 2021-08-13T00:00.000Z. * 2021-08 (`YYYY-MM`), equivalent to 2021-08-01T00:00.000Z. * 2021-08-13T12:32+02(`YYYY-MM-DDThh:mm:ss+hh:mm`) where the part after the `+` (it can also be `-`) represents the time zone UTC offset. Keep in mind that when specifying dates in URL parameters, the `+` character must be encoded into `%2B` (for example: `2021-08-13T12:32:40%2B02:00`). * 2021-08-13T12+02(`YYYY-MM-DDThh:mm+hh:mm`), equivalent to 2021-08-13T12:32+02. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Date Ranges","description":"How to manage Metrics endpoints date ranges","url":"https://docs.contentsquare.com/en/api/metrics/date-ranges/","inLanguage":"en","dateModified":"2025-04-25T18:04:06+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Limits - APIs description: Metrics API requests limits lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/api/metrics/limits/ md: https://docs.contentsquare.com/en/api/metrics/limits/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Metrics API enforces request and credential limits at the project level. * 10 concurrent requests maximum per project * 10 OAuth credentials (`client_id`/`client_secret`) per project and per account maximum * The data available for query is limited to the project contractual data retention period Note **Limitations are tracked at the project level**, not at the OAuth credentials level. So if you have created several OAuth credentials requesting resources for a target project, the total number of concurrent requests must not exceed 10 for a specific project, all credentials taken into account. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Limits","description":"Metrics API requests limits","url":"https://docs.contentsquare.com/en/api/metrics/limits/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Update an integration schema - APIs description: Update an integration schema with the Enrichment API lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/api/enrichment/update-an-integration-schema/ md: https://docs.contentsquare.com/en/api/enrichment/update-an-integration-schema/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. If the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) wants to update the schema of an integration, it can be done thanks to the `integrationVersion` key. By incrementing the version, the provider can decide to add, delete, or edit keys of the data schema while protecting enrichment flows that may prevail based on a previous schema. Enrichments batches should specify the `integrationVersion` so that the data is compared to the right schema. ## Example In a scenario where a [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) wants to update its integration to add new enrichment fields, the provider can: * Send to Contentsquare a new integration version to be registered * While Contentsquare is reviewing and registering the new schema, enrichments can still be sent on the previous schema * When the new schema is registered eventually, the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) can switch to the new schema for all new enrichment by the specifying the right version in the enrichment batches * Potentially some customers could still decide to rely on the previous schema if needed (then the [Provider](https://docs.contentsquare.com/en/api/enrichment/definitions/#provider) would need to keep a mapping of which customer relies on which version) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Update an integration schema","description":"Update an integration schema with the Enrichment API","url":"https://docs.contentsquare.com/en/api/enrichment/update-an-integration-schema/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Object endpoints - APIs description: Metrics API objects reference lastUpdated: 21 September 2025 source_url: html: https://docs.contentsquare.com/en/api/metrics/objects-endpoints/ md: https://docs.contentsquare.com/en/api/metrics/objects-endpoints/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The metrics API replicates the behavior of the analysis context in Contentsquare. To get a metric, you can filter by device, segment etc. Plus, for page groups and zones metrics, you will have to define for which page group or zones you want data. To help you, we provide an API that retrieves these objects: segments, page groups etc. ## Segments GET /v1/segments Get the list of all segments for a project. [More information regarding segments in Contentsquare ↗](https://support.contentsquare.com/hc/en-us/articles/204368141) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### ids  string   Filter the results and get a list of segments that matches the ids provided. Multiple IDs should be separated by a comma. ### Example of response ```json { "payload": [ { "id": 1, "name": "New visitors", "source": "contentsquare", "createdAt": "2019-11-21T09:46:16.000Z", "updatedAt": "2019-11-21T09:46:16.000Z" } ], "success": true } ``` ## Goals GET /v1/goals Get the list of all goals for a project. [More information regarding goals in Contentsquare ↗](https://support.contentsquare.com/hc/en-us/articles/37271667397905) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. ### Example of response ```json { "payload": [ { "id": 100, "name": "Reach Cart", "type": "pageview", "createdAt": "2019-10-05T10:34:42.670Z", "updatedAt": "2019-11-21T09:46:09.000Z" } ], "success": true } ``` ## Mappings GET /v1/mappings Get the list of all mappings for a project. [More information regarding mappings in Contentsquare ↗](https://support.contentsquare.com/hc/en-us/articles/37271862920465) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### ids  string   Filter the results and get a list of segments that matches the ids provided. Multiple IDs should be separated by a comma. ### Example of response ```json { "payload": [ { "id": 101010, "name": "New Zoning Mapping", "description": "Test", "createdAt": "2019-11-05T09:44:51.000Z", "updatedAt": "2019-11-05T09:45:05.000Z" } ], "success": true } ``` GET /v1/mappings/{mappingId} Get information for a specific mapping [More information regarding mappings in Contentsquare ↗](https://support.contentsquare.com/hc/en-us/articles/208559985) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. ### Path parameters * #### mappingId  integer  Required The Mapping ID. ### Example of response ```json { "payload": [ { "id": 101010, "name": "New Zoning Mapping", "description": "Test", "createdAt": "2019-11-05T09:44:51.000Z", "updatedAt": "2019-11-05T09:45:05.000Z" } ], "success": true } ``` ## Page Groups GET /v1/mappings/{mappingId}/page-groups Get all the page groups for a specific mapping [More information regarding mappings and page groups in Contentsquare ↗](https://support.contentsquare.com/hc/en-us/articles/208559985) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. ### Path parameters * #### mappingId  integer  Required The Mapping ID. ### Example of response ```json { "payload": [ { "id": 1010, "name": "Product Pages", "category": "Other" } ], "success": true } ``` GET /v1/page-groups/{pageGroupId} Get information about a page and all the related mappings [More information regarding page groups in Contentsquare ↗](https://support.contentsquare.com/hc/en-us/articles/208559985) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. ### Path parameters * #### pageGroupId  integer  Required The Page Group ID. ### Example of response ```json { "payload": { "id": 1010, "name": "Product pages", "category": "Other", "mappings": [ { "id": 147, "name": "Ecommerce", "description": null, "createdAt": "2018-10-16T11:37:36.000Z", "updatedAt": "2019-08-21T07:12:18.000Z" }, { "id": 148, "name": "All pages", "description": null, "createdAt": "2018-10-16T12:49:49.000Z", "updatedAt": "2019-08-21T07:12:23.000Z" } ] }, "success": true } ``` ## Zonings GET /v1/page-groups/{pageGroupId}/zonings Get all the zonings for a page group [More information regarding zonings in Contentsquare ↗](https://support.contentsquare.com/hc/en-us/articles/360010600620) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. ### Path parameters * #### pageGroupId  integer  Required The Page Group ID. ### Example of response ```json { "payload": [ { "id": 100, "name": "Revamp product page", "createdAt": "2019-10-25T13:12:45.000Z", "lastUpdatedAt": "2019-10-29T11:11:22.000Z" } ], "success": true } ``` ## Zones GET /v1/zonings/{zoningId}/zones Get all the zones for a zoning [More information regarding zonings in Contentsquare ↗](https://support.contentsquare.com/hc/en-us/articles/360010600620) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. ### Path parameters * #### zoningId  integer  Required The Zoning ID. ### Example of response ```json { "payload": [ { "id": 100, "name": "Add to cart button" } ], "success": true } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Object endpoints","description":"Metrics API objects reference","url":"https://docs.contentsquare.com/en/api/metrics/objects-endpoints/","inLanguage":"en","dateModified":"2025-09-21T10:20:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Page Group Metrics endpoints - APIs description: Page Group Metrics endpoints reference lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/api/metrics/page-group-metrics-endpoints/ md: https://docs.contentsquare.com/en/api/metrics/page-group-metrics-endpoints/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use these endpoints to query metrics at the page group level. ## All page groups metrics GET /v1/metrics/page-group/{pageGroupId} Returns all page group metrics between two dates. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments * #### goalId  integer   To return conversion metrics for a non-ecommerce goal. ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 4.820247587511826, "name": "activityRate", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 64.65578424414478, "name": "bounceRate", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 4.267288693743139, "name": "conversionRate", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 9.558127422045425, "name": "elapsedTime", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 63.23623764917233, "name": "exitRate", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 907.4778647504171, "name": "foldHeight", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 1009.0064436943848, "name": "interactionTime", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 13.648339726452013, "name": "landingRate", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 1.6267757352941177, "name": "loadingTime", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 3862.80071859361, "name": "pageHeight", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 53.2996317888923, "name": "scrollRate", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 4.267288693743139, "name": "transformationRate", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 7284, "name": "uniqueVisits", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 7793, "name": "views", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 1.0692919868276618, "name": "viewsVisits", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 7288, "name": "visits", "currency": "USD" } ] }, "success": true } ``` ## Activity rate GET /v1/metrics/page-group/{pageGroupId}/activity-rate The ratio of time visitors spend interacting with the page to the time spent on the page. Displayed as percentage. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955253) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 4.820247587511827, "name": "activityRate", "currency": "USD" } ] }, "success": true } ``` ## Bounce rate GET /v1/metrics/page-group/{pageGroupId}/bounce-rate The ratio between the visitors who landed on the page and left the site without having seen a second page and all visitors who landed on the page. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017792914) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 64.65578424414478, "name": "bounceRate", "currency": "USD" } ] }, "success": true } ``` ## Conversion rate GET /v1/metrics/page-group/{pageGroupId}/conversion-rate Ratio between the number of users that viewed the page and reached the goal during their navigation and the number of users that viewed the page. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments * #### goalId  integer   To return conversion metrics for a non-ecommerce goal. ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 4.267288693743139, "name": "conversionRate", "currency": "USD" } ] }, "success": true } ``` ## Exit rate GET /v1/metrics/page-group/{pageGroupId}/exit-rate The ratio between the number of views of the page which are the last page view of the session and the total number of views of the page. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360018106413) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 63.23623764917233, "name": "exitRate", "currency": "USD" } ] }, "success": true } ``` ## Height / Fold Height GET /v1/metrics/page-group/{pageGroupId}/fold-height Average screen height. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 907.4778647504171, "name": "foldHeight", "currency": "USD" } ] }, "success": true } ``` ## Interaction time GET /v1/metrics/page-group/{pageGroupId}/interaction-time The average time spent interacting on the page. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 1009.0064436943848, "name": "interactionTime", "currency": "USD" } ] }, "success": true } ``` ## Landing rate GET /v1/metrics/page-group/{pageGroupId}/landing-rate Ratio between users that landed on this screen and the total number of users. For mobile project only. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 13.648339726452013, "name": "landingRate", "currency": "USD" } ] }, "success": true } ``` ## Loading time / Load time Deprecated As of July 8th, 2024, this endpoint is deprecated.\ To retrieve the web performance metrics of a page, use the [Web Vitals](https://docs.contentsquare.com/en/api/metrics/page-group-metrics-endpoints/#web-vitals) endpoint instead. GET /v1/metrics/page-group/{pageGroupId}/loading-time The average time in seconds between the call of the page and when the visitor can start interacting with it. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955393) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 1.6267757352941177, "name": "loadingTime", "currency": "USD" } ] }, "success": true } ``` ## Page height GET /v1/metrics/page-group/{pageGroupId}/page-height The average height of the page in pixels at its first load (an average for all the URLs included in the page). [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017793174) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 3862.80071859361, "name": "pageHeight", "currency": "USD" } ] }, "success": true } ``` ## Scroll rate GET /v1/metrics/page-group/{pageGroupId}/scroll-rate The proportion of the page displayed by visitors (the ratio between the last line of pixels displayed on the screen and the height of the page). [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017792994) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 53.2996317888923, "name": "scrollRate", "currency": "USD" } ] }, "success": true } ``` ## Time spent / Elapsed time GET /v1/metrics/page-group/{pageGroupId}/elapsed-time The average time spent on the page, from the first page view trigger to the last event sent. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017793034) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments * #### goalId  integer   To return conversion metrics for a non-ecommerce goal. ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 9.558127422045425, "name": "elapsedTime", "currency": "USD" } ] }, "success": true } ``` ## Unique visits GET /v1/metrics/page-group/{pageGroupId}/unique-visits The number of unique users who saw the selected page at least once during their session. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 7284, "name": "uniqueVisits", "currency": "USD" } ] }, "success": true } ``` ## Views GET /v1/metrics/page-group/{pageGroupId}/views The number of times the page was viewed. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955073) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 7793, "name": "views", "currency": "USD" } ] }, "success": true } ``` ## Views / Visit GET /v1/metrics/page-group/{pageGroupId}/views-visits The average number of times the page is viewed per visit. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017968913) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 1.0692919868276618, "name": "viewsVisits", "currency": "USD" } ] }, "success": true } ``` ## Visits GET /v1/metrics/page-group/{pageGroupId}/visits Number of sessions where the page has been seen at least once. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955153) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 7288, "name": "visits", "currency": "USD" } ] }, "success": true } ``` ## Web Vitals Access to some metrics / capabilities requires Speed Analysis RUM. Reach out to your point of contact at Contentsquare for more information. GET /v1/metrics/page-group/{pageGroupId}/web-vitals Returns a list of Web Vitals metrics (including Core Web Vitals). The `firstInputDelay` metric has been deprecated in favor of `interactionToNextPaint` and will be removed in the future. ### Query parameters * #### projectId  integer   Required only for an account-level API key. Specifies the target project * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments * #### metricType  string   Possible values: `Quantile` (default), `Average`. * #### quantile  number   Default to the 75th percentile of each metric if the metric type is `Quantile`. It is ignored if the metric type is `Average`. ### Path parameters * #### pageGroupId  integer  Required The ID of the Page Group. ### Example of response ```json { "payload": { "values": [ { "value": 0.003103, "startDate": "2024-06-01T00:00:00.000Z", "endDate": "2024-06-04T00:00:00.000Z", "name": "cumulativeLayoutShift", "metricType": "Quantile", "quantile": 0.9 }, { "value": 0.016, "startDate": "2024-06-01T00:00:00.000Z", "endDate": "2024-06-04T00:00:00.000Z", "name": "interactionToNextPaint", "metricType": "Quantile", "quantile": 0.9 }, { "value": 0.002, "startDate": "2024-06-01T00:00:00.000Z", "endDate": "2024-06-04T00:00:00.000Z", "name": "firstInputDelay", // deprecated "metricType": "Quantile", "quantile": 0.9 }, { "value": 2.468, "startDate": "2024-06-01T00:00:00.000Z", "endDate": "2024-06-04T00:00:00.000Z", "name": "firstContentfulPaint", "metricType": "Quantile", "quantile": 0.9 }, { "value": 2.256, "startDate": "2024-06-01T00:00:00.000Z", "endDate": "2024-06-04T00:00:00.000Z", "name": "timeToFirstByte", "metricType": "Quantile", "quantile": 0.9 }, { "value": 2.444, "startDate": "2024-06-01T00:00:00.000Z", "endDate": "2024-06-04T00:00:00.000Z", "name": "largestContentfulPaint", "metricType": "Quantile", "quantile": 0.9 } ] }, "success": true } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Page Group Metrics endpoints","description":"Page Group Metrics endpoints reference","url":"https://docs.contentsquare.com/en/api/metrics/page-group-metrics-endpoints/","inLanguage":"en","dateModified":"2026-04-14T16:34:01+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Site metrics endpoints - APIs description: Site metrics endpoints reference lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/api/metrics/site-metrics-endpoints/ md: https://docs.contentsquare.com/en/api/metrics/site-metrics-endpoints/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use these endpoints to query metrics at the site level. ## All site metrics GET /v1/metrics/site Returns all site metrics between two dates. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments * #### goalId  integer   To return conversion metrics for a non-ecommerce goal. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 93.00790024010534, "name": "bounceRate", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 186.890756302521, "name": "cartAverage", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 3649, "name": "conversionCount", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 7.068828577516902, "name": "conversionRate", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 1.1468321586244288, "name": "pageviewAverage", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 22240, "name": "revenueSum", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 3.1195242041669893, "name": "sessionTimeAverage", "currency": "USD" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 51644, "name": "visits", "currency": "USD" } ] }, "success": true } ``` ## Bounce rate GET /v1/metrics/site/bounce-rate The ratio between the visitors who entered the site and left it without having seen a second page and all visitors. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017952113) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 93.00790024010534, "name": "bounceRate", "currency": "USD" } ] }, "success": true } ``` ## Cart average GET /v1/metrics/site/cart-average The average cart amount is calculated by dividing the total revenue by the number of transactions. This metric is only accessible for "e-commerce" projects. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017789914) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 186.890756302521, "name": "cartAverage", "currency": "USD" } ] }, "success": true } ``` ## Conversions GET /v1/metrics/site/conversions The number of sessions where a specified goal was reached. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017952553) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### goalId  integer   **Required only for non "e-commerce" projects**. Goal filter for analysis. If not specified for an "e-commerce" project, the API will return data for the "e-commerce" goal. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 3649, "name": "conversionCount", "currency": "USD" } ] }, "success": true } ``` ## Conversion rate GET /v1/metrics/site/conversion-rate Ratio between the number of sessions where a specified goal was reached and the total number of sessions. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017789914) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### goalId  integer   **Required only for non "e-commerce" projects**. Goal filter for analysis. If not specified for an "e-commerce" project, the API will return data for the "e-commerce" goal. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 7.068828577516902, "name": "conversionRate", "currency": "USD" } ] }, "success": true } ``` ## Pageview average GET /v1/metrics/site/pageview-average Average number page views during a session (a page that has been refreshed counts as one view). ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 1.1468321586244288, "name": "pageviewAverage", "currency": "USD" } ] }, "success": true } ``` ## Revenue GET /v1/metrics/site/revenue Sum of all the transaction amounts. This metric is only accessible for "e-commerce" projects. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 22240, "name": "revenueSum", "currency": "USD" } ] }, "success": true } ``` ## Session time average GET /v1/metrics/site/session-time-average Average time spent from entry on the site to site exit for each visit. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 3.1195242041669893, "name": "sessionTimeAverage", "currency": "USD" } ] }, "success": true } ``` ## Visits GET /v1/metrics/site/visits Number of sessions. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017951413) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 51644, "name": "visits", "currency": "USD" } ] }, "success": true } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Site metrics endpoints","description":"Site metrics endpoints reference","url":"https://docs.contentsquare.com/en/api/metrics/site-metrics-endpoints/","inLanguage":"en","dateModified":"2026-04-14T16:34:01+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Zone metrics for Apps endpoints - APIs description: Zone Metrics for Apps endpoints reference lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/api/metrics/zone-metrics-endpoints-apps/ md: https://docs.contentsquare.com/en/api/metrics/zone-metrics-endpoints-apps/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use these endpoints to query zone metrics for apps. ## All zone metrics GET /v1/metrics/zone/{zoneId} Returns all zone metrics between two dates ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 16.953225338691635, "name": "avgTransactionAfterTap", "device": "mobile", "currency": "EUR" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 0.11907269940804448, "name": "dragFlickRate", "device": "mobile", "currency": "EUR" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 1.0633130962705983, "name": "dragFlickRecurrence", "device": "mobile", "currency": "EUR" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 7.6946619277745105, "name": "revenuePerTap", "device": "mobile", "currency": "EUR" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 12.096980737693068, "name": "tapRate", "device": "mobile", "currency": "EUR" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 1.0165105816266422, "name": "tapRecurrence", "device": "mobile", "currency": "EUR" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 4.493400932241734, "name": "timeBeforeFirstTap", "device": "mobile", "currency": "EUR" }, { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 902791.6, "name": "totalRevenueWithTap", "device": "mobile", "currency": "EUR" } ] }, "success": true } ``` ## Conversion rate per tap GET /v1/metrics/zone/{zoneId}/conversion-rate-per-tap Of users that tapped on the zone, the percentage that also completed the selected goal during the same session. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments * #### goalId  integer   To return conversion metrics for a non-ecommerce goal. ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 16.953225338691635, "name": "avgConversionAfterTap", "device": "mobile", "currency": "EUR" } ] }, "success": true } ``` ## Revenue GET /v1/metrics/zone/{zoneId}/revenue Total revenue generated by users who clicked on the zone. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 900157.6, "name": "totalRevenueWithTap", "device": "mobile", "currency": "EUR" } ] }, "success": true } ``` ## Revenue per tap GET /v1/metrics/zone/{zoneId}/revenue-per-tap Average revenue per tap generated by users after they tapped on an element. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 7.684434465625721, "name": "revenuePerTap", "device": "mobile", "currency": "EUR" } ] }, "success": true } ``` ## Swipe rate GET /v1/metrics/zone/{zoneId}/swipe-rate Percentage of users performing at least one swipe on a zone during a screen display. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 0.6463799007761929, "name": "dragFlickRate", "device": "mobile", "currency": "EUR" } ] }, "success": true } ``` ## Swipe recurrence GET /v1/metrics/zone/{zoneId}/swipe-recurrence Average number of times an element was swiped when engaged with during a screenview. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 1.0633130962705983, "name": "dragFlickRecurrence", "device": "mobile", "currency": "EUR" } ] }, "success": true } ``` ## Tap rate GET /v1/metrics/zone/{zoneId}/tap-rate Percentage of users that tapped on the zone at least once. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 12.096980737693068, "name": "tapRate", "device": "mobile", "currency": "EUR" } ] }, "success": true } ``` ## Tap recurrence GET /v1/metrics/zone/{zoneId}/tap-recurrence Average number of times an element was tapped when engaged with during a screenview. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 1.0165105816266422, "name": "tapRecurrence", "device": "mobile", "currency": "EUR" } ] }, "success": true } ``` ## Time before first tap GET /v1/metrics/zone/{zoneId}/time-before-first-tap Number of seconds between screen load and first tap on an element. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-07-16T00:00:00.000Z", "endDate": "2021-07-22T00:00:00.000Z", "value": 4.493400932241734, "name": "timeBeforeFirstTap", "device": "mobile", "currency": "EUR" } ] }, "success": true } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Zone metrics for Apps endpoints","description":"Zone Metrics for Apps endpoints reference","url":"https://docs.contentsquare.com/en/api/metrics/zone-metrics-endpoints-apps/","inLanguage":"en","dateModified":"2026-04-14T16:34:01+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Zone metrics for Web endpoints - APIs description: Zone Metrics for Web endpoints reference lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/api/metrics/zone-metrics-endpoints-web/ md: https://docs.contentsquare.com/en/api/metrics/zone-metrics-endpoints-web/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use these endpoints to query zone metrics for web. ## All zone metrics GET /v1/metrics/zone/{zoneId} Returns all zone metrics between two dates ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments * #### goalId  integer   To return conversion metrics for a non-ecommerce goal. ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T09:59:03.543Z", "value": 6.033720930232558, "name": "averageRevenueAfterClick", "device": "desktop", "currency": "USD" }, { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T09:59:03.543Z", "value": 10.497237569060774, "name": "avgConversionAfterClick", "device": "desktop", "currency": "USD" }, { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T09:59:03.543Z", "value": 10.9011137360783, "name": "avgConversionAfterHover", "device": "desktop", "currency": "USD" }, { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T09:59:03.543Z", "value": 0.003087246192893401, "name": "avgHoverTime", "device": "desktop", "currency": "USD" }, { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T09:59:03.543Z", "value": 33.472123489387634, "name": "clickRate", "device": "desktop", "currency": "USD" }, { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T09:59:03.543Z", "value": 1.4462985436893203, "name": "clickRepetition", "device": "desktop", "currency": "USD" }, { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T09:59:03.543Z", "value": 104.56852791878173, "name": "engagementRateLive", "device": "desktop", "currency": "USD" }, { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T09:59:03.543Z", "value": 0.5985779733009708, "name": "hesitation", "device": "desktop", "currency": "USD" }, { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T09:59:03.543Z", "value": 32.00974916218137, "name": "hoverRate", "device": "desktop", "currency": "USD" }, { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T09:59:03.543Z", "value": 15.274424150485437, "name": "timeBeforeFirstClick", "device": "desktop", "currency": "USD" }, { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T09:59:03.543Z", "value": 4767, "name": "totalClicks", "device": "desktop", "currency": "USD" }, { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T09:59:03.543Z", "value": 25945, "name": "totalRevenueAfterClick", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Attractiveness rate GET /v1/metrics/zone/{zoneId}/attractiveness-rate The percentage of page views with at least one select the zone out of the views where the zone was displayed. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017956153) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-10-10T22:00:00.000Z", "endDate": "2021-10-17T21:59:59.000Z", "value": 4.808743169398907, "name": "attractivityRate", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Click rate GET /v1/metrics/zone/{zoneId}/click-rate The percentage of pageviews with at least one select the zone. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955553) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T17:10:50.314Z", "value": 33.472123489387634, "name": "clickRate", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Click recurrence GET /v1/metrics/zone/{zoneId}/click-recurrence The average number of clicks on the zone, for pageviews with at least one select the zone. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017793794) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T17:11:13.661Z", "value": 1.4462985436893203, "name": "clickRepetition", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Conversion Rate per Click GET /v1/metrics/zone/{zoneId}/conversion-rate-per-click Percentage of visitors who achieved the goal after clicking on a zone. This metric allows you to determine whether interaction (click) with a zoning encourages or prevents visitors from exhibiting the goal. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955713) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments * #### goalId  integer   To return conversion metrics for a non-ecommerce goal. ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T17:11:44.754Z", "value": 10.497237569060774, "name": "avgConversionAfterClick", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Conversion Rate per Hover GET /v1/metrics/zone/{zoneId}/conversion-rate-per-hover Percentage of visitors who achieved the goal after hovering on a zone. This metric allows you to determine whether consumption (hover) of zone is contributing or detrimental to completing the goal. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955633) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments * #### goalId  integer   To return conversion metrics for a non-ecommerce goal. ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T17:12:16.518Z", "value": 10.9011137360783, "name": "avgConversionAfterHover", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Engagement Rate GET /v1/metrics/zone/{zoneId}/engagement-rate Percentage of visitors who clicked after having hovered a zone. This metric translates the affordance of an element, that is its capacity to define how it should be interacted with through its design. For example, the design of a CTA should make it obvious that it should be clicked. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955793) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T17:12:56.222Z", "value": 104.56852791878173, "name": "engagementRateLive", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Exposure rate GET /v1/metrics/zone/{zoneId}/exposure-rate The exposure rate takes into account the time spent on a zone. If a user scrolled through a zone very quickly, it will not be taken into account in the exposure data. A zone can only be considered "exposed" if it has been displayed for at least 150 milliseconds. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955993) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-10-10T22:00:00.000Z", "endDate": "2021-10-17T21:59:59.000Z", "value": 87.4, "name": "exposureRate", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Exposure time GET /v1/metrics/zone/{zoneId}/exposure-time Time a zone was exposed. A zone can only be considered "exposed" if it has been displayed for at least 150 milliseconds. If you scroll fast from the top to the bottom of the page, the middle page will not be taken into account as the scroll movement is too fast to consider the zones in the middle have been exposed.. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017956013) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-10-10T22:00:00.000Z", "endDate": "2021-10-17T21:59:59.000Z", "value": 20.451490710382515, "name": "exposureTime", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Hesitation time GET /v1/metrics/zone/{zoneId}/hesitation Average time elapsed between the last hover and the first select a zone. This metric translates whether the content is understood quickly or if users hesitate before clicking. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017794714) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T17:13:21.844Z", "value": 0.5985779733009708, "name": "hesitation", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Hover Rate GET /v1/metrics/zone/{zoneId}/hover-rate Percentage of users who hovered a zone at least once. This metric determines which zones are consumed the most. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955753) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T17:13:51.154Z", "value": 32.00974916218137, "name": "hoverRate", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Hover time / Float time GET /v1/metrics/zone/{zoneId}/hover-time Average total time spent hovering over an element. This metric translates interest or lack of clarity, depending on the type of element. For example, a float time over 3 seconds is positive on an image or description text but is not on a CTA. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955833) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T17:14:10.533Z", "value": 0.003087246192893401, "name": "avgHoverTime", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Number of clicks GET /v1/metrics/zone/{zoneId}/number-of-clicks The total number of clicks on the zone, for pageviews with at least one select the zone. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T17:14:33.276Z", "value": 4767, "name": "totalClicks", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Revenue GET /v1/metrics/zone/{zoneId}/revenue Total revenue generated by the segmented users after they clicked on an element. This metric ranks elements based on their contribution to revenue. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017790814) This metric is only accessible for "e-commerce" projects. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T17:14:56.993Z", "value": 25945, "name": "totalRevenueAfterClick", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Revenue per Click GET /v1/metrics/zone/{zoneId}/revenue-per-click Average revenue per click generated by users after they clicked on an element. This metric ranks elements based on their contribution to revenue. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955733) This metric is only accessible for "e-commerce" projects. ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T17:15:15.384Z", "value": 7.871662621359223, "name": "averageRevenueAfterClick", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ## Time Before First Click GET /v1/metrics/zone/{zoneId}/time-before-first-click Number of seconds between page load and first select an element. This metric identifies which elements were interacted with first. [More information regarding the metric and how to interpret it... ↗](https://support.contentsquare.com/hc/en-us/articles/360017955593) ### Query parameters * #### projectId  integer   Required only for an account-level API key. The target project. * #### startDate  ISO 8601 date string  Required Beginning of date range for analysis. Must be a date before `endDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### endDate  ISO 8601 date string  Required End of date range for analysis. Must be a date after `startDate`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### device  string   Device filter for analysis. Possible values: `all` (default), `desktop`, `mobile`, or `tablet`. * #### period  string   Granularity of the results. Can only be used on a date range larger than one day. It allows you to have data for each day instead of having a combined result. Possible values: none (default), `daily`. * #### segmentIds  integer   Filter analysis with Contentsquare segments. Default: All visitors. You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified segments ### Path parameters * #### zoneId  integer  Required The ID of the Zone. ### Example of response ```json { "payload": { "values": [ { "startDate": "2021-08-03T00:00:00.000Z", "endDate": "2021-08-11T17:15:40.261Z", "value": 15.274424150485437, "name": "timeBeforeFirstClick", "device": "desktop", "currency": "USD" } ] }, "success": true } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Zone metrics for Web endpoints","description":"Zone Metrics for Web endpoints reference","url":"https://docs.contentsquare.com/en/api/metrics/zone-metrics-endpoints-web/","inLanguage":"en","dateModified":"2026-04-14T16:34:01+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Authentication - APIs description: How to authenticate to use the Export API lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/api/export/authentication/ md: https://docs.contentsquare.com/en/api/export/authentication/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare APIs authenticate via server-to-server OAuth 2.0 credentials generated from the Contentsquare console. Warning **Since April 30th, 2024, API keys are no longer supported**. You must use OAuth credentials instead to authenticate on our APIs, and migrate your existing applications using API keys. ## OAuth2 authentication The Contentsquare APIs use the server-to-server OAuth 2.0 standard for authentication, also know as 2-legged OAuth or OAuth 2LO. The flow basically consists in calling an authentication endpoint with a pair `client_id` / `client_secret` to retrieve an access token that remains valid for 1 hour. This JWT token should then be used as a Bearer token in the headers of your HTTPS requests (in the form `Authorization: Bearer YOUR_API_KEY`). the API call to the authentication endpoint will also dynamically return the right base URL that you must use. This base URL depends on which cloud the target project is installed on. You can refer below to a [detailed example](#example-of-authentication-flow) of the overall flow to retrieve a token and a base URL, and use those to query the Data Export API. You can generate a pair `client_id` / `client_secret` from the Contentsquare [console ↗](https://console.contentsquare.com), as a Contentsquare administrator. You can find how to generate these credentials in our [Help Center documentation ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593). You can create OAuth credentials either: * At the Project level, to request access resources from a specific project only * At the Account level: to request access for any project of the account Warning Your OAuth credentials carry many privileges, so make sure to keep them secure! Do not share them in publicly accessible areas such as GitHub, client-side code, and so forth. ## Refresh your access token Once you get a JWT access token (see the [authentication endpoint](#authentication-endpoint) below), it's valid for 1 hour. If you try to query the Contentsquare APIs with access to token that has expired, you will receive a `401 Unauthorized` error with the error code `JWT_EXPIRED`, in the form: ```json { "success": false, "errorMessage": "Auth token is expired.", "errorCode": "JWT_EXPIRED" } ``` In that case, you should first use your OAuth credentials (your pair `client_id` / `client_secret`) to query a new The OAuth credentials expire after 1 year. See [How to regenerate OAuth credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593-How-to-create-API-credentials#section4). ## Authentication endpoint POST [https://api.contentsquare.com/v1/oauth/token ↗](https://api.contentsquare.com/v1/oauth/token) ### Request parameters * #### client\_id  string  Required The OAuth `client_id` generated from the Contentsquare console. * #### client\_secret  string  Required The OAuth `client_secret` generated from the Contentsquare console. * #### grant\_type  string  Required Always set it to `"client_credentials"`, as required by the OAuth 2.0 standard. * #### scope  string  Required You should use `"data-export"`. If needed, you can specify a list of several scopes to get a token that can query several APIs (for example `"data-export metrics"` if you want your token to cover both the Data Export API and [Metrics API](https://docs.contentsquare.com/en/api/metrics/) scopes). The only scope that cannot be combined with other scopes is `enrichment`. * #### project\_id  string   Required only if you use account-level OAuth credentials, to specify which project of the account you want to target. ### Request example ```shell curl --location 'https://api.contentsquare.com/v1/oauth/token' \ --header 'Content-Type: application/json' \ --data '{ "client_id": "c3133d76-a768-4f5a-XXX", "client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX", "grant_type": "client_credentials", "scope": "data-export", "project_id": 42 }' ``` ### Response example ```json { "access_token": "eyJhbGciOiJSIsImtpY5MTXXX.CNTcKWAUb2mTp2cZyiDRYYOtGCKXXX", // to be used as bearer token to query the APIs "token_type": "bearer", "expires_in": 3600, "scope": "data-export", "project_id": 42, "endpoint": "https://api.eu-west-1.production.contentsquare.com" // this is the base URL you should use to query the Data Export API endpoints - the provided URL depends on the cloud the project is installed on } ``` ## Example of authentication flow Below is a sample of JavaScript code to show a complete API call flow that first retrieves an access token and then use it to retrieve the list of export jobs on a project: ```javascript const clientId = "<your_client_id>"; const clientSecret = "<your_client_secret>"; const authEndpoint = "https://api.contentsquare.com/v1/oauth/token"; const authRequestOptions = { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ client_id: clientId, client_secret: clientSecret, grant_type: "client_credentials", project_id: 42, scope: "data-export", }), }; const authResponse = await fetch(authEndpoint, authRequestOptions); const authJsonData = await authResponse.json(); // Below are the access token and base URL that must be used to query the Data Export API endpoints const accessToken = authJsonData.access_token; const baseURL = authJsonData.endpoint; // Using the access token and base URL to query the Data Export API endpoints and get the export jobs in this example const dataExportApiEndpointResponse = await fetch(`${baseURL}/v1/exports`, { headers: { Authorization: `Bearer ${accessToken}` }, }); const dataExportApiEndpointauthJsonData = await dataExportApiEndpointResponse.json(); const exports = dataExportApiEndpointauthJsonData.payload; ``` ## OAuth credentials information endpoint POST [https://api.contentsquare.com/v1/oauth/me ↗](https://api.contentsquare.com/v1/oauth/me) ### Request parameters * #### client\_id  string  Required The OAuth `client_id` generated from the Contentsquare console. * #### client\_secret  string  Required The OAuth `client_secret` generated from the Contentsquare console. ### Request example ```shell curl --location 'https://api.contentsquare.com/v1/oauth/me' \ --header 'Content-Type: application/json' \ --data '{ "client_id": "c3133d76-a768-4f5a-XXX", "client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX", }' ``` ### Response example ```json { "scopes": "metrics data-export session-replay symbolicator", "permissions": { "projects": [ { "id": 42, "name": "UX ANALYTICS" } ] } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Authentication","description":"How to authenticate to use the Export API","url":"https://docs.contentsquare.com/en/api/export/authentication/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Endpoints reference - APIs description: Data Export API endpoints reference lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/api/export/endpoints-reference/ md: https://docs.contentsquare.com/en/api/export/endpoints-reference/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Data Export API provides endpoints to create and manage export jobs, list job runs, and download extraction files. ## Create an export job POST /v1/exports This endpoint allows for creating a new export job. ### Request parameters * #### name  string  Required The name of the export. Must not be empty. * #### format  string  Required The file format of the export output. Possible values: `JSONL`, or `CSV`. * #### scope  string (<= 255 chars)   The scope of the export. * #### frequency  object  Required The frequency of the export. * #### value  string   The frequency value. Possible values: `once`, `daily`, or `hourly`. * #### dateRange.from  string   Required only if frequency.value is "once". The value must be a valid ISO 8601 date string. It should be anterior to frequency.dateRange.to, but not anterior to the project data retention period * #### dateRange.to  string   Required only if frequency.value is "once". The value must be a valid ISO 8601 date string. It should be posterior but not more than 7 days after frequency.dateRange.from. * #### fields  object  Required The list of fields to export. To list the exportable fields for a given scope, see the [dedicated endpoint](https://docs.contentsquare.com/en/api/export/endpoints-reference/#get-the-list-of-all-exportable-fields). * #### fieldName  string  Required A valid `fieldName` corresponding to the name property of the fields that can be listed via the [/v1/exportable-fields](https://docs.contentsquare.com/en/api/export/endpoints-reference/#get-the-list-of-all-exportable-fields) endpoint. You cannot specify a `fieldName` more than once, except for the special values `custom_var` and `dynamic_var` (used to export custom or dynamic variables). * #### aliasName  string   An alias that will be used to rename the exported field in the output file. * #### customVarPosition  string   Required only if `custom_var` is specified as `fieldName`. The custom variable position. Must be between 1 and 20 inclusive. To learn more about custom variables, see [Sending custom vars](https://docs.contentsquare.com/en/web/sending-custom-vars/). To list custom variables available on the authenticated project, see the [/v1/custom\_vars](https://docs.contentsquare.com/en/api/export/endpoints-reference/#get-the-list-of-custom-variables) endpoint. * #### dynamicVarKey  string   Required only if `dynamic_var` is specified as `fieldName`. The dynamic variable key. To learn more about dynamic variables, see [Sending dynamic vars](https://docs.contentsquare.com/en/web/sending-dynamic-vars/). To list dynamic variables available on the authenticated project, see the [/v1/dynamic\_var\_keys](https://docs.contentsquare.com/en/api/export/endpoints-reference/#get-the-list-of-dynamic-variables) endpoint. * #### deviceLabel  string  Required A device filter. Possible values: `all`, `desktop`, `mobile`, or `tablet`. * #### segmentId  string   A valid `segmentId`. If no segment is provided, the data for all users will be exported. To retrieve the list of available segments for the project, you can call the [/v1/segment](https://docs.contentsquare.com/en/api/metrics/objects-endpoints/#segments) endpoint. ### Request example 1 ```shell curl --location --request POST 'https://api.contentsquare.com/v1/exports' \ --header 'Authorization: Bearer <your_access_token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Test API POST", "format": "JSONL", "scope": "sessions", "frequency": { "value": "daily" }, "fields": [ { "fieldName": "project_id", }, { "fieldName": "session_id", } ], "deviceLabel": "all", "segmentId": 123 }' ``` ### Request example 2 ```shell curl --location --request POST 'https://api.contentsquare.com/v1/exports' \ --header 'Authorization: Bearer <your_access_token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Test API POST", "format": "CSV", "scope": "views", "frequency": { "value": "once", "dateRange": { "from": "2023-02-14T00:00:00.000Z", "to": "2023-02-15T23:59:59.999Z" } }, "fields": [ { "fieldName": "session_id", "aliasName": "Session ID" }, { "fieldName": "view_number", "aliasName": "View number in session" }, { "fieldName": "custom_var", "customVarPosition": 2, "aliasName": "My Custom Variable of index 2" }, { "fieldName": "dynamic_var", "dynamicVarKey": "AB Test", "aliasName": "Experiment" } ], "deviceLabel": "desktop", "segmentId": 123 }' ``` ### Response example ```json { "payload": { "jobId": 1372 }, "success": true } ``` ## Get the list of all export jobs GET /v1/exports This endpoint provides the list of all the available export jobs (be they in status active, suspended, computing, or completed). ### Query parameters * #### format  string   To filter based on the export format (see [Enumerations](https://docs.contentsquare.com/en/api/export/enumerations/#format)) * #### frequency  string   To filter based on the export frequency (see [Enumerations](https://docs.contentsquare.com/en/api/export/enumerations/#format)) * #### limit  integer   To change the page size of results (25 by default, 100 max). * #### order  string   To change the order of the results list ("ASC" or "DESC", "DESC" by default). Ordering is based on the `jobId`. * #### page  integer   The page of results to retrieve. * #### scope  string   To filter based on the job scope (see [Enumerations](https://docs.contentsquare.com/en/api/export/enumerations/#scope)). * #### state  string   To filter based on the job status (see [Enumerations](https://docs.contentsquare.com/en/api/export/enumerations/#state-job-state)) ### Request example ```shell curl --location --request GET 'https://api.contentsquare.com/v1/exports?state=completed' \ --header 'Authorization: Bearer <your_access_token>' ``` ### Response example ```json { "payload": [ { "jobId": 0, "name": "string", "ownerId": 0, "lastUpdatorId": 0, "accountId": 0, "nextFrom": "2021-05-02T16:22:43.439Z", "nextTo": "2021-05-02T16:22:43.439Z", "projectIds": [0], "state": "ACTIVE", "createdAt": "2021-05-02T16:22:43.439Z", "format": "JSON", "scope": "views", "frequency": "string", "fields": [ { "fieldName": "string", "aliasName": "string" } ], "lastRunTime": "2021-05-02T16:22:43.439Z", "nextRunTime": "2021-05-02T16:22:43.439Z", "updatedAt": "2021-05-02T16:22:43.439Z", "filters": { "deviceId": 0 } } ], "success": true } ``` `nextFrom` and `nextTo` represent the next date range that will be extracted, while `lastRunTime` and `nextRunTime` indicate when the last and next execution started / will start. ## Get the list of all successful job runs GET /v1/exports/successful-runs This endpoint provides the list of all the jobs runs that completed successfully. Use it to find which jobs have generated extraction files to be downloaded. ### Query parameters * #### page  integer   The page of results to retrieve. * #### order  string   To change the order of the results list ("ASC" or "DESC", "DESC" by default). Ordering is based on the `jobId`. * #### limit  integer   To change the page size of results (25 by default, 100 max). ### Request example ```shell curl --location --request GET 'https://api.contentsquare.com/v1/exports/successful-runs' \ --header 'Authorization: Bearer <your_access_token>' ``` ### Response example ```json { "payload": [ { "jobId": 0, "jobRunId": 0, "name": "string", "projectIds": [0], "from": "2021-05-02T16:40:14.022Z", "to": "2021-05-02T16:40:14.022Z", "completionTime": "2021-05-02T16:40:14.022Z", "format": "JSONL", "scope": "views", "frequency": "string", "nbOfFiles": 0 } ], "success": true } ``` ## Get a specific job GET /v1/exports/{jobId} This endpoint allows for retrieving a specific job with its ID. ### Path parameters * #### jobId  integer  Required The Job ID. ### Request example ```shell curl --location --request GET 'https://api.contentsquare.com/v1/exports/1234' \ --header 'Authorization: Bearer <your_access_token>' ``` ### Response example ```json { "payload": { "jobId": 0, "name": "string", "ownerId": 0, "lastUpdatorId": 0, "accountId": 0, "nextFrom": "2021-05-02T16:50:29.301Z", "nextTo": "2021-05-02T16:50:29.301Z", "projectIds": [0], "state": "ACTIVE", "createdAt": "2021-05-02T16:50:29.301Z", "format": "JSONL", "scope": "views", "frequency": "string", "fields": [ { "fieldName": "string", "aliasName": "string" } ], "lastRunTime": "2021-05-02T16:50:29.301Z", "nextRunTime": "2021-05-02T16:50:29.301Z", "updatedAt": "2021-05-02T16:50:29.301Z", "filters": { "deviceId": 0 } }, "success": true } ``` `nextFrom` and `nextTo` represent the next date range that will be extracted, while `lastRunTime` and `nextRunTime` indicate when the last and next execution started / will start. ## Get the list of all job runs of a job GET /v1/exports/{jobId}/runs This endpoint provides the list of all the job runs related to a specific job. ### Path parameters * #### jobId  integer  Required The Job ID. ### Query parameters * #### limit  integer   To change the page size of results (25 by default, 100 max). * #### order  string   To change the order of the results list ("ASC" or "DESC", "DESC" by default). Ordering is based on the `jobId`. * #### page  integer   The page of results to retrieve. * #### state  string   To filter based on the job status (see [Enumerations](https://docs.contentsquare.com/en/api/export/enumerations/#state-job-state)). ### Request example ```shell curl --location --request GET 'https://api.contentsquare.com/v1/exports/1354/runs' \ --header 'Authorization: Bearer <your_access_token>' ``` ### Response example ```json { "payload": [ { "jobRunId": 0, "startDate": "2021-05-02T16:51:51.004Z", "state": "CREATED", "endDate": "2021-05-02T16:51:51.004Z", "completionRate": 0 } ], "success": true } ``` ## Get a specific job run GET /v1/exports/{jobId}/runs/{runId} This endpoint allows for retrieving a specific job run with its ID. The response includes all the extraction files available for download if any (in the `files` field). The files can be downloaded via the provided URL in the `url` field. Files will not be available for download after the `expirationDate`. ### Path parameters * #### jobId  integer  Required The Job ID. * #### runId  integer  Required The Job Run ID. ### Request example ```shell curl --location --request GET 'https://api.contentsquare.com/v1/exports/1354/runs/67226' \ --header 'Authorization: Bearer <your_access_token>' ``` ### Response example ```json { "payload": { "jobRunId": 0, "startDate": "2021-05-02T16:54:55.983Z", "state": "CREATED", "files": [ { "partId": 0, "fileSize": 0, "url": "string", "expirationDate": "2021-05-02T16:54:55.983Z" } ], "endDate": "2021-05-02T16:54:55.983Z", "completionRate": 0 }, "success": true } ``` ## Get the list of all exportable fields GET /v1/exportable-fields This endpoint allows for retrieving all fields that can be extracted for a specified scope (the list of fields will depend on the scope). ### Query parameters * #### scope  string  Required To filter based on the job scope (see [Enumerations](https://docs.contentsquare.com/en/api/export/enumerations/#state-job-state)) ### Request example ```shell curl --location --request GET 'https://api.contentsquare.com/v1/exportable-fields?scope=sessions' \ --header 'Authorization: Bearer <your_access_token>' ``` ### Response example ```json { "payload": [ { "name": "string", "description": "string", "example": "string", "aliases": ["string"], "parameters": ["string"] } ], "success": true } ``` ## Get the list of custom variables GET /v1/custom-vars This endpoint allows for retrieving all the custom variables available on a project. To learn more about custom variables, see [Sending custom vars](https://docs.contentsquare.com/en/web/sending-custom-vars/). ### Parameters * No parameters. ### Request example ```shell curl --location --request GET 'https://api.contentsquare.com/v1/custom-vars' \ --header 'Authorization: Bearer <your_access_token>' ``` ### Response example ```json { "payload": [ { "position": 2, "key": "dataType", "values": [ "journey", "recording", "zoning" ] }, { "position": 3, "key": "pageType", "values": [ "checkoutstep 1" "checkoutstep 2", "checkoutstep 3", ] }, { "position": 1, "key": "Goal achieved", "values": [ "false", "true" ] } ], "success": true } ``` ## Get the list of dynamic variables GET /v1/dynamic-var-keys This endpoint allows for retrieving all the dynamic variables available on a project between two dates. To learn more about dynamic variables, see [Sending dynamic variables](https://docs.contentsquare.com/en/web/sending-dynamic-vars/). ### Query parameters * #### from  ISO 8601 date string   Start date of the query date range. * #### to  ISO 8601 date string   End date of the query date range. ### Request example ```shell curl --location --request GET 'https://api.contentsquare.com/v1/dynamic-var-keys?from=2023-02-10T00:00:00&to=2023-02-17T00:00:00' \ --header 'Authorization: Bearer <your_access_token>' ``` ### Response example ```json { "payload": [ { "key": "AB Test", "type": "string" }, { "key": "Traffic Source", "type": "string" }, { "key": "VoC feedback score", "type": "string" }, { "key": "Web Analytics Segment", "type": "string" } ], "success": true } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Endpoints reference","description":"Data Export API endpoints reference","url":"https://docs.contentsquare.com/en/api/export/endpoints-reference/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Enumerations - APIs description: Data Export objects enumerations reference lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/api/export/enumerations/ md: https://docs.contentsquare.com/en/api/export/enumerations/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Enumerations used in the request or response payloads. ## `deviceId` **integer** * `-1`: All devices * `0`: Unknown * `1`: Desktop * `2`: Mobile (Web) * `3`: Tablet (Web) * `4`: Mobile (App) * `5`: Tablet (App) ## `format` **string** Beginning of date range for analysis. * `CSV`: CSV (with first row as headers) * `JSONL`: JSON Lines format, a file format with one line per row of data, each line being a JSON object ## `frequency` **string** * `daily`: daily job * `hourly`: hourly job * `once`: one-time job ## `scope` **string** * `sessions`: to extract session-level data * `views`: to extract pageview-level data ## `state` (job state) **string** * `ACTIVE`: active jobs (as opposed to SUSPENDED for daily jobs). An active job will start job runs. A one-time "once" job in ACTIVE status is a job queued waiting for execution. * `COMPLETED`: for completed one-time ("once") jobs (not relevant for daily jobs) * `COMPUTING`: for running one-time ("once") jobs * `DELETED`: for deleted jobs * `SUSPENDED`: for deactivated daily jobs (as opposed to ACTIVE); only relevant for daily jobs. A suspended job will not start job runs. ## `state` (job run state) **string** * `CREATED`: for job runs created and not yet RUNNABLE * `FAILURE`: for job runs terminated with an error * `RUNNABLE`: for job runs ready-to-start * `RUNNING`: for deleted jobs * `SUCCESS`: for job runs completed with success ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Enumerations","description":"Data Export objects enumerations reference","url":"https://docs.contentsquare.com/en/api/export/enumerations/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Fields reference (pageview) - APIs description: Data Export pageview fields reference lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/api/export/fields-reference-pageview/ md: https://docs.contentsquare.com/en/api/export/fields-reference-pageview/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Pageview exports contain the following fields, grouped by category. ## Errors ### `errors.message` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of descriptions of the JavaScript error events. Each event has the same index in all `errors.*` fields. | Data type | Example value | | - | - | | Array(String) | \['Uncaught Error: Mismatched anonymous define() module...', 'Uncaught TypeError: Cannot read properties of undefined'] | ### `errors.error_time` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of timestamps of the JavaScript error events. Each event has the same index in all `errors.*` fields. | Data type | Example value | | - | - | | Array(String) | \['2020-07-11 18:55','2020-07-11 18:55'] | ### `errors.filename` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of URLs of the files where the JavaScript error events occurred. Each event has the same index in all `errors.*` fields. | Data type | Example value | | - | - | | Array(String) | \['https\://a.site.com/static/scripts/lib1.js', 'https\://b.site.com/static/scripts/lib2.js'] | ### `errors.line_number` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of line numbers in the files where the JavaScript error events occurred. Each event has the same index in all `errors.*` fields. | Data type | Example value | | - | - | | Array(Number) | \[2, 1998] | ### `errors.col_number` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of column numbers in the files where the JavaScript error events occurred. Each event has the same index in all `errors.*` fields. | Data type | Example value | | - | - | | Array(Number) | \[55, 44] | ### `errors.group_id` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of Group IDs of the JavaScript error events, used to regroup similar errors together in Contentsquare. Each event has the same index in all `errors.*` fields. | Data type | Example value | | - | - | | Array(Number) | \[2406037528566246307, 17923195893144918451] | ### `errors_api.url` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of URL endpoints of the API error events. Each event has the same index in all `errors_api.*` fields. | Data type | Example value | | - | - | | Array(String) | \['https\://some.site.com/login', 'https\://someother.site.com/login'] | ### `errors_api.method` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of HTTP methods of the API error events. Each event has the same index in all `errors_api.*` fields. | Data type | Example value | | - | - | | Array(String) | \['GET', 'POST'] | ### `errors_api.status_code` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of HTTP status codes of the API error events. Each event has the same index in all `errors_api.*` fields. | Data type | Example value | | - | - | | Array(Number) | \[500, 501] | ### `errors_api.request_time` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of the API call start timestamps of the API error events. Each event has the same index in all `errors_api.*` fields. | Data type | Example value | | - | - | | Array(String) | \['2023-01-19 01:50:36', '2023-01-21 01:50:36'] | ### `errors_api.group_id` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of Group IDs of the API error events, used to regroup similar errors together in Contentsquare. Each event has the same index in all `errors_api.*` fields. | Data type | Example value | | - | - | | Array(Number) | \[2406037528566246307, 17923195893144918451] | ### `custom_errors.message` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of descriptions of the custom error events. Each event has the same index in all `custom_errors.*` fields. | Data type | Example value | | - | - | | Array(String) | \['An error happened', 'Another error happened'] | ### `custom_errors.error_time` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of timestamps of the custom error events. Each event has the same index in all `custom_errors.*` fields. | Data type | Example value | | - | - | | Array(String) | \['2023-01-19 01:50:36', '2023-01-20 01:50:36'] | ### `custom_errors.attributes` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of key/value pairs of custom tags of the custom error events. Each event can have a list of several key/value pairs. Each event has the same index in all `custom_errors.*` fields. | Data type | Example value | | - | - | | Array(Array(String)) | \[\[('severity', 'high'), ('category', 'login')]] | ### `custom_errors.group_id` Note This field is only available for [Experience Monitoring ↗](https://contentsquare.com/platform/digital-experience-monitoring/) customers. Contact your CSM if you don't have access to the Errors module. The list of Group IDs of the custom error events, used to regroup similar errors together in Contentsquare. Each event has the same index in all `custom_errors.*` fields. | Data type | Example value | | - | - | | Array(Number) | \[2406037528566246307, 17923195893144918451] | ## Events ### `has_all_interaction_events` If we got all kinds of events (clicks, mouse moves etc.) on the page, value is 1, else 0. | Data type | Example value | | - | - | | Integer | 0 | ### `page_events` List of page events. | Data type | Example value | | - | - | | Array(String) | \['Config: Release\_20201112','FB\_MD\_Feedback Submitted'] | ### `raw_clicks.event_time` The list of the dates and UTC times of the click events. Each event has the same index in all `raw_click.*` fields. | Data type | Example value | | - | - | | String | \['2020-07-26 05:53', '2020-07-26 05:54'] | ### `raw_clicks.event_type` The list of the raw events types. Can be either: * `5`: CLICK * `10`: CHANGE * `11`: FOCUS * `12`: BLUR Each event has the same index in all `raw_click.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[5, 11] | ### `raw_clicks.relative_time_ms` Number of milliseconds between the beginning of the view and each of the raw events. Each event has the same index in all `raw_click.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[3981, 1782] | ### `raw_clicks.target_blank_field` Whether the event was an interaction with a blank field in a form. Can be either: * `0`: Not applicable * `1`: False * `2`: True Each event has the same index in all `raw_click.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[1, 2] | ### `raw_clicks.target_path` The list of the paths that were clicked. Each event has the same index in all `raw_click.*` fields. | Data type | Example value | | - | - | | Array(String) | \['html:eq(0)>form:eq(0)>div:eq(0)>button:eq(0)', 'html:eq(0)>button:eq(0)'] | ### `targets_clicks.path` The list of the paths of the target zone. Each target has the same index in all `targets_clicks.*` fields. | Data type | Example value | | - | - | | Array(String) | \['html:eq(0)>form:eq(0)>div:eq(0)>button:eq(0)', 'html:eq(0)>button:eq(0)'] | ### `targets_clicks.sum` The number of times the target was clicked on (aggregation of `raw_clicks`). Each target has the same index in all `targets_clicks.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[2, 1] | ### `targets_clicks.time_before_msec` The delay between the loading of the page and the time the user clicked on the target for the first time (in milliseconds). Each target has the same index in all `targets_clicks.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[779, 391] | ### `targets_clicks.time_between_last_hover_and_first_click` Time before last hover and first select the target (in milliseconds). Each target has the same index in all `targets_clicks.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[13533, 30791] | ### `targets_focus.path` List of the raw path of the targets. Each target has the same index in all `targets_focus.*` fields. | Data type | Example value | | - | - | | Array(String) | \['html:eq(0)>form:eq(0)>div:eq(0)>button:eq(0)', 'html:eq(0)>button:eq(0)'] | ### `targets_focus.sum` List of the number of times the target was focused on. Each target has the same index in all `targets_focus.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[2, 5] | ### `targets_focus.time_before_msec` List of times before first focus on a zone (in milliseconds). Each target has the same index in all `targets_focus.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[13533, 30791] | ### `targets_hover.path` List of the raw path of the targets. Each target has the same index in all `targets_hover.*` fields. | Data type | Example value | | - | - | | Array(String) | \['html:eq(0)>form:eq(0)>div:eq(0)>button:eq(0)', 'html:eq(0)>button:eq(0)'] | ### `targets_hover.sum` List of the number of times the target was hovered on. Each target has the same index in all `targets_hover.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[2, 5] | ### `targets_hover.sum_times` List of the total time the target was hovered on (in milliseconds). Each target has the same index in all `targets_hover.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[2563 ,252] | ### `targets_hover.time_before_msec` List of times before first hover on a zone (in milliseconds). Each target has the same index in all `targets_hover.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[13533, 30791] | ## Frustration Those fields are only exportable for projects with access to the frustration score in Contentsquare. ### `any_api_error_ind` A normalized score between 0 and 1 to indicate whether any API error occurred on the page. This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Float | 0.27 | ### `any_js_error_ind` A normalized score between 0 and 1 to indicate whether any JavaScript error occurred on the page. This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Float | 0.27 | ### `api_error_after_click_ind` A normalized score between 0 and 2 to indicate whether API errors occurred after some clicks. This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Float | 0.27 | ### `excessive_hovers_ind` A normalized score between 0 and 2 to indicate whether excessive hovers occurred on the page. This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Float | 1.64 | ### `frustration_score` A normalized score between 0 and 100 computed based on all other frustration indicators, to express an overall frustration level on the page. This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Float | 0.27 | ### `is_watchable` Whether the page is considered watchable (1) or not (0). Only pages that are watchable have a frustration score. To be considered watchable, the page view must respect the following conditions: * Be part of a collected session ([`is_recorded`](#is_recorded) = 1) * Its duration should be at least 2 seconds * There should be at least 2 clicks on the page This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Integer | 0 | ### `js_error_after_click_ind` A normalized score between 0 and 2 to indicate whether any JavaScript error occurred after clicks on the page. This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Float | 1.64 | ### `loading_time_ind` A normalized score between 0 and 1 to indicate whether loading time was slow on the page. This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Float | 0.27 | ### `multiple_button_interaction_ind` A normalized score between 0 and 2 to indicate multiple interactions on button targets on the page. This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Float | 1.64 | ### `multiple_field_interaction_ind` A normalized score between 0 and 2 to indicate multiple interactions on field targets on the page. This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Float | 1.64 | ### `multiple_used_targets_ind` A normalized score between 0 and 1 to indicate multiple interactions on targets on the page. This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Float | 0.27 | ### `no_clicks_on_page_ind` A normalized score between 0 and 1 to indicate low activity on the page. This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Float | 0.27 | ### `rage_click_all_targets_ind` A normalized score between 0 and 2 to indicate rage clicks (multiple clicks in a short time frame). This field is only exportable for projects with access to the frustration score in Contentsquare. | Data type | Example value | | - | - | | Float | 1.64 | ## Geography ### `city` City associated to the user. | Data type | Example value | | - | - | | String | Paris | ### `country_code` Country associated to the user. | Data type | Example value | | - | - | | String | FR | ### `language` Language associated to the user. | Data type | Example value | | - | - | | String | fr | ## Identifiers ### `project_id` Unique project identifier. | Data type | Example value | | - | - | | Integer | 42 | ### `user_id` Unique user identifier. This is the hash of the `user_id_unashed` identifier. | Data type | Example value | | - | - | | Integer | 5066017809039612144 | ### `user_id_unhashed` Unique user identifier. User id stored in a cookie named `_cs_id`, which has a lifetime of 13 months. Note This field will be empty for dates before September, 5th 2023, as this identifier was not collected before that date. | Data type | Example value | | - | - | | String | ae267-6g87D-88Nn6od | ## Mobile (CS App) ### `app_events.event_name` List of the app event names. Each app event has the same index in all `app_events.*` fields. | Data type | Example value | | - | - | | Array(String) | \['appStartEvent', 'appShowEvent', 'appHideEvent'] | ### `app_events.event_time` List of dates and UTC time of the app events. Each app event has the same index in all `app_events.*` fields. | Data type | Example value | | - | - | | Array(String) | \['2020-06-24 17:07', '2020-06-24 17:07', '2020-06-24 17:08'] | ### `app_events.event_type` List of the app events types related to the session: * `0`: app start * `1`: app show * `2`: app hide Each app event has the same index in all `app_events.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[0, 1, 2] | ### `app_events.view_number` The pageview number related to the event. Each app event has the same index in all `app_events.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[0, 0, 1] | ### `app_version` The client app version. | Data type | Example value | | - | - | | String | 10.8.2.0 | ### `density` Pixel density measured in Pixels Per Inch (PPI) on the display. | Data type | Example value | | - | - | | Float | 38912.312 | ### `manufacturer` The mobile device manufacturer. | Data type | Example value | | - | - | | String | HUAWEI | ### `model` The mobile device model. | Data type | Example value | | - | - | | String | SNE-LX1 | ### `os_version` Version of Android or iOS used by the visitor (iOS 13.1. or iOS 13.2 etc.) | Data type | Example value | | - | - | | Integer | 2251799813685248 | ### `screen_name` The screen name. | Data type | Example value | | - | - | | String | Showroom | ### `targets_drag.finger_direction` List of finger directions related to the swipe events: * `1`: up * `2`: down * `3`: left * `4`: right * `5`: complex Each target has the same index in all `targets_drag.*` fields. | Data type | Example value | | - | - | | List(Integer) | \[2, 5] | ### `targets_drag.sum` The number of times the target was swiped. | Data type | Example value | | - | - | | List(Integer) | \[3, 1] | Each target has the same index in all `targets_drag.*` fields. ### `targets_drag_and_flick.finger_direction` List of finger directions related to the swipe or fast swipe events: * `1`: up * `2`: down * `3`: left * `4`: right * `5`: complex Each target has the same index in all `targets_drag_and_flick.*` fields. | Data type | Example value | | - | - | | List(Integer) | \[2, 5] | ### `targets_drag_and_flick.orientation` List of orientations related to the swipe or fast swipe events: * `0`: portrait * `1`: landscape Each target has the same index in all `targets_drag_and_flick.*` fields. | Data type | Example value | | - | - | | List(Integer) | \[1, 0] | ### `targets_drag_and_flick.sum` Each target has the same index in all `targets_drag_and_flick.*` fields. | Data type | Example value | | - | - | | List(Integer) | \[3, 1] | Each value has the same array index as their corresponding `targets_drag_and_flick.finger_direction` and `targets_drag_and_flick.orientation`. ### `targets_flick.finger_direction` List of finger directions related to the fast swiped events: * `1`: up * `2`: down * `3`: left * `4`: right * `5`: complex Each target has the same index in all `targets_flick.*` fields. | Data type | Example value | | - | - | | List(Integer) | \[2, 5] | ### `targets_flick.sum` The number of times the target was fast swiped. | Data type | Example value | | - | - | | List(Integer) | \[3, 1] | Each target has the same index in all `targets_flick.*` fields. ### `targets_long_press.sum` List of the number of times the target was long press (a target is considered long pressed after at least 500ms). | Data type | Example value | | - | - | | List(Integer) | \[3, 1] | ### `targets_tap.responsive` List of values equal to 1 if the App reacted to the tap, else 0. Each target has the same index in all `targets_tap.*` fields. | Data type | Example value | | - | - | | Aray(Integer) | \[0, 1] | ### `targets_tap.sum` List of the number of times the target was tapped. Each target has the same index in all `targets_tap.*` fields. | Data type | Example value | | - | - | | Aray(Integer) | \[3, 1] | ### `targets_tap.time_before_msec` List of delays between the loading of the page and the time the user taps on the target for the first time (in milliseconds). Each target has the same index in all `targets_tap.*` fields. | Data type | Example value | | - | - | | Aray(Integer) | \[31029, 26496] | ## Page ### `custom_vars_view.key` Array of keys of custom variables extracted from the website datalayer. Each variable has the same index in all `custom_vars_view.*` fields. | Data type | Example value | | - | - | | Array(String) | `['pageType', 'page_error', 'user_logged']` | ### `custom_vars_view.position` Array of positions of custom variables extracted from the website datalayer. Each variable has the same index in all `custom_vars_view.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[1, 7, 16] | ### `custom_vars_view.value` Array of values of custom variables extracted from the website datalayer. Each variable has the same index in all `custom_vars_view.*` fields. | Data type | Example value | | - | - | | Array(String) | `['catalogsearch_result_index', '200', 'not_logged']` | ### `document_height` Page height in pixels. | Data type | Example value | | - | - | | Integer | 4326 | ### `document_width` Page width in pixels. | Data type | Example value | | - | - | | Integer | 1280 | ### `dom_interactive_after_msec` The time in milliseconds required before the user is able to interact with the page (although all resources may not be fully loaded yet). | Data type | Example value | | - | - | | Integer | 5356 | ### `dynamic_vars_int_in_view.key` Array of keys of integer dynamic variables extracted from the website datalayer of the pageview. Each variable has the same index in all `dynamic_vars_int_in_view.*` fields. | Data type | Example value | | - | - | | Array(String) | \['VAR\_name\_123', VAR\_name\_456'] | ### `dynamic_vars_int_in_view.value` Array of values of integer dynamic variables extracted from the website datalayer of the pageview. Each variable has the same index in all `dynamic_vars_int_in_view.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[123, 456] | ### `dynamic_vars_string_in_view.key` Array of keys of string dynamic variables extracted from the website datalayer of the pageview. Each variable has the same index in all `dynamic_vars_string_in_view.*` fields. | Data type | Example value | | - | - | | Array(String) | \['VAR\_name\_123', VAR\_name\_456'] | ### `dynamic_vars_string_in_view.value` Array of values of string dynamic variables extracted from the website datalayer of the pageview. Each variable has the same index in all `dynamic_vars_string_in_view.*` fields. | Data type | Example value | | - | - | | Array(String) | \['VAR\_value\_123', 'VAR\_value\_456'] | ### `fully_loaded` The time in milliseconds required to fully load all the resources of the page, from initiation of the pageview to load completion in the browser. | Data type | Example value | | - | - | | Integer | 8186 | ### `is_first` If the page is the entry page then value is 1, otherwise value is 0. | Data type | Example value | | - | - | | Integer | 0 | ### `is_last` If the page is the exit page then value is 1, otherwise value is 0. | Data type | Example value | | - | - | | Integer | 1 | ### `last_hover_path` The last path that was hovered by the visitor. | Data type | Example value | | - | - | | String | html:eq(0)>body:eq(0)>div(4)>input:eq(0) | ### `page_interaction_time_msec` Interaction time in milliseconds. | Data type | Example value | | - | - | | Integer | 4967 | ### `path` Path of the pageview URL. | Data type | Example value | | - | - | | String | /cs-squad-3307216025801.html | ### `prefix` Host of the pageview URL. | Data type | Example value | | - | - | | String | www\.contentsquare.com | ### `query` Query of the pageview URL. | Data type | Example value | | - | - | | String | cs=42\&lang=fr | ### `scheme` Protocol (HTTP or HTTPS). | Data type | Example value | | - | - | | String | https | ### `scroll_rate` The portion of the page which was displayed (in percentage points). | Data type | Example value | | - | - | | Float | 61.4 | ### `start_render` Timestamp sent by tag when the rendering of the page started. | Data type | Example value | | - | - | | Integer | 112 | ### `url` The complete URL of the page (concatenation of [prefix](#prefix), [path](#path), and [query](#query)). | Data type | Example value | | - | - | | String | https\://contentsquare.com/?s=ux | ### `url_no_query_param` The URL of the page excluding query parameters (concatenation of [prefix](#prefix) and [path](#path)). | Data type | Example value | | - | - | | String | https\://contentsquare.com/ | ### `view_duration_msec` Duration between the page view event time (`view_time`) and the timestamp of the last interaction event (in milliseconds). | Data type | Example value | | - | - | | Integer | 49118 | ### `view_number` The pageview number in the session. | Data type | Example value | | - | - | | Integer | 2 | ### `view_time` The pageview date and UTC time. | Data type | Example value | | - | - | | String | 2020-07-26 05:53 | ### `viewports.bottom_screen_position` Array of bottom positions of the screen of the user. A new value is appended in the array after each scroll event if it's not already present in the array. | Data type | Example value | | - | - | | Array(Integer) | \[754, 2332, 2620] | The values in this array can be combined with the values at the same index in the arrays `viewports.top_screen_position` and `viewports.exposition_time_msec` to find corresponding top position of viewports and the total time the viewport was exposed in a given position. For example, say a user: * Starts at a viewport position (top=0, bottom=800) and stays in that position for 30 seconds; then * Scrolls down to a viewport position (top=600, bottom=1400) and stays there for 10 seconds; then * Scrolls up again back to the original viewport position (top=0, bottom=800) and stays there for another 20 seconds Then the 3 `viewports` array fields will look like this: * `viewports.bottom_screen_position`: \[0, 600] * `viewports.top_screen_position`: \[800, 1400] * `viewports.exposition_time_msec`: \[50000, 10000] (30s + 20s = 50s = 50000ms) ### `viewports.exposition_time_msec` The exposition time in milliseconds of the areas that were exposed to the user. A new value is appended in the array after each scroll event. | Data type | Example value | | - | - | | Array(Integer) | \[22740, 679, 1338] | The values in this array can be combined with the values at the same index in the arrays `viewports.bottom_screen_position` and `viewports.top_screen_position` to find corresponding top position of viewports and the total time the viewport was exposed in a given position. For example, say a user: * Starts at a viewport position (top=0, bottom=800) and stays in that position for 30 seconds; then * Scrolls down to a viewport position (top=600, bottom=1400) and stays there for 10 seconds; then * Scrolls up again back to the original viewport position (top=0, bottom=800) and stays there for another 20 seconds Then the 3 `viewports` array fields will look like this: * `viewports.bottom_screen_position`: \[0, 600] * `viewports.top_screen_position`: \[800, 1400] * `viewports.exposition_time_msec`: \[50000, 10000] (30s + 20s = 50s = 50000ms) ### `viewports.top_screen_position` Array of top positions of the screen of the user. A new value is appended in the array after each scroll event if it's not already present in the array. | Data type | Example value | | - | - | | Array(Integer) | \[0, 1578, 1866] | The values in this array can be combined with the values at the same index in the arrays `viewports.bottom_screen_position` and `viewports.exposition_time_msec` to find corresponding top position of viewports and the total time the viewport was exposed in a given position. For example, say a user: * Starts at a viewport position (top=0, bottom=800) and stays in that position for 30 seconds; then * Scrolls down to a viewport position (top=600, bottom=1400) and stays there for 10 seconds; then * Scrolls up again back to the original viewport position (top=0, bottom=800) and stays there for another 20 seconds Then the 3 `viewports` array fields will look like this: * `viewports.bottom_screen_position`: \[0, 600] * `viewports.top_screen_position`: \[800, 1400] * `viewports.exposition_time_msec`: \[50000, 10000] (30s + 20s = 50s = 50000ms) ### `window_height` Height of the window in which the page is opened. | Data type | Example value | | - | - | | Integer | 720 | ### `window_width` Width of the window in which the page is opened. | Data type | Example value | | - | - | | Integer | 1280 | ## Session ### `is_excludable` Values are either 1 or 0, to indicate whether the session is generated from bot traffic (1) or not (0). | Data type | Example value | | - | - | | Integer | 1 | ### `is_recorded` For Session Replay, indicates whether the session was collected (1) or not (0). | Data type | Example value | | - | - | | Integer | 1 | ### `session_date` Session start date. | Data type | Example value | | - | - | | String | 2020-07-26 | ### `session_duration_msec` Session duration in milliseconds. | Data type | Example value | | - | - | | Integer | 881633 | ### `session_id` Unique session identifier. | Data type | Example value | | - | - | | Integer | 5066017809039605767 | ### `session_number` The number of sessions of the user (takes into account how many times the user visited before). | Data type | Example value | | - | - | | Integer | 7 | ### `session_number_of_transactions` Number of transactions placed during the session. | Data type | Example value | | - | - | | Integer | 2 | ### `session_number_of_views` The number of page views in the session. | Data type | Example value | | - | - | | Integer | 5 | ### `session_replay_link` The replay link, if the session was collected (see `is_recorded` field). | Data type | Example value | | - | - | | String | https\://app.contentsquare.com/quick-playback/index.html?pid=... | ### `session_time` Session start date and UTC time. | Data type | Example value | | - | - | | String | 2020-07-26 05:53 | ### `session_transactions_revenue_cents` Total revenue generated by the session (in US dollar cents). | Data type | Example value | | - | - | | Integer | 37655 | ### `referer_url` The referring URL to the first page view of the session. | Data type | Example value | | - | - | | String | https\://[www.google.fr/ ↗](http://www.google.fr/) | ## Speed Analysis Those fields are only exportable for projects with access to the Speed Analysis module in Contentsquare. ### `time_to_first_byte` Delay (in milliseconds) between the request for the web page and when the web browser received the first piece of data. This field is only exportable for projects with access to the Speed Analysis module in Contentsquare. | Data type | Example value | | - | - | | Integer | 83 | ### `first_contentful_paint` Delay (in milliseconds) to render the first piece of content. This field is only exportable for projects with access to the Speed Analysis module in Contentsquare. | Data type | Example value | | - | - | | Integer | 196 | ### `largest_contentful_paint` Delay (in milliseconds) to render the largest piece of content (part of Core Web Vitals). This field is only exportable for projects with access to the Speed Analysis module in Contentsquare. | Data type | Example value | | - | - | | Integer | 297 | ### `cumulative_layout_shift` Score about the layout stability of the page rendering (part of Core Web Vitals). This field is only exportable for projects with access to the Speed Analysis module in Contentsquare. | Data type | Example value | | - | - | | Integer | 7 | ### `first_input_delay` Delay (in milliseconds) between the first user interaction and when the web browser can handle it (part of Core Web Vitals). This field is only exportable for projects with access to the Speed Analysis module in Contentsquare. This metric has been deprecated in favor of [`interaction_to_next_paint`](#interaction_to_next_paint) and will be removed in the future. | Data type | Example value | | - | - | | Integer | 42 | ### `interaction_to_next_paint` Longest visual delay (in milliseconds) experienced by a user when interacting with the page (clicks or keystrokes). This field is only exportable for projects with access to the Speed Analysis module in Contentsquare. | Data type | Example value | | - | - | | Integer | 61 | ## Technology ### `browser_major_version` The browser major version. | Data type | Example value | | - | - | | Integer | 83 | ### `browser_name` The browser name. | Data type | Example value | | - | - | | String | Chrome | ### `browser_version` The browser version. | Data type | Example value | | - | - | | String | 83.0.4103.116 | ### `device_id` Unique device identifier: * `0`: Unknown * `1`: Desktop * `2`: Mobile (Web) * `3`: Tablet (Web) * `4`: Mobile (App) * `5`: Tablet (App) | Data type | Example value | | - | - | | Integer | 2 | ### `platform_name` The operating system name. | Data type | Example value | | - | - | | String | Windows | ### `platform_version` The operating system version. | Data type | Example value | | - | - | | Integer | 10 | ### `screen_height` The screen height in pixels. | Data type | Example value | | - | - | | Integer | 700 | ### `screen_width` The screen width in pixels. | Data type | Example value | | - | - | | Integer | 1280 | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Fields reference (pageview)","description":"Data Export pageview fields reference","url":"https://docs.contentsquare.com/en/api/export/fields-reference-pageview/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Limits - APIs description: Data Export API requests limits lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/api/export/limits/ md: https://docs.contentsquare.com/en/api/export/limits/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Data Export API enforces request and credential limits at the project level. * 10 concurrent requests maximum per project * 10 OAuth credentials (`client_id`/`client_secret`) per project and per account maximum * The data available for query is limited to the project contractual data retention period * The retention period for the generated files is 7 days. Passed this period, you will not be able to download them anymore. If you missed some files from a daily job for example, keep in mind that you can still create a one-time ("once") job to retrieve the data later. * For one-time jobs, you cannot extract data for a date range including more than 7 days. Note **Limitations are tracked at the project level**, not at the OAuth credentials level. So if you have created several OAuth credentials requesting resources for a target project, the total number of concurrent requests must not exceed 10 for a specific project, all credentials taken into account. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Limits","description":"Data Export API requests limits","url":"https://docs.contentsquare.com/en/api/export/limits/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Fields reference (session) - APIs description: Data Export session fields reference lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/api/export/fields-reference-session/ md: https://docs.contentsquare.com/en/api/export/fields-reference-session/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Session exports contain the following fields, grouped by category. ## Geography ### `city` City associated to the user. | Data type | Example value | | - | - | | String | Paris | ### `country_code` Country associated to the user. | Data type | Example value | | - | - | | String | FR | ### `language` Language associated to the user. | Data type | Example value | | - | - | | String | fr | ## Identifiers ### `project_id` Unique project identifier. | Data type | Example value | | - | - | | Integer | 42 | ### `user_id` Unique user identifier. This is the hash of the `user_id_unashed` identifier. | Data type | Example value | | - | - | | Integer | 5066017809039612144 | ### `user_id_unhashed` Unique user identifier. User id stored in a cookie named `_cs_id`, which has a lifetime of 13 months. Note This field will be empty for dates before September, 5th 2023, as this identifier was not collected before that date. | Data type | Example value | | - | - | | String | ae267-6g87D-88Nn6od | ## Mobile (CS App) Those fields are only available for Apps projects. ### `app_events.event_name` List of the app event names. Each app event has the same index in all `app_events.*` fields. | Data type | Example value | | - | - | | Array(String) | \['appStartEvent', 'appShowEvent', 'appHideEvent'] | ### `app_events.event_time` List of dates and UTC times of the app events. Each app event has the same index in all `app_events.*` fields. | Data type | Example value | | - | - | | Array(String) | \['2020-06-24 17:07', '2020-06-24 17:07', '2020-06-24 17:08'] | ### `app_events.event_type` List of the app events types related to the session: * `0`: app start * `1`: app show * `2`: app hide Each app event has the same index in all `app_events.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[0, 1, 2] | ### `app_events.view_number` The pageview number related to the event. Each app event has the same index in all `app_events.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[0, 0, 1] | ### `app_version` The client app version. | Data type | Example value | | - | - | | String | 10.8.2.0 | ### `density` Pixel density measured in Pixels Per Inch (PPI) on the display. | Data type | Example value | | - | - | | Float | 38912.312 | ### `manufacturer` The mobile device manufacturer. | Data type | Example value | | - | - | | String | HUAWEI | ### `model` The mobile device model. | Data type | Example value | | - | - | | String | SNE-LX1 | ### `os_version` Version of Android or iOS used by the visitor (iOS 13.1. or iOS 13.2 etc.) | Data type | Example value | | - | - | | Integer | 2251799813685248 | ## Session ### `dynamic_vars_int_in_session.key` Array of keys of integer dynamic variables extracted from the website datalayer. Each variable has the same index in all `dynamic_vars_int_in_session.*` fields. | Data type | Example value | | - | - | | Array(String) | \['VAR\_name\_123', VAR\_name\_456'] | ### `dynamic_vars_int_in_session.value` Array of values of integer dynamic variables extracted from the website datalayer. Each variable has the same index in all `dynamic_vars_int_in_session.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[123, 456] | ### `dynamic_vars_string_in_session.key` Array of keys of string dynamic variables extracted from the website datalayer. Each variable has the same index in all `dynamic_vars_string_in_session.*` fields. | Data type | Example value | | - | - | | Array(String) | \['VAR\_name\_123', VAR\_name\_456'] | ### `dynamic_vars_string_in_session.value` Array of values of string dynamic variables extracted from the website datalayer. Each variable has the same index in all `dynamic_vars_string_in_session.*` fields. | Data type | Example value | | - | - | | Array(String) | \['VAR\_value\_123', 'VAR\_value\_456'] | ### `is_excludable` Values are either 1 or 0, to indicate whether the session is generated from bot traffic (1) or not (0). | Data type | Example value | | - | - | | Integer | 1 | ### `is_recorded` For Session Replay, indicates whether the session was collected (1) or not (0). This field can only be exported for projects with access to Session Replay. | Data type | Example value | | - | - | | Integer | 1 | ### `session_add_to_cart_items.add_to_cart_time` *Those values are populated when sending an add to cart event to Contentsquare.* Array of the datetimes when the items were added to cart. Each item has the same index in all `session_add_to_cart_items.*` fields. | Data type | Example value | | - | - | | Array(String) | \['2020-06-24 17:07', '2020-06-24 17:07', '2020-06-24 17:08'] | ### `session_add_to_cart_items.add_to_cart_view_number` *Those values are populated when sending an add to cart event to Contentsquare.* Array of the page view numbers (position in session) from which items were added to cart. Each item has the same index in all `session_add_to_cart_items.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[2, 5, 3] | ### `session_add_to_cart_items.catalog_id` *Those values are populated when sending an add to cart event to Contentsquare.* Array of the catalog identifiers of the items added to the cart. Will be 0 if the project has no Merchandising catalog set-up. Each item has the same index in all `session_add_to_cart_items.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[71893, 0, 991893] | ### `session_add_to_cart_items.is_in_transaction` *Those values are populated when sending an add to cart event to Contentsquare.* Array of the booleans indicating whether the items added to cart were purchased (1) or not (0). Each item has the same index in all `session_add_to_cart_items.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[0, 0, 1] | ### `session_add_to_cart_items.product_id_hashed` *Those values are populated when sending an add to cart event to Contentsquare.* Array of the items' hashed identifiers. Will be '0' if the project has no Merchandising catalog set-up. Each item has the same index in all `session_add_to_cart_items.*` fields. | Data type | Example value | | - | - | | Array(String) | \['3976139', '0', '30230O013'] | ### `session_add_to_cart_items.sku` *Those values are populated when sending an add to cart event to Contentsquare.* Array of the SKUs of the items added to cart. Each item has the same index in all `session_add_to_cart_items.*` fields. | Data type | Example value | | - | - | | Array(String) | \['987897849120', '47807017348784'] | ### `session_date` Session start date. | Data type | Example value | | - | - | | String | 2020-07-26 | ### `session_duration_msec` Session duration in milliseconds. | Data type | Example value | | - | - | | Integer | 881633 | ### `session_id` Unique session identifier. | Data type | Example value | | - | - | | Integer | 5066017809039605767 | ### `session_number` The number of sessions of the user (takes into account how many times the user visited before). | Data type | Example value | | - | - | | Integer | 7 | ### `session_number_of_transactions` Number of transactions placed during the session. | Data type | Example value | | - | - | | Integer | 2 | ### `session_number_of_views` The number of page views in the session. | Data type | Example value | | - | - | | Integer | 5 | ### `session_replay_link` The replay link, if the session was collected (see `is_recorded` field). This field can only be exported for projects with access to Session Replay. | Data type | Example value | | - | - | | String | https\://app.contentsquare.com/quick-playback/index.html?pid=... | ### `session_time` Session start date and UTC time. | Data type | Example value | | - | - | | String | 2020-07-26 05:53 | ### `session_transaction_items.catalog_id` *Those values are populated when sending a transaction event to Contentsquare.* Array of the catalog identifiers of the purchased items. Will be 0 if the project has no Merchandising catalog set-up. Each item has the same index in all `session_transaction_items.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[71893, 0, 991893] | ### `session_transaction_items.id` *Those values are populated when sending a transaction event to Contentsquare.* Array of the transactions identifiers. Each item has the same index in all `session_transaction_items.*` fields. | Data type | Example value | | - | - | | Array(String) | \['ABC287632', 'ABC1290873'] | ### `session_transaction_items.product_id_hashed` *Those values are populated when sending a transaction event to Contentsquare.* Array of the items' hashed identifiers. Will be '0' if the project has no Merchandising catalog set-up. Each item has the same index in all `session_transaction_items.*` fields. | Data type | Example value | | - | - | | Array(String) | \['3976139', '0', '30230O013'] | ### `session_transaction_items.quantity` *Those values are populated when sending a transaction event to Contentsquare.* Array of the purchased quantity of the items. Each item has the same index in all `session_transaction_items.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[2, 4, 1] | ### `session_transaction_items.revenue_cents` *Those values are populated when sending a transaction event to Contentsquare.* Array of the revenues (in cents) of the purchased items. Each item has the same index in all `session_transaction_items.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[89211, 450] | ### `session_transaction_items.sku` *Those values are populated when sending an add to cart event to Contentsquare.* Array of the SKUs of the purchased items. Each item has the same index in all `session_transaction_items.*` fields. | Data type | Example value | | - | - | | Array(String) | \['987897849120', '47807017348784'] | ### `session_transaction_items.transaction_time` *Those values are populated when sending a transaction event to Contentsquare.* Array of the datetimes when the items were purchased. Each item has the same index in all `session_transaction_items.*` fields. | Data type | Example value | | - | - | | Array(String) | \['2020-06-24 17:07', '2020-06-24 17:07', '2020-06-24 17:08'] | ### `session_transaction_items.transaction_view_number` *Those values are populated when sending a transaction event to Contentsquare.* Array of the page view numbers (position in session) from which items were purchased. Each item has the same index in all `session_transaction_items.*` fields. | Data type | Example value | | - | - | | Array(Integer) | \[2, 5, 3] | ### `session_transactions_revenue_cents` Total revenue generated by the session (in US dollar cents). | Data type | Example value | | - | - | | Integer | 37655 | ### `referer_url` The referring URL to the first page view of the session. | Data type | Example value | | - | - | | String | https\://www\.google.fr/ | ## Technology ### `browser_major_version` The browser major version. | Data type | Example value | | - | - | | Integer | 83 | ### `browser_name` The browser name. | Data type | Example value | | - | - | | String | Chrome | ### `browser_version` The browser version. | Data type | Example value | | - | - | | String | 83.0.4103.116 | ### `device_id` Unique device identifier: * `0`: Unknown * `1`: Desktop * `2`: Mobile (Web) * `3`: Tablet (Web) * `4`: Mobile (App) * `5`: Tablet (App) | Data type | Example value | | - | - | | Integer | 2 | ### `platform_name` The operating system name. | Data type | Example value | | - | - | | String | Windows | ### `platform_version` The operating system version. | Data type | Example value | | - | - | | Integer | 10 | ### `screen_height` The screen height in pixels. | Data type | Example value | | - | - | | Integer | 700 | ### `screen_width` The screen width in pixels. | Data type | Example value | | - | - | | Integer | 1280 | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Fields reference (session)","description":"Data Export session fields reference","url":"https://docs.contentsquare.com/en/api/export/fields-reference-session/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Authentication - APIs description: How to authenticate to use the Speed Lab API lastUpdated: 06 May 2026 source_url: html: https://docs.contentsquare.com/en/api/speed-analysis-lab/authentication/ md: https://docs.contentsquare.com/en/api/speed-analysis-lab/authentication/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare APIs authenticate via server-to-server OAuth 2.0 credentials generated from the Contentsquare console. Warning **Since April 30th, 2024, API keys are no longer supported**. You must use OAuth credentials instead to authenticate on our APIs, and migrate your existing applications using API keys. ## OAuth2 authentication The Contentsquare APIs use the server-to-server OAuth 2.0 standard for authentication, also know as 2-legged OAuth or OAuth 2LO. The flow basically consists in calling an authentication endpoint with a pair `client_id` / `client_secret` to retrieve an access token that remains valid for 1 hour. This JWT token should then be used as a Bearer token in the headers of your HTTPS requests (in the form `Authorization: Bearer YOUR_ACCESS_TOKEN`). the API call to the authentication endpoint will also dynamically return the right base URL that you must use. This base URL depends on which cloud the target project is installed on. You can refer below to a [detailed example](#example-of-authentication-flow) of the overall flow to retrieve a token and a base URL, and use those to query the Speed Analysis Lab API. You can generate a pair `client_id` / `client_secret` from the Contentsquare [console ↗](https://console.contentsquare.com), as a Contentsquare administrator. You can find how to generate these credentials in our Help Center documentation. You can create OAuth credentials either: * At the Project level, to request access resources from a specific project only * At the Account level: to request access for any project of the account Warning Your OAuth credentials carry many privileges, so make sure to keep them secure! Do not share them in publicly accessible areas such as GitHub, client-side code, and so forth. ## Refresh your access token Once you get a JWT access token (see the [authentication endpoint](#authentication-endpoint) below), it's valid for 1 hour. If you try to query the Contentsquare APIs with access to token that has expired, you will receive a `401 Unauthorized` error with the error code `JWT_EXPIRED`, in the form: ```json { "success": false, "errorMessage": "Auth token is expired.", "errorCode": "JWT_EXPIRED" } ``` In that case, you should first use your OAuth credentials (your pair `client_id` / `client_secret`) to query a new The OAuth credentials expire after 1 year. See [How to regenerate OAuth credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593-How-to-create-API-credentials#section4). ## Authentication endpoint POST [https://api.contentsquare.com/v1/oauth/token ↗](https://api.contentsquare.com/v1/oauth/token) ### Parameters * #### client\_id  string  Required The OAuth `client_id` generated from the Contentsquare console. * #### client\_secret  string  Required The OAuth `client_secret` generated from the Contentsquare console. * #### grant\_type  string  Required Always set it to `"client_credentials"`, as required by the OAuth 2.0 standard. * #### scope  string  Required You should use `"speed-analysis"`. If needed, you can specify a list of several scopes to get a token that can query several APIs (for example "data-export speed-analysis" if you want your token to cover both the [Data Export API](https://docs.contentsquare.com/en/api/export/) and Speed Analysis Lab API scopes). The only scope that cannot be combined with other scopes is `enrichment`. * #### project\_id  integer   Required only if you use account-level OAuth credentials, to specify which project of the account you want to target. ### Request example ```shell curl --location 'https://api.contentsquare.com/v1/oauth/token' \ --header 'Content-Type: application/json' \ --data '{ "client_id": "c3133d76-a768-4f5a-XXX", "client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX", "grant_type": "client_credentials", "scope": "speed-analysis", "project_id": 42 }' ``` ### Response example ```json { "access_token": "eyJhbGciOiJSIsImtpY5MTXXX.CNTcKWAUb2mTp2cZyiDRYYOtGCKXXX", // to be used as bearer token to query the APIs "token_type": "bearer", "expires_in": 3600, "scope": "speed-analysis", "project_id": 42, "endpoint": "https://api.eu-west-1.production.contentsquare.com" // this is the base URL you should use to query the Speed Analysis Lab API endpoints - the provided URL depends on the cloud the project is installed on } ``` ## Example of authentication flow Below is a sample of JavaScript code to show a complete API call flow that first retrieves an access token and then use it to retrieve the list of segments on a project: ```javascript const clientId = "<your_client_id>"; const clientSecret = "<your_client_secret>"; const authEndpoint = "https://api.contentsquare.com/v1/oauth/token"; const authRequestOptions = { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ client_id: clientId, client_secret: clientSecret, grant_type: "client_credentials", project_id: 42, scope: "speed-analysis", }), }; const authResponse = await fetch(authEndpoint, authRequestOptions); const authJsonData = await authResponse.json(); // Below are the access token and base URL that must be used to query the Speed Analysis Lab API endpoints const accessToken = authJsonData.access_token; const baseURL = authJsonData.endpoint; // Using the access token and base URL to query the Speed Analysis Lab API endpoints and get the monitoring list in this example const speedAnalysisLabResponse = await fetch(`${baseURL}/v1/speed-analysis/monitoring/list`, { method: "POST", headers: { Authorization: `Bearer ${accessToken}` }, }); const data = await speedAnalysisLabResponse.json(); const monitorings = data.payload.monitorings; ``` ## OAuth credentials information endpoint POST [https://api.contentsquare.com/v1/oauth/me ↗](https://api.contentsquare.com/v1/oauth/me) ### Parameters * #### client\_id  string  Required The OAuth `client_id` generated from the Contentsquare console. * #### client\_secret  string  Required The OAuth `client_secret` generated from the Contentsquare console. ### Request example ```shell curl --location 'https://api.contentsquare.com/v1/oauth/me' \ --header 'Content-Type: application/json' \ --data '{ "client_id": "c3133d76-a768-4f5a-XXX", "client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX", }' ``` ### Response example ```json { "scopes": "speed-analysis metrics data-export session-replay symbolicator", "permissions": { "projects": [ { "id": 42, "name": "UX ANALYTICS" } ] } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Authentication","description":"How to authenticate to use the Speed Lab API","url":"https://docs.contentsquare.com/en/api/speed-analysis-lab/authentication/","inLanguage":"en","dateModified":"2026-05-06T17:30:22+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Event endpoints - APIs description: Speed Analysis Lab Event endpoints reference lastUpdated: 06 May 2026 source_url: html: https://docs.contentsquare.com/en/api/speed-analysis-lab/event-endpoints/ md: https://docs.contentsquare.com/en/api/speed-analysis-lab/event-endpoints/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use these endpoints to query Speed Analysis Lab events. ## Get a list of events POST /v1/speed-analysis/event/list Returns the list of events. ### Parameters * #### key  string   Key of the event. * #### dateFrom  ISO 8601 date string   Retrieve events executed after this date. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### monitoringId  number   Unique identifier of a monitoring. It can used to get events for a specific monitoring. * #### scenarioId  number   Unique identifier of a scenario. It can used to get events for a specific scenario. ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/event/list' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "key": "" }' ``` ### Response example ```json { "payload": { "events": [ { "key": "", "text": "", "date": "2016-10-07T12:00:00.000+02:00" } ] }, "success": true } ``` ## Create an event POST /v1/speed-analysis/event/create Returns the created event. ### Parameters * #### key  string  Required Key of the event. * #### text  string  Required Text of the event. * #### date  ISO 8601 date string  Required Date of the event. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### monitorings  number\[]   List of monitoring identifiers that can be retrieved from the monitoring list (`/monitoring/list`). It can be used to associate the event with multiple monitorings. * #### scenarios  number\[]   List of scenario identifiers that can be retrieved from the scenario list (`/scenario/list`). It can be used to associate the event with multiple scenarios. ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/event/create' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "key":"", "text": "", "date": "", "monitorings":[0] }' ``` ### Response example ```json { "payload": { "key": "" }, "success": true } ``` ## Delete an event POST /v1/speed-analysis/event/delete Returns the deleted event. ### Parameters * #### key  string  Required Key of the event. ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/event/delete' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "key":"" }' ``` ### Response example ```json { "payload": { "key": "" }, "success": true } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Event endpoints","description":"Speed Analysis Lab Event endpoints reference","url":"https://docs.contentsquare.com/en/api/speed-analysis-lab/event-endpoints/","inLanguage":"en","dateModified":"2026-05-06T17:30:22+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Analysis endpoints - APIs description: Speed Analysis Lab Analysis endpoints reference lastUpdated: 06 May 2026 source_url: html: https://docs.contentsquare.com/en/api/speed-analysis-lab/analysis-endpoints/ md: https://docs.contentsquare.com/en/api/speed-analysis-lab/analysis-endpoints/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use these endpoints to run and retrieve Speed Analysis Lab reports. ## Get an analysis report POST /v1/speed-analysis/analysis/report Returns the analysis report. ### Parameters * #### reportId  string  Required Unique identifier of a report. * #### metricsOnly  boolean   Set to true to only generate a summary report, excluding advice, categories, and detected technologies (default: `false`). * #### getUniqueIDsForTips  boolean   Set to true to get an ID for each element of `report.tips` (default: `false`). ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/analysis/report' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "reportId": "", "metricsOnly": true, "getUniqueIDsForTips": false }' ``` ### Response example ```json { "payload": { "missing": [""], "report": { "publicReportUrl": "https://www.dareboost.com/[lang]/report/[reportId]", "harFileUrl": "https://www.dareboost.com/download/harFile/[reportId]", "date": 0, "url": "", "lang": "", "config": { "location": "", "browser": { "name": "", "version": "" }, "isMobile": false, "bandwidth": { "upstream": 0, "downstream": 0 }, "latency": 0, "isPrivate": false, "adblock": false, "screen": { "height": 0, "width": 0 }, "basicAuth": { "user": "", "password": "" }, "postData": [ { "key": "", "value": "" } ], "header": [ { "key": "", "value": "" } ], "blacklist": [], "whiteList": [], "dnsMapping": [ { "origin": "", "destination": "" } ], "cookies": [], "repeatedView": false, "hhtp2Disabled": false, "animationsStopped": {} }, "summary": { "loadTime": 0, "score": 0, "requestsCount": 0, "weight": 0 }, "categories": [ { "name": "", "mark": 0 } ], "tips": [ { "advice": "", "category": "", "score": -1, "name": "", "priority": 0 } ], "timings": { "navigationStart": 0, "firstByte": 0, "firstPaint": 0, "domInteractive": 0, "loadEvent": 0, "startRender": 0, "speedIndex": 0, "visuallyComplete": 0, "oldVisuallyComplete": 0, "loadEventStart": 0, "lastByte": 0, "domLoading": 0, "domContentLoadedEventStart": 0, "domContentLoadedEventEnd": 0, "domComplete": 0, "firstContentfulPaint": 0, "firstConsistentlyInteractive": 0, "largestContentfulPaint": 0, "totalBlockingTime": 0, "maxPotentialFirstInputDelay": 0, "totalLongTasks": 0, "lastLongTask": 0, "nbLongTasks": 0, "cumulativeLayoutShift": 0 }, "resourceByType": [ { "type": "", "bodyWeight": 0, "headerWeight": 0, "requestCount": 0 } ], "customTimings": [ { "type": "", "name": "", "startTime": 0, "duration": 0 } ], "technos": [ { "name": "", "version": "" } ] } }, "success": true } ``` ## Get HAR from an analysis POST /v1/speed-analysis/analysis/har Returns the HAR from the analysis. ### Parameters * #### reportId  string  Required Unique identifier of a report. ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/analysis/har' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "reportId": "" }' ``` ### Response example ```json { "payload": { "har": "" }, "success": true } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Analysis endpoints","description":"Speed Analysis Lab Analysis endpoints reference","url":"https://docs.contentsquare.com/en/api/speed-analysis-lab/analysis-endpoints/","inLanguage":"en","dateModified":"2026-05-06T17:30:22+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Monitoring endpoints - APIs description: Speed Analysis Lab Monitoring endpoints reference lastUpdated: 06 May 2026 source_url: html: https://docs.contentsquare.com/en/api/speed-analysis-lab/monitoring-endpoints/ md: https://docs.contentsquare.com/en/api/speed-analysis-lab/monitoring-endpoints/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use these endpoints to manage Speed Analysis Lab monitorings. ## Get the list of monitorings POST /v1/speed-analysis/monitoring/list Returns the list of monitorings. ### Parameters * #### name  string   String pattern to filter your monitorings and return only those that contain the pattern in their name * #### url  string   String pattern to filter your monitorings and return only those that contain the pattern in their URL ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/monitoring/list' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "name": "", "url": "" }' ``` ### Response example ```json { "payload": { "monitorings": [ { "id": 0, "url": "", "name": "", "state": "OK", "errorMessage": "", "lastExecution": 0, "enabled": true, "frequency": 1440, "lang": "en", "config": { "location": "", "browser": { "name": "", "version": "" }, "isMobile": false, "bandwidth": { "upstream": 0, "downstream": 0 }, "latency": 0, "isPrivate": false, "screen": { "height": 0, "width": 0 }, "basicAuth": { "user": "", "password": "" }, "postData": [ { "key": "", "value": "" } ], "header": [ { "key": "", "value": "" } ], "blacklist": [], "whiteList": [], "dnsMapping": [ { "origin": "", "destination": "" } ], "cookies": [], "repeatedView": false, "hhtp2Disabled": false, "animationsStopped": {} } } ] }, "success": true } ``` ## Get the monitoring last report POST /v1/speed-analysis/monitoring/last-report Returns the last report of a monitoring. ### Parameters * #### monitoringId  number  Required Unique identifier of a monitoring. * #### metricsOnly  boolean   Set to true to only generate a summary report, excluding advice, categories, and detected technologies (default: `false`). * #### getUniqueIDsForTips  boolean   Set to true to get an ID for each element of `report.tips` (default: `false`). ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/monitoring/last-report' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "monitoringId": 0, "metricsOnly": false, "getUniqueIDsForTips": false }' ``` ### Response example ```json { "payload": { "lastExecution": 0, "alerts": [ { "type": "", "threshold": 0, "value": 0 } ], "missing": [], "report": { "publicReportUrl": "https://www.dareboost.com/[lang]/report/[reportId]", "harFileUrl": "https://www.dareboost.com/download/harFile/[reportId]", "date": 0, "url": "", "lang": "", "config": { "location": "", "browser": { "name": "", "version": "" }, "isMobile": false, "bandwidth": { "upstream": 0, "downstream": 0 }, "latency": 0, "isPrivate": false, "adblock": false, "screen": { "height": 0, "width": 0 }, "basicAuth": { "user": "", "password": "" }, "postData": [ { "key": "", "value": "" } ], "header": [ { "key": "", "value": "" } ], "blacklist": [], "whiteList": [], "dnsMapping": [ { "origin": "", "destination": "" } ], "cookies": [], "repeatedView": false, "hhtp2Disabled": false, "animationsStopped": {} }, "summary": { "loadTime": 0, "score": 0, "requestsCount": 0, "weight": 0 }, "categories": [ { "name": "", "mark": 0 } ], "tips": [ { "advice": "", "category": "", "score": -1, "name": "", "priority": 0 } ], "timings": { "navigationStart": 0, "firstByte": 0, "firstPaint": 0, "domInteractive": 0, "loadEvent": 0, "startRender": 0, "speedIndex": 0, "visuallyComplete": 0, "oldVisuallyComplete": 0, "loadEventStart": 0, "lastByte": 0, "domLoading": 0, "domContentLoadedEventStart": 0, "domContentLoadedEventEnd": 0, "domComplete": 0, "firstContentfulPaint": 0, "firstConsistentlyInteractive": 0, "largestContentfulPaint": 0, "totalBlockingTime": 0, "maxPotentialFirstInputDelay": 0, "totalLongTasks": 0, "lastLongTask": 0, "nbLongTasks": 0, "cumulativeLayoutShift": 0 }, "resourceByType": [ { "type": "", "bodyWeight": 0, "headerWeight": 0, "requestCount": 0 } ], "customTimings": [ { "type": "", "name": "", "startTime": 0, "duration": 0 } ], "technos": [ { "name": "", "version": "" } ] } }, "success": true } ``` ## Get the monitoring reports POST /v1/speed-analysis/monitoring/reports Returns the monitoring reports. ### Parameters * #### monitoringId  number  Required Unique identifier of a monitoring. * #### limit  number   Limits the number of reports to return (default: `30`). Set to `0` to get all monitoring reports. * #### lastDays  number   Retrieve reports from the last X days, where X is the value of this parameter. * #### dateFrom  ISO 8601 date string   Retrieve audit executed after this date. Must be a date before `dateTo`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### dateTo  ISO 8601 date string   Retrieve audit executed before this date. Must be a date after `dateFrom`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### error  boolean   By default, all results are returned. Set to `false` to retrieve only executions without error. Set to `true` to retrieve only executions with error. ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/monitoring/reports' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "monitoringId": 0, "limit": 30, "lastDays": 0, "dateFrom": "2016-03-11T00:00:00.000+0100", "dateTo": "2016-03-11T23:59:59.000+0100", "error": false }' ``` ### Response example ```json { "payload": { "statistics": { "averageScore": 0, "averageWeight": 0, "averageRequests": 0, "averageLoadTime": 0, "averageTimings": { "navigationStart": 0, "firstByte": 0, "firstPaint": 0, "domInteractive": 0, "loadEvent": 0, "startRender": 0, "speedIndex": 0, "visuallyComplete": 0, "oldVisuallyComplete": 0, "loadEventStart": 0, "lastByte": 0, "domLoading": 0, "domContentLoadedEventStart": 0, "domContentLoadedEventEnd": 0, "domComplete": 0, "firstContentfulPaint": 0, "firstConsistentlyInteractive": 0, "largestContentfulPaint": 0, "totalBlockingTime": 0, "maxPotentialFirstInputDelay": 0, "totalLongTasks": 0, "lastLongTask": 0, "nbLongTasks": 0, "cumulativeLayoutShift": 0 }, "averageCustomTimings": [ { "type": "", "name": "", "startTime": 0, "duration": 0 } ] }, "monitoringData": [ { "state": "OK", "errorMessage": "", "id": 0, "date": 0, "score": 0, "weight": 0, "requests": 0, "loadTime": 0, "unreachableRequests": 0, "timings": { "navigationStart": 0, "firstByte": 0, "firstPaint": 0, "domInteractive": 0, "loadEvent": 0, "startRender": 0, "speedIndex": 0, "visuallyComplete": 0, "oldVisuallyComplete": 0, "loadEventStart": 0, "lastByte": 0, "domLoading": 0, "domContentLoadedEventStart": 0, "domContentLoadedEventEnd": 0, "domComplete": 0, "firstContentfulPaint": 0, "firstConsistentlyInteractive": 0, "largestContentfulPaint": 0, "totalBlockingTime": 0, "maxPotentialFirstInputDelay": 0, "totalLongTasks": 0, "lastLongTask": 0, "nbLongTasks": 0, "cumulativeLayoutShift": 0 }, "customTimings": [ { "type": "mark", "name": "bootstrap_start", "startTime": 3510, "duration": 0 } ] } ] }, "success": true } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Monitoring endpoints","description":"Speed Analysis Lab Monitoring endpoints reference","url":"https://docs.contentsquare.com/en/api/speed-analysis-lab/monitoring-endpoints/","inLanguage":"en","dateModified":"2026-05-06T17:30:22+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Scenario endpoints - APIs description: Speed Analysis Lab Scenario endpoints reference lastUpdated: 06 May 2026 source_url: html: https://docs.contentsquare.com/en/api/speed-analysis-lab/scenario-endpoints/ md: https://docs.contentsquare.com/en/api/speed-analysis-lab/scenario-endpoints/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use these endpoints to manage Speed Analysis Lab scenarios. ## Get the list of scenarios POST /v1/speed-analysis/scenario/list Returns the list of scenarios. ### Parameters * #### name  string   String pattern to filter your scenarios and return only those that contain the pattern in their name ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/scenario/list' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "name": "" }' ``` ### Response example ```json { "payload": { "scenarios": [ { "id": 1, "name": "" } ] }, "success": true } ``` ## Get a scenario report POST /v1/speed-analysis/scenario/report Returns a scenario report. ### Parameters * #### scenarioId  number  Required Unique identifier of a scenario. * #### date  number  Required Timestamp (in ms) indicating when the report was generated. ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/scenario/report' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "scenarioId": 0, "date": 1542117158294 }' ``` ### Response example ```json { "payload": { "scenarioReport": { "scenarioId": 0, "name": "", "resultId": 0, "date": 0, "viewOnTheWeb": "https://www.dareboost.com/scenario/[scenarioId]/report/[date]", "summary": { "fail": 0, "unavailableResource": 0, "browserError": 0, "sum": { "firstPaint": 0, "request": 0, "startRender": 0, "lastByte": 0, "weight": 0, "domInteractive": 0, "domContentLoadedEventStart": 0, "domComplete": 0, "loadEvent": 0, "firstContentfulPaint": 0, "loadTime": 0, "loadEventStart": 0, "firstConsistentlyInteractive": 0, "visuallyComplete": 0, "speedIndex": 0, "firstByte": 0, "domContentLoadedEventEnd": 0, "domLoading": 0, "largestContentfulPaint": 0, "totalBlockingTime": 0, "maxPotentialFirstInputDelay": 0, "totalLongTasks": 0, "lastLongTask": 0, "nbLongTasks": 0, "cumulativeLayoutShift": 0 }, "average": { "firstPaint": 0, "request": 0, "startRender": 0, "lastByte": 0, "weight": 0, "domInteractive": 0, "domContentLoadedEventStart": 0, "domComplete": 0, "loadEvent": 0, "firstContentfulPaint": 0, "loadTime": 0, "loadEventStart": 0, "firstConsistentlyInteractive": 0, "visuallyComplete": 0, "speedIndex": 0, "firstByte": 0, "domContentLoadedEventEnd": 0, "domLoading": 0, "largestContentfulPaint": 0, "totalBlockingTime": 0, "maxPotentialFirstInputDelay": 0, "totalLongTasks": 0, "lastLongTask": 0, "nbLongTasks": 0, "cumulativeLayoutShift": 0 } }, "steps": [ { "stepId": 0, "stepResultId": "", "name": "", "description": "", "fail": 0, "unavailableResource": 0, "browserError": 0, "timings": { "navigationStart": 0, "firstByte": 0, "firstPaint": 0, "domInteractive": 0, "loadEvent": 0, "startRender": 0, "speedIndex": 0, "visuallyComplete": 0, "oldVisuallyComplete": 0, "loadEventStart": 0, "lastByte": 0, "domLoading": 0, "domContentLoadedEventStart": 0, "domContentLoadedEventEnd": 0, "domComplete": 0, "firstContentfulPaint": 0, "firstConsistentlyInteractive": 0, "largestContentfulPaint": 0, "totalBlockingTime": 0, "maxPotentialFirstInputDelay": 0, "totalLongTasks": 0, "lastLongTask": 0, "nbLongTasks": 0, "cumulativeLayoutShift": 0 }, "weight": 0, "requestsCount": 0, "loadTime": 0, "customTimings": [ { "type": "", "name": "", "startTime": 0, "duration": 0 } ] } ] } }, "success": true } ``` ## Get the scenario reports POST /v1/speed-analysis/scenario/reports Returns the scenario reports. ### Parameters * #### scenarioId  number  Required Unique identifier of a scenario. * #### limit  number   Limits the number of reports to return (default: `30`). Set to `0` to get all scenario reports. * #### lastDays  number   Retrieve reports from the last X days, where X is the value of this parameter. * #### dateFrom  ISO 8601 date string   Retrieve audit executed after this date. Must be a date before `dateTo`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### dateTo  ISO 8601 date string   Retrieve audit executed before this date. Must be a date after `dateFrom`. ISO format in UTC (for example "2021-08-13T12:32:40.000Z") or with a time zone offset ("2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL). * #### error  boolean   By default, all results are returned. Set to `false` to retrieve only executions without error. Set to `true` to retrieve only executions with error. ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/scenario/reports' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "scenarioId": 0, "limit": 30, "lastDays": 0, "dateFrom": "2016-03-11T00:00:00.000+0100", "dateTo": "2016-03-11T23:59:59.000+0100", "error": false }' ``` ### Response example ```json { "payload": { "scenario": { "id": 0, "name": "", "reports": [ { "resultId": 0, "date": 0, "viewOnTheWeb": "https://www.dareboost.com/scenario/[scenarioId]/report/[date]", "summary": { "fail": 0, "unavailableResource": 0, "browserError": 0, "sum": { "firstPaint": 0, "request": 0, "startRender": 0, "lastByte": 0, "weight": 0, "domInteractive": 0, "domContentLoadedEventStart": 0, "domComplete": 0, "loadEvent": 0, "firstContentfulPaint": 0, "loadTime": 0, "loadEventStart": 0, "firstConsistentlyInteractive": 0, "visuallyComplete": 0, "speedIndex": 0, "firstByte": 0, "domContentLoadedEventEnd": 0, "domLoading": 0, "largestContentfulPaint": 0, "totalBlockingTime": 0, "maxPotentialFirstInputDelay": 0, "totalLongTasks": 0, "lastLongTask": 0, "nbLongTasks": 0, "cumulativeLayoutShift": 0 }, "average": { "firstPaint": 0, "request": 0, "startRender": 0, "lastByte": 0, "weight": 0, "domInteractive": 0, "domContentLoadedEventStart": 0, "domComplete": 0, "loadEvent": 0, "firstContentfulPaint": 0, "loadTime": 0, "loadEventStart": 0, "firstConsistentlyInteractive": 0, "visuallyComplete": 0, "speedIndex": 0, "firstByte": 0, "domContentLoadedEventEnd": 0, "domLoading": 0, "largestContentfulPaint": 0, "totalBlockingTime": 0, "maxPotentialFirstInputDelay": 0, "totalLongTasks": 0, "lastLongTask": 0, "nbLongTasks": 0, "cumulativeLayoutShift": 0 } }, "steps": [ { "stepId": 0, "stepResultId": "", "name": "", "description": "", "fail": 0, "unavailableResource": 0, "browserError": 0, "timings": { "navigationStart": 0, "firstByte": 0, "firstPaint": 0, "domInteractive": 0, "loadEvent": 0, "startRender": 0, "speedIndex": 0, "visuallyComplete": 0, "oldVisuallyComplete": 0, "loadEventStart": 0, "lastByte": 0, "domLoading": 0, "domContentLoadedEventStart": 0, "domContentLoadedEventEnd": 0, "domComplete": 0, "firstContentfulPaint": 0, "firstConsistentlyInteractive": 0, "largestContentfulPaint": 0, "totalBlockingTime": 0, "maxPotentialFirstInputDelay": 0, "totalLongTasks": 0, "lastLongTask": 0, "nbLongTasks": 0, "cumulativeLayoutShift": 0 }, "weight": 0, "requestsCount": 0, "loadTime": 0, "customTimings": [ { "type": "", "name": "", "startTime": 0, "duration": 0 } ] } ] } ] } }, "success": true } ``` ## Get the scenario step report POST /v1/speed-analysis/scenario/step/report Returns the report of the scenario step. ### Parameters * #### stepId  string  Required Unique identifier of the step result of a scenario. Refers to the `stepResultId` of `/scenario/reports` and `/scenario/report`. ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/scenario/step/report' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "stepId": "" }' ``` ### Response example ```json { "payload": { "step": { "id": "", "previousStepId": "", "nextStepId": "", "stepResultId": 0, "date": 0, "timings": { "firstByte": 0, "firstPaint": 0, "domInteractive": 0, "loadEvent": 0, "startRender": 0, "speedIndex": 0, "visuallyComplete": 0, "oldVisuallyComplete": 0, "loadEventStart": 0, "lastByte": 0, "domLoading": 0, "domContentLoadedEventStart": 0, "domContentLoadedEventEnd": 0, "domComplete": 0, "firstContentfulPaint": 0, "firstConsistentlyInteractive": 0, "largestContentfulPaint": 0, "totalBlockingTime": 0, "maxPotentialFirstInputDelay": 0, "totalLongTasks": 0, "lastLongTask": 0, "nbLongTasks": 0, "cumulativeLayoutShift": 0 }, "browserError": "[]", "unavailableResource": "{}", "actionsResult": [ { "id": 0, "time": 0, "status": "", "message": "" } ], "customTimings": [ { "type": "", "name": "", "startTime": 0, "duration": 0 } ] } }, "success": true } ``` ## Get HAR from an analysis POST /v1/speed-analysis/scenario/report/har Returns the HAR from the analysis. ### Parameters * #### scenarioStepResultId  string  Required Unique identifier of the scenario step result, obtained when launching a scenario execution. ### Request example ```shell curl --location --request POST 'https://api.contentsquare.com/v1/speed-analysis/scenario/report/har' \ --header 'Authorization: Bearer <your_access_token>' --data '{ "scenarioStepResultId": "" }' ``` ### Response example ```json { "payload": { "har": "" }, "success": true } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Scenario endpoints","description":"Speed Analysis Lab Scenario endpoints reference","url":"https://docs.contentsquare.com/en/api/speed-analysis-lab/scenario-endpoints/","inLanguage":"en","dateModified":"2026-05-06T17:30:22+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Adobe Analytics - Android description: Leverage our native integration to use Adobe Analytics segments in Contentsquare lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/adobe-analytics/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/adobe-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Analyze your data from anywhere in the customer journey using your Adobe Analytics segments. Contentsquare allows you to use your Adobe Analytics segments in every Contentsquare feature (Journey Analysis, Page Comparator, Session Replay). Warning Sessions without at least one screenview will be discarded. You should implement your screen tracking plan first, to have your Adobe Analytics integration work. See [Track screens](../track-screens/). ## Prerequisites **Adobe SDK code requirements** Make sure you register at least `Identity.EXTENSION` and `Analytics.EXTENSION` extensions before starting `MobileCore`. Check the [Getting Started with Adobe Analytics Android Extension ↗](https://github.com/adobe/aepsdk-analytics-android/blob/main/Documentation/getting-started.md) repository for that. 1. Follow the instructions from [Adobe Analytics for mobile apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271665881745) 2. Add the [AEP Android SDK ↗](https://github.com/adobe/aepsdk-analytics-android) to your project ## Code implementation Add the CSAppLifecycleObserver to the [ProcessLifecycleOwner ↗](https://developer.android.com/reference/androidx/lifecycle/ProcessLifecycleOwner) Note **Why 30 minutes before sending a new csMatchingKey** * 30 minutes is Contentsquare default session duration. * Setting a value **higher** than 30 minutes would cause overlapping on our sessions, and would impact negatively the data import from Adobe. * Setting a value **lower** than 30 minutes would make you to send more data to Adobe. This could cause the variable to reach Adobe's threshold, causing Adobe to filter values, and potentially impact your billing. See [Low-traffic value in Adobe Analytics ↗](https://experienceleague.adobe.com/docs/analytics/technotes/low-traffic.html) ```kotlin class CSAppLifecycleObserver(appContext: Context) : DefaultLifecycleObserver { private val sharedPreferences = appContext.getSharedPreferences( "CSAppLifecycleObserver", Context.MODE_PRIVATE ) private val random = Random() override fun onResume(owner: LifecycleOwner) { super.onResume(owner) sendCSMatchingKeyIfNeeded() } private fun sendCSMatchingKeyIfNeeded() { val csMatchingKeyTimestampKey = "csMatchingKey_ts" val csMatchingKeyValidityMs = 1800000 // 30 minutes val currentTimestamp = Date().time val csMatchingKeyIsPreviousTimestamp = sharedPreferences.getLong(csMatchingKeyTimestampKey, 0) if (currentTimestamp - csMatchingKeyIsPreviousTimestamp <= csMatchingKeyValidityMs) { return } sharedPreferences.edit().putLong(csMatchingKeyTimestampKey, currentTimestamp).apply() val csMatchingKey = "csMatchingKey" val csMatchingKeyValue = random.nextDouble().toString() + "_" + currentTimestamp CSQ.addDynamicVar(csMatchingKey, csMatchingKeyValue) MobileCore.trackState("${csMatchingKey}_state", Collections.singletonMap(csMatchingKey, csMatchingKeyValue)) } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Adobe Analytics","description":"Leverage our native integration to use Adobe Analytics segments in Contentsquare","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/adobe-analytics/","inLanguage":"en","dateModified":"2026-05-04T12:00:05+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - Android description: The Contentsquare Android SDK changelog lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/changelog/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. 📬 Stay updated! ## Opt-in to CSQ Experience Platform Already using the CSQ SDK in standalone mode? Follow these steps to switch to CSQ Experience Platform and combine Experience Analytics and Product Analytics under a single data source. CSQ Experience Platform is currently an Early Access program. To gain access, contact your Customer Success Manager. CSQ Experience Platform guidance Throughout the documentation, code samples highlight differences between standalone and CSQ Experience Platform integrations.  1. [Update the SDK package to 1.10.1 or later](../#install-the-sdk). 2. Replace your current `CSQ.start(this)` or `CSQ.start(this, StartConfig.withEnvironmentId(...))` call with the `dataSourceId` provided by your Customer Success Manager. This links your app to the CSQ Experience Platform data source. **MyApplication.kt** ```kotlin CSQ.start(this, StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")) ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 3. Review changes [introduced in 1.10.0](#1100---20260504) which notably removes support for several Product Analytics options. ## 1.12.1 - 2026.08.06 Experience Analytics * Update Experience Analytics SDK version to `4.52.1`: * **Analytics** * Extended `ignoreInteractions` API for single Views only * **Bug fix:** Added missing support for custom views inheriting from WebView * **WebViews** * **Bug fix:** fixing duplicate taps for WebView child classes * **Core** * **Bug fix:** no more install and upgrade event fired on every app relaunch * **Bug fix:** resolved a ANR issue when migrating from CSQ SDK before 1.10.0 * **Bug fix:** resolved a crash when migrating from CSQ SDK before 1.10.0 * **Bug fix:** resolved a few memory leaks * **Bug fix:** resolved a build failure when referencing CSQ.metadata * **Bug fix:** avoid crash due to malformed environment and datasource ID * **Session Replay** * Improved Image capture for Coil libraries on Jetpack Compose * Improved capture synchronization to capture screen transitions * **Bug fix:** resolved a few memory leaks when a dialog is captured Product Analytics * Update Product Analytics Core SDK version to `0.9.5`. * Update Product Analytics Autocapture SDK version to `0.9.5`. * Adds support for the latest Jetpack Compose BOM. * **Bug fix:** fixes an issue where certain overlays were not removed from the composition correctly. * **Bug fix:** fixes an issue that prevented notification autocapture from capturing some notifications as expected ## 1.12.0 - 2026.07.27 Experience Analytics * Update Experience Analytics SDK version to `4.52.0`: * **Analytics** * Added support for Android multi-window mode and activity resizing * Added support for screenshots when using PA autocapture screenviews only * **Bug fix:** Fixed background issue for WebViews embedded in Jetpack Compose * **Session Replay** * Improved Image capture for Jetpack Compose * **Bug fix:** Fixed an issue detecting Jetpack Compose bottom sheet position * **Bug fix:** Prevent potential Personal Data leaks on some scrollable containers on Jetpack Compose * **WebViews** * **Bug fix:** fixed a synchronisation issue that could result in a "Webview Not Tracked" in the Session Replay Player * **Bug fix:** fixed an issue where coming back from background into a webview would result in a "Webview Not Tracked" in the Session Replay Player Product Analytics * Update Product Analytics Core SDK version to `0.9.4`. * Update Product Analytics Autocapture SDK version to `0.9.4`. ## 1.11.2 - 2026.07.03 Experience Analytics * Update Experience Analytics SDK version to `4.51.2`: * **Analytics** * **Bug fix:** Ensured gesture listener attachment is executed on the main thread to prevent potential crashes on some screens. * **Session Replay** * Optimized Session Replay to degrade the capture rate to 1 FPS instead of stopping completely when main thread performance impact is detected. * **Bug fix:** Fixed an issue where Session Replay could fail to start when used with Autocapture. * **WebViews** * **Bug fix:** Aligned native Android behavior to respect the server-side kill-switch for disabling tag injection in WebViews. * **Bug fix:** Fixed a crash that could occur when registering or unregistering WebViews before the SDK is fully initialized. Product Analytics * Update Product Analytics Core SDK version to `0.9.3`. * Update Product Analytics Autocapture SDK version to `0.9.3`. ## 1.11.1 - 2026.06.29 Experience Analytics * Update Experience Analytics SDK version to `4.51.1`: * **Core** * **Bug fix:** Fixed an issue where the configured sampling rate could be ignored in some rare cases ## 1.11.0 - 2026.06.05 Experience Analytics * Update Experience Analytics SDK version to `4.51.0`: * **Core** * **Security** Resolved a security vulnerability where the SDK's deeplink feature could be exploited via crafted deeplinks to arbitrarily modify SDK configuration. * **Bug fix:** Fixed persisting PA-DXA session synchronization issues where session counts and screen quantities diverged between DXA and PA collection. * **Analytics** * **Bug fix:** Fixed an issue where screenshot can not be generated when tracking is paused. * **Session Replay** * Session Replay can now resume collection within the same session after a performance-based stop, restarting at LOW quality and re-evaluating start/stop rules. * Compose capture robustness work, foundation for better SR capture in Compose-heavy apps tied to harmonized masking. * Removed obsolete MultiWindow Feature Flag as the newer image processor rollout progresses. * **Bug fix:** Fixed an issue where button text disappeared in the live app but was correctly captured in the Session Replay. * **Bug fix:** Fixed missing images in Session Replay for Compose apps when harmonized masking is enabled . * **Bug fix:** Addressing Session Replay rendering issues where certain screens display only wide empty elements instead of actual content. Product Analytics * Update Product Analytics Core SDK version to `0.9.2`. * Update Product Analytics Autocapture SDK version to `0.9.1`. ## 1.10.1 - 2026.05.05 Product Analytics * Fixed an issue where Product Analytics could fail to start when the remote config is unavailable, causing the opt-in call to be ignored. ## 1.10.0 - 2026.05.04 Experience Analytics * Update Experience Analytics SDK version to `4.50.0`: * The Session timeout definition changes from "30 minutes after being in background" to **30 minutes after last event**. See [Session definition](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/data-collection/#session-definition). Product Analytics * Update Product Analytics Core SDK version to `0.9.0`. * Update Product Analytics Autocapture SDK version to `0.9.0`. ### Configuration **API update:** `CSQ.start()` now takes a `StartConfig` wrapping the environment ID and options. `ProductAnalyticsOptions` is renamed to `AnalyticsOptions` and `envID` to `id`. ```kotlin CSQ.configureProductAnalytics( context = this, envId = "YOUR_ENVIRONMENT_ID", options = ProductAnalyticsOptions( enableViewAutocapture = true ) ) CSQ.start(this) CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true ) ) ) ``` ### Options **Added:** `sessionReplayAutoStart` — set to `false` to disable automatic Session Replay start and control it manually. Defaults to `true`. ```kotlin CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions(sessionReplayAutoStart = false) ) ) ``` **Removed:** `captureVendorId`, `captureAdvertiserId`, `clearEventPropertiesOnNewUser`, `messageBatchMessageLimit`, `resumePreviousSession`, `pruningLookBackWindow`, `maximumDatabaseSize`, `maximumBatchCountPerUpload`, `disableUploadsInBackground`, `disableScreenviewForwardToDXA`, and `disableScreenviewForwardToPA` are no longer available. Remove them from your `CSQ.start()` call if present: ```kotlin CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( captureVendorId = true, captureAdvertiserId = true, clearEventPropertiesOnNewUser = true, messageBatchMessageLimit = 100, resumePreviousSession = true, pruningLookBackWindow = 6, maximumDatabaseSize = 200_000, maximumBatchCountPerUpload = 10, disableUploadsInBackground = true, disableScreenviewForwardToDXA = true, disableScreenviewForwardToPA = true, ) ) ) ``` ### APIs * **Breaking change:** `CSQ.optIn(context: Context)` deprecated API has been removed, use `CSQ.optIn()` (no context parameter required). ### Agent skills Contentsquare now provides [Agent skills for Android](https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/using-agent-skills/) — structured files that let AI coding assistants such as GitHub Copilot, Cursor, and Claude Code integrate, upgrade, and configure the SDK automatically. ## 1.5.3 - 2026.06.25 Experience Analytics * Update Experience Analytics SDK version to `4.44.2`: * **Analytics** * **Bug fix:** Prevent crash in `ViewTreeObserver.dispatchOnPreDraw()` ## 1.5.2 - 2026.04.1 Experience Analytics * Update Product Analytics Core SDK version to `0.8.10`. * Update Product Analytics Autocapture SDK version to `0.8.12`. ## 1.5.1 - 2026.03.05 Experience Analytics * Update Experience Analytics SDK version to `4.44.1`: * **Analytics** * **Bug fix:** Improved invisible overlay detection to resolve an issue where long screenshots were not scrollable * **Bug fix:** Fixed duplicate tap event in tracked WebViews * Update Product Analytics Core SDK version to `0.8.9`. ## 1.5.0 - 2026.02.18 Experience Analytics * Update Experience Analytics SDK version to `4.44.0`: * **Session Replay** * Improve UI change detection to prevent unplayable screens * **Bug fix:** improve synchronisation of session between Heap and Contentsquare * **Bug fix:** resolved an internal `java.util.ConcurrentModificationException` * **Bug fix:** resolved an internal `java.lang.NullPointerException` * **Bug fix:** improve masking stability * **Errors** * Now setUrlMaskingPatterns can be called before the SDK start * OkHttp 5 compatibility with Network Plugin 1.7.0 * Sanity checked added to URL masking patterns resolving a `java.util.regex.PatternSyntaxException` * **Bug fix:** validate URL patterns when setUrlMaskingPatterns is called * Update Product Analytics Core SDK version to `0.8.8`. * Update Product Analytics Autocapture SDK version to `0.8.10`. ## 1.4.7 - 2026.01.05 Experience Analytics * Update Experience Analytics SDK version to `4.43.8`: * **Errors** * Fixed API Error URL not masked until SDK is fully initialized ## 1.4.6 - 2026.01.02 Experience Analytics * Update Experience Analytics SDK version to `4.43.7`: * **Session Replay** * **Bug fix:** resolved a masking issues when multi-window is enabled ## 1.4.5 - 2025.12.26 Experience Analytics * Update Experience Analytics SDK version to `4.43.6`: * **Core** * **Bug fix:** resolves crash in WindowCallbackWrapper ## 1.4.4 - 2025.12.19 Experience Analytics * Update Experience Analytics SDK version to `4.43.5`: * **Analytics** * Add support of material `ModalBottomSheetLayout` for Zoning and Heatmap analysis, using the `CsqTag()` API * **Core** * Improve compatibility with DexGuard ## 1.4.3 - 2025.12.16 Experience Analytics * Update Experience Analytics SDK version to `4.43.4`: * **Session Replay** * **Bug fix:** Improve memory management to avoid memory leak * **Bug fix:** Prevent crash during activity destroy process * **Analytics** * **Bug fix:** Fixed an issue where heatmap positions were not tracked correctly on some Compose screens with lazy scroll elements. * **Bug fix:** Improved invisible overlay detection to resolve an issue where long screenshots were not scrollable. * **Core** * Migrated from Android `ContentProvider` to AndroidX Startup for initialization * **Bug fix:** Resolved `java.lang.NullPointerException` crash on `FileProvider` ## 1.4.2 - 2025.11.28 Experience Analytics * Update Experience Analytics SDK version to `4.43.3`: * **Zoning Analytics** * CsqIgnoreInteraction() now excludes wrapped Composable from the screenshot ## 1.4.1 - 2025.11.24 Experience Analytics * Update Experience Analytics SDK version to `4.43.2`: * **Session Replay** * **Bug fix:** Resolved `java.util.ConcurrentModificationException` crash on Session Replay touch listener. * **Analytics** * **Bug fix:** Resolved `java.lang.ArrayIndexOutOfBoundsException` crash with Exposure Metrics. * **Core** * Improved SDK initialization performance by moving certain operations off the main thread Product Analytics * Update Product Analytics Core SDK version to `0.8.7`. * Update Product Analytics Autocapture SDK version to `0.8.9`. ## 1.4.0 - 2025.11.13 Experience Analytics * Update Experience Analytics SDK version to `4.43.0`: * **Analytics** * Fixed an issue where screenshot button was not visible after visiting In-app settings. * Fixed compatibility issues with Jetpack Compose 1.10. * **Session Replay** * Improved gesture detection to reliably identify the targeted view. Product Analytics * Update Product Analytics Core SDK version to `0.8.6`. ## 1.3.0 - 2025.10.20 * **Webviews** * The One WebView Tag feature is now available in controlled general availability. It brings key Product Analytics features — Identity, User Properties, Hierarchy, and Target Text — to WebViews, enabling unified Product Analytics and Experience Analytics. To gain access, contact your Customer Success Manager to be added to the eligibility list. ## 1.2.1 - 2025.10.07 Experience Analytics * Update Experience Analytics SDK version to `4.41.1`: * Analytics * Fixed a crash when Jetpack Compose Node is not attached * **Session Replay** * Fixed a bug that cause parent masking not being propagated to child views on some scenarios * Improve capture of Native views inside Jetpack Compose Product Analytics * Update Product Analytics Core SDK version to `0.8.5`. * Update Product Analytics Autocapture SDK version to `0.8.8`. ## 1.2.0 - 2025.09.05 Experience Analytics * Update Experience Analytics SDK version to `4.41.0`: * Analytics * **Bug fix:** Fixed an issue when the very first item of a RecyclerView is bigger than the scrollable area * Core * **Bug fix:** Fixed an issue when the very first item of a RecyclerView is bigger than the scrollable area Product Analytics * Update Product Analytics Core SDK version to `0.8.4`. * Update Product Analytics Autocapture SDK version to `0.8.7`. ## 1.1.0 - 2025.08.04 Experience Analytics * Update Experience Analytics SDK version to `4.40.0`: * Session Replay * Image and Text masking configuration in the CSQ Console * Added new APIs to start Session Replay on demand * Added new APIs to support Event-Triggered Replays * Analytics * **Bug fix:** Fixed a potential crash when generating scroll metrics on certain Compose screens * Improve heatmap data accuracy for Compose lazy lists and grids Product Analytics * Update Product Analytics Core SDK version to `0.8.3`. * Update Product Analytics Autocapture SDK version to `0.8.6`. ## 1.0.1 - 2025.07.02 Experience Analytics * Update Experience Analytics SDK version to `4.39.3`: * Session Replay * **Bug fix:** Fix blank screens in Jetpack Compose when the dialogs and bottom sheets capture was enabled. * **Bug fix:** Fixed an issue causing an inconsistent Tag injection for Webviews in Capacitor apps. * **Bug fix:** Fixed an issue causing unreliable Session Replay starts in Capacitor apps. * Improved Session Replay screen change consistency on Capacitor apps ## 1.0.0 - 2025.06.27 Initial release of the CSQ SDK. * Introduces the unified CSQ API, which combines Product Analytics, Experience Analytics, and Monitoring features into a single, cohesive library. * This initial release includes: * Experience Analytics SDK version `4.39.2`. * Product Analytics Core SDK version `0.8.2`. * Product Analytics Autocapture SDK version `0.8.3`. Upgrade to CSQ SDK 1.+ Looking to upgrade from CSQ SDK 0.x to the latest? See the [upgrade guide](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-heap-and-cs-sdk/). ## 0.11.1 - 2026.03.03 * Update Experience Analytics SDK version to [`4.44.1`](https://docs.contentsquare.com/en/android/changelog/#4441---20260303). * Update Product Analytics [Core `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.10` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.10` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.11.0 - 2026.02.18 * Update Experience Analytics SDK version to [`4.44.0`](https://docs.contentsquare.com/en/android/changelog/#4440---20260217). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.10` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.10` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.6 - 2026.01.05 * Update Experience Analytics SDK version to [`4.43.8`](https://docs.contentsquare.com/en/android/changelog/#4438---20260105). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.5 - 2026.01.02 * Update Experience Analytics SDK version to [`4.43.7`](https://docs.contentsquare.com/en/android/changelog/#4437---20260102). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.4 - 2025.12.26 * Update Experience Analytics SDK version to [`4.43.6`](https://docs.contentsquare.com/en/android/changelog/#4436---20251226). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.3 - 2025.12.22 * Update Experience Analytics SDK version to [`4.43.5`](https://docs.contentsquare.com/en/android/changelog/#4435---20251219). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.2 - 2025.12.16 * Update Experience Analytics SDK version to [`4.43.4`](https://docs.contentsquare.com/en/android/changelog/#4434---20251216). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.1 - 2025.11.24 * Update Experience Analytics SDK version to [`4.43.2`](https://docs.contentsquare.com/en/android/changelog/#4432---20251124). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.0 - 2025.11.13 * Update Experience Analytics SDK version to [`4.43.0`](https://docs.contentsquare.com/en/android/changelog/#4430---20251113). * Update Product Analytics [Core `0.8.6` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.8` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.8` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.9.1 - 2025.10.07 * Update Experience Analytics SDK version to [`4.41.1`](https://docs.contentsquare.com/en/android/changelog/#4411---20251007). * Update Product Analytics [Core `0.8.5` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.8` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.8` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.8.0 - 2025.08.04 * Update Experience Analytics SDK version to [`4.40.0`](https://docs.contentsquare.com/en/android/changelog/#4400---20250801). * Update Product Analytics [Core `0.8.3` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.6` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.6` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.7.2 - 2025.07.09 * Update Experience Analytics SDK version to [`4.39.3`](https://docs.contentsquare.com/en/android/changelog/#4393---20250701). * Update Product Analytics [Core `0.8.2` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.3` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.3` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.7.1 - 2025.05.16 * Update Experience Analytics SDK version to [`4.38.2`](https://docs.contentsquare.com/en/android/changelog/#4382---20250516). * Update Product Analytics [Core `0.8.1` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.2` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.2` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.7.0 - 2025.05.09 * Update Experience Analytics SDK version to [`4.38.1`](https://docs.contentsquare.com/en/android/changelog/#4381---20250430). * Update Product Analytics [Core `0.8.1` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.2` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.2` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.6.0 - 2025.04.03 * Update Experience Analytics SDK version to [`4.37.0`](https://docs.contentsquare.com/en/android/changelog/#4370---20250402). * Update Product Analytics [Core `0.8.0` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.5.1 - 2025.03.13 * Update Experience Analytics SDK version to [`4.36.1`](https://docs.contentsquare.com/en/android/changelog/#4361---20250313). * Update Product Analytics [Core `0.7.6` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.7.7` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.7.7` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.5.0 - 2025.02.13 * Update Experience Analytics SDK version to [`4.36.0`](https://docs.contentsquare.com/en/android/changelog/#4360---20250210). * Update Product Analytics [Core `0.7.6` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.7.5` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.7.5` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.4.0 - 2025.01.07 * Update Experience Analytics SDK version to [`4.35.0`](https://docs.contentsquare.com/en/android/changelog/#4350---20250102). * Update Product Analytics [Core `0.7.5` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.7.3` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.7.3` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.3.0 - 2024.10.25 * Update Experience Analytics SDK version to [`4.34.0`](https://docs.contentsquare.com/en/android/changelog/#4340---20241025). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.7.1` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.7.1` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.2.0 - 2024.10.18 * Update Experience Analytics SDK version to [`4.33.2`](https://docs.contentsquare.com/en/android/changelog/#4332---20241018). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.7.1` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.7.1` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.1.1 - 2024.09.10 * Update Experience Analytics SDK version to [`4.32.1`](https://docs.contentsquare.com/en/android/changelog/#4321---20240910). * Update Product Analytics [Core `0.7.1` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.1.0 - 2024.09.02 * This release marks the introduction of the CSQ SDK which brings together Product Analytics, Experience Analytics, and Monitoring features. From this version onwards, the SDK releases follow a new versioning scheme. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare Android SDK changelog","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/changelog/","inLanguage":"en","dateModified":"2026-07-08T17:11:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: SDK API reference - Android description: SDK commands reference including signature, parameter descriptions, and examples lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/command-reference/ md: https://docs.contentsquare.com/en/csq-sdk-android/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). ```kotlin CSQ.optIn() ``` ### CSQ.optOut() **Added in:** `1.0.0` Revoke user consent, remove stored `userId`. Stop CSQ SDK, flush, and clear all data. ```kotlin CSQ.optOut() ``` #### Parameters * #### Context  object   Android [Context object ↗](https://developer.android.com/reference/android/content/Context) ### CSQ.identify() **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. 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`. ```kotlin CSQ.identify(identity: String) ``` #### Parameters * #### identity  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 equivalent to calling [`optOut()`](#csqoptout) then [`optIn()`](#csqoptin). ```kotlin CSQ.resetIdentity() ``` #### Parameters * No parameters. ### CSQ.sendUserIdentifier() **Added in:** `1.0.0` Associate a user identifier to the session. ```kotlin CSQ.sendUserIdentifier(identity: String) ``` #### Parameters * #### identity  String (<= 100 chars)   The string value representing the user identifier to be associated with the current session. Should be max 100 characters long. ### 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. This is an identifier from Product Analytics by default or Experience Analytics if Product Analytics is not active. ```kotlin 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. ```kotlin CSQ.metadata.sessionId ``` #### CSQ.metadata.projectId Project identifier for Experience Analytics. ```kotlin CSQ.metadata.projectId ``` #### CSQ.metadata.environmentId Environment identifier for Product Analytics. ```kotlin CSQ.metadata.environmentId ``` #### CSQ.metadata.sessionReplayUrl URL of current Session Replay. ```kotlin CSQ.metadata.sessionReplayUrl ``` #### CSQ.metadata.identity Identity associated with the user by calling [`identify()`](#csqidentify). ```kotlin CSQ.metadata.identity ``` ### CSQ.metadata.onChanged() **Added in:** `1.0.0` A block triggered each time user information is updated. For example when `sessionReplayUrl` becomes available or `userId` updates. Set this block to subscribe to the updates. Contentsquare will call this block with updated metadata. Note This may not trigger on changes to Product Analytics data. ```kotlin CSQ.metadata.onChanged = OnMetadataChanged { metadata -> // Handle information change } ``` #### Parameters * #### metadata  Metadata   Metadata associated with the current user and project. ## Logging ### CSQ.debug.setLogLevel() **Added in:** `1.0.0` Sets the current log level. ```kotlin CSQ.debug.logLevel = loglevel ``` #### Parameters * #### level  Enum (CSQ.Log.Level)   Possible values: `none`, `trace`, `debug`, `info`, `warn` or `error`. ### CSQ.debug.logChannel() **Added in:** `1.0.0` Add a `LogChannel` to which send log messages. ```kotlin CSQ.debug.logChannel = channel ``` #### Parameters * #### LogChannel  interface   The interface where log messages will be routed. ### LogChannel.printLog() **Added in:** `1.0.0` Routes SDK logs to another location such as Timber, Arbor, or similar logging libraries. The default implementation routes all logs through Logcat. ```kotlin LogChannel.printLog() ``` #### Parameters * No parameters. ## Property Tracking ### CSQ.addDynamicVar() Experience Analytics | **Added in:** `1.0.0` Adds one or multiple dynamic variables to the session properties. This method allows you to pass a `DynamicVar` object, representing a key-value pair that is scoped to the session. ```kotlin val var1 = DynamicVar("key1", "value1") val var2 = DynamicVar("key2", 10L) CSQ.addDynamicVar(var1) CSQ.addDynamicVar(var2) ``` #### Parameters * #### DynamicVar  object   The dynamic variable * #### key  String (<= 512 chars)   Dynamic variable key * #### value  String/Long   Dynamic variable value ### CSQ.addUserProperties() Product Analytics | **Added in:** `1.0.0` Add a collection of properties to be associated with the current user. ```kotlin CSQ.addUserProperties(properties: Map<String, Any>) ``` #### Parameters * #### properties  Map\<String, Any>   A map of user properties. ### CSQ.addEventProperties() Product Analytics | **Added in:** `1.0.0` Add a collection of properties to be associated with all future events. ```kotlin CSQ.addEventProperties(properties: Map<String, Any>) ``` #### Parameters * #### properties  Map\<String, Any>   A map of event properties. * #### key  String   the UserProperty key * #### value  Any   values can be any combination of any `Number`, `Boolean`, `String` or Java/Kotlin object that implements `Property` ### CSQ.removeEventProperty() Product Analytics | **Added in:** `1.0.0` Removes a single property from the collection of event-wide properties. ```kotlin CSQ.removeEventProperty(property: String) ``` #### Parameters * #### property  String   The key of the property to remove. ### CSQ.clearEventProperties() Product Analytics | **Added in:** `1.0.0` Removes all event-wide properties. ```kotlin CSQ.clearEventProperties() ``` ## View Tracking ### CSQ.excludeFromExposureMetric() Experience Analytics | **Added in:** `1.0.0` Exclude a scrollable view or subclass from Exposure Metric computations. Warning iOS-only, applicable on `UIScrollView` or a class inheriting from `UIScrollView`. Android-only application on `ScrollView` & `RecyclerView`. ```kotlin CSQ.excludeFromExposureMetric(View) ``` #### Parameters * #### View  View   The view to exclude from exposure metrics. ### CsqTag() Experience Analytics | **Added in:** `1.4.4` Jetpack Compose composable function for tagging composables that require special handling by SDK. It is used to enable support for material `ModalBottomSheetLayout` in Zoning and Heatmap analysis. ```kotlin enum class CsqTag { ModalBottomSheetLayout } @Composable fun CsqTag(tag: CsqTag, block: @Composable () -> Unit) ``` #### Parameters * #### tag  Enum (CsqTag)   indicates the type of special handling required by the SDK `CsqTag.ModalBottomSheetLayout` - enables the SDK to properly capture and analyze content within a material `ModalBottomSheetLayout` for Zoning and Heatmaps. * #### block  @Composable () -> Unit   the composable lambda representing the UI content to be tagged ## Interoperability ### CSQ.registerWebView() **Added in:** `1.0.0` Register a webview for tracking. ```kotlin CSQ.registerWebView(webView) ``` #### Parameters * #### webView  WebView   The webview to register for tracking. ### CSQ.unregisterWebView() **Added in:** `1.0.0` Unregister a webview for tracking. ```kotlin CSQ.unregisterWebView(webView) ``` #### Parameters * #### webView  WebView   The webview to unregister from tracking. ## Event Tracking ### CSQ.trackTransaction() Experience Analytics | **Added in:** `1.0.0` Send a transaction. ```kotlin CSQ.trackTransaction(Transaction) ``` #### Parameters * #### Transaction  Transaction   The transaction object to be sent. ### CSQ.trackScreenview() **Added in:** `1.0.0` Send a screen view with or without custom variables. ```kotlin CSQ.trackScreenview(name: String, cvars: List<CustomVar> = emptyList()) ``` #### Parameters * #### name  String   The name of the screen. * #### cvars  List\<CustomVar> (optional)   A list of custom variables to attach to the screen view. * #### index  Int (@IntRange(from = 0, to = 20))   A number identifying a CustomVar * #### name  String (<= 512 chars)   Custom variable key * #### value  String   Custom variable value ### CSQ.trackEvent() Product Analytics | **Added in:** `1.0.0` Creates an event message to be tracked and sent to the API. ```kotlin CSQ.trackEvent(name: String, properties: Map<String, Any> = mapOf()) ``` #### Parameters * #### name  String   The name of the event to be tracked. * #### properties  Map\<String, Any> (optional)   Optional properties to associate with the event. ### CSQ.trackMotionEvent() Experience Analytics | **Added in:** `1.0.0` Track a gesture manually. ```kotlin CSQ.trackMotionEvent(motionEvent: MotionEvent) ``` #### Parameters * #### motionEvent  MotionEvent   The [MotionEvent ↗](https://developer.android.com/reference/android/view/MotionEvent) to be tracked. ### TriggeredOnResume() Experience Analytics | **Added in:** `1.0.0` Helper function for Jetpack Compose to ensure only one screen view is triggered when a given screen is presented to the user. ```kotlin @Composable TriggeredOnResume(block: () -> Unit) ``` #### Parameters * #### block  Function   The block of code to run when the screen is resumed. ## Surveys ### CSQ.triggerSurvey() Experience Analytics Voice of Customer | **Added in:** `1.0.0` Triggers a survey by referencing a predefined trigger name. This method allows your mobile app to trigger surveys at specific moments in the user journey. Triggers act as flexible placeholders that are not bound to individual surveys, enabling your business team to assign or update surveys later without requiring code changes. ```kotlin CSQ.triggerSurvey(triggerName: String) ``` #### Parameters * #### triggerName  String   The name of the trigger associated with the survey. This should match the trigger name configured in the Contentsquare platform. #### Example ```kotlin // Trigger a survey after a purchase is completed CSQ.triggerSurvey("purchase-complete") ``` ## Error tracking ### CSQ.setUrlMaskingPatterns() Experience Analytics | **Added in:** `1.0.0` Sets URL masking patterns. ```kotlin CSQ.setUrlMaskingPatterns(patterns: List<String>) ``` #### Parameters * #### patterns  List\<String>   A list of URL patterns to mask. ### CSQ.trackNetworkMetric() Experience Analytics | **Added in:** `1.0.0` Track network metrics. ```kotlin CSQ.trackNetworkMetric(networkMetric: NetworkMetric) ``` #### Parameters * #### networkMetric  NetworkMetric   The network metric to be tracked. ### CsqOkHttpInterceptor() Experience Analytics | **Added in:** `1.0.0` Intercept every OkHttp call to manually collect API errors. ```kotlin val okhttpClient = OkHttpClient().newBuilder() .addInterceptor(CsqOkHttpInterceptor()) .build() ``` ## Personal Data/Masking ### CSQ.ignoreInteractions() **Added in:** `1.0.0` Ignore interactions for a specific view. ```kotlin CSQ.ignoreInteractions(view: View, includeSubtree: Boolean = true) ``` #### Parameters * #### view  View   The view for which interactions should be ignored. * #### includeSubtree  Boolean   Whether to include the view's subtree when ignoring interactions. ### View\.csqIgnoreInteractions **Added in:** `1.0.0` Kotlin extension function to ignore interactions for a specific view. ```kotlin View.csqIgnoreInteractions(includeSubtree: Boolean = true) ``` #### Parameters * #### includeSubtree  Boolean   Whether to include the view's subtree when ignoring interactions. ### CsqIgnoreInteraction() Jetpack Compose composable function to ignore interactions for a specific view. ```kotlin @Composable fun CsqIgnoreInteraction(ignore: Boolean, block: @Composable () -> Unit) ``` #### Parameters * #### ignore  Boolean   indicating whether interactions should be ignored or not * #### block  @Composable () -> Unit   composable lambda function representing the UI content to apply ignore condition ### CSQ.setDefaultMasking() Experience Analytics | **Added in:** `1.0.0` Set the default masking state. All Android View elements, their subclasses and Jetpack Compose components are fully masked by default. ```kotlin CSQ.setDefaultMasking(masked: Boolean) ``` #### Parameters * #### masked  Boolean   The masking state to be set. ### CSQ.mask(View) **Added in:** `1.0.0` Mask a view's content. ```kotlin CSQ.mask(view: View) ``` #### Parameters * #### View  View   The view which content will be masked. ### View\.csqMaskContents(enable: Boolean) **Added in:** `1.0.0` Kotlin extension function to mask the content of a view. ```kotlin View.csqMaskContents(enable: Boolean) ``` #### Parameters * #### enable  Boolean   Whether to mask the content of the view. ### CsqMask() Jetpack Compose composable function that applies masking to Compose UI content This will mask both Session Replay and analytics event.. ```kotlin @Composable CsqMask(enable: Boolean, block: @Composable () -> Unit) ``` #### Parameters * #### enable  Boolean   Whether to mask the content of the view. * #### block  @Composable () -> Unit   composable lambda function representing the content to apply masking condition ### CSQ.unmask(View) **Added in:** `1.0.0` Unmask a view's content. ```kotlin CSQ.unmask(view: View) ``` #### Parameters * #### View  View   The view whose content will be unmasked. ### CSQ.mask(Class\<?> type) Experience Analytics | **Added in:** `1.0.0` Mask content for views of a specific type. ```kotlin CSQ.mask(type: Class<*>) ``` #### Parameters * #### type  Class\<?>   The class type of the view whose content will be masked. ### CSQ.unmask(Class\<?> type) Experience Analytics | **Added in:** `1.0.0` Unmask content for views of a specific type. ```kotlin CSQ.unmask(type: Class<*>) ``` #### Parameters * #### type  Class\<?>   The class type of the view whose content will be unmasked. ### CSQ.maskTexts() **Added in:** `1.0.0` Mask text input fields. ```kotlin CSQ.maskTexts(mask: Boolean) ``` #### Parameters * #### mask  Boolean   Whether to mask text. ## SDK initialization and management ### CSQ.configureProductAnalytics() Deprecated Product Analytics | **Added in:** `1.0.0` SDK configuration method for Product Analytics. Use [`CSQ.start()`](#csqstart) instead, which combines configuration and initialization in a single call. ### CSQ.start() **Added in:** `1.0.0` Start the SDK. This method combines configuration and initialization in a single call. There are three overloads depending on whether you want Experience Analytics, Product Analytics, or CSQ Experience Platform. **Experience Analytics only:** ```kotlin CSQ.start(context = this) ``` **Product Analytics (optionally with Experience Analytics extension) with environmentId:** ```kotlin CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true ) ) ) ``` **CSQ Experience Platform with `dataSourceId`:** ```kotlin CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID" ) ) ``` #### Parameters * #### context  Context   Android [Context object ↗](https://developer.android.com/reference/android/content/Context) * #### startConfig  StartConfig (optional)   Configuration created via `StartConfig.withEnvironmentId(id, options)` or `StartConfig.withDataSourceId(id, options)`. Omit for Experience Analytics only. ### CSQ.stop() **Added in:** `1.0.0` Stop all activity from the SDK. Once run no requests, telemetry collection, or logs will be generated. ```kotlin CSQ.stop() ``` ### CSQ.pauseTracking() **Added in:** `1.0.0` Pause all tracking features. ```kotlin CSQ.pauseTracking() ``` ### CSQ.resumeTracking() **Added in:** `1.0.0` Resume all tracking features. ```kotlin CSQ.resumeTracking() ``` ### CSQ.startSessionReplay() **Added in:** `1.10.0` Enable and eventually start Session Replay independently of other CSQ SDK features, allowing for on-demand collection. To use this functionality, disable the automatic start of Session Replay at SDK initialization using the [`.sessionReplayAutoStart`](#sessionreplayautostart) option. ```kotlin CSQ.startSessionReplay() ``` ### CSQ.stopSessionReplay() **Added in:** `1.10.0` Stop Session Replay immediately. ```kotlin CSQ.stopSessionReplay() ``` ## SDK configuration options CSQ SDK options passed to [`CSQ.start()`](#csqstart). ```kotlin // optional: StartConfig.withEnvironmentId(id: String, options) | StartConfig.withDataSourceId(id: String) CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true, baseUri = URI.create("https://mh.ba.contentsquare.net"), // EU; https://mh.bf.contentsquare.net (default) uploadInterval = 15.0, disablePageviewAutocapture = false, enablePushNotificationAutocapture = true, enablePushNotificationTitleAutocapture = true, enablePushNotificationBodyAutocapture = false, sessionReplayAutoStart = false ) ) ) ``` ### `baseUri` The CSQ API endpoint to use: * `https://mh.ba.contentsquare.net` — EU-hosted environments * `https://mh.bf.contentsquare.net` — all other environments (default) ### `uploadInterval` Interval in seconds at which event batches are uploaded to the API. Defaults to 15 seconds. ### `disablePageviewAutocapture` Whether source pageview events will be auto-captured. Defaults to false. ### `enableViewAutocapture` Whether the SDK will auto capture UI interactions and source pageviews. Only for Android View system, no Compose support. Defaults to false. ### `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 set to `true`. Defaults to false. ### `enablePushNotificationBodyAutocapture` Whether capture the body text of the notification where an interaction was performed. `enablePushNotificationAutocapture` must be set to `true`. Defaults to false. ### `maximumDatabaseSize` 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. ### `messageBatchMessageLimit` 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. ### `maximumBatchCountPerUpload` The maximum number of batches to send per upload cycle. This can be used in conjunction with messageBatchMessageLimit to control the amount of data that is uploaded in a given cycle. ### `resumePreviousSession` Enables Contentsquare behavior of persisting non-expired sessions across app launch. ### `pruningLookBackWindow` The number of days to look back when pruning old data in days. Defaults to 6 days. Requires an entitlement to use. ### `sessionReplayAutoStart` Whether Session Replay starts automatically at SDK launch. Defaults to `true`. Set to `false` to disable automatic start and control Session Replay manually. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"SDK API reference","description":"SDK commands reference including signature, parameter descriptions, and examples","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/command-reference/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - Android description: Requirements and limitations to develop with the Contentsquare Android SDK lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/compatibility/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare Android SDK has specific language, platform, and version requirements for integration. * **Supported languages**: The Contentsquare SDK supports and tracks content written in Kotlin or Java. * **Minimum Android version**: Your app must be running Android 5.0 (Lollipop) or a later version (API Level 21+) to use the Contentsquare SDK. * **Compilation information**: The Contentsquare SDK is built and compiled using Android SDK version 34. Warning If your app supports Android devices running versions below 7.1, you must include the ISRG Root X1 certificate in your app to ensure Let's Encrypt certificates work correctly. For more details and guidance, check this link: [Let's Encrypt Cross-Sign Expiration ↗](https://letsencrypt.org/2023/07/10/cross-sign-expiration/). ## Java versions This version has been compiled on `Java 17` (Bytecode version 61). Note If you try to import the Contentsquare SDK while using a lower Java version in your project, you will get a `bad class file` error. Update your Java version to get rid of the error. ## Kotlin versions Contentsquare Android SDK is compiled with Kotlin version `1.8.22`. If you don't use the `1.8.22` Kotlin version and you have conflict issues; you must exclude the Kotlin `stdlib` from our SDK. * Kotlin ```kotlin implementation("com.contentsquare.android:sdk:1.12.1") { exclude(group = "org.jetbrains.kotlin", module = "kotlin-stdlib-jdk8") } ``` * Groovy ```groovy implementation("com.contentsquare.android:sdk:1.12.1") { exclude group: "org.jetbrains.kotlin", module: "kotlin-stdlib-jdk8" } ``` Compatibility modes We use [Kotlin Compatibility modes ↗](https://kotlinlang.org/docs/compatibility-modes.html) flags to be backward compatible with two previous Kotlin versions and one next version. For an in-depth understanding of compatibility modes, see this [quicksheet ↗](https://blog.mbonnin.net/kotlin-compatibility-quicksheet). ## Jetpack Compose versions Contentsquare Compose SDK `com.contentsquare.android:sdk-compose:1.12.1` is compiled using Jetpack Compose version `1.7.0` (`bom 2024.09.00`). | CSQ SDK Version | CS Compose version | Embedded Compose version | Minimum Compose version | Latest tested Compose version | | - | - | - | - | - | | 1.12.1 | 4.52.1 | 1.7.0 | 1.7.0 | 1.11.0 | | 1.12.0 | 4.52.0 | 1.7.0 | 1.7.0 | 1.11.0 | | 1.11.2 | 4.51.2 | 1.7.0 | 1.7.0 | 1.11.0 | | 1.11.1 | 4.51.1 | 1.7.0 | 1.7.0 | 1.11.0 | | 1.11.0 | 4.51.0 | 1.7.0 | 1.7.0 | 1.11.0 | | 1.10.1 | 4.45.0 | 1.7.0 | 1.7.0 | 1.10.0 | | 1.5.3 | 4.44.2 | 1.7.0 | 1.7.0 | 1.10.0 | | 1.5.2 | 4.44.1 | 1.7.0 | 1.7.0 | 1.10.0 | | 1.5.1 | 4.44.1 | 1.7.0 | 1.7.0 | 1.10.0 | | 1.5.0 | 4.44.0 | 1.7.0 | 1.7.0 | 1.10.0 | | 1.4.2 | 4.43.3 | 1.7.0 | 1.7.0 | 1.10.0-beta02 | | 1.4.1 | 4.43.2 | 1.7.0 | 1.7.0 | 1.10.0-beta02 | | 1.4.0 | 4.43.0 | 1.7.0 | 1.7.0 | 1.10.0-beta02 | | 1.3.0 | 4.42.0 | 1.7.0 | 1.7.0 | 1.9.0-beta02 | | 1.2.0 | 4.41.0 | 1.7.0 | 1.7.0 | 1.9.0-beta02 | | 1.1.0 | 4.40.0 | 1.7.0 | 1.7.0 | 1.9.0-beta02 | | 1.0.1 | 4.39.3 | 1.7.0 | 1.7.0 | 1.8.0-rc02 | | 1.0.0 | 4.39.2 | 1.7.0 | 1.7.0 | 1.8.0-rc02 | | 0.7.1 | 4.38.2 | 1.5.0 | 1.5.0 | 1.8.0-rc02 | | 0.7.0 | 4.38.1 | 1.5.0 | 1.5.0 | 1.8.0-rc02 | | | 4.38.0 | 1.5.0 | 1.5.0 | 1.8.0-rc02 | | 0.6.0 | 4.37.0 | 1.5.0 | 1.5.0 | 1.7.7 | | 0.5.1 | 4.36.1 | 1.5.0 | 1.5.0 | 1.7.7 | | 0.5.0 | 4.36.0 | 1.5.0 | 1.5.0 | 1.7.7 | | 0.4.0 | 4.35.0 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | 0.3.0 | 4.34.0 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | 0.2.0 | 4.33.2 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | | 4.33.1 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | | 4.33.0 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | 0.1.1 | 4.32.1 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | 0.1.0 | 4.32.0 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | | 4.31.0 | 1.5.4 | 1.5.0 | 1.7.0-beta06 | | | 4.30.0 | 1.5.4 | 1.5.0 | | | | 4.29.1 | 1.5.4 | 1.5.0 | | | | 4.28.0 | 1.5.4 | 1.5.0 | | | | 4.27.1 | 1.5.4 | 1.4.0 | | | | 4.26.0 | 1.5.4 | 1.4.0 | | | | 4.25.0 | 1.5.4 | 1.4.0 | | | | 4.24.1 | 1.5.4 | 1.4.0 | | | | 4.23.1 | 1.4.0 | 1.4.0 | | | | 4.22.0 | 1.4.0 | 1.4.0 | | | | 4.21.0 | 1.4.0 | 1.4.0 | | | | 4.20.0 | 1.4.0 | 1.4.0 | | Note If your project uses a lower Compose version than the one embedded in the Contentsquare Compose SDK, Gradle will automatically use the latter version. Update the Compose version to the one used by our SDK or later. ## Dependencies The Contentsquare SDK has a few dependencies. We try to be up-to-date as much as possible to avoid conflict issues. ### Handling conflicts We may sometimes have conflicts between your app dependencies VS SDK dependencies. In this case, you can exclude from our SDK any dependency we pull and use your version instead. #### Example with excluding `recyclerview` dependency If you have a version of the **`recyclerview`** in your app which is older than the one we use, you can use the following to exclude it in your Gradle file. * Kotlin ```kotlin implementation("com.contentsquare.android:sdk:1.12.1") { exclude(group = "androidx.recyclerview", module = "recyclerview") exclude(group = "androidx.swiperefreshlayout", module = "swiperefreshlayout") } ``` * Groovy ```groovy implementation("com.contentsquare.android:sdk:1.12.1") { exclude group: "androidx.recyclerview", module: "recyclerview" exclude group: "androidx.swiperefreshlayout", module: "swiperefreshlayout" } ``` By doing this, you skip the **`recyclerview`** and **`swiperefreshlayout`** dependencies provided by our SDK. ### Dependencies list The list of dependencies for each artifact is searchable on central.sonatype.com: * [`com.contentsquare.android:sdk` ↗](https://central.sonatype.com/artifact/com.contentsquare.android/sdk/dependencies) * [`com.contentsquare.android:sdk-compose` ↗](https://central.sonatype.com/artifact/com.contentsquare.android/sdk-compose/dependencies) ## Known limitations and recommendations ### Native UI Elements are not supported **Symptom:** 1. You capture screenshots but main elements of the screen are not appearing. 2. SDK does not log any gesture events when interacting with some native UI elements. **Explanation:** Native UI Elements such as Bottom Sheets, Dialogs, Menus are not supported by the SDK. ### Gestures not attached to the expected view (Layout visibility) **Symptom:** In some cases, we found that gestures tracked by the SDK are not attached to the right UI element of the screen. These gestures will be attached to an invisible view. **Explanation:** The reason for this is that when the SDK attaches the gesture to a UI element, it generates a path regarding the visibility of the view when traversing the view hierarchy. If a view is visible and it matches the coordinates on where the gesture was performed it will be taken into account. Most of the time, the issue is that a layout is still present on the screen even if there is no content. **Best Practice:** When designing your application UI, do not let any layout stray along if it is not used. If a layout contains widgets like progress bar, remember to set its visibility to `GONE` or `INVISIBLE` after its purpose is served. ### Taps will be assigned to the first clickable view **Symptom:** A tap is not assigned to the tapped view, but to a view higher in the view hierarchy. **Explanation:** When a tap is captured, the view hierarchy is traversed to find all views that match the tap coordinates. The tap is assigned to the first clickable view, starting at the tail of the view list, meaning the search starts at the lowest hierarchy level. If no clickable view is found, then the tap is assigned to the view at the tail of the list. Jetpack Compose example: ```kotlin Button( onClick = { ... } ) { Text(text = "Simple Button") } ``` A tap on the `Text` will be assigned to the `Button`, because the `Button` is clickable. **Best practice:** If the described behavior does not fit your needs, you may add click listeners to the corresponding views. In the example above, you may add an identical click listener to the `Text`. ### Heatmaps: Initial scroll position has to be 0 **Symptom:** The tap positions in the Tap Heatmap do not match the actual tap positions on the screen. **Explanation:** For lists with lazy item generation, we may be unable to determine the correct initial scroll position. This is because the top list items may not be generated yet. We expect the initial scroll position to always be 0. **Best practice:** Ensure that the initial scroll position is always 0 for RecyclerViews and Compose lazy lists and lazy grids. ### No gesture detection for WebViews embedded in scroll container **Symptom:** Swipe gestures are not detected for a WebView. **Explanation:** For WebViews, the gesture detection is completely covered by the CS Tag, not the native Android SDK. However, when a WebView is placed inside a scrollable container, for example a `ScrollView`, the WebView will expand to its full size and all scrolling will be done by the scrollable container. In this case, no swipe gestures will be detected. **Best practice:** Ensure that WebViews are not placed inside any scrollable containers. ### Long Screenshot: Large Capture Limitation **Symptom:** The Long Screenshot capture completes the creation process, but then fails at the very end without a clear error message. **Explanation:** Long Screenshots can produce a very large amount of data. For reliability and performance reasons, the server enforces a maximum payload size (\~75 MB). Very long or content-heavy screens may exceed this limit, causing the screenshot to be rejected. **Workaround:** Capture a shorter area (reduce the scroll length) and/or reduce the amount of on-screen content (for example fewer or lighter elements), then retry the Long Screenshot. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Contentsquare Android SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/compatibility/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Data Collection - Android description: Understand how the Android SDK loads, tracks, and send data lastUpdated: 11 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/data-collection/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/data-collection/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The SDK starts automatically at launch, fetches its configuration, and sends collected analytics events in batches; a session ends after 30 minutes of inactivity. ## Configuration Once started, our SDK fetches it configuration from our servers. Then depending on the segmentation size (defined by our team when you sign a contract) and the user consent status, it will start collecting analytics data from system and user events it detects from the runtime. ## Data collection ### Analytics data collection The SDK monitors the application, lifecycle events, the view hierarchy, and generates data from the behavior of the app, the content of the screen and the user interactions. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. ### Session Replay data collection See [Session Replay Initialization](../session-replay/#initialization) to learn how Session Replay data collection works. ## Sending data ### Sending analytics data Analytics data are sent in batches of maximum 50 events. Requests are triggered when network conditions allow for the server to be reached and: * The current batch of events has reached 50 * Or the app is put in background ### Sending Session Replay Data See [Session Replay Requests](../session-replay/#requests) to learn more about how Session Replay data is sent. ### Sending crash Data See [Send Crash data](../error-analysis/#sending-crash-data) to learn more about how crash data is sent. ## Session definition A session is one continuous period of user interaction. It starts upon app launch and persists through state changes, including putting the app in the background or terminating and restarting it. As long as users interact at least once every 30 minutes, it remains the same session. ## Collected data points * The events are in JSON format, which lists the properties and their description in comment. * Events are sent to the server in batches. * A batch is a subset of events originating from one session. A session can send events in more than one batch. * The batch size is defined in a run configuration file specific to each app (50 events by default). ### Requests meta data Each batch has a common header, a set of device specific, and repeatable information and an array of events, which is immutable. The header is composed at the moment of sending, so it has to be constant info ONLY. The array in the payload is data stored at the moment of collection. The structure of the batches of events will have the following format: ```javascript { pid:8, // int - ProjectId - represented in the mobile config format uid:"ac1529a7-59f6-49d9-b254-6f0a22f57284", // String - uuid Unique user ID dt:4, // int - device type (loosely enforced enum - [sdk-phone : 4, sdk-tablet :5]) dma:"Samsung", // String - device manufacturer. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. dmo:"SG", // String - device model. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. os:"10.0", // String - os version (Android version name 8.0, 9.0, 10.0) l:"en_US", // String - Language in iso-639 format https://www.ibabbleon.com/iOS-Language-Codes-ISO-639.html tz:"Europe/Paris", // String - timezone https://en.wikipedia.org/wiki/List_of_tz_database_time_zones now:1522159618000, // long - timestamp when the batch was sent to:{ // object - type origin of the event an:"appname" // String - application name st:"sdk-android", // String - type of sdk sf:"release", // string - sdk flavor/variant [release/debug/god] }, r:{ // Device - resolution. w:1080, // int - width h:1920 // int - height d: 1.5 // The device density as float. Its values can vary between (0.75 and 10) }, pl:[] // JSON array payload - list of event objects, see below } ``` ### Events meta data All events have a common first part (don't confuse it with the header explained above). This common section is data which is common for all events by type but is gathered at the moment the event occurred. This common section is a part of the actual event payload. ```javascript { upt:1522, // long - system update in milliseconds euid:"euid", // String - event UUID url:"app-and://identifier/mainPath/secondaryPath?title=screeName", // String - screenName is passed in the title query Parameter scn:4, // int - the number of screens already shown in the session c:3, // int - connectivity type [-1 - offline, 0 - error, 1 - wifi, 2 - 2g, 3 - 3g, 4 - 4g] ci:"verizon", // String - carrier_id when user is on mobile network o:1, // int - orientation [0 = portrait, 1 = landscape] vo:{ // object - version origin of the event sv:"2.1", // string version of the sdk sb:4, // int - sdk build number av:"appVersion", // String - application version af:"appFlavor" // String - application string - [release/debug/god] ab:1 // int - application build number }, sn:1, // int - session id (positive int) t:12894726459435 // long - timestamp of the event (in milliseconds) } ``` All event specific properties are appended to this JSON object. ### App Start This event describes the absolute start of the app. The trigger for this event is the absolute start of the app. This is the first event sent when the SDK is invoked. ```javascript ea: 0; // int - event action - defined above ``` ### App Show This event is sent when the user brings the app in the foreground (switching from another app, exiting lock screen, etc.). This event means the app is focused. ```javascript ea: 1; // int - event action - defined above ``` ### App Hide This event is sent when the user exits (minimizes) the app, or switches to something else. This event means the app is not focused and the session might end, but we have not completely ended the session yet, as the user might return. ```javascript ea: 2; // int - event action - defined above ``` ### Screenview Everything starts with a View event. This is an event which describes the equivalent of a "page view" on the web. This event is sent when the Track Screen API is called. ```javascript ea:4 // int - event action - defined above st:"title", // String - screen title sl:34543 // int - (load time) screen load time (diff between last action and this event) ``` ### Tap Single Finger gesture event, when the user is interacting with a loaded screen. This is an event which describes the equivalent of a "click" in the web. This event is defined by the following sequence of touch events: * Touch Down -> N x Touch Move -> Touch Up ```javascript ea:6 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ur: true, // boolean - was this a "responsive" touch event (the target view had a handler) ``` ### Long press Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Duration: > 500ms * Distance: < 24 dp ```javascript ea:8 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ``` ### Drag (Slow Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity < 100 dp/s ```javascript ea:9 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance dragged tvv:100 // int - target view velocity while dragging dp/s ``` ### Flick (Fast Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity > 100 dp/s ```javascript ea:10 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view graph path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance scrolled tvv:100 // int - target view velocity while scrolling dp/s ``` ### Transaction To track transactions we provide a public API which can send a transaction object (see section [Track Transactions](../track-transactions/)). This object must contain the following parameters: ```javascript ea:16, // int - event action - defined above tr:{ // a json object with different properties defining the transaction made vl: 20.0, // mandatory - float - the value of the transaction cu: 978, // mandatory - int - the ISO 4217 code of the currency of the transaction id: "32akjkljklJ575775" // optional - string - an id for the transaction } ``` ### Dynamic variables To track dynamic variables we provide a public API (see section [Dynamic variables](../track-dynamic-variables/)). **Event with a string value** ```javascript ea:18, // int - event action - defined above k:"key", // String - Custom key assigned by client. v:"value" // String - Custom value assigned by client. ``` **Event with a number value** ```javascript ea:19, // int - event action - defined above k:"key", // String - Custom key assigned by client. v: 2344 // Integer - Custom value assigned by client. ``` ## Exposure Metrics In the Zoning Analysis module, Exposure Metrics provide information on the size of the display zone in the application, and data about content exposure in scrolling elements. ### Behavior for scrollable elements Exposure Metrics data for scrolling is only calculated on the first scrollable element on the screen. Other scrolling elements in the view hierarchy are not taken into account. This event is defined by the following content: ```javascript ea:23, // int - event action dx:10, // int - normalized x content offset dy:10, // int - normalized y content offset du: 5, // int - duration of the movement (in milliseconds) ``` #### Exclude `ScrollView`, `HorizontalScrollView`, `NestedScrollView`, or `RecyclerView` type object from Exposure Metrics To exclude a scrollable container from Exposure Metrics, use the `Contentsquare.excludeFromExposureMetric(View)` API. Call it from the `onCreate` method of the activity or the `onCreateView` method of the fragment. ```kotlin import com.contentsquare.CSQ public override fun onResume() { super.onResume() // ... val scrollView = findViewById<ScrollView>(R.id.scrollView) // or HorizontalScrollView, NestedScrollView, or RecyclerView CSQ.excludeFromExposureMetric(scrollView) } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Data Collection","description":"Understand how the Android SDK loads, tracks, and send data","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/data-collection/","inLanguage":"en","dateModified":"2026-05-11T08:01:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Error Analysis - Android description: Implement error tracking and crash reporting in your Android app with the CSQ SDK to identify and resolve issues affecting user experience lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/error-analysis/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/error-analysis/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. Error Analysis automatically captures API errors and network failures in your app and surfaces them in the Contentsquare platform. ## Prerequisites ### Screen tracking implemented Tracking will start at the 1st screenview event, it is required to have screen tracking implemented. Make sure to follow the [Android Track screens](../track-screens/) sections. ### Reminder about User consent If you are in the process of implementing the SDK for the 1st time (or choose to take this update as an opportunity to review your Privacy related implementation), make sure to follow the [Android Privacy](../privacy/) sections. ## API errors ### Automatic network inspection By using code instrumentation, network calls will be instrumented to collect network data. This way, two largely used network stacks are supported, and all the libraries that use them: * [OkHttp ↗](https://square.github.io/okhttp/), * [HttpURLConnection ↗](https://developer.android.com/reference/java/net/HttpURLConnection) #### Adding the Gradle plugin With the use of a Gradle plugin, an instrumentation of your code will be performed to collect the data about network errors. Add the Contentsquare Network Gradle plugin to the plugins block in both your root-level and app-level Gradle files: * Kotlin **build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.network") version "1.9.0" apply false } ``` **app/build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.network") } ``` * Groovy **build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.network" version "1.9.0" apply false } ``` **app/build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.network" } ``` #### Task added The plugin adds new tasks for network code instrumentation: `transformVariantClassesWithAsm` #### Configure Gradle plugin By default the plugin is enabled for each variant, there are three ways to disable the Gradle plugin: ##### Build type * Kotlin **build.gradle.kts** ```kotlin android { buildTypes { debug { configure<com.contentsquare.gradle.error.analysis.network.ErrorAnalysisNetworkExtension> { setInstrumentationEnabled(false) } } } } ``` * Groovy **build.gradle** ```groovy android { buildTypes { debug { errorAnalysisNetwork { setInstrumentationEnabled(false) } } } } ``` ##### By flavor * Kotlin **build.gradle.kts** ```kotlin android { flavorDimensions += "example" productFlavors { create("enable") { dimension = "example" } create("disable") { dimension = "example" configure<com.contentsquare.gradle.error.analysis.network.ErrorAnalysisNetworkExtension> { setInstrumentationEnabled(false) } } } } ``` * Groovy **build.gradle** ```groovy android { flavorDimensions "example" productFlavors { enable { dimension "example" } disable { dimension "example" errorAnalysisNetwork { setInstrumentationEnabled(false) } } } } ``` ##### With a Gradle properties **gradle.properties** ```properties errorAnalysisNetworkInstrumentationEnabled=false ``` Command line: ```shell ./gradlew :app:assembleDebug -PerrorAnalysisNetworkInstrumentationEnabled=false ``` ### Manual inspection Note Our recommendation is to use the Gradle plugin. #### OkHttp interceptor If your project is using OkHttp client, an interceptor (`CsqOkHttpInterceptor`) can be added to collect all the network errors: ```kotlin import com.contentsquare.api.contract.CsqOkHttpInterceptor OkHttpClient().newBuilder() .addInterceptor(CsqOkHttpInterceptor()) .build() ``` #### Custom implementation If no other solution works, the `CSQ.trackNetworkMetric()` API can be used to send custom Network Metric events. Multiple data will need to be gathered: **URL** and **method** at the creation of the metric, and **status code** after the request is done. To work properly, the `NetworkMetric` object must be created just before the request and `CSQ.trackNetworkMetric(metric)` must be called just after the request, to have the time metrics. ```kotlin import com.contentsquare.api.model.HttpMethod import com.contentsquare.api.model.NetworkMetric val metric = NetworkMetric(url, HttpMethod.GET) // execute your request... // fill the network metric with result metric.statusCode = statusCode metric.responseHeaders = responseHeaders // (optional) metric.responseBody = "Hi there !".toByteArray() // (optional) CSQ.trackNetworkMetric(metric) // will stop and send the metric ``` ### Removing Personal Data in request URL path By default, the API errors feature collects the URL path of the failed API requests. To prevent the collection of Personal Data in the URL path, you can rewrite the request URL path with the `CSQ.setUrlMaskingPatterns` SDK API. Replace a step of the path - meaning between two slashes (/) - containing Personal Data with a variable: * `:user_id` becomes CS\_ANONYMIZED\_USER\_ID * `:address` becomes CS\_ANONYMIZED\_ADDRESS #### Example ```kotlin CSQ.setUrlMaskingPatterns( listOf("https://www.contentsquare.com/users/:user_id/address/:address") ) ``` ##### Result | URL before masking | URL after masking | | - | - | | `https://www.contentsquare.com/users/123/address/castle+black` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS` | | `https://www.contentsquare.com/users/123/address/castle+black/reset-token/abcdef123456` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS/reset-token/abcdef123456` | ### Validate API error integration #### Validate API error collection is enabled If in-app features are enabled, an info log should appear when API Error collection has successfully been enabled (see [Android Debugging and Logging](../in-app-features/#debugging-and-logging) section).: ```plaintext CSLIB: Api Error collection is enabled ``` #### Validate API error collection If you have [logging enabled](../in-app-features/#debugging-and-logging), you will see API errors: * Displayed in [Contentsquare Log Visualizer](../in-app-features/#viewing-logs-in-the-contentsquare-platform). * As an Info log in Logcat: ```plaintext CSLIB: API Error - 401 GET https://api.client.com ``` ### How API errors works #### Initialization The way our SDK works is by auto-starting with the application launch and collects the API errors through the instrumented code added by the Gradle plugin. #### Configuration Once started, our SDK fetches its config from our servers. It will start collecting data from network events if the API errors setting is enabled in the config (this is handled by the Contentsquare team). #### API errors collection The SDK monitors only the API errors with response code equal or above 400, and generates analytics data. These events are then locally stored, and eventually sent to our servers in batches. Warning For API errors to be tracked and processed, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. #### Sending API errors data For each network error, a new event will be sent in analytics and Session Replay data. Check the following sections to learn more about how data is processed and sent: * [Analytics requests](../data-collection/#sending-data) * [Session Replay requests](../session-replay/#requests) ### API Troubleshooting Details API errors troubleshooting details enables you to collect more information about API errors so you can troubleshoot errors faster. With this feature you will be able to see three types of additional API error details in the Event Stream of Session Replay. * The HTTP headers of the request and the response. * The body (the data sent by the request or received in the response). * The query parameters of the request endpoint (of the URL of the information you request for). Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. See [API Troubleshooting Details ↗](https://support.contentsquare.com/hc/en-us/articles/37271885035537) for more details. ### Collected data points Only network calls in error (response code above 400) will be collected. Here the exhaustive list of data collected: * Response code * URL (without query strings) * HTTP method * Timestamp of the request * Timestamp of the response ### Known limitations and recommendations #### Conflict with Firebase Performance using code instrumentation Code instrumentation of requests made using HttpURLConnection does not work well with Firebase Performance plugin. Network events will not be logged when using Contentsquare Error Analysis network and Firebase performance plugin (only one of the two will log events). If you want to use both libraries, prefer using interceptors than code instrumentation. ## Crash Reporter ### Upload mapping file Android mapping files are generated during the process of obfuscating Android application code using tools like ProGuard. A mapping file for your app will be generated for all [obfuscated builds ↗](https://developer.android.com/build/shrink-code) at compile time. [Download the mapping file example](https://docs.contentsquare.com/ff-sample-mapping.txt) generated when building the [Contentsquare Android sample app ↗](https://github.com/ContentSquare/contentsquare-android-sample). To produce readable crash reports from builds that have been obfuscated, Contentsquare requires to upload the mapping file produced by your build to our servers. To simplify this process, we've provided a Gradle plugin that you can integrate into your build. It adds a distinct Gradle task that will be executed immediately after the build is done. This new task will be automatically triggered on assemble task for any minified build. #### Adding the Gradle plugin Add the Contentsquare Crash Gradle plugin to the plugins block in both your root-level and app-level Gradle files: * Kotlin **build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.crash") version "1.10.0" apply false } ``` **app/build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.crash") } ``` * Groovy **build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.crash" version "1.10.0" apply false } ``` **app/build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.crash" } ``` #### Configuring the Gradle Plugin To use the plugin, you must provide it with the relevant credentials to be able to upload the mapping file. ##### Get project ID 1. Login to the Contentsquare platform on [https://app.contentsquare.com ↗](https://app.contentsquare.com) 2. Make sure to be on the right project 3. The project ID can be found in the URL query parameter `project`: `https://app.contentsquare.com/#/{MODULE_NAME}?project={PROJECT_ID}&hash={HASH}` ##### Get project credentials Follow the dedicated documentation from the Help Center to get the **client ID** and **client Secret**: [How to create API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/9292880837660). ##### Use credentials You can do this by setting the `uploadCredentials` property of the errorAnalysisCrash extension in your app-level `build.gradle` or `build.gradle.kts` file, as shown below. The errorAnalysisCrash extension is available on all build types and product flavours. * Kotlin **build.gradle.kts** ```kotlin android { buildTypes { release { configure<ErrorAnalysisCrashExtension> { uploadCredentials { projectId = <your project Id> clientId = "<your client Id>" clientSecret = "<your client secret>" } } } } } ``` * Groovy **build.gradle** ```groovy android { buildTypes { release { errorAnalysisCrash { uploadCredentials { projectId = <you project Id> clientId = "<your client Id>" clientSecret = "<your client secret>" } } } } } ``` #### Disable Upload By default, the mapping file will be uploaded automatically. If you need to disable the upload, you can do it by adding a specific flag `mappingFileUploadEnabled` to the plugin configuration: * Kotlin **build.gradle.kts** ```kotlin android { buildTypes { release { configure<ErrorAnalysisCrashExtension> { mappingFileUploadEnabled = false uploadCredentials { ... } } } } } ``` * Groovy **build.gradle** ```groovy android { buildTypes { release { errorAnalysisCrash { mappingFileUploadEnabled = false uploadCredentials { ... } } } } } ``` It is also possible to disable the upload using the command line when the assemble task is triggered by using the flag `errorAnalysisCrashMappingFileUploadEnabled` as follow: ```plaintext ./gradlew app:assembleRelease -PerrorAnalysisCrashMappingFileUploadEnabled=false ``` Doing that, the upload task will be disabled and you will see the following log: ```plaintext [ErrorAnalysisCrashPlugin] uploadContentsquareMappingFileRelease disabled for release ``` #### ProGuard Configuration To ensure that we can provide line numbers and file names in the crash reports, add the following configuration to your ProGuard file: ```plaintext -keepattributes SourceFile,LineNumberTable # Keep file names and line numbers ``` #### Custom mapping file If you obfuscate your app with a tool other than R8/ProGuard, or need to control exactly which mapping file is uploaded, you can point the plugin at a specific file with `customMappingFile`. When set, it takes precedence over the auto-detected R8 mapping. * Kotlin **build.gradle.kts** ```kotlin android { buildTypes { release { configure<ErrorAnalysisCrashExtension> { customMappingFile = file("path/to/mapping.txt") uploadCredentials { ... } } } } } ``` * Groovy **build.gradle** ```groovy android { buildTypes { release { errorAnalysisCrash { customMappingFile = file("path/to/mapping.txt") uploadCredentials { ... } } } } } ``` #### DexGuard support The plugin is compatible with [DexGuard ↗](https://www.guardsquare.com/dexguard). It auto-detects DexGuard and uploads the **DexGuard** mapping instead of the R8 one. The mapping upload is wired as a finalizer of the DexGuard protect task, so running `./gradlew guardsquareProtectApk` (or `guardsquareProtectBundle` for app bundles) obfuscates the app and uploads the correct mapping automatically. ### Validate Crash reporter integration #### Validate crash collection is activated If in-app features are enabled, an info log should appear when the Crash reporter has successfully been initialized (see [Android Debugging and Logging](../in-app-features/#debugging-and-logging) section).: ```plaintext CSLIB: Crash reporter is enabled ``` #### Validate crash reporting To test that the Crash Reporter is working properly, you can force a crash in your application. The next time you start your application, the crash will be sent to our servers. If you have [logging enabled](../in-app-features/#debugging-and-logging), you will see the upload reflected in the log: ```plaintext CSLIB: Crash event detected and sent for userID: <user-id>, session: <session-number> on screen: <screen-number> crashID: <crash-id> ``` ### How Crash Reporter works #### Initialization Crash Reporter is started automatically and begins to report basic information for crashes in your application when it is launched. #### Configuration Once started, our SDK fetches its configuration from our servers. It will start reporting crashes if the Crash Reporter setting is enabled (this is handled by the Contentsquare team). #### Reporting When a crash occurs, a report is created and stored locally in the device. Once the app is launched again, the report is sent to our servers and then removed from the local storage. Warning For crashes to be reported and processed, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. #### Sending crash data For each crash, a new event will be sent to Analytics and Session Replay data when the app is launched again after the crash occurred and the network conditions allow for the server to be reached. ### Collected data points The Crash Reporter will capture any crashes caused by an unhandled exception in applications written in Java or Kotlin. It will collect information about the application, system, process, threads, stack traces and some other event metadata you can find in [collected data points](../data-collection/#collected-data-points) ### Known limitations and recommendations Native crashes from applications written using C or C++ are not supported. #### Compatibility with other crash reporters It is possible that the Crash Reporter will work with other SDKs, but we cannot guarantee it. Android has a global error handling class and therefore we rely on other SDKs forwarding the error on to us in the event of a crash, should they have been registered first. If the Contentsquare Crash Reporter is registered first, it will forward on errors to any other registered handlers. Based on our tests, we can confirm it is compatible with Firebase Crashlytics. ## WebView errors Errors occurring in web pages loaded in WebViews can be collected if Webview tracking is setup in your app. See 📚 [Webview Tracking implementation](https://docs.contentsquare.com/en/webview-tracking-tag/). Once WebView tracking is implemented, errors collection can be set up. See 📚 [Errors (in WebView)](https://docs.contentsquare.com/en/webview-tracking-tag/error-analysis/) ## Compatibility ### Dependencies list | Package | Name | Version | | - | - | - | | androidx.annotation | annotation | 1.5.0 | ## Impact on Performance We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. The following performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | Pixel 5 | | Android version | 13 | We used [Android Microbenchmark ↗](https://developer.android.com/topic/performance/benchmarking/microbenchmark-overview) to measure the time added by our implementation. Note The numbers provided below will vary depending on the user's device, Android version, SDK version. The instrumented code added is running in *less than 1ms* per request: our benchmarks show less 400µs. About CPU and memory, the overhead of adding the collection of network error is negligible. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Error Analysis","description":"Implement error tracking and crash reporting in your Android app with the CSQ SDK to identify and resolve issues affecting user experience","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/error-analysis/","inLanguage":"en","dateModified":"2026-08-03T10:30:43+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Google Tag Manager - Android description: Use our integration to send Google Tag Manager events to Contentsquare lastUpdated: 02 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/google-tag-manager/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/google-tag-manager/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. If you are using Firebase to track events such as screenviews or transactions, you can trigger these events for Contentsquare with minimal effort, thanks to Google Tag Manager. ## Prerequisites If you are following this Google Tag Manager integration process, you should already have followed the Google Tag Manager + Firebase setup as described in [Google's Tag Manager + Firebase: Getting Started ↗](https://developers.google.com/tag-manager/android/) You also need to [integrate the CSQ SDK](../#install-the-sdk). ## Screenview events This section covers how to trigger a Contentsquare screenview event for every Firebase screenview event. Firebase allows you to [log screenviews automatically or manually ↗](https://firebase.google.com/docs/analytics/screenviews) for an exhaustive coverage of your app screens. ### Variables Contentsquare screenview events require a `name` parameter. Firebase has 2 ways to track screens: #### 1. Variable for automatically tracked screens Firebase's `screen_view` events have an `_sc` parameter (for screen class) which we can use as parameter for screens that are **automatically tracked**. We will create a variable called **Auto Screenview** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `_sc`  #### 2. Variable for manually tracked screens Firebase's `screen_view` events have a `_sn` parameter (for screen name) which we can use as parameter for screens that are **manually tracked**. We will create a variable called **Manual Screenview** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `_sn`  We can also create variables for our own custom parameters, for example, we can send a `screen_view` event like this: ```kotlin firebaseAnalytics.logEvent(FirebaseAnalytics.Event.SCREEN_VIEW) { param(FirebaseAnalytics.Param.SCREEN_NAME, "MyScreenName") param("is_user_logged_in", "true") } ``` and create a variable called **Is User Logged In** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `is_user_logged_in` Check out [Configure variables in Tag Manager ↗](https://developers.google.com/tag-platform/tag-manager/android/v5#configure_variables_in_tag_manager) for more information. ### Screenview trigger We will need to tell Google Tag Manager when to send a Contentsquare screenview, and for that we need to create a **Trigger**. Firebase sends screenviews as events of name `screen_view`, so we need to create a trigger for that event. * Name your trigger `Screenview Trigger` * **Trigger Type** should be set to **Custom** * Trigger should fire on **Some Events** * For the Event, the **Event Name** should be **equal** to `screen_view`  ### Create the custom function Tag In Google Tag Manager, a **Tag** is what configures what happens when some trigger is activated. It will be automatically linked to a custom class which we will create in a later step. The **Tag Type** should be a **Function Call**. You will also need to fill in the **Class Path** field with a class name of your liking, typically related to what the tag is about (here we chose `com.myapp.ContentsquareScreenviewTag`), which you will re-use later.  ### Adding the trigger and the variables to the Tag Edit the `ContentsquareScreenviewTag` Tag: * Add an argument with the key `auto_screen_name` and the variable `{{Automatic Screenview Name}}` as the value * Add an argument with the key `manual_screen_name` and the variables `{{Manual Screenview Name | Is User Logged In}}` or `{{Manual Screenview Name}}` as the value * Add **Contentsquare Screenview Trigger** as the Tag's trigger It should look like this now:  ### Create the custom function Tag class In your app code, create a class of the same name as the `Class Path` you configured in the GTM interface, for example `ContentsquareScreenviewTag`. This is how GTM connects the configuration and the actual class to trigger. This class is used to call the Contentsquare screenview tracking function as follows: ```kotlin @Keep class ContentsquareScreenviewTag : com.google.android.gms.tagmanager.CustomTagProvider { override fun execute(map: MutableMap<String, Any>?) { val autoScreenName = map?.get("auto_screen_name") as String? val manualScreenName = map?.get("manual_screen_name") as String? if (autoScreenName != null) { CSQ.trackScreenview(autoScreenName) Log.w("GTM", "-------> $autoScreenName") } if (manualScreenName != null) { CSQ.trackScreenview(manualScreenName) Log.w("GTM", "-------> $manualScreenName") } } } ``` Now, every time Firebase sends a screenview event, Contentsquare will send one as well. ## Screenview events with Custom Variables Custom Variables Custom variables are additional information on the page, the user or the session, sent within screenviews. For more information about custom variables, see [Track Custom Variables](../track-custom-variables/). It is possible to send custom variables along with the screenview events. To do so: 1. Follow **Use Google Tag Manager** > [Screenview events](#screenview-events) 2. Add extra arguments to the `ContentsquareScreenviewTag` Tag as follows: * *Key:* the index of the custom variable * *Value:* a string that will contain the custom variable name and value such as `CVAR_NAME : {{Event Name}}` Note The value of the custom variable is composed of a name and a value: `NAME : VALUE` concatenated into a single string and separated by `:`. It should look like this:  For Custom Variables You are free to implement your own logic for filling key and value in GTM, but the application side must be able to receive and extract for each custom variable: 1. An index 2. A name 3. A value In the code of your application, edit the code of your class to handle the added custom variables: ```kotlin @Keep class ContentsquareScreenviewTag : com.google.android.gms.tagmanager.CustomTagProvider { override fun execute(map: Map<String, Any>) { val autoScreenName = map["auto_screen_name"] as String? val manualScreenName = map["manual_screen_name"] as String? val screenName = manualScreenName ?: autoScreenName ?: "No screen name!" val cvars = mutableListOf<CustomVar>() for ((tagKey, tagValue) in map) { val varIndex = tagKey.toIntOrNull() ?: continue val tagValueString = tagValue as? String ?: continue val splitTagValues = tagValueString.split(':') if (splitTagValues.size == 2) { val varName = splitTagValues[0].trim() val varValue = splitTagValues[1].trim() cvars.add(CustomVar(varIndex, varName, varValue)) } } CSQ.trackScreenview(screenName, cvars.toTypedArray()) Log.d("GTM", "-------> $screenName") } } ``` With this code, the custom variables will be sent by Contentsquare automatically along with the screenview. ## Transaction events A Contentsquare transaction event can also be triggered for every Firebase `purchase` event ([See Firebase documentation ↗](https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics.Event#public-static-final-string-purchase)). To do so, you will need to follow the setup described below. ### Variables We have to create at least two variables to be able to build a transaction event: Value and Currency. Optionally, it is also possible to pass a transaction identifier, meaning you would need to create an additional variable to be able to use it. #### Value (mandatory)  #### Currency (mandatory)  #### Transaction ID (optional)  ### Trigger Create the following custom trigger.  ### Tag Create a **Function call** Tag called `ContentsquareTransactionTag`.\ You will also need to fill in the **Class Path** field with a class path of your liking, typically related to what the tag is about (here we chose `com.myapp.ContentsquareTransactionTag`), which you will re-use later.\ Pass the two to three variables created earlier as arguments (skip the `id` line if you do not want to use it) and set its trigger to the one you just created.  ### Implementing the function call We need to create a `ContentsquareTransactionTag` class, and have it adhere to the `CustomTagProvider` interface to link it to the Google Tag Manager custom Tag of the same name. Take good to be able to create and send a Contentsquare Transaction successfully, when you create a Firebase purchase event you will **have to** at least pass values for `VALUE` and `CURRENCY`, and can optionally pass a value for `TRANSACTION_ID` [see Firebase reference docs ↗](https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics.Event#PURCHASE) ```kotlin @Keep class ContentsquareTransactionTag : com.google.android.gms.tagmanager.CustomTagProvider { override fun execute(map: MutableMap<String, Any>?) { val value = map?.get("value") as String? val currency = map?.get("currency") as String? if (value != null && currency != null) { val transactionBuilder = Transaction.builder(value.toFloat(), currency) val id = map?.get("id") as String? if (id != null) { transactionBuilder.id(id) } CSQ.send(transactionBuilder.build()) } } } ``` Now, every time Firebase sends an `ecommerce_purchase` event, Contentsquare will send one as well. ## Dynamic variable events We can send values from any Firebase event as a Contentsquare dynamic variable: ```kotlin firebaseAnalytics.logEvent("addToCart") { param("product_count", 12) param("product_name", "ProductA") } ``` ### Variables The `addToCart` event has parameters `product_count`, `product_name`, we will create variables called **Product Count** and **Product Name** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `product_count`/`product_name` Check out [Configure variables in Tag Manager ↗](https://developers.google.com/tag-platform/tag-manager/android/v5#configure_variables_in_tag_manager) for more information. ### Triggers We need to create a **Trigger** to tell Google Tag Manager when to send a Contentsquare dynamic variable, so we will create one for the event `addToCart`. * Name your trigger `AddToCartTrigger` * **Trigger Type** should be set to **Custom** * Trigger should fire on **Some Events** * For the Event, the **Event Name** should be **equal** to `addToCart` ### Create the custom function Tag We need to create a function tag **AddToCartDynamicVar** * The **Tag Type** set to **Function Call** * The **Class Name** set to **DynamicVarTag** (we'll create this class later) * Add two arguments * Key: `cs_dynamic_var_key`, Value: `Product` * Key: `cs_dynamic_var_value`, Value: `{{Product Name}}: {{Product Count}}` * The **Triggering** set to **AddToCartTrigger** It should look like this now:  ### Create the custom function Tag class In your app code, create a class of the same name as the `Class Name` you configured in the GTM interface, for example `DynamicVarTag`. This is how GTM connects the configuration and the actual class to trigger. This class is used to call the Contentsquare dynamic variable function as follows: ```kotlin @Keep class DynamicVarTag : com.google.android.gms.tagmanager.CustomTagProvider { override fun execute(parameters: MutableMap<String, Any>) { val dynamicVarKey = parameters["cs_dynamic_var_key"] as? String ?: return when (val dynamicVarValue = parameters["cs_dynamic_var_value"]) { is String -> CSQ.addDynamicVar(dynamicVarKey, dynamicVarValue) is Long -> CSQ.addDynamicVar(dynamicVarKey, dynamicVarValue) } } } ``` Now, every time Firebase sends an `addToCart` event, Contentsquare will send a dynamic variable `key: "Product", value: "ProductA: 12"`. Note To create another tag for a dynamic variable, you can use the `DynamicVarTag` class again. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Google Tag Manager","description":"Use our integration to send Google Tag Manager events to Contentsquare","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/google-tag-manager/","inLanguage":"en","dateModified":"2026-06-02T10:48:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Impact on performance - Android description: Metrics to evaluate the impact on performance of the SDK on your apps lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/impact-on-performance/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/impact-on-performance/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The CSQ SDK strives to be non-intrusive and transparent to client app developers. The following are the technical specifics we can share on performance. ## Performance impact The performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | Pixel 5 | | Android version | 34 (Android 14) | Note The numbers provided below will vary depending on the user's device and Android version. | Property | Value | | - | - | | SDK size | \~4.0Mb | | Nbr. of methods | 4834 | | Nbr. of fields | 3199 | | RAM usage | <4 MB | | SDK CPU peak on event | <15 % | | Data transmitted over network for a default batch size of 50 events. The size of the batch can be customized if needed. | \~25kb | ## Performance test procedure | CPU Usage Test | RAM Usage Test | Memory Leak Test | | - | - | - | | We are profiling our Demo app with and without the SDK dependency by following the same use case. | We are profiling our Demo app with and without the SDK dependency by following the same use case. | We are profiling our demo app and we are using the ADB Monkey tool to create random user input events | | We are measuring the CPU peak for both versions of the app and we are computing the difference | We are measuring the RAM usage peak for both versions of the app and we are computing the difference | During this time we are monitoring the RAM behavior for any anomaly. We are using the Memory Profiler to track/fix the issue | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Impact on performance","description":"Metrics to evaluate the impact on performance of the SDK on your apps","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/impact-on-performance/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: In-app features - Android description: Enable testing and debugging capabilities within your Android app using in-app features for enhanced development workflow lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/in-app-features/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/in-app-features/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Alongside its tracking capabilities, the SDK embeds some features aimed at Contentsquare users such as [Screenshot Capture](#screenshot-capture) and [SDK Logs](#debugging-and-logging). ## Enable in-app features To enable in-app features within your app, you have to **first make sure your app is launched in the background**. To do so, start it and press the Android home button. Then, follow the appropriate method described as follows. If access is blocked by the Android OS, you may need to allow the restricted settings first. To do this, go to your device settings, navigate to **Apps**, tap on your app, open the **More** menu (three dots), and then tap on **Allow restricted settings**. ### On a device: scan the QR code If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code with your phone.  Note On Android, some devices have a built-in QR code reader feature in the default camera app. If that is not the case for you, use [QR & Barcode Reader by TeaCapps ↗](https://play.google.com/store/apps/details?id=com.teacapps.barcodescanner\&hl=en\&gl=US). ### On an emulator: use the ADB command If you are using an emulator, you can use the ADB command to enable in-app features. If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and select "Copy this ADB command".  It will look like this: ```shell adb shell am start -W -a android.intent.action.VIEW -d "cs-{{packageName}}://contentsquare.com?activationKey={{uniqueActivationKey}}\&userId={{userId}}" ``` If you don't have access to the Contentsquare platform, you can ask the Contentsquare team to share the link with you. ## Debugging and Logging Contentsquare provides Logging capabilities that allow you to see the raw event data logged by your app in Android Studio or in the Contentsquare platform. Check logs for validation purposes during the instrumentation phase of development and can help you discover errors and mistakes in your analytics implementation and confirm that all events are being logged correctly. ### Viewing logs in Android Studio By default, almost all logs are disabled. There is only one log that is always visible to notify that the SDK has started: ```text CSLIB: Contentsquare SDK 1.12.1 starting in app: your.application.package ``` To enable all logs, activate [in-app features](#enable-in-app-features). Logging is directly linked to in-app features state: it starts when in-app features is enabled and stops when you disable in-app features. To view logs: 1. Plug your Android Phone to your Computer (or use emulator) 2. Start the Android Studio app 3. Open the Logcat view and select your phone or emulator 4. Filter logs on `CSLIB`  ### Viewing logs in the Contentsquare platform To view logs directly on the platform, you can use Log visualizer. Log visualizer is a helper tool to see SDK logs without logging tools. It requires having platform access for your project and enabling in-app features. See the [SDK Log Visualizer Help Center Article ↗](https://support.contentsquare.com/hc/en-us/articles/37271699876625) for more information. ## Screenshot capture To unlock the full data-visualization capabilities of Contentsquare, the SDK provides a way to capture screenshots of your app screens. These screenshots can only be taken by Contentsquare's users on their device. They are not captured from your end-users device. It means your Personal Data is safe, as long as you use a test user account. Warning For screenshot capture to work, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. Note The screenshot capture is only supported from Android API 26 (Android Oreo). Note To maintain accurate statistics in the Zoning Analysis module, the SDK prevents R8/ProGuard from obfuscating the names of all [View ↗](https://developer.android.com/reference/android/view/View) subclasses. However, class methods and fields can still undergo obfuscation and optimization.  Screenshots are used in the **Zoning Analysis** module to look at zone-level metrics (Tap rate, Swipe rate...):  ### Jetpack Compose support To enable Jetpack Compose support for Zoning, it is necessary to add a new Gradle dependency to your Gradle build file. Make sure to follow the [Track screens](../track-screens/#jetpack-compose-support) section. ### Invisible overlays covering other elements of a Compose screen Invisible overlays are transparent information overlays that do not display any information most of the time. These overlays may lead to issues in the Zoning editor. The screen elements covered by the overlay will display 0 taps. On the Contentsquare SDK side, the gesture recognition assigns the taps to the overlay, that is the target view path (TVP) of the tap differs from the TVP of the covered element in the Zoning editor. To avoid this issue, you may change the layout of the screen so that the overlay is no longer present. Alternatively, wrap the overlay with the `CsqIgnoreInteraction()` composable. ```kotlin /** * A composable function that conditionally ignores user interactions or gestures on Compose UI content. */ @Composable fun CsqIgnoreInteraction(ignore: Boolean, block: @Composable () -> Unit) ``` The wrapped Composable and all of its children will be excluded from gesture recognition, so no gestures will be assigned to this part of the Composable hierarchy. Additionally, this Composable subtree will not be included in the screenshot generated by the SDK and will therefore not appear in the Zoning editor. For example: ```kotlin @Composable private fun InfoOverlay() { CsqIgnoreInteraction(ignore = true) { Box(modifier = Modifier.fillMaxSize()) { // some content that is displayed occasionally } } } ``` ### Lists with Slowly Rendering Items When creating a Long Screenshot of a RecyclerView or a lazy Compose list, the contents of the list are scrolled automatically. If individual elements of the list are missing in the resulting screenshot, that is they are invisible, this may be because the elements take too long to render. In such a case, automatic scrolling can be delayed. You must have enabled in-app features: 1. Long press on the screenshot button to open the Contentsquare settings. 2. Move the slider to set the delay for scrolling. The value is displayed in milliseconds. 3. Tap on the arrow back to close the Contentsquare settings. You can now repeat the screenshot and then check it in the zoning editor.  ## Known limitations ### Screenshot capture * The screenshot capture is only supported from Android API 26 (Android Oreo). * The combination of `CoordinatorLayout`, `AppBarLayout`, and `RecyclerView` is not supported. * `ConcatAdapter` is not supported. * Lists with different item layouts are not supported. * Two or more scrollable containers are not supported. Furthermore, horizontal scrollable containers are not supported. * Screenshots of screens in edge-to-edge / fullscreen mode may contain visual artifacts in Zoning Analysis module, for example from the status and navigation button bar. Although some zoning elements will be visually altered by system bars, creating zones and displaying statistics will still work correctly. * Taps and other gestures are assigned to UI elements so the Zoning editor can display metrics. The SDK favors clickable elements. For instance, a tap on a button that is part of an overlay is assigned to the button. A tap on a non-clickable element results in the assignment of a background element. * Some lifecycle events are not handled, for example app in background, device rotation, fragment change. * Dark mode is not supported. ### Additional limitations for Compose Screens * The screenshot for Jetpack Compose is not fully supported yet. This also applies to the combination of Compose and WebViews. * The visual information may not be consistent for screenshots of Jetpack Compose screens. This applies in particular to transparency and visibility. * Scrollable elements with spacings and paddings may not yet be fully supported. While all elements can be selected as zones in the Zoning editor and statistics will be accurate, visual presentation might be affected by artifacts. * Screens containing transparent overlays are not supported in the Zoning module. Any transparent Composables covering the main content of the screen need to be fully removed when unused. * Android views embedded within scrollable Compose containers are not fully supported. These views can be selected as zones in the Zoning editor, and the statistics will be accurate. However, they will not scroll properly with the rest of the content. * Sometimes, `LazyColumn` items may contain more than one direct composable, or no composables at all. This can result in an error during screenshot creation or an invalid screenshot in the Zoning editor. To avoid this, wrap the `LazyColumn` items with an additional Column wrapper, like this: ```kotlin LazyColumn(modifier = Modifier.fillMaxSize()) { items(20) { itemIndex -> // Wrapping every item with additional Column avoids issues if some // items have multiple direct composables, or no composables at all. Column { when (itemIndex % 3) { 0 -> { // Item with 1 direct composable (Row). Row { Text(text = "Sample") } } 1 -> { // Item with multiple direct composables (Text, Row). Text(text = "Sample") Row { Text(text = "Sample") } } // No else statement: some items will have no composables at all. } } } } ``` * Material `ModalBottomSheetLayout` contains an internal `Scrim` composable that may prevent the SDK from tracking content wrapped by `ModalBottomSheetLayout`. Explicit tagging of `ModalBottomSheetLayout` using the `CsqTag()` API is required for Zoning and Heatmaps to work correctly. For example: ```kotlin CsqTag(CsqTag.ModalBottomSheetLayout) { ModalBottomSheetLayout(..) { .. } } ``` * When modifying the semantics of a clickable element, the order of the modifiers is important. For example, when clearing the semantics with the `clearAndSetSemantics` modifier, the clickable modifier should be placed before the `clearAndSetSemantics` modifier. ```kotlin Column( modifier = modifier .clickable(..) .clearAndSetSemantics { contentDescription = .. } ) ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"In-app features","description":"Enable testing and debugging capabilities within your Android app using in-app features for enhanced development workflow","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/in-app-features/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Security - Android description: Data transfer and security information lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/security/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/security/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Android SDK requires specific permissions to function and follows Android security guidelines for deep link handling. ## App permissions The SDK includes the following permissions, which are mandatory for the SDK to operate properly: **AndroidManifest.xml** ```xml <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.READ_BASIC_PHONE_STATE" /> <uses-permission-sdk-23 android:name="android.permission.SYSTEM_ALERT_WINDOW" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> ``` | Permission | Required to | Associated with read/write operations under e-privacy directive | | - | - | - | | `android.permission.INTERNET` | Send collected data to Contentsquare servers | Yes. The end-user's data is collected for analytics purposes. | | `android.permission.READ_BASIC_PHONE_STATE` | Retrieve non-sensitive device information such as carrier name for analytics purposes | Yes. The end-user's data is collected for analytics purposes. | | `android.permission.SYSTEM_ALERT_WINDOW` | Use Contentsquare in-app features | No. This permission is solely used to display Contentsquare UI elements in our customers' apps. | | `android.permission.ACCESS_NETWORK_STATE` | Check network availability before sending data | No. This permission is solely used to check the network status check. | Note Some of these permissions involve read and write operations within the meaning of the e-privacy directive and article 82 of the French Data Protection Act, which may require the end-user's specific consent as specified above. This requirement applies in particular to customers based in the EU or targeting end-users in the EU. For more information on how to combine technical permission and legal consent, refer to the [CNIL (French data protection authority) recommendations ↗](https://www.cnil.fr/fr/permissions-applications-mobiles-recommandations-de-la-cnil-pour-respecter-la-vie-privee). ## Deep links usage in Contentsquare SDK As outlined in the [Android Security Guidelines ↗](https://developer.android.com/privacy-and-security/risks/unsafe-use-of-deeplinks), there are security risks associated with using deep links. To address these concerns, the Contentsquare SDK implements robust data validation for deep links and safeguards to prevent deep link hijacking, following these guidelines. If you have specific security concerns and prefer to remove the Contentsquare SDK deep link declaration from your application, add the following code snippet to your `AndroidManifest.xml` file inside the `<application>` tag: ```xml <application> <activity android:name="com.contentsquare.android.analytics.internal.features.deeplink.DeepLinkActivity" tools:node="remove" /> </application> ``` Removing the deep link will disable the In-app feature within your application. ## Transmission and hosting Our server uses HTTPS to make sure that data is encrypted in transport. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Security","description":"Data transfer and security information","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/security/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Session Replay - Android description: Learn how to integrate and configure Session Replay capabilities in your Android app with the CSQ SDK lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/session-replay/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/session-replay/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Session Replay enables replaying real sessions to observe how users interact with your product, by capturing screen content - including text and images - as users navigate your mobile app. For more details, see [Introduction to Session Replay for Apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) in the Help Center. ## Starter guide ### Prerequisites #### Update to latest SDK version To enable Session Replay in your app and get the most stable version, it is required to [upgrade the SDK](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/#install-the-sdk) to its latest version. #### Implement screen tracking Ensure screen tracking is implemented, since Session Replay collection starts at the first screenview event. See [Track screens](../track-screens/). #### Handle User consent Ensure user consent is handled for Contentsquare data collection, especially if you're implementing the SDK for the first time. See [Privacy](../privacy/) section. #### Add Gradle dependency for Jetpack Compose To enable Jetpack Compose support in Session Replay, it is necessary to add a new Gradle dependency to your Gradle build file. Make sure to follow the [Track screens](../track-screens/#jetpack-compose-support) section. * Kotlin **build.gradle.kts** ```kotlin implementation("com.contentsquare.android:sdk-compose:1.12.1") ``` * Groovy **build.gradle** ```groovy implementation "com.contentsquare.android:sdk-compose:1.12.1" ``` Note Mandatory data collection settings are configured by Contentsquare in your project parameters. [Learn more about Data collection configurations ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) on the Help Center. ### Configure Session Replay masking #### Masking behavior By default, the Contentsquare SDK is configured to mask all content displayed on the user interface (UI) to prevent unnecessary data collection. For more details, see what a fully masked screen looks like in [Masking mechanisms](#masking-mechanisms). **For testing purposes**, use this setup: * Either unmasking all the content by setting the [default masking](#default-masking) status to false. * Or unmasking most content with the [Text and Image unmasking configuration ↗](https://support.contentsquare.com/hc/en-us/articles/37271682878353-Data-masking-in-Session-Replay-Mobile-Apps) in your Console parameters. **For more granular control in deployment mode**, you can use the [Text and Image unmasking configuration ↗](https://support.contentsquare.com/hc/en-us/articles/17800059306396-Data-masking-in-Session-Replay-Mobile-Apps) in your Console parameters in combination with [SDK public masking APIs](#public-masking-apis) to fine-tune exactly which elements remain masked. Warning Always keep sensitive data masked to ensure compliance with privacy regulations and to protect users' personal data. ### Configure Event-Triggered Replays (optional) If Event-Triggered Replays is included in your contract, you can set up ETR events to enable specific screen and session collection in Session Replay. See [Event-Triggered Replays (ETR)](#event-triggered-replays-etr). ### Configure Webviews (optional) If your mobile app includes Webviews, specific implementation steps are required to ensure they are properly reflected in Session Replay: * Implement [Webview tracking](https://docs.contentsquare.com/en/webview-tracking-tag/) * Handle [personal data within WebViews](https://docs.contentsquare.com/en/webview-tracking-tag/session-replay/#personal-data-handling) ### Test your setup #### Enable Session Replay on your device If the Session Replay sampling rate is less than 100%, only a portion of sessions are collected. To ensure data collection on your device for testing and debugging purposes, you can force it from the In-app Features settings by following these steps: 1. [Enable In-app Features](../in-app-features/#enable-in-app-features) 2. Open In-app Features settings with a long press on the screenshot button 3. Under "Session Replay", toggle "Enable Session Replay" on 4. Kill the app 5. Start app, a new session is starting with Session Replay enabled A restart is required Toggling **Enable Session Replay** does **not** start collecting for the current session. The host app must be fully killed and relaunched. If you skip the restart, the SDK will start collecting mid-session but the resulting replay will contain unplayable screens.  #### How do I know if Session Replay is enabled? There are 2 places where you can check if Session Replay is enabled: **In the logs:** The log `CSLIB|SessionReplay: Session Replay is starting.` will confirm that Session Replay is enabled. **In in-app features settings:** Below the "Enable Session Replay" *(see below [Access the replay](#access-the-replay))*, you will either see: * `No replay link available`, which means Session Replay is not running for the current session * `Get Replay link`, which means Session Replay is running for the current session #### Access the Replay The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay your session up to the previous screenview if the session is still running. The Session can be accessed by tapping on `Get replay link` button from the in-app features settings:  ## Define when Session Replay starts Session Replay starts automatically by default, but if you need to ensure that Session Replay data is collected only under certain conditions — for example, only after receiving explicit user consent for Session Replay or in specific geolocations — follow instructions described below. ### Disable Automatic Session Replay Initialization Set the option `sessionReplayAutoStart` to `false` when starting the SDK to prevent Session Replay from starting automatically at app launch. ```kotlin CSQ.start( context = context, startConfig = StartConfig.dxa(AnalyticsOptions( sessionReplayAutoStart = false )), ) ``` ### Start Session Replay Once your app has determined that Session Replay can start — for example, via a reverse geocoding service or after receiving specific user consent for Session Replay — you can call `CSQ.startSessionReplay()` to start Session Replay. Note Calling `startSessionReplay()` does not force Session Replay data collection. It enables the Session Replay module, allowing it to begin checking whether the global Replay sampling rate or Event Triggered Replay conditions are met. Session Replay data collection will only start if these conditions are satisfied. For more information, see [Data collection for Session Replay (Apps) ↗](https://support.contentsquare.com/hc/en-us/articles/37271951720721) on the Help Center. ### Stop Session Replay If you need to stop Session Replay immediately, you can call `CSQ.stopSessionReplay()`. Note A Session Replay stopped with `stopSessionReplay()` cannot be restarted until next app launch. ## Personal Data Masking The Session Replay feature replays every interaction of your users with your app. To respect the user's right to privacy, the Contentsquare SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our [Masking rules](#masking-rules) Warning If you decide to unmask elements leading to the collection of new data or use already collected data but for a different purpose, it is up to you to update your Google Play Data Safety declaration accordingly. Here are some common examples of data collected via unmasked Session Replay: Search history, Purchase history, Advertising data, and so on. See [Types of data and purpose](../privacy/). Contentsquare is not intended nor designed to collect sensitive personal data (such as health, financial, or racial data). It is the customer's responsibility not to send any sensitive personal data to Contentsquare. ### Masking mechanisms Every single UI element is converted into a highly pixelated image to reach a very low resolution. Text and images will appear very blurry so that the content cannot be identified. #### Original vs Replay fully masked  ### Masking rules Masking rules can be applied in two ways: 1. **Through remote masking configuration in the CSQ Console (for admin users):** These configurations are managed directly in the Console and take effect for all sessions as soon as the app is restarted or brought to the foreground See [How to customize masking rules from the Data Masking tab ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) in the Help Center. 2. **Using public masking APIs in the SDK (for mobile application developers):** These configurations require developer implementation and will be applied only after the mobile app has gone through its release cycle. Masking rules set via the CSQ Console or the public APIs are applied according to different priorities, as described below. The SDK determines whether a view is masked by evaluating the rules in the order specified below. Once a rule is triggered, the state is set, and subsequent rules are not applied: #### General case | Rule | Configured via | | - | - | | 1. The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text or Image masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. An [instance](#maskingun-masking-by-instance) is specifically masked or unmasked | API | | 4. A [type](#maskingun-masking-by-type) is masked or unmasked | API | | 5. A [parent](#masking-and-unmasking-behaviors-on-a-parent-view) is specifically masked or unmasked | API | | 6. A parent [type](#maskingun-masking-by-type) is masked or unmasked | API | | 7. Remote Text or Image unmasking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 8. Otherwise the [default masking state](#default-masking) is applied | API | #### Exception: Text input fields Special consideration is needed for text inputs, as the risk of leaking personal data is higher with these elements. As a result, the SDK applies slightly different rules to `EditText` and Jetpack Compose `TextField`: | Rule | Configured via | | - | - | | 1. The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text input masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. An `EditText` [instance](#maskingun-masking-by-instance) is specifically unmasked | API | | 4. The `EditText` [type](#maskingun-masking-by-type) is unmasked | API | | 5. Otherwise a text input field remains masked | default | Specifically, default masking and parent masking won't change the masking state of text inputs. ### Public masking APIs #### Default masking Warning You should not perform any call to Contentsquare APIs before the first visible Activity to be sure the SDK is initialized. If you perform a call too soon, it will be discarded and you will see the following log: ```plaintext CSLIB Contentsquare SDK: Unable to call the public API, make sure you are not opted out of the Contentsquare tracker and SDK was correctly initialized. ``` All Android View elements, their subclasses, and Jetpack Compose components are fully masked by default. Change the default masking state with: ```kotlin /** * Sets the default masking state for the Contentsquare's Session Replay features. * * @param masked A boolean value indicating whether masking should be enabled (true) or disabled (false). */ @JvmStatic fun setDefaultMasking(masked: Boolean) ``` Note Setting the default masking state to `false` does not affect `EditText` or `TextField` (Jetpack Compose). #### Masking/Un-masking by instance Warning Animations are not supported when masking by instance. * Views Use `mask(view: View)` and `unmask(view: View)` methods to mask or unmask a specific view instance. ```kotlin /** * Masks the contents of a specific view. * * @param view an instance of [View] to mask. */ @JvmStatic fun mask(view: View) ``` ```kotlin /** * Unmasks the contents of a specific view. * * @param view an instance of [View] to unmask. */ @JvmStatic fun unmask(view: View) ``` Alternatively, you can also apply the masking rule to a specific view instance directly with `View.csqMaskContents(enable: Boolean)` extension function. ```kotlin /** * [View] extension function to mask the contents of a view. * This extension function can be used as alternative to [CSQ.mask] and [CSQ.unmask]. * * @param enable A boolean value indicating whether masking should be enabled (true) or disabled (false) for this view. */ fun View.csqMaskContents(enable: Boolean) ``` Following the previous example, we have the views hierarchy in which all instances of TextView type are unmasked with the default masking state of all the views are masked by default.  In this example, if you want to mask a specific text view TextView1, call `mask(textView1)`. The view instance rule overrides the type rule and the default rule. * Jetpack Compose Use the `CsqMask(enable: Boolean, block: @Composable () -> Unit)` composable function to mask or unmask a composable. ```kotlin /** * A composable function that applies masking to Compose UI content. * * @param enable A boolean value indicating whether masking should be enabled (true) or disabled (false). * @param block A composable lambda function representing the content to apply masking condition. */ @Composable fun CsqMask(enable: Boolean, block: @Composable () -> Unit) ``` For example: ```kotlin CsqMask(true) { Text( text = "Text" ) } ``` #### Masking/Un-masking by type Although the SDK allows masking elements by type for convenience but it isn't the recommended masking mechanism because it impacts all screens of your application. Use this when you have a specific class for presenting user information or for displaying the user profile picture to make sure it always stays masked, for instance. Warning Animations are not supported when masking by type. * Views Use `mask(type: Class<*>)` and `unmask(type: Class<*>)` methods to mask or unmask a specific type. ```kotlin /** * Masks the contents of the view for all instances of a specific [Class] and subclass of a [View]. * This will be applied only for Session Replay feature. * * @param type a [Class] object representing the type to be masked. */ @JvmStatic fun mask(type: Class<*>) ``` ```kotlin /** * Unmasks the contents of the view for all instances of a specific [Class] and subclass of a [View] for * Session Replay feature. * * @param type a [Class] object representing the type to be unmasked. */ @JvmStatic fun unmask(type: Class<*>) ``` For example, given the views hierarchy:  The default masking state of all the views is masked and, for example, to unmask all **TextView** types, you can call `unmask(TextView.class)` then all instances of **TextView** type will be unmasked. In this example, the button is also impacted by the `unmask()` call because the button is also a **TextView** type (a subclass of **TextView**). The **EditText** is also a **TextView** type but isn't impacted by `unmask(TextView.class)` call because the **EditText** type is [masked by default](#masking-rules). * Jetpack Compose It is not possible to mask or unmask composables by type. Alternatively, you can mask or unmask a group of composables by wrapping multiple composables within the same parent, then applying the `CsqMask(enable: Boolean, block: @Composable () -> Unit)` on the parent. #### Masking and Unmasking behaviors on a parent view * Views You can mask ViewGroups (and subclasses such as RelativeLayout, LinearLayout, ConstraintLayout, and so on). When a parent view is masked all of its children inherit the masking state. The children's view masking state can be overridden by using a specific API to mask or unmask by instance or by type.  For example, given the view hierarchy with the default masking state. All the views are masked by default in the initial state and in this case, you may want to unmask all children's views of the parent view **LinearLayout1**, you can call `unmask(linearLayout1)` then all children views of the parent view **LinearLayout1** will be unmasked. As noticed here the **EditText** is not impacted from the parent call because the **EditText** type is [masked by default](#masking-rules). * Jetpack Compose You can mask a parent layout (such as `Column`, `Row`, or `Box`). If a parent composable is masked, then all of its children inherit the masking state from the parent. The children's masking state can be overridden by using the dedicated `CsqMask(enable: Boolean, block: @Composable () -> Unit)` function: ```kotlin CsqMask(true) { Column { Row { CsqMask(false) { // unmask this `Text` composable Text( text = "Text", ) } } Row { Text( // this `Text` composable will be masked, as it inherits the masking state from the parent text = "Text 2", ) } } } ``` #### Masking and Unmasking of Bottom Sheets, Dialogs, and Menus Contentsquare Android SDK 4.39.0 and earlier If you were using Contentsquare Android SDK versions before 4.39.0 in your mobile app, then masking is automatically enforced on all bottom sheets, dialogs, and menus, as these elements were not supported in earlier versions. To unmask any of these elements, contact your CSM to disable the forced masking and use the APIs described below. **Bottom Sheets** Bottom sheets can be masked or unmasked using the same APIs available for any other view, whether you're working with Android Views or Jetpack Compose. To apply the masking behavior, ensure that you call the appropriate API after the bottom sheet has been created. **AlertDialogs** * Views Dialogs, such as AlertDialog, TimePickerDialog, and DatePickerDialog, can be masked or unmasked using the APIs provided below. In addition, the masking behavior of individual components within these dialogs can be customized using the provided Kotlin extension functions. For instance, if an AlertDialog is fully masked by default, you can selectively unmask specific elements—such as the title or action buttons—using the extension functions provided below for more granular control. For example, given an AlertDialog with the default masking state, all views in the dialog are masked by default in the initial state. In this case, you may want to unmask the title and buttons of the dialog. To do that, we provide Kotlin extension functions to the Dialog API to make it easy. ```kotlin /** * Masks the entire [AlertDialog]. */ fun AlertDialog.csqMask() /** * Masks the title of the [AlertDialog]. */ fun AlertDialog.csqMaskTitle() /** * Masks the message of the [AlertDialog]. */ fun AlertDialog.csqMaskMessage() /** * Masks the positive button of the [AlertDialog]. */ fun AlertDialog.csqMaskPositiveButton() /** * Masks the negative button of the [AlertDialog]. */ fun AlertDialog.csqMaskNegativeButton() /** * Unmasks the entire [AlertDialog]. */ fun AlertDialog.csqUnMask() /** * Unmasks the title of the [AlertDialog]. */ fun AlertDialog.csqUnMaskTitle() /** * Unmasks the message of the [AlertDialog]. */ fun AlertDialog.csqUnMaskMessage() /** * Unmasks the positive button of the [AlertDialog]. */ fun AlertDialog.csqUnMaskPositiveButton() /** * Unmasks the negative button of the [AlertDialog]. */ fun AlertDialog.csqUnMaskNegativeButton() ``` Note The mask API for dialogs should be called immediately after the `show` method in the main thread. Example: ```kotlin val builder: AlertDialog.Builder = AlertDialog.Builder(context) builder.setMessage("This is a dialog. This text should be masked") builder.setTitle("Dialog Title") builder.setCancelable(true) builder.setPositiveButton("Close") { ... } builder.setNegativeButton("Idle") { ... } val alertDialog: AlertDialog = builder.create() alertDialog.show() alertDialog.csqUnMaskTitle() alertDialog.csqUnMaskPositiveButton() alertDialog.csqUnMaskNegativeButton() ``` * Jetpack Compose The AlertDialog composable in Jetpack Compose can be masked or unmasked using the same APIs applied to other composables. Simply use the appropriate `CsqMask` composables function on the elements you want to mask or unmask within the dialog. Example: ```kotlin AlertDialog( icon = { Icon(icon, contentDescription = "Example Icon") }, title = { Text(text = dialogTitle) }, text = { // Mask the dialog text CsqMask(true) { Text( text = dialogText ) } }, onDismissRequest = { onDismissRequest() }, confirmButton = { TextButton( onClick = { onConfirmation() } ) { // Unmask the dialog confirm button CsqMask(false) { Text( "Confirm" ) } } } ) ``` **TimePickerDialog and DatePickerDialog** * Views Time and date pickers function similarly to AlertDialogs but contain their own distinct UI components. These sections can be selectively masked or unmasked using the APIs provided below. To support masking on this dialogs we added the following APIs: ```kotlin /** * Masks the entire [DatePickerDialog]. */ fun DatePickerDialog.csqMask() /** * Masks the header of the DatePicker, which typically displays the selected date. * This affects the [DatePickerDialog]. */ fun DatePickerDialog.csqMaskHeader() /** * Masks the calendar view (day picker) of the [DatePickerDialog]. */ fun DatePickerDialog.csqMaskCalendar() /** * Masks the button panel of the [DatePickerDialog], typically containing "OK" and "Cancel" buttons. */ fun DatePickerDialog.csqMaskButtonPanel() /** * Unmasks the entire [DatePickerDialog]. */ fun DatePickerDialog.csqUnMask() /** * Unmasks the header of the DatePicker. * This affects the [DatePickerDialog]. */ fun DatePickerDialog.csqUnMaskHeader() /** * Unmasks the calendar view (day picker) of the DatePicker. * This affects the [DatePickerDialog]. */ fun DatePickerDialog.csqUnMaskCalendar() /** * Unmasks the button panel of the [DatePickerDialog]. */ fun DatePickerDialog.csqUnMaskButtonPanel() /** * Masks the entire TimePicker view within the [TimePickerDialog]. */ fun TimePickerDialog.csqMask() /** * Masks the header of the TimePicker, including the time display and input mode header. * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqMaskHeader() /** * Masks the radial picker (clock face) of the TimePicker. * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqMaskRadialPicker() /** * Masks the input mode view of the TimePicker (keyboard input for time). * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqMaskInputMode() /** * Masks the button panel of the [TimePickerDialog], including positive, negative, and toggle mode buttons. */ fun TimePickerDialog.csqMaskButtonPanel() /** * Unmasks the entire TimePicker view within the [TimePickerDialog]. */ fun TimePickerDialog.csqUnMask() /** * Unmasks the header of the TimePicker, including the time display and input mode header. * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqUnMaskHeader() /** * Unmasks the radial picker (clock face) of the TimePicker. * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqUnMaskRadialPicker() /** * Unmasks the input mode view of the TimePicker (keyboard input for time). * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqUnMaskInputMode() /** * Unmasks the button panel of the [TimePickerDialog], including positive, negative, and toggle mode buttons. */ fun TimePickerDialog.csqUnMaskButtonPanel() ``` * Jetpack Compose The Time and Picker composables in Jetpack Compose can be masked or unmasked using the same APIs applied to other composables. Simply use the appropriate `CsqMask` composables function on the elements you want to mask or unmask within the dialog. **Custom Dialogs** * Views If you're creating a custom dialog by extending the Dialog base class and inflating a layout using the setContentView method, you can mask or unmask individual views within your custom view hierarchy, using the masking APIs. * Jetpack Compose The custom dialogs in Jetpack Compose can be masked or unmasked using the same APIs applied to other composables. Simply use the appropriate `CsqMask` composables function on the elements you want to mask or unmask within the dialog. **Menu Items** * Views Menu items captured by Session Replay can be selectively masked or unmasked. For example, consider a context menu, including an action item and another item displaying the user's name (see XML example below). If masking is disabled by default, you may want to mask sensitive menu items to prevent personal data from appearing in Session Replays. Conversely, if masking is enabled by default, you may choose to unmask certain non-sensitive items to keep them visible. To achieve this, simply apply masking or unmasking to individual menu items as needed. ```xml <?xml version="1.0" encoding="utf-8"?> <menu xmlns:android="http://schemas.android.com/apk/res/android" xmlns:app="http://schemas.android.com/apk/res-auto"> <item android:id="@+id/action_settings" android:orderInCategory="10" android:title="@string/action_settings" app:showAsAction="never" /> <item android:id="@+id/profile_settings" android:orderInCategory="100" android:title="Name Placeholder" app:showAsAction="never" /> </menu> ``` Note This API does not need to be called strictly after menu inflation; it can be invoked earlier if necessary. As a best practice, apply it during or after menu inflation when you have clear context about what is being masked and where. ```kotlin override fun onCreateOptionsMenu(menu: Menu): Boolean { // Inflate the menu; this adds items to the action bar if it is present. menuInflater.inflate(R.menu.activity_main, menu) val item = menu.findItem(R.id.profile_settings) item.title = current_user.fullName // Unmask action menu item CSQ.unmaskMenuItem(R.id.action_settings) // Mask profile menu item that contains user's name CSQ.maskMenuItem(R.id.profile_settings) return true } ``` * Jetpack Compose The Menu components in Jetpack Compose can be masked or unmasked using the same APIs applied to other composables. Use the appropriate `CsqMask` composable function on the elements you want to mask or unmask within the menu. #### Handling Transparent Views The SDK processes [masked views first](#masking-rules), ensuring that if a view has transparency and is not masked, it will not expose any personal data since masked views have already been processed. This approach ensures the protection of sensitive information, even in UIs with transparent views. Warning If the view below the transparent view is a **WebView**, and you unmask the view on top of it (for example a dialog progress bar), it leaks the content of the WebView. This is a known limitation. On the left, a possible implementation of a payment screen in a WebView. On the right, the result in Session Replay.  ### Implementation recommendations #### Where to perform masking operations Masking operation should be performed before the first draw of the view and it should always be called on the UI thread. At the **Activity** level, call the masking API methods on the `onCreate` lifecycle method. At the **Fragment** level, call the masking API methods on the `onViewCreated` lifecycle method. Note The masking API stores the view element to be masked or unmasked inside a WeakHashMap, repeating the masking operation multiple times on the same element will override the old value that is already stored in the map. #### Keeping track of what is masked The SDK doesn't provide a list of what is currently masked, if you need to keep track, you probably will have to write your specific wrapper. #### Masking operations performance impact You can call `unmask(View view)` multiple times without impacting the SDK performance or your app. ### Masking limitations #### Maps You can mask or unmask a Map, that will then be captured as an image in the replay. However, you won't be able to mask or unmask specific elements within the Map. #### Navigate between fragments using animations Masking rules don't apply on Fragments using animations. So to mask this type of Fragment, mask the container view where the Fragment is inserted, rather than masking its content. This ensures that the Fragment content remains masked during transitions. Additionally, you can unmask some specific views within the Fragment content, by using `CSQ.unmask(view: View)`. #### Rotated or Scaled Views The masking solution relies on the bounding box reported by a view to determine the area that should be masked. In most cases, this approach is sufficient, as the bounding box accurately reflects the view's position and dimensions on the screen. However, when a view is rotated or scaled, the bounding box no longer represents the view's actual position or size after the transformation. To prevent any personal data from being leaked, we advise adopting one of the following approaches: * **Mask the Parent View**: Apply masking to the parent container of the transformed view. This ensures that the entire area encompassing the rotated or scaled view is covered, regardless of transformations. * **Mask the Entire Window**: In case of complex layouts, transformations, or critical scenarios where absolute certainty is required, mask the entire window to guarantee that no personal data is exposed. These approaches provide the highest level of confidence in preventing personal data leakage while working within the constraints of the current implementation. ## Event-Triggered Replays (ETR) Event-Triggered Replays (ETR) is an add-on feature that allows you to selectively collect specific screens or sessions for Session Replay, based on predefined custom events. Once configured, ETR events can be used to filter specific replays, or view these events as they happen in the player event stream. To enable ETR, contact your CSM or Implementation Manager. For more information, see [Event-Triggered Replays ↗](https://support.contentsquare.com/hc/en-us/articles/4412027865874) in the Help Center. Note When ETR is enabled, the SDK collects data for the entire session even if none of the ETR methods described below are called. After collection, only the sessions or screens that match the global replay sampling rate or are associated with ETR events are retained. As a result, you may notice a network activity during all sessions, regardless of whether ETR has been triggered or not. Warning To protect end-user personal data, ensure that appropriate masking configurations are applied to all screens even the ones that are not associated with ETR events. ### Trigger Replay for the Session Use the following function to trigger Session Replay for the entire current session, with the parameter `name` as "ETR event". ```kotlin CSQ.triggerReplayForCurrentSession(name: name) ``` ### Trigger Replay for the Screen Use the following function to trigger Session Replay for the entire current screen, with the parameter `name` as "ETR event". ```kotlin CSQ.triggerReplayForCurrentScreen(name: name) ``` ## Advanced features for Experience Monitoring Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. ### Send user identifier CSQ SDK provides the ability to search for sessions associated with a specific visitor, based on an identifier: email, phone number, customer ID… As these values are typically personal data, from the moment the SDK is collecting the User Identifier, we immediately encode the value using a hashing algorithm so that the information is hidden and can never be accessed. Use the following code to send a user identifier: ```kotlin CSQ.sendUserIdentifier("any_identifier") ``` When called, the SDK will log: ```plaintext CSLIB: User identifier hashed sent {value} ``` #### Sending a user identifier for each session You may want to send the user identifier for each session. While triggering the user identifier at app launch will cover most cases, it will not be enough. A session ends 30 minutes after the last event. See [Session definition](../data-collection/#session-definition) for more information. That is why we also recommend sending the user identifier every time the app enters foreground. You can use the [`ProcessLifecycleOwner` Class ↗](https://developer.android.com/reference/androidx/lifecycle/ProcessLifecycleOwner) to detect foreground and trigger a `sendUserIdentifier()`. #### Limitations * User identifier max length is 100 characters (if the limit is exceeded, the user identifier will not be handled and you will see an error message in the Console/Logcat) * Only the first 15 user identifiers per view will be processed on server side * The SDK will trim and lowercase user identifier * User identifier event are not visible in Log visualizer ## Integrations CSQ SDK provides the ability to retrieve the link of the replay to be attached to other vendors such as Voice of Customer or Crash reporting tools. ### Get current replay Link Generate a link to the replay of the current session. This link can be pushed to any internal or 3rd-party tool as a custom property/variable. For instance, you can add the replay link to: * Each user request sent to your customer service tool * Each user voting in your Voice of Customer tool * Each user session in your App Performance, Observability tool * ... Note The replay link can also be accessed from the in-app features settings. See [Access the Replay](#access-the-replay). Warning For the API to return a valid replay link, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before it's called, since Session Replay only starts after the first screenview event. `CSQ.metadata.sessionReplayUrl` can be used to retrieve the last Session Replay URL if the SDK was successfully initialized and the Session Replay is running. Alternatively you can use the following code to retrieve a Session Replay link each time it changes: ```kotlin CSQ.metadata.onChanged = OnMetadataChanged { metadata -> // Send link to your customer service tool val sessionReplayLink = metadata.sessionReplayUrl } ``` To unregister the current callback, pass `null` as the argument: ```kotlin CSQ.metadata.onChanged = null ``` To avoid memory leaks, you can use the [`ProcessLifecycleOwner` Class ↗](https://developer.android.com/reference/androidx/lifecycle/ProcessLifecycleOwner) to detect foreground and background events and register or unregister the callback. When a new link is available, the SDK will also log: ```plaintext CSLIB: SessionReplay link: https://app.contentsquare.com/quick-playback/index.html?pid={projectId}&uu={userId}&sn={sessionNumber}&recordingType=cs ``` Warning You can only have one callback at a time. Calling this API twice will override the previous callback. The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay the session up to the previous screenview if the session is still running. ## How Session Replay works ### Initialization Sessions can be collected for Session Replay if the Session Replay feature has been enabled for your project and the session matches the collection criteria. The following conditions will have an impact on which sessions will be collected: * **User consent**: The users have given their **consent** (if required) * **Collection rate**: The session is being **drawn for collection** (see Collection rate below) * **Compatibility**: The **OS version** is supported. * **App version**: The **app version** is not part of the block list (see App version block list below) When Session Replay is turned off, no content specific to Session Replay is collected whatsoever. Other CSQ tracking remains unaffected by this. #### Collection rate Data collection for Session Replay is based on a percentage of the total sessions. By default data collection for Session Replay is disabled. During the early access phase, the percentage or collected sessions will be set to 1% at the beginning. It will then be adjusted according to: * The traffic on your app * The volume of collected sessions set in the contract #### Compatibility See [compatibility](../compatibility/). #### App version block list CSQ team can add versions of your app in the block list to make sure Session Replay does not start on these versions. This is done when a problem is discovered on a specific version of your app, such as a Personal Data for which the masking was forgotten. This allows to keep Session Replay to work on the other app versions (especially the new ones with the fix). ### Data collection The SDK monitors the application lifecycle events and the view hierarchy, and generates Session Replay data from the behavior of the app, the content of the screen and the interaction of the user. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. Tip Data collection for Session Replay will start at the 1st screenview event. ### Quality levels Session Replay has three quality levels available: High, Medium, Low. Quality level is defined by the frame rate and the image quality. The quality level is defined independently for **Wi-Fi** and **Cellular Network**. The default level for both is **Medium**. For more information on network data consumption see: [Performance Impact section](#performance-impact). Note If you require a particular setting, reach out to your Contentsquare contact that will make the adjustment in the project configuration. #### Quality-level examples Select the image to open it in full size and GIF format. [](https://docs.contentsquare.com/_astro/android-quality-levelgrand.Djk7sO10.gif) ### Network and Storage By default, Session Replay data can be sent over **cellular network**. If the particular context of your app or users requires a very limited impact on cellular data consumption, **sending data over cellular network can be completely disabled**. Once disabled, data will be sent when the device is using Wi-Fi. Reach out to your Contentsquare contact that will make the adjustment in the project configuration. #### Storage Before being sent, data is stored in local files on disk up to 20MB on Android. When the limit is reached, all collected data is dropped, and data collection continues. Then, every time the limit is reached again, the same process is applied. ### Requests The maximum request size is 1Mbyte. Requests are sent: * On screen change * When [Replay Link API](#get-current-replay-link) is called ## Performance impact ### Performance impact mitigation Most operations related to Session Replay are performed on dedicated background threads, for a minimal impact on the main thread. If CPU usage is too high for background tasks, some expensive calculations will be discarded. To make sure of this, we run performance tests on testing applications, along with the Android profiler. If too much time is spent on the main thread, the [quality level](#quality-levels) will decrease automatically: from high to medium to low to a complete stop if required. Once conditions are back to normal, quality level will be changed back to the default value set in the configuration. We defined our network strategy to have the lesser impact on CPU, memory, and data consumption of the users devices. We measure these impacts, using the Android profiler and dedicated logging system, for each release of our SDK. You can reduce the quality level if you want to favor performance impact over quality. ### Performance test results We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. The performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | Pixel 5 | | Android version | 34 (Android 14) | | Quality level | High | | Default Masking State | Disabled | Note That the numbers provided below will vary depending on the user's device and Android version. | Property | Value | | - | - | | Total % on main thread (CPU Profiling) | <15 % | | Memory overhead | 15 MB | | Session Replay data transmitted over network during 1 minute of use: | | | - with "High quality" level | <838 KB | | - with "Medium quality" level | <545 KB | | - with "Low quality" level | <369 KB | #### Additional info on performance test procedure **CPU Usage Test** We are profiling our Demo app with and without the SDK dependency by following the same use case. We are measuring the CPU peak for both versions of the app and we are computing the difference. **RAM Usage Test** We are profiling our Demo app with and without the SDK dependency by following the same use case. We are measuring the RAM usage peak for both versions of the app and we are computing the difference. **Memory Leak Test** We are profiling our demo app and we are using the ADB Monkey tool to create random user input events. During this time we are monitoring the RAM behavior for any anomaly. We are using the Memory Profiler to identify leaks. **Data consumption** We replay a predefined, repeatable, and automated user scenario on our demo app and all data sent is measured in kB/min. **JankStats** If you use the alpha library from Google to monitor the jank frames and you already have some jank frames in your application (main thread overwhelmed), you can expect an increase of 1% or 2% with data collection for Session Replay activated. Data collection for Session Replay requires to perform tasks on the main thread (screen capture and view hierarchy inspection). ## Known limitations ### SurfaceView [SurfaceView ↗](https://developer.android.com/reference/android/view/SurfaceView) are not supported for now. They will be displayed as white views. This includes views used for video streaming and camera previews, ensuring that no such content is captured. ### Animations are unsupported when masking by instance or type When views are masked by instance or type, personal data may leak during animations in the collected session. To prevent this, there are two possible options: masking the entire screen or masking around the animation. **Mask the entire Screen** Apply default masking to the entire screen with `setDefaultMasking(true)`, without using any [instance-based](#maskingun-masking-by-instance) or [type-based](#maskingun-masking-by-type) masking/unmasking. After the user navigates to another screen, you can deactivate the default masking with `setDefaultMasking(false)` and use any view masking APIs. **Mask around the animation** Mask the entire screen just before the animation, following the [Masking rules](#masking-rules). This involves reversing any [instance-based](#maskingun-masking-by-instance) or [type-based](#maskingun-masking-by-type) masking/unmasking for views and then calling `setDefaultMasking(true)`. After the animation, you can restore the previous masking settings by instance or type. ## Troubleshooting ### Requests are not sent from an Android emulator If you struggle to watch a replay created on an emulator/simulator, it may be due to some network constraints applied on your computer (VPN, company network restrictions, etc.). Check your configuration or use a real device. See [Requests are failing](../troubleshooting/#requests-are-failing) for more information about our endpoints and requests. #### Very long session on an Android emulator It is important to remember that **an app kill does not end a session**. See [Session definition](../data-collection/#session-definition) for more information. If you leave the simulator/emulator running with the app in foreground, the session will not end, even if you are inactive. To better reflect actual end user behavior and avoid unusually long sessions (last hours), put the app in background or kill it. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Session Replay","description":"Learn how to integrate and configure Session Replay capabilities in your Android app with the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/session-replay/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - Android description: Configure privacy settings and user consent management in your Android app with the CSQ SDK to ensure regulatory compliance lastUpdated: 28 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/privacy/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Customers ("Customer(s)", "you," or "your"), as app developers and/or publishers, shall ensure compliance with applicable data privacy laws and regulatory guidelines while using Contentsquare SDK for your app. This section explains the data processing involved in the use of Contentsquare SDK and provides information to help you comply with data protection laws, including the GDPR, e-privacy directive, and the [French Data Protection authority (CNIL) guidelines on mobile applications ↗](https://www.cnil.fr/sites/cnil/files/2025-05/recommendation-mobiles-app.pdf). This section is for informational purposes only and is not legal advice. If you are not sure of how to comply with data protection laws that apply to you, refer to legal counsel. To learn about Contentsquare privacy practices, see our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Purpose of processing and categories of personal data processed ### Purpose of processing The Contentsquare SDK is designed to collect personal data from end-users interacting with your app to analyze their digital behavior, visualize their journey, and improve digital user experience and your app performance. ### Categories of personal data collected By default, the SDK processes the following categories of personal data: * **Online identifier**: Contentsquare user ID * **Behavioral data**: touch gestures (taps, swipes), user journey (pages visited), time of engagement, transactions, and so on. * **Technical data**: device information (such as operating system, resolution, time zone, or language), API error messages and crashes Additional types of personal data may be processed (such as username, email address, customer ID, account number), depending on your configuration of the SDK and the applicable order form you signed with Contentsquare. Note Contentsquare is not designed to collect sensitive personal data (such as health, financial, or racial data). It is your responsibility to prevent any sensitive data from being sent to Contentsquare. If you accidentally send sensitive data, contact your customer success manager to immediately delete them from Contentsquare servers. ## User identifiers ### Contentsquare User ID The SDK generates a randomized hash unique user ID (UUID) that is specific to each end-user on a given device. Contentsquare cannot identify an end-user across devices with this UUID. This UUID is not persisted when the app is deleted and re-installed. The SDK generates a new UUID after install or re-install. ### "User identifier" feature Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier provided by the customer. See [User identifier feature](../../experience-analytics/session-replay/#send-user-identifier) for more information. ### Usage of App Set ID Contentsquare does not use App Set ID. ## Data retention and storage location ### Data retention By default, end-users personal data are kept for 13 months. The retention of end-users personal data collected via the Session Replay is customizable by customers, from 3 to 24 months. ### Storage location End-users personal data are stored in Europe or in the US, depending on your location. For more details on applicable hosting locations, refer to our [subprocessors list ↗](https://contentsquare.com/privacy-center/subprocessors/). ## Informing your end-user The Contentsquare SDK collects end-user's personal data on your app. As a data controller, app developers, or app publishers, it is your responsibility to provide appropriate information to your end-users on how their personal data is handled when using the CSQ SDK, for example via a privacy policy or cookie banner. Contentsquare provides a sample [description of the services ↗](https://contentsquare.com/privacy-center/sample-cookie-description/) (including Experience Analytics and Product Analytics) to help customers meet their transparency obligations. This description is for information only and is not legal advice. ## Handling User Consent Contentsquare collects usage data on your app. **By default, the SDK will consider every new user to be opted-out.** To start tracking, the SDK [Opt-in API](#opt-in) must be called. You are responsible for handling the UI asking end-users for their consent and allowing them to manage their privacy settings. Use the following APIs to pass the user decision to the Contentsquare SDK. Note If data protection laws that apply to you do not require end-user consent for your app, discuss it during implementation with your Contentsquare contact. ### Opt-in Use the Opt-in API to get user consent. Calling this API will generate a user ID and initiate tracking. ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` ### Opt-Out When this API is called, tracking stops immediately, all settings are reset (Session number, Page number, and so on) and all files and directory including personal data collected via the SDK created by Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track and collect any data from the user's phone unless the Opt-in API is called again. ```kotlin import com.contentsquare.CSQ // To opt-out of CSQ Tracking CSQ.optOut() ``` ### Get Contentsquare User ID Since Contentsquare SDK does not collect by default any directly identifiable personal data about your end-user, we cannot help you respond to an end-user's data subject request without their Contentsquare User ID. Use this API to get the Contentsquare User ID of your end-user and forward the end-user's data subject request (such as data deletion or data access request) via Contentsquare's [portal ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ```kotlin import com.contentsquare.CSQ // Get CSQ User ID val userId = CSQ.metadata.userId ``` ### Pause / Resume Tracking Use pause and resume tracking APIs to completely pause data collection of your end-users on your app. When pause is called, the Contentsquare SDK pauses all tracking (Analytics, Session Replay, Errors) of your end-users. When resume is called, the Contentsquare SDK resumes all tracking (Analytics, Session Replay, Errors) and starts collecting your end-users personal data again with the same Contentsquare user ID. ```kotlin import com.contentsquare.CSQ // Pause tracking CSQ.pauseTracking() // Resume tracking CSQ.resumeTracking() ``` Note As this mechanism pauses the tracking, make sure that you call resume once your user exits the sensitive screen. Best practice would be to link these method calls to lifecycle events on activities/fragments. ### Stop automatic gesture tracking End-users' personal data, including behavioral data (such as taps, scrolls, swipes) are collected automatically by the Contentsquare SDK. In specific cases, you might want to stop the tracking of individual Views. To do so, use the following API: ```kotlin CSQ.ignoreInteractions(view, includeSubtree) ``` In case you still need to track these Activities or Views but the automatic gesture tracking does not work, we offer the possibility to do this manually by capturing and sending the gesture events via our public API method: ```kotlin class MainActivity : AppCompatActivity() { // ... override fun dispatchTouchEvent(motionEvent: MotionEvent): Boolean { CSQ.trackMotionEvent(motionEvent) return super.dispatchTouchEvent(motionEvent) } } ``` ### Disable user tracking across sessions If you don't want to link the different sessions of a user to the same userID, reset the userID at each app start: ```kotlin class MyApplication : Application() { override fun onCreate() { super.onCreate() // Start Contentsquare SDK CSQ.start(this) CSQ.optOut() CSQ.optIn(this) } } ``` Starting the SDK manually using `start()` will ensure that opt-out is called right after the start of the SDK (no event tracked in between). Calling `optOut()` will delete the previous userID. Calling `optIn()` will set a new one. Note If you are monitoring the network requests, you may see event requests being sent at app start. This is expected as there may be events from the previous session that haven't been sent yet. The opt-out API makes sure to send all data stored locally before stopping the tracking and wiping all data. ### Session Replay personal data masking mechanisms As part of Session Replay, Contentsquare provides masking mechanisms to prevent unwanted end-user's personal data from the Session Replay module from being transmitted to Contentsquare. See [Session Replay Personal data masking](../../experience-analytics/session-replay/#personal-data-masking) for more information. ## Permissions The Contentsquare SDK requires technical permissions to operate properly. Some of these permissions involve read and write operations within the meaning of the e-privacy directive and article 82 of the French Data Protection Act, which may require the end-user's specific consent. See [App permissions](../security/#app-permissions) for more information. ## Play Store Privacy Guidelines Compliance As customer app developers, it is your responsibility to comply with the [Play Store Privacy guidelines ↗](https://support.google.com/googleplay/android-developer/answer/10144311?visit_id=637574546075634450-3505282410\&rd=1). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Configure privacy settings and user consent management in your Android app with the CSQ SDK to ensure regulatory compliance","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/privacy/","inLanguage":"en","dateModified":"2026-04-28T22:12:27+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Product Analytics data capture - Android description: Access to acquisition analysis and lifetime metrics by implementing the Product Analytics data capture using the CSQ SDK lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/set-up-product-analytics-data-capture/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/set-up-product-analytics-data-capture/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This page instructs how to set up Product Analytics data capture in combination with Experience Analytics. 1. Initialize the SDK with your environment ID. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID" ) ) } } ``` Find your environment ID `YOUR_ENVIRONMENT_ID` is either provided to you by Contentsquare or you can find it in **Account** > **Manage** > **Projects** > \[Select your project] > **Environments** within the [Product Analytics web app ↗](https://heapanalytics.com/app/). * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID" ) ) } } ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 2. Add the Android View Autocapture Plugin to instrument your app code: * Kotlin **build.gradle.kts** ```kotlin plugins { // ... id("io.heap.gradle") version "1.1.1" } ``` * Groovy **build.gradle** ```groovy plugins { // ... id 'io.heap.gradle' version "1.1.1" } ``` 3. Set up autocapture by adding `enableViewAutocapture = true`. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( enableViewAutocapture = true ) ) ) } } ``` 4. (Optional) For Jetpack Compose, add the dedicated import and register the Compose Autocapture SDK. * Kotlin **build.gradle.kts** ```kotlin dependencies { implementation("com.contentsquare.android:sdk:1.12.1") implementation("com.contentsquare.android:sdk-compose:1.12.1") } ``` * Groovy **build.gradle** ```groovy dependencies { implementation 'com.contentsquare.android:sdk:1.12.1' implementation 'com.contentsquare.android:sdk-compose:1.12.1' } ``` - Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import io.heap.autocapture.compose.ComposeAutocaptureSDK class MyApplication : Application() { override fun onCreate() { super.onCreate() ComposeAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true ) ) ) } } ``` - CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import io.heap.autocapture.compose.ComposeAutocaptureSDK class MyApplication : Application() { override fun onCreate() { super.onCreate() ComposeAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( enableViewAutocapture = true ) ) ) } } ``` 5. (Optional) If your Product Analytics environment is hosted in the EU, set the `baseUri` option to `https://mh.ba.contentsquare.net`. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true, baseUri = URI.create("https://mh.ba.contentsquare.net") ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( enableViewAutocapture = true, baseUri = URI.create("https://mh.ba.contentsquare.net") ) ) ) } } ``` 1) Add the `disablePageviewAutocapture: true` option to the configuration. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true, disablePageviewAutocapture = true ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( enableViewAutocapture = true, disablePageviewAutocapture = true ) ) ) } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Product Analytics data capture","description":"Access to acquisition analysis and lifetime metrics by implementing the Product Analytics data capture using the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/set-up-product-analytics-data-capture/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Third-party libraries license - Android description: Contentsquare includes several third-party libraries, which are licensed under their own respective licenses lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/third-party-libraries-license/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/third-party-libraries-license/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The CSQ SDK for Android includes third-party libraries; the table below lists each library, its license, and copyright notice. | Libraries | License | Copyright | | - | - | - | | AndroidX | Apache-2.0 license | Copyright 2025 The Android Open Source Project Licensed under the Apache License, Version 2.0 (the "License"); | | KotlinX | Apache-2.0 license | Copyright 2010-2025 JetBrains s.r.o. and Kotlin Programming Language contributors. | | Kotlin lite Protocol Buffers | BSD-3-Clause | Copyright 2025 Google Inc. All rights reserved. | | Curtains | Apache-2.0 license | Copyright 2025 Square Inc. | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Third-party libraries license","description":"Contentsquare includes several third-party libraries, which are licensed under their own respective licenses","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/third-party-libraries-license/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track custom variables - Android description: Enhance analytics by capturing custom variables for detailed user behavior analysis in your Android app with the CSQ SDK lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-custom-variables/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-custom-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Custom variables attach additional information about the screen, user, or session to screenview events. For example, they can include information on the current layout of a screen, like dark or light mode. ## Defining custom variables To define and send custom variables, follow this: ```kotlin val customVar1 = CustomVar(1, "CustomVarName1", "CustomVarValue1") val customVar2 = CustomVar(2, "CustomVarName2", "CustomVarValue2") CSQ.trackScreenview("ScreenName", listOf(customVar1, customVar2)) ``` Warning For consistent analytics, use the same index/name pair values across your application: **Screen A** ```kotlin val customVar4 = CustomVar(4, "hero_banner_type", "carousel") CSQ.trackScreenview("ScreenA", listOf(customVar4)) ``` **Screen A** ```kotlin val customVar4 = CustomVar(4, "hero_banner_type", "slider") CSQ.trackScreenview("ScreenB", listOf(customVar4)) ``` ## Limits ### On the server side * It is possible to save up to 20 distinct custom variables per screenview. If more are received, only the first 20 custom variables, based on their `index` value, will be kept. * The `index` value of custom variable is used to determine which custom variable to be kept. Only `index` value between 1 and 20 will be taken into account. ### On the SDK side * Every custom variable is composed of `index`, `name` and `value`. * If you are using the same `index` twice in a single screen only the first (`name`, `value`) pair associated with the `index` will be kept. * In case `name` (max. 512 characters) or `value` (max. 255 characters) maximum characters length is reached, the SDK will automatically trim the exceeding characters. * If `name` or `value` are empty, the SDK will instead send the literal string `"cs-empty"`. * Use a consistent `index` for a given variable within an application - for instance, if the "screen layout" is collected with an `index` of 3, use the slot 3 for this information on every screen of the application. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track custom variables","description":"Enhance analytics by capturing custom variables for detailed user behavior analysis in your Android app with the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-custom-variables/","inLanguage":"en","dateModified":"2026-05-04T12:00:05+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track dynamic variables - Android description: Learn how to implement dynamic variable tracking to enrich your analytics data in your Android application with the CSQ SDK lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-dynamic-variables/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-dynamic-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. *Dynamic variables* are additional information on the session that can be used to *segment sessions*. For example, they can include information on the A/B Test variations displayed to the current user. ## Defining dynamic variables To define and send a dynamic variable, directly use the key and String/Long value: ```kotlin CSQ.addDynamicVar("cart_value", 123) CSQ.addDynamicVar("user_account_status", "premium") CSQ.addDynamicVar("ab_test_variant", "control") CSQ.addDynamicVar("session_id", 456789) ``` **Type of the value** — The value can be either a **whole number** or a **string**. For each case, available features won't be the same in the Contentsquare app: * For **whole numbers**, you will be able to do some algebra. Example: *sessions with dynamic variable key = "numberOfFriends" and value >= 10* * For **strings**, auto-completion and Regular Expression will be available. Example: *sessions with dynamic variable key = "accountType" and value = "Premium"* ## Sending a dynamic variable for each session You may want to send a dynamic variable for each session (like the user's country or store). While **triggering the dynamic variable at app launch will cover most cases, it will not be enough**. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See [Session definition](../data-collection/#session-definition) section for more information. That is why we also recommend **sending such dynamic variable every time the app enters foreground**. You can use the [`ProcessLifecycleOwner` Class ↗](https://developer.android.com/reference/androidx/lifecycle/ProcessLifecycleOwner) to detect foreground and trigger a dynamic variable. ## Limits ### On the server side * It is possible to save up to 40 distinct *dynamic variable keys* per screenview. If more are received, only the first 40 keys will be kept. * If you are using the same key twice on the same screenview, the last value associated with the key will be collected. ### On the SDK side * Every dynamic variable is composed of a pair of key (max. 50 characters) and value (max. 255 characters string or number of type `Long` between 0 and 232 - 1). In case these maximums length are reached, the SDK will automatically trim the exceeding characters. * If key or value are empty, the SDK will instead send the literal string "cs-empty". ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track dynamic variables","description":"Learn how to implement dynamic variable tracking to enrich your analytics data in your Android application with the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-dynamic-variables/","inLanguage":"en","dateModified":"2026-05-04T12:00:05+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track screens - Android description: Learn how to implement screen tracking in your Android app with CSQ SDK to capture user navigation patterns and screen interactions lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-screens/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-screens/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare aggregates user behavior and engagement at the screen level. To achieve this, it is necessary to provide a name for each screen by calling a dedicated screenview API. Warning Sessions without at least one screenview will be discarded. ```kotlin import com.contentsquare.CSQ // Sends Screenview CSQ.trackScreenview("screen_name") ``` ## Jetpack Compose support To enable Jetpack Compose support, it is necessary to add a new dependency to your Gradle build file. * Kotlin **build.gradle** ```kotlin implementation("com.contentsquare.android:sdk-compose:1.12.1") ``` * Groovy **build.gradle** ```groovy implementation 'com.contentsquare.android:sdk-compose:1.12.1' ``` Attention must be paid to recompositions. The call should be wrapped using `TriggeredOnResume` composable to ensure only one screenview is triggered when a given screen is presented to the user. ```kotlin import com.contentsquare.CSQ import com.contentsquare.api.compose.screen.TriggeredOnResume @Composable fun MyScreen() { TriggeredOnResume { CSQ.trackScreenview("screen_name") } // ... } ``` ## Screen name handling The screen name is limited to 2083 characters. However, this limit is not enforced by the SDK, but rather by the Contentsquare servers. ## Implementation recommendations ### General rules From a functional standpoint, we expect a screenview to be sent when: * The screen appears on the device * A modal or pop-up is displayed * A modal or pop-up is closed, returning the user to the screen * The app is brought back to the foreground (after being minimized) ### When to send your first screenview Most events collected by the SDK require a screenview event to be sent first so they can be associated with that screen; otherwise, they will be discarded. If you need to collect events from the moment the app launches, you should trigger a screenview event immediately after the SDK has started: ```kotlin CSQ.start(this) CSQ.trackScreenview("Launch screen") ``` ### Activities To trigger a screenview each time the activity becomes visible, place the call in the `onResume` method (Android view system only). ### ViewPagers To avoid double tagging on Fragments, make sure to include the call in each ViewPager's `onPageChangeListener` callback. ### Popups When tracking a popup as an isolated screen, use the API to send a screenview event in `onShow`. To re-trigger a screenview of the current activity when the popup is dismissed, make sure to trigger a screenview event with the original activity screenName on the popup `DismissListener`. ### Bottom sheets When tracking a bottom sheet as an isolated screen, use the API to send a screenview event on view displayed. On its dismiss, make sure to trigger a screenview event with the original screen name on `BottomSheetBehaviorCallback` state change (Usually when STATE\_HIDDEN) to track the complete cycle. ### Back navigation and navigation between screens Make sure that screenview events will be triggered when a user will go to the previous screen (example: Home → Profile → Home), it is expected to have a screenview event for the Home screen that might be reached with the back navigation button. Trigger screenview event in a [**custom callback** ↗](https://developer.android.com/guide/navigation/navigation-custom-back) to catch the back events. ### Redirecting the user to another screen (authentication, home) when closing the app/re-opening the app For some apps, you might want to redirect users whenever they hide your app, for example for security purposes (bank apps, password managers, etc...). If that is the case, pay specific attention to the way Screen name events are sent, in order not to track a screen which is not actually shown users. ## How to name screens As a general rule, keep the number of distinct screen names under 100. Since these names are used to map your app in Contentsquare, choose names that are clear and comprehensive. ### Separate words with spaces, dashes, or underscores When generating screen names with multiple words, separate them using spaces, dashes, or underscores. For instance, use `Home & Living - Home Furnishings` instead of ~~`homeLivingHomeFurnishings`~~ for a sub-category in a retail app. ### Screen name limitations Casing sensitivity Screen names are not case sensitive and will appear in lowercase on the Contentsquare platform. ```kotlin CSQ.trackScreenview("ScreenName") // screenname CSQ.trackScreenview("Screen Name") // screen name CSQ.trackScreenview("screen_name") // screen_name CSQ.trackScreenview("screenname") // screenname ``` ### Use screen template/layout names As a general recommendation, use names referring to the screen template/layout rather than referring to the specific content (data). This will help: * To keep the number of distinct screen names low and therefore make Contentsquare easier to use * Remove the risk of sending Personal Data to Contentsquare List of screen types falling into that category: Product detail, Event detail, Conversation/Chat, and User profile. ### Screens with multiple states/layouts Screens can have different layouts or states depending on the user context. In this case, append its value to the screen name. **Home screen** | State | Screen name | | - | - | | App landing layout | `Home` | | Women products layout | `Home - Women` | | Men products layout | `Home - Men` | | Sales layout | `Home - Sales` | **Product Detail screen (PDP)** | State | Screen name | | - | - | | Users on a Top for Women PDP | `PDP - Clothing - Women - Tops` | | Users on a Microwave PDP | `PDP - Kitchenware - Electrics - Microwave` | | Users on a Hotel details screen | `PDP - Holiday type - Season - Board` | **User account screen** | State | Screen name | | - | - | | Overview | `My Account - Dashboard` | | Order history | `My Account - Order history` | | Returns | `My Account - Returns` | **Search screen** | State | Screen name | | - | - | | Search | `Search` | | Search results for "Skincare" products | `Search - Skincare` | | Search results error screen | `Search - Error` | **Cart screen** | State | Screen name | | - | - | | Empty cart | `Cart - Empty` | | Items have been added to the cart | `Cart - Populated` | | Issues with availability or pricing | `Cart - Error` | **Checkout screen** | State | Screen name | | - | - | | User provides name, surname, and date of birth | `Checkout - User Details` | | User provides shipping address | `Checkout - Shipping Details` | | User inputs their credit card information | `Checkout - Payment` | ## How to track sessions and screen metadata **Custom Variables** Custom variables are designed to provide additional details about the screenview or user information during end-user engagement. These variables can encompass various aspects, including screen-specific attributes or user-related information, and serve to enhance data collection and analysis. Example: * Product name: "Acme Widget" * Product color: "red" * Product price: "$19.99" [Learn how to setup Custom Variables](../track-custom-variables/) **Dynamic Variables** Dynamic variables are used to provide additional information on the session, such as the name of a campaign or the version of a variation for an A/B test integration. They can be sent at any time during a session and do not require sending a screenview. dynamic variables should be used only in segments. Example: * Campaign name: "Summer Sale 2023" * Variation version: "Version A" [Learn how to setup Dynamic Variables](../track-dynamic-variables/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track screens","description":"Learn how to implement screen tracking in your Android app with CSQ SDK to capture user navigation patterns and screen interactions","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-screens/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track transactions - Android description: Track transactions with the Contentsquare Android SDK lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-transactions/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-transactions/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To associate a user's session with their potential purchases (and corresponding revenue), you must send the transaction via a dedicated API. For each transaction, we send: * Price (mandatory) * Currency (mandatory) * Transaction ID (optional) ```kotlin import com.contentsquare.api.model.Transaction import com.contentsquare.api.contract.Currency val transaction = Transaction(430.99f, Currency.EUR, "my_id") CSQ.trackTransaction(transaction) ``` Warning **Each transaction must only be sent once**. A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ## Currency The `Currency` enum provides a list of all supported currencies, conforming to the [ISO 4217 ↗](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) standard. ```kotlin import com.contentsquare.api.contract.Currency val currency = Currency.USD val currencyFromString = Currency.fromString("USD") val currencyFromInteger = Currency.fromInteger(840) // string or integer ISO code can also be retrieved from the enum value Currency.USD.stringCode // "USD" ``` Note If the currency passed for conversion doesn't match a supported currencies, the SDK will send a currency value of `-1`. It will be processed as the default currency of the project. ## Float precision The `Transaction` API uses a `Float` to represent the transaction value, which means very large numbers may be **rounded** when stored or serialized. For example, `1234567890f` becomes `1234567936f`. This behavior is normal for floating-point values and does not affect regular currency amounts (`0.99`, `430.00`, `100000.00`). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track transactions","description":"Track transactions with the Contentsquare Android SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-transactions/","inLanguage":"en","dateModified":"2026-05-04T12:00:05+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track WebViews - Android description: Track webviews with the Contentsquare Android SDK lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-webviews/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-webviews/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. WebView tracking links the Contentsquare SDK to the JavaScript tag running inside your WebViews to support analytics and Session Replay for web content displayed within your app. Android compatibility Contentsquare **only** allows to track instances of `android.webkit.WebView`. `androidx.browser.customtabs` is **not** supported: The CSQ SDK **cannot** track what is happening within its context, and its content will **not** be visible in replays. ## Enable tracking in WebViews ### Where to inject your WebViews? It is **essential** that the registration is done before a URL is loaded in your WebView. With that in mind, you should register your WebViews in `onCreate()` for Activities and `onCreateView()` for Fragments. Unregister them in the corresponding `onDestroy()` or `onDestroyView()` methods. No matter where you decide to add the following injection code, keep in mind that it will not take effect until the next WebView content reload. ### WebView tracking lifecycle Use the [`CSQ.registerWebView()`](../command-reference/#csqregisterwebview) API to start tracking a specific WebView and [`CSQ.unregisterWebView()`](../command-reference/#csqunregisterwebview) to stop tracking it. ### Tag setup To complete the implementation, inject the **CS Tag in WebView mode** on your pages. See 📚 [Mobile Apps WebView Tracking Documentation](https://docs.contentsquare.com/en/webview-tracking-tag/#manual-injection). ## Full example Here is an Activity implementation. Register the WebView in `onCreate()` and unregister it in `onDestroy()`: ```kotlin override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_web_view) val webView = findViewById<WebView>(R.id.webview) webView.settings.javaScriptEnabled = true webView.webViewClient = object : WebViewClient() {} // Inject the Bridge between the CS Tag in WebView mode and the SDK CSQ.registerWebView(webView) webView.loadUrl(DEFAULT_WEB_VIEW_CONTENT_URL) webView.reload() } override fun onDestroy() { super.onDestroy() val webView = findViewById<WebView>(R.id.webview) CSQ.unregisterWebView(webView) } ``` If you are using Fragments, the approach is similar, but should be done in the `onCreateView()` method for registration and `onDestroyView()` method for unregistration. ## Validate your implementation of WebView tracking *There is no way of validating the implementation on the native side only.* ### Validating the implementation on the web side Once you arrive on the screen with the tracked WebView, you should see the following logs in sequence: 1. **JS interface injected:** ```plaintext [WebView] Js interface added to the webView ``` 2. **WebView registered:** ```plaintext [WebView] Registering WebView on native side ``` 3. **Tag configuration received — confirms successful tag to SDK communication:** ```plaintext [WebView JS log] (TAG_CONFIGURATION) [Config] ``` 4. **Tracking active:** ```plaintext [WebView] onWebViewTrackingReady ``` Specific logs are then emitted for: * Page views fired by the WebView Tracking Tag in the same format as for screen views: `Screenview - Screen name: {{page name given}} - Screen number: 11` * Taps and swipes detected by the WebView Tracking Tag in the same format as for defaults taps and swipe but with the target matching an HTML DOM element value: `Tap - Target: {Last view info: div:eq(0)} - Unresponsive: false` ***Going further:*** If you still have doubt, you can look for logs by filtering on `WebViewEventProcessor`. Their presence will confirm that it is well implemented on both web and native sides. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track WebViews","description":"Track webviews with the Contentsquare Android SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-webviews/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Troubleshooting - Android description: Need help? We share probable causes and recommended fixes lastUpdated: 29 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/troubleshooting/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/troubleshooting/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. When the SDK is not sending data as expected, use this page to identify probable causes and apply recommended fixes. ## Requests are failing In order for Contentsquare to work, you need to make sure the following endpoints are not blocked by your network (VPN): | Request | Endpoint | Detail | | - | - | - | | Config file | `https://mobile-production.content-square.net` | See [Configuration](../data-collection/#configuration) | | Experience Analytics data (EU) | `https://m.csqtrk.net` `https://m.ba.contentsquare.net` `https://m.aa.contentsquare.net` | See [Sending data](../data-collection/#sending-data) | | Experience Analytics data (US) | `https://m-aus1.contentsquare.net` `https://m.bf.contentsquare.net` `https://m.af.contentsquare.net` | See [Sending data](../data-collection/#sending-data) | | Product Analytics data | `https://mh.bf.contentsquare.net` | See [Product Analytics](../../product-analytics/) | | Monitoring | `https://l.contentsquare.net` | Used by the SDK to send SDK monitoring analysis in JSON format over HTTPS. | | Session Replay data (EU) | `https://ka-aeu1.contentsquare.net` `https://ka.ba.contentsquare.net` `https://ka.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Session Replay data (US) | `https://ka-aus1.contentsquare.net` `https://ka.bf.contentsquare.net` `https://ka.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Screenshot (EU) | `https://s.contentsquare.net` `https://b.ba.contentsquare.net` `https://b.aa.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Screenshot (US) | `https://s-aus1.contentsquare.net` `https://b.bf.contentsquare.net` `https://b.af.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Resources manager (EU) | `https://srm.ba.contentsquare.net` `https://srm.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Resources manager (US) | `https://srm.bf.contentsquare.net` `https://srm.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | ## Wrong tag loaded in WebView When using Manual tag injection for dual context (WebView and Browser tracking on the same webpage), the SDK injects a script that may load after the page, causing the wrong tag to load in the WebView. Use the following solution: Add a query parameter to the URL of the page you are loading in the WebView: ```kotlin webView.loadUrl("https://www.example.com/?isWebView=1") ``` Then add it to the conditions in the page script itself: ```javascript function isWebView() { return navigator.userAgent.indexOf('CS_WebView') !== -1 || typeof CSJavascriptBridge != 'undefined' || !!window.CS_isWebView || new URLSearchParams(window.location.search).get('isWebView') === '1'; } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Troubleshooting","description":"Need help? We share probable causes and recommended fixes","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/troubleshooting/","inLanguage":"en","dateModified":"2026-07-29T20:54:18+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Contentsquare SDK to CSQ SDK - Android description: Learn how to migrate from the Contentsquare SDK to the CSQ SDK lastUpdated: 12 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-android/experience-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide provides a step-by-step upgrade process from your current installation of Contentsquare Mobile SDK to the latest version of the CSQ SDK.  **Contentsquare SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. ## Dependency upgrades Replace Contentsquare SDK dependencies with the CSQ SDK: * Kotlin **build.gradle** ```diff implementation("com.contentsquare.android:library:4.39.1") implementation("com.contentsquare.android:compose:4.39.1") implementation("com.contentsquare.android:sdk:1.12.1") implementation("com.contentsquare.android:sdk-compose:1.12.1") ``` * Groovy **build.gradle** ```diff implementation 'com.contentsquare.android:library:4.39.1' implementation 'com.contentsquare.android:compose:4.39.1' implementation 'com.contentsquare.android:sdk:1.12.1' implementation 'com.contentsquare.android:sdk-compose:1.12.1' ``` ## Library imports Replace the Contentsquare SDK import with a CSQ SDK import. ```diff import com.contentsquare.android.Contentsquare import com.contentsquare.CSQ ``` ## SDK start Start the CSQ SDK manually using `CSQ.start()` — unlike earlier versions, it no longer starts automatically. **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this) } } ``` Note (Optional) If you have chosen to deactivate the autostart of the Contentsquare SDK, you can now remove the entry in the manifest, as the CSQ SDK doesn't have an autostart. **AndroidManifest.xml** ```xml <application> ... <meta-data android:name="com.contentsquare.android.autostart" android:value="false" /> ... </application> ``` ## Get user consent Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more. Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code. ## Transactions 1. Update your transaction imports: ```diff import com.contentsquare.android.api.model.Transaction import com.contentsquare.api.model.Transaction ``` 2. Update your currency imports: ```diff import com.contentsquare.android.api.Currencies import com.contentsquare.api.model.Currency ``` 3. Replace the currency type from `Int` to `Currency` enum: ```diff val currency: Int = Currencies.USD val currency: Currency = Currency.USD ``` 4. Replace `Transaction.builder` by `Transaction` and `Contentsquare.send()` by `CSQ.trackTransaction()`: ```diff val builder = Transaction.builder(100f, Currency.EUR).id("optionalId") Contentsquare.send(builder.build()) val transaction = Transaction(100f, Currency.EUR, "optionalId") CSQ.trackTransaction(transaction) ``` ## API Errors If you manually added an OkHttp interceptor (`ErrorAnalysisInterceptor`) to monitor network requests, switch to the new `CsqOkHttpInterceptor`: ```diff import com.contentsquare.android.error.analysis.network.ErrorAnalysisInterceptor import com.contentsquare.api.contract.CsqOkHttpInterceptor OkHttpClient().newBuilder() .addInterceptor(ErrorAnalysisInterceptor()) .addInterceptor(CsqOkHttpInterceptor()) .build() ``` ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. ```diff Contentsquare.start(this) CSQ.start(this) ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### GDPR / Identification | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.optIn(context: Context)` | `CSQ.optIn()` | | `Contentsquare.optOut(context: Context)` | `CSQ.optOut()` | | `Contentsquare.getUserId()` | `CSQ.metadata.userId` | | `Contentsquare.getProjectId()` | `CSQ.metadata.projectId` | | `Contentsquare.getSessionNumber()` | `CSQ.metadata.sessionId` | | `Contentsquare.sendUserIdentifier(identifier: String)` | `CSQ.sendUserIdentifier(identifier: String)` | ### Property tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.send(key: String, value: Long)` | `CSQ.addDynamicVar(key: String, value: Long)` | | `Contentsquare.send(key: String, value: String)` | `CSQ.addDynamicVar(key: String, value: String)` | ### View tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.excludeFromExposureMetric(view: View)` | `CSQ.excludeFromExposureMetric(view: View)` | ### Interoperability | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.onSessionReplayLinkChange(callback: Consumer<String>)` | `CSQ.metadata.onChanged(metadata: Metadata)` | | `CsWebViewManager.injectEventTrackingInterface(webView: WebView)` | `CSQ.registerWebView(webView: WebView)` | | `CsWebViewManager.removeEventTrackingInterface(webView: WebView)` | `CSQ.unregisterWebView(webView: WebView)` | ### Event tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.send(transaction: Transaction)` | `CSQ.trackTransaction(transaction: Transaction)` | | `Contentsquare.send(screenName: String)` / `Contentsquare.send(screenName: String, customVars: Array<CustomVar>)` | `CSQ.trackScreenview(name: String, customVars: List<CustomVar>)` | | `Contentsquare.consumeEvent(motionEvent: MotionEvent)` | `CSQ.trackMotionEvent(motionEvent: MotionEvent)` | Jetpack compose | Contentsquare SDK | CSQ SDK | | - | - | | `import com.contentsquare.android.compose.analytics.TriggeredOnResume` `TriggeredOnResume(block: () -> Unit)` | `import com.contentsquare.api.compose.screen.TriggeredOnResume` `TriggeredOnResume(block: () -> Unit)` | ### Error tracking | Contentsquare SDK | CSQ SDK | | - | - | | `import com.contentsquare.android.error.analysis.network.ErrorAnalysisInterceptor` | `import com.contentsquare.api.contract.CsqOkHttpInterceptor` | | `import com.contentsquare.android.error.analysis.ErrorAnalysis` | `import com.contentsquare.api.model.NetworkMetric` | | `ErrorAnalysis.setUrlMaskingPatterns(patterns: List<String>)` | `CSQ.setUrlMaskingPatterns(patterns: List<String>)` | | `ErrorAnalysis.getInstance().newNetworkMetric(url: String, httpMethod: HttpMethod)` | `NetworkMetric(url: String, httpMethod: HttpMethod)` | | `ErrorAnalysisInterceptor()` | `CsqOkHttpInterceptor()` | ### Personal Data Handling and Masking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.doNotTrack(vararg activitiesClasses: Class<Activity?>)` | `CSQ.ignoreInteractions(view: View)` | | `Contentsquare.setDefaultMasking(masked: Boolean)` | `CSQ.setDefaultMasking(masked: Boolean)` | | `Contentsquare.mask(view: View)` | `CSQ.mask(view: View)` | | `Contentsquare.mask(type: Class<*>)` | `CSQ.mask(type: Class<*>)` | | `Contentsquare.unMask(view: View)` | `CSQ.unmask(view: View)` | | `Contentsquare.unmask(type: Class<*>)` | `CSQ.unmask(type: Class<*>)` | | `Contentsquare.maskMenuItem(resourceID: Int)` | `CSQ.maskMenuItem(resourceID: Int)` | | `Contentsquare.unMaskMenuItem(resourceID: Int)` | `CSQ.unmaskMenuItem(resourceID: Int)` | Kotlin extension functions If you use Kotlin, the CSQ SDK comes with Extension functions for: * `CSQ.ignoreInteractions(view: View, includeSubtree: Boolean)` -> `View.csqIgnoreInteractions(includeSubtree: Boolean)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(true)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(false)` ### Jetpack compose | Contentsquare SDK | CSQ SDK | | - | - | | `Modifier.sessionReplayMask(enableMasking: Boolean)` | `@Composable CsqMask(enable: Boolean) { }` | | `Modifier.excludeFromGestureRecognition()` | `@Composable CsqIgnoreInteraction(ignore: Boolean)` | ### SDK initialization and manipulation | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.start(context: Context)` | `CSQ.start(context: Context)` | | `Contentsquare.stopTracking()` | `CSQ.pauseTracking()` | | `Contentsquare.resumeTracking()` | `CSQ.resumeTracking()` | ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that your build files no longer reference `com.contentsquare.android`, `com.contentsquare.android:library`, or `com.contentsquare.android:sdk-compose`. Your `import com.contentsquare.android.Contentsquare` declarations have been updated to `import com.contentsquare.CSQ`. You no longer have references to `Contentsquare.` methods in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Contentsquare SDK to CSQ SDK","description":"Learn how to migrate from the Contentsquare SDK to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/","inLanguage":"en","dateModified":"2026-05-12T12:05:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Core SDK + Contentsquare SDK to CSQ SDK - Android description: Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK lastUpdated: 05 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-heap-and-cs-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-heap-and-cs-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-android/experience-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide provides a step-by-step upgrade process from your current installation of Contentsquare and Heap Mobile to the latest version of the CSQ SDK.  **Heap Core SDK** \+  **Contentsquare SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. ## Dependency upgrades Replace Heap and Contentsquare SDK dependencies by the CSQ SDK: * Kotlin **build.gradle.kts** ```diff implementation("io.heap.core:heap-android-core:0.8.+") implementation("io.heap.contentsquare.csbridge:contentsquare-bridge:0.8.+) implementation("io.heap.autocapture:heap-autocapture-view:0.8.+") implementation("io.heap.autocapture:heap-autocapture-compose:0.8.+") implementation("com.contentsquare.android:library:4.39.1") implementation("com.contentsquare.android:compose:4.39.1") implementation("com.contentsquare.android:sdk:1.12.1") implementation("com.contentsquare.android:sdk-compose:1.12.1") ``` * Groovy **build.gradle** ```diff implementation 'io.heap.core:heap-android-core:0.8.+' implementation 'io.heap.contentsquare.csbridge:contentsquare-bridge:0.8.+' implementation 'io.heap.autocapture:heap-autocapture-view:0.8.+' implementation 'io.heap.autocapture:heap-autocapture-compose:0.8.+' implementation 'com.contentsquare.android:library:4.39.1' implementation 'com.contentsquare.android:sdk-compose:4.39.1' implementation 'com.contentsquare.android:sdk:1.12.1' implementation 'com.contentsquare.android:sdk-compose:1.12.1' ``` Migrating from CSQ SDK 0.x? Update the versions for both dependencies. Skip the Heap dependency lines. All other steps in this guide still apply. * Kotlin **build.gradle.kts** ```diff implementation("com.contentsquare.android:sdk:0.11.1") implementation("com.contentsquare.android:sdk-compose:0.11.1") implementation("com.contentsquare.android:sdk:1.12.1") implementation("com.contentsquare.android:sdk-compose:1.12.1") ``` * Groovy **build.gradle** ```diff implementation 'com.contentsquare.android:sdk:0.11.1' implementation 'com.contentsquare.android:sdk-compose:0.11.1' implementation 'com.contentsquare.android:sdk:1.12.1' implementation 'com.contentsquare.android:sdk-compose:1.12.1' ``` ## Library imports Replace the Heap and Contentsquare dependency imports with a CSQ SDK import. ```diff import io.heap.core.Heap import io.heap.autocapture.ViewAutocaptureSDK import io.heap.contentsquare.csbridge.HeapContentsquareIntegration import com.contentsquare.android.Contentsquare import com.contentsquare.CSQ ``` ## SDK start Follow these steps to start the CSQ SDK with your current configuration. 1. Delete `Heap.startRecording()` and migrate configuration options to `CSQ.start()`. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() Heap.startRecording( context = this, "YOUR_ENVIRONMENT_ID", Options( // ...options ) ) CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() Heap.startRecording( context = this, "YOUR_ENVIRONMENT_ID", Options( // ...options ) ) CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options ) ) ) } } ``` Deprecated configuration options The following Heap SDK configuration options are not supported in the CSQ SDK: * `startSessionImmediately` * `disableInteractionTextCapture` * `disableInteractionAccessibilityLabelCapture` * `captureVendorId` * `captureAdvertiserId` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `resumePreviousSession` * `pruningLookBackWindow` * `maximumDatabaseSize` * `maximumBatchCountPerUpload` * `disableUploadsInBackground` See [supported options](../command-reference/#sdk-configuration-options) for more information. 2. Enable Autocapture with `enableViewAutocapture = true` and remove the call to `ViewAutocaptureSDK.register()` * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() ViewAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() ViewAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` 3. (Optional) For Autocapture Jetpack Compose, register the Compose Autocapture SDK. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import io.heap.autocapture.compose.ComposeAutocaptureSDK class MyApplication : Application() { override fun onCreate() { super.onCreate() ComposeAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import io.heap.autocapture.compose.ComposeAutocaptureSDK class MyApplication : Application() { override fun onCreate() { super.onCreate() ComposeAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` 4. Remove `HeapContentsquareIntegration.bind()`. Sending Heap screenviews to Contentsquare **MyApplication.kt** ```kotlin HeapContentsquareIntegration.bind( applicationContext, sendHeapPageviewsToContentsquare = true, sendContentsquareScreenviewsToHeap = false ) ``` Note Make sure you don't have calls to `CSQ.trackScreenview()` if you have Android View autocapture enabled. Sending Contentsquare screenviews to Heap * Product Analytics **MyApplication.kt** ```kotlin HeapContentsquareIntegration.bind( applicationContext, sendHeapPageviewsToContentsquare = false, sendContentsquareScreenviewsToHeap = true ) CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( disablePageviewAutocapture = true ) ) ) ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin HeapContentsquareIntegration.bind( applicationContext, sendHeapPageviewsToContentsquare = false, sendContentsquareScreenviewsToHeap = true ) CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( disablePageviewAutocapture = true ) ) ) ``` 5. (Optional) For Autocapture notifications, replace `NotificationAutocaptureSDK.register()` with these options: * Product Analytics **MyApplication.kt** ```kotlin NotificationAutocaptureSDK.register( captureTitleText = true, captureBodyText = true ) CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options enablePushNotificationAutocapture = true, enablePushNotificationTitleAutocapture = true, enablePushNotificationBodyAutocapture = true ) ) ) ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin NotificationAutocaptureSDK.register( captureTitleText = true, captureBodyText = true ) CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options enablePushNotificationAutocapture = true, enablePushNotificationTitleAutocapture = true, enablePushNotificationBodyAutocapture = true ) ) ) ``` 6. (Optional) If you have chosen to deactivate the autostart of the Contentsquare SDK, you can now remove the entry in the manifest, as the CSQ SDK doesn't have an autostart. **AndroidManifest.xml** ```xml <application> ... <meta-data android:name="com.contentsquare.android.autostart" android:value="false" /> ... </application> ``` ## Get user consent Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more. Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code. ## Transactions 1. Update your transaction imports: ```diff import com.contentsquare.android.api.model.Transaction import com.contentsquare.api.model.Transaction ``` 2. Update your currency imports: ```diff import com.contentsquare.android.api.Currencies import com.contentsquare.api.model.Currency ``` 3. Replace the currency type from `Int` to `Currency` enum: ```diff val currency: Int = Currencies.USD val currency: Currency = Currency.USD ``` 4. Replace `Transaction.builder` by `Transaction` and `Contentsquare.send()` by `CSQ.trackTransaction()`: ```diff val builder = Transaction.builder(100f, Currency.EUR).id("optionalId") Contentsquare.send(builder.build()) val transaction = Transaction(100f, Currency.EUR, "optionalId") CSQ.trackTransaction(transaction) ``` ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. ```diff Contentsquare.start(this) Heap.startRecording("YOUR_ENVIRONMENT_ID") CSQ.start(this, StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")) ``` The latest version of our CSQ SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. For more information on SDK methods, see the [SDK API reference](../command-reference/). ### Product Analytics ### GDPR / Identification | Heap Core SDK | CSQ SDK | | - | - | | `Heap.identify(identity: String)` | `CSQ.identify(identity: String)` | | `Heap.resetIdentity()` | `CSQ.resetIdentity()` | | `Heap.getUserId()` | `CSQ.metadata.userId` | | `Heap.getSessionId()` | `CSQ.metadata.sessionId` | | `Heap.getEnvironmentId()` | `CSQ.metadata.environmentId` | | `Heap.getIdentity()` | `CSQ.metadata.identity` | ### Logging | Heap Core SDK | CSQ SDK | | - | - | | `import io.heap.core.logs.LogLevel` | `import com.contentsquare.api.contract.LogLevel` | | `Heap.setLogLevel()` | `CSQ.debug.logLevel = LogLevel.{LEVEL}` Possible values: - `LogLevel.NONE` - `LogLevel.TRACE` - `LogLevel.DEBUG` - `LogLevel.INFO` - `LogLevel.WARN` - `LogLevel.ERROR` | | `import io.heap.core.logs.LogChannel` | `import com.contentsquare.api.contract.LogChannel` | | `Heap.setLogChannel(logChannel: LogChannel)` | `interface LogChannel` `CSQ.debug.logChannel = LogChannel()` | ### Property tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.addUserProperties(properties: Map<String, Any>)` | `CSQ.addUserProperties(properties: Map<String, Any>)` | | `Heap.addEventProperties(properties: Map<String, Any>)` | `CSQ.addEventProperties(properties: Map<String, Any>)` | | `Heap.removeEventProperty(name: String)` | `CSQ.removeEventProperty(name: String)` | | `Heap.clearEventProperties()` | `CSQ.clearEventProperties()` | | `import io.heap.core.api.contract.HeapProperty` | `import com.contentsquare.api.contract.Property` | ### Event tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.trackPageview()` | `CSQ.trackScreenview(name: String, customVars: List<CustomVar>)` | | `Heap.track()` | `CSQ.trackEvent(name: String, properties: Map<String, PropertyValue>?)` | ### Personal Data Handling and Masking | Heap Core SDK | CSQ SDK | | - | - | | `ViewAutocaptureSDK.ignoreInteractions(view: View)` | `CSQ.ignoreInteractions(view: View, includeSubtree: Boolean)` | | `ViewAutocaptureSDK.redactText(view: View)` | `CSQ.mask(view: View)` | | `view.setTag(R.id.heapRedactText, false)` | `CSQ.unmask(view: View)` | | Initialization options `disableInteractionTextCapture` and `disableInteractionAccessibilityLabelCapture` | `CSQ.maskTexts(mask: Boolean)` | Kotlin extension functions If you use Kotlin, the CSQ SDK comes with Extension functions for: * `CSQ.ignoreInteractions(view: View, includeSubtree: Boolean)` -> `View.csqIgnoreInteractions(includeSubtree: Boolean)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(true)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(false)` ### Jetpack compose | Heap Core SDK | CSQ SDK | | - | - | | ``` @Composable HeapRedact(redact: Boolean) ``` | ``` @Composable CsqMask(enable: Boolean) ``` | | ``` @Composable HeapIgnore(ignore: Boolean) ``` | ``` @Composable CsqIgnoreInteraction(ignore: Boolean) ``` | ### SDK initialization and manipulation | Heap Core SDK | CSQ SDK | | - | - | | `import io.heap.core.Options` | `import com.contentsquare.api.model.AnalyticsOptions` | | Heap SDK initialization options | `CSQ.start(context, StartConfig.withEnvironmentId(id = "envId", options = AnalyticsOptions()))` See [supported options](../command-reference/#sdk-configuration-options) for more information. | | `Heap.startRecording(context: Context, envId: String, options: Options)` | `CSQ.start(context, StartConfig.withEnvironmentId(id = "envId", options = AnalyticsOptions()))` | | `Heap.startRecording(context: Context, envId: String, options: Options)` with `resumePreviousSession = true` | `CSQ.resumeTracking()` | | `Heap.stopRecording()` | `CSQ.stop()` or `CSQ.pauseTracking()` | | `Heap.stopRecording(deleteUser = true)` | `CSQ.stop()` + `CSQ.optOut()` | ### Experience Analytics ### GDPR / Identification | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.optIn(context: Context)` | `CSQ.optIn()` | | `Contentsquare.optOut(context: Context)` | `CSQ.optOut()` | | `Contentsquare.getUserId()` | `CSQ.metadata.userId` | | `Contentsquare.getProjectId()` | `CSQ.metadata.projectId` | | `Contentsquare.getSessionNumber()` | `CSQ.metadata.sessionId` | | `Contentsquare.sendUserIdentifier(identifier: String)` | `CSQ.sendUserIdentifier(identifier: String)` | ### Property tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.send(key: String, value: Long)` | `CSQ.addDynamicVar(key: String, value: Long)` | | `Contentsquare.send(key: String, value: String)` | `CSQ.addDynamicVar(key: String, value: String)` | ### View tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.excludeFromExposureMetric(view: View)` | `CSQ.excludeFromExposureMetric(view: View)` | ### Interoperability | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.onSessionReplayLinkChange(callback: Consumer<String>)` | `CSQ.metadata.onChanged(metadata: Metadata)` | | `CsWebViewManager.injectEventTrackingInterface(webView: WebView)` | `CSQ.registerWebView(webView: WebView)` | | `CsWebViewManager.removeEventTrackingInterface(webView: WebView)` | `CSQ.unregisterWebView(webView: WebView)` | ### Event tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.send(transaction: Transaction)` | `CSQ.trackTransaction(transaction: Transaction)` | | `Contentsquare.send(screenName: String)` / `Contentsquare.send(screenName: String, customVars: Array<CustomVar>)` | `CSQ.trackScreenview(name: String, customVars: List<CustomVar>)` | | `Contentsquare.consumeEvent(motionEvent: MotionEvent)` | `CSQ.trackMotionEvent(motionEvent: MotionEvent)` | Jetpack compose | Contentsquare SDK | CSQ SDK | | - | - | | `import com.contentsquare.android.compose.analytics.TriggeredOnResume` `TriggeredOnResume(block: () -> Unit)` | `import com.contentsquare.api.compose.screen.TriggeredOnResume` `TriggeredOnResume(block: () -> Unit)` | ### Error tracking | Contentsquare SDK | CSQ SDK | | - | - | | `import com.contentsquare.android.error.analysis.network.ErrorAnalysisInterceptor` | `import com.contentsquare.api.contract.CsqOkHttpInterceptor` | | `import com.contentsquare.android.error.analysis.ErrorAnalysis` | `import com.contentsquare.api.model.NetworkMetric` | | `ErrorAnalysis.setUrlMaskingPatterns(patterns: List<String>)` | `CSQ.setUrlMaskingPatterns(patterns: List<String>)` | | `ErrorAnalysis.getInstance().newNetworkMetric(url: String, httpMethod: HttpMethod)` | `NetworkMetric(url: String, httpMethod: HttpMethod)` | | `ErrorAnalysisInterceptor()` | `CsqOkHttpInterceptor()` | ### Personal Data Handling and Masking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.doNotTrack(vararg activitiesClasses: Class<Activity?>)` | `CSQ.ignoreInteractions(view: View)` | | `Contentsquare.setDefaultMasking(masked: Boolean)` | `CSQ.setDefaultMasking(masked: Boolean)` | | `Contentsquare.mask(view: View)` | `CSQ.mask(view: View)` | | `Contentsquare.mask(type: Class<*>)` | `CSQ.mask(type: Class<*>)` | | `Contentsquare.unMask(view: View)` | `CSQ.unmask(view: View)` | | `Contentsquare.unmask(type: Class<*>)` | `CSQ.unmask(type: Class<*>)` | | `Contentsquare.maskMenuItem(resourceID: Int)` | `CSQ.maskMenuItem(resourceID: Int)` | | `Contentsquare.unMaskMenuItem(resourceID: Int)` | `CSQ.unmaskMenuItem(resourceID: Int)` | Kotlin extension functions If you use Kotlin, the CSQ SDK comes with Extension functions for: * `CSQ.ignoreInteractions(view: View, includeSubtree: Boolean)` -> `View.csqIgnoreInteractions(includeSubtree: Boolean)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(true)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(false)` ### Jetpack compose | Contentsquare SDK | CSQ SDK | | - | - | | `Modifier.sessionReplayMask(enableMasking: Boolean)` | `@Composable CsqMask(enable: Boolean) { }` | | `Modifier.excludeFromGestureRecognition()` | `@Composable CsqIgnoreInteraction(ignore: Boolean)` | ### SDK initialization and manipulation | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.start(context: Context)` | `CSQ.start(context: Context)` | | `Contentsquare.stopTracking()` | `CSQ.pauseTracking()` | | `Contentsquare.resumeTracking()` | `CSQ.resumeTracking()` | ## Number of sessions Session timeout definition changed: * **Before**: 30 minutes after app goes to background * **Now**: 30 minutes after last event This may affect session counts and aligns with web and market standards. ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that your build files no longer reference `io.heap.core:heap-android-core`, `io.heap.autocapture:heap-autocapture-view`, `com.contentsquare.android:library`, or `com.contentsquare.android:sdk-compose`. Your `import io.heap.core.Heap`, `import io.heap.autocapture.ViewAutocaptureSDK`, and `com.contentsquare.android.Contentsquare;` declarations have been updated to `import com.contentsquare.CSQ`. You no longer have references to `Heap.` (except if you are using webviews), `HeapContentsquareIntegration.`, or `Contentsquare.` methods in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK + Contentsquare SDK to CSQ SDK","description":"Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-heap-and-cs-sdk/","inLanguage":"en","dateModified":"2026-06-05T17:39:25+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Upgrade your SDK - Android description: Understand the benefits of upgrading to the CSQ SDK lastUpdated: 12 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-your-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-your-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-android/experience-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This section guides you through the upgrade from your current SDK implementation to our latest CSQ SDK. Upgrading has no impact on your current data collection and does not alter the data observed on the platform. It mainly consists of searching and replacing APIs according to the mappings provided in the upgrade guides. Get started by selecting the upgrade guide that corresponds to your current implementation: * **[Contentsquare SDK](../upgrade-from-cs-sdk/)** - Upgrade from the legacy Contentsquare SDK * **[Heap SDK + Contentsquare SDK](../upgrade-from-heap-and-cs-sdk/)** - Upgrade from combined Heap and Contentsquare SDKs ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Upgrade your SDK","description":"Understand the benefits of upgrading to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-your-sdk/","inLanguage":"en","dateModified":"2026-05-12T12:05:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Agent skills for Android - Android description: Use AI coding assistants to integrate, upgrade, and configure the Contentsquare Android SDK with downloadable Agent skills lastUpdated: 16 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/using-agent-skills/ md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/using-agent-skills/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use the Contentsquare wizard or skills to set up, update, and configure Android with your AI coding assistant. Disclaimer This skill guides your AI coding agent through the SDK installation and implementation. The agent you use (Cursor, Claude Code, Copilot) is your own tool and operates under your settings and permissions. Contentsquare is not responsible for how your agent interprets or applies the instructions contained in these files. ## Contentsquare wizard Run the wizard in your project directory. It configures your AI coding assistant, installs the matching Contentsquare integration, and verifies the installation. ```shell npx @contentsquare/wizard install ``` Supports GitHub Copilot, Cursor, and Claude Code. Requires Node.js ≥ 18 and an AI coding agent with MCP support. ## Manual setup Use this path when you prefer to configure your AI coding assistant yourself. ### 1. Add the Contentsquare skill Choose how to install the Contentsquare skill. * Copilot CLI Add the Contentsquare marketplace, then install the plugin for Android: ```shell copilot plugin marketplace add ContentSquare/agents copilot plugin install contentsquare-android@contentsquare ``` * Claude Code Add the Contentsquare marketplace, then install the plugin for Android: ```shell /plugin marketplace add ContentSquare/agents /plugin install contentsquare-android@contentsquare ``` * Cursor Install **contentsquare** from the [Cursor marketplace ↗](https://cursor.com/marketplace), or add the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents) directly. Cursor reads the `.cursor-plugin` catalog in the repository. * Other agents Install the Contentsquare skill pack with the open `skills.sh` ecosystem: ```shell npx skills add contentsquare/agents ``` * From source Download or clone the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents), then copy `skills/contentsquare-android-sdk` into the location your AI coding assistant scans for skills: | AI coding assistant | Skill location | | - | - | | GitHub Copilot | `.github/skills/` or `.agents/skills/` | | Cursor | `.cursor/rules/` or the project root | | Claude Code | `.claude/skills/` or the project root | | Other compatible agents | `.agents/skills/` | ### 2. Ask your AI coding assistant After installing the skill, paste this prompt into your AI coding assistant: ```text Install Contentsquare for Android. ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Agent skills for Android","description":"Use AI coding assistants to integrate, upgrade, and configure the Contentsquare Android SDK with downloadable Agent skills","url":"https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/using-agent-skills/","inLanguage":"en","dateModified":"2026-07-16T17:50:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - Android description: The Contentsquare Android SDK changelog lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/changelog/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. 📬 Stay updated! ## Opt-in to CSQ Experience Platform Already using the CSQ SDK in standalone mode? Follow these steps to switch to CSQ Experience Platform and combine Experience Analytics and Product Analytics under a single data source. CSQ Experience Platform is currently an Early Access program. To gain access, contact your Customer Success Manager. CSQ Experience Platform guidance Throughout the documentation, code samples highlight differences between standalone and CSQ Experience Platform integrations.  1. [Update the SDK package to 1.10.1 or later](../#install-the-sdk). 2. Replace your current `CSQ.start(this)` or `CSQ.start(this, StartConfig.withEnvironmentId(...))` call with the `dataSourceId` provided by your Customer Success Manager. This links your app to the CSQ Experience Platform data source. **MyApplication.kt** ```kotlin CSQ.start(this, StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")) ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 3. Review changes [introduced in 1.10.0](#1100---20260504) which notably removes support for several Product Analytics options. ## 1.12.1 - 2026.08.06 Experience Analytics * Update Experience Analytics SDK version to `4.52.1`: * **Analytics** * Extended `ignoreInteractions` API for single Views only * **Bug fix:** Added missing support for custom views inheriting from WebView * **WebViews** * **Bug fix:** fixing duplicate taps for WebView child classes * **Core** * **Bug fix:** no more install and upgrade event fired on every app relaunch * **Bug fix:** resolved a ANR issue when migrating from CSQ SDK before 1.10.0 * **Bug fix:** resolved a crash when migrating from CSQ SDK before 1.10.0 * **Bug fix:** resolved a few memory leaks * **Bug fix:** resolved a build failure when referencing CSQ.metadata * **Bug fix:** avoid crash due to malformed environment and datasource ID * **Session Replay** * Improved Image capture for Coil libraries on Jetpack Compose * Improved capture synchronization to capture screen transitions * **Bug fix:** resolved a few memory leaks when a dialog is captured Product Analytics * Update Product Analytics Core SDK version to `0.9.5`. * Update Product Analytics Autocapture SDK version to `0.9.5`. * Adds support for the latest Jetpack Compose BOM. * **Bug fix:** fixes an issue where certain overlays were not removed from the composition correctly. * **Bug fix:** fixes an issue that prevented notification autocapture from capturing some notifications as expected ## 1.12.0 - 2026.07.27 Experience Analytics * Update Experience Analytics SDK version to `4.52.0`: * **Analytics** * Added support for Android multi-window mode and activity resizing * Added support for screenshots when using PA autocapture screenviews only * **Bug fix:** Fixed background issue for WebViews embedded in Jetpack Compose * **Session Replay** * Improved Image capture for Jetpack Compose * **Bug fix:** Fixed an issue detecting Jetpack Compose bottom sheet position * **Bug fix:** Prevent potential Personal Data leaks on some scrollable containers on Jetpack Compose * **WebViews** * **Bug fix:** fixed a synchronisation issue that could result in a "Webview Not Tracked" in the Session Replay Player * **Bug fix:** fixed an issue where coming back from background into a webview would result in a "Webview Not Tracked" in the Session Replay Player Product Analytics * Update Product Analytics Core SDK version to `0.9.4`. * Update Product Analytics Autocapture SDK version to `0.9.4`. ## 1.11.2 - 2026.07.03 Experience Analytics * Update Experience Analytics SDK version to `4.51.2`: * **Analytics** * **Bug fix:** Ensured gesture listener attachment is executed on the main thread to prevent potential crashes on some screens. * **Session Replay** * Optimized Session Replay to degrade the capture rate to 1 FPS instead of stopping completely when main thread performance impact is detected. * **Bug fix:** Fixed an issue where Session Replay could fail to start when used with Autocapture. * **WebViews** * **Bug fix:** Aligned native Android behavior to respect the server-side kill-switch for disabling tag injection in WebViews. * **Bug fix:** Fixed a crash that could occur when registering or unregistering WebViews before the SDK is fully initialized. Product Analytics * Update Product Analytics Core SDK version to `0.9.3`. * Update Product Analytics Autocapture SDK version to `0.9.3`. ## 1.11.1 - 2026.06.29 Experience Analytics * Update Experience Analytics SDK version to `4.51.1`: * **Core** * **Bug fix:** Fixed an issue where the configured sampling rate could be ignored in some rare cases ## 1.11.0 - 2026.06.05 Experience Analytics * Update Experience Analytics SDK version to `4.51.0`: * **Core** * **Security** Resolved a security vulnerability where the SDK's deeplink feature could be exploited via crafted deeplinks to arbitrarily modify SDK configuration. * **Bug fix:** Fixed persisting PA-DXA session synchronization issues where session counts and screen quantities diverged between DXA and PA collection. * **Analytics** * **Bug fix:** Fixed an issue where screenshot can not be generated when tracking is paused. * **Session Replay** * Session Replay can now resume collection within the same session after a performance-based stop, restarting at LOW quality and re-evaluating start/stop rules. * Compose capture robustness work, foundation for better SR capture in Compose-heavy apps tied to harmonized masking. * Removed obsolete MultiWindow Feature Flag as the newer image processor rollout progresses. * **Bug fix:** Fixed an issue where button text disappeared in the live app but was correctly captured in the Session Replay. * **Bug fix:** Fixed missing images in Session Replay for Compose apps when harmonized masking is enabled . * **Bug fix:** Addressing Session Replay rendering issues where certain screens display only wide empty elements instead of actual content. Product Analytics * Update Product Analytics Core SDK version to `0.9.2`. * Update Product Analytics Autocapture SDK version to `0.9.1`. ## 1.10.1 - 2026.05.05 Product Analytics * Fixed an issue where Product Analytics could fail to start when the remote config is unavailable, causing the opt-in call to be ignored. ## 1.10.0 - 2026.05.04 Experience Analytics * Update Experience Analytics SDK version to `4.50.0`: * The Session timeout definition changes from "30 minutes after being in background" to **30 minutes after last event**. See [Session definition](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/data-collection/#session-definition). Product Analytics * Update Product Analytics Core SDK version to `0.9.0`. * Update Product Analytics Autocapture SDK version to `0.9.0`. ### Configuration **API update:** `CSQ.start()` now takes a `StartConfig` wrapping the environment ID and options. `ProductAnalyticsOptions` is renamed to `AnalyticsOptions` and `envID` to `id`. ```kotlin CSQ.configureProductAnalytics( context = this, envId = "YOUR_ENVIRONMENT_ID", options = ProductAnalyticsOptions( enableViewAutocapture = true ) ) CSQ.start(this) CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true ) ) ) ``` ### Options **Added:** `sessionReplayAutoStart` — set to `false` to disable automatic Session Replay start and control it manually. Defaults to `true`. ```kotlin CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions(sessionReplayAutoStart = false) ) ) ``` **Removed:** `captureVendorId`, `captureAdvertiserId`, `clearEventPropertiesOnNewUser`, `messageBatchMessageLimit`, `resumePreviousSession`, `pruningLookBackWindow`, `maximumDatabaseSize`, `maximumBatchCountPerUpload`, `disableUploadsInBackground`, `disableScreenviewForwardToDXA`, and `disableScreenviewForwardToPA` are no longer available. Remove them from your `CSQ.start()` call if present: ```kotlin CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( captureVendorId = true, captureAdvertiserId = true, clearEventPropertiesOnNewUser = true, messageBatchMessageLimit = 100, resumePreviousSession = true, pruningLookBackWindow = 6, maximumDatabaseSize = 200_000, maximumBatchCountPerUpload = 10, disableUploadsInBackground = true, disableScreenviewForwardToDXA = true, disableScreenviewForwardToPA = true, ) ) ) ``` ### APIs * **Breaking change:** `CSQ.optIn(context: Context)` deprecated API has been removed, use `CSQ.optIn()` (no context parameter required). ### Agent skills Contentsquare now provides [Agent skills for Android](https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/using-agent-skills/) — structured files that let AI coding assistants such as GitHub Copilot, Cursor, and Claude Code integrate, upgrade, and configure the SDK automatically. ## 1.5.3 - 2026.06.25 Experience Analytics * Update Experience Analytics SDK version to `4.44.2`: * **Analytics** * **Bug fix:** Prevent crash in `ViewTreeObserver.dispatchOnPreDraw()` ## 1.5.2 - 2026.04.1 Experience Analytics * Update Product Analytics Core SDK version to `0.8.10`. * Update Product Analytics Autocapture SDK version to `0.8.12`. ## 1.5.1 - 2026.03.05 Experience Analytics * Update Experience Analytics SDK version to `4.44.1`: * **Analytics** * **Bug fix:** Improved invisible overlay detection to resolve an issue where long screenshots were not scrollable * **Bug fix:** Fixed duplicate tap event in tracked WebViews * Update Product Analytics Core SDK version to `0.8.9`. ## 1.5.0 - 2026.02.18 Experience Analytics * Update Experience Analytics SDK version to `4.44.0`: * **Session Replay** * Improve UI change detection to prevent unplayable screens * **Bug fix:** improve synchronisation of session between Heap and Contentsquare * **Bug fix:** resolved an internal `java.util.ConcurrentModificationException` * **Bug fix:** resolved an internal `java.lang.NullPointerException` * **Bug fix:** improve masking stability * **Errors** * Now setUrlMaskingPatterns can be called before the SDK start * OkHttp 5 compatibility with Network Plugin 1.7.0 * Sanity checked added to URL masking patterns resolving a `java.util.regex.PatternSyntaxException` * **Bug fix:** validate URL patterns when setUrlMaskingPatterns is called * Update Product Analytics Core SDK version to `0.8.8`. * Update Product Analytics Autocapture SDK version to `0.8.10`. ## 1.4.7 - 2026.01.05 Experience Analytics * Update Experience Analytics SDK version to `4.43.8`: * **Errors** * Fixed API Error URL not masked until SDK is fully initialized ## 1.4.6 - 2026.01.02 Experience Analytics * Update Experience Analytics SDK version to `4.43.7`: * **Session Replay** * **Bug fix:** resolved a masking issues when multi-window is enabled ## 1.4.5 - 2025.12.26 Experience Analytics * Update Experience Analytics SDK version to `4.43.6`: * **Core** * **Bug fix:** resolves crash in WindowCallbackWrapper ## 1.4.4 - 2025.12.19 Experience Analytics * Update Experience Analytics SDK version to `4.43.5`: * **Analytics** * Add support of material `ModalBottomSheetLayout` for Zoning and Heatmap analysis, using the `CsqTag()` API * **Core** * Improve compatibility with DexGuard ## 1.4.3 - 2025.12.16 Experience Analytics * Update Experience Analytics SDK version to `4.43.4`: * **Session Replay** * **Bug fix:** Improve memory management to avoid memory leak * **Bug fix:** Prevent crash during activity destroy process * **Analytics** * **Bug fix:** Fixed an issue where heatmap positions were not tracked correctly on some Compose screens with lazy scroll elements. * **Bug fix:** Improved invisible overlay detection to resolve an issue where long screenshots were not scrollable. * **Core** * Migrated from Android `ContentProvider` to AndroidX Startup for initialization * **Bug fix:** Resolved `java.lang.NullPointerException` crash on `FileProvider` ## 1.4.2 - 2025.11.28 Experience Analytics * Update Experience Analytics SDK version to `4.43.3`: * **Zoning Analytics** * CsqIgnoreInteraction() now excludes wrapped Composable from the screenshot ## 1.4.1 - 2025.11.24 Experience Analytics * Update Experience Analytics SDK version to `4.43.2`: * **Session Replay** * **Bug fix:** Resolved `java.util.ConcurrentModificationException` crash on Session Replay touch listener. * **Analytics** * **Bug fix:** Resolved `java.lang.ArrayIndexOutOfBoundsException` crash with Exposure Metrics. * **Core** * Improved SDK initialization performance by moving certain operations off the main thread Product Analytics * Update Product Analytics Core SDK version to `0.8.7`. * Update Product Analytics Autocapture SDK version to `0.8.9`. ## 1.4.0 - 2025.11.13 Experience Analytics * Update Experience Analytics SDK version to `4.43.0`: * **Analytics** * Fixed an issue where screenshot button was not visible after visiting In-app settings. * Fixed compatibility issues with Jetpack Compose 1.10. * **Session Replay** * Improved gesture detection to reliably identify the targeted view. Product Analytics * Update Product Analytics Core SDK version to `0.8.6`. ## 1.3.0 - 2025.10.20 * **Webviews** * The One WebView Tag feature is now available in controlled general availability. It brings key Product Analytics features — Identity, User Properties, Hierarchy, and Target Text — to WebViews, enabling unified Product Analytics and Experience Analytics. To gain access, contact your Customer Success Manager to be added to the eligibility list. ## 1.2.1 - 2025.10.07 Experience Analytics * Update Experience Analytics SDK version to `4.41.1`: * Analytics * Fixed a crash when Jetpack Compose Node is not attached * **Session Replay** * Fixed a bug that cause parent masking not being propagated to child views on some scenarios * Improve capture of Native views inside Jetpack Compose Product Analytics * Update Product Analytics Core SDK version to `0.8.5`. * Update Product Analytics Autocapture SDK version to `0.8.8`. ## 1.2.0 - 2025.09.05 Experience Analytics * Update Experience Analytics SDK version to `4.41.0`: * Analytics * **Bug fix:** Fixed an issue when the very first item of a RecyclerView is bigger than the scrollable area * Core * **Bug fix:** Fixed an issue when the very first item of a RecyclerView is bigger than the scrollable area Product Analytics * Update Product Analytics Core SDK version to `0.8.4`. * Update Product Analytics Autocapture SDK version to `0.8.7`. ## 1.1.0 - 2025.08.04 Experience Analytics * Update Experience Analytics SDK version to `4.40.0`: * Session Replay * Image and Text masking configuration in the CSQ Console * Added new APIs to start Session Replay on demand * Added new APIs to support Event-Triggered Replays * Analytics * **Bug fix:** Fixed a potential crash when generating scroll metrics on certain Compose screens * Improve heatmap data accuracy for Compose lazy lists and grids Product Analytics * Update Product Analytics Core SDK version to `0.8.3`. * Update Product Analytics Autocapture SDK version to `0.8.6`. ## 1.0.1 - 2025.07.02 Experience Analytics * Update Experience Analytics SDK version to `4.39.3`: * Session Replay * **Bug fix:** Fix blank screens in Jetpack Compose when the dialogs and bottom sheets capture was enabled. * **Bug fix:** Fixed an issue causing an inconsistent Tag injection for Webviews in Capacitor apps. * **Bug fix:** Fixed an issue causing unreliable Session Replay starts in Capacitor apps. * Improved Session Replay screen change consistency on Capacitor apps ## 1.0.0 - 2025.06.27 Initial release of the CSQ SDK. * Introduces the unified CSQ API, which combines Product Analytics, Experience Analytics, and Monitoring features into a single, cohesive library. * This initial release includes: * Experience Analytics SDK version `4.39.2`. * Product Analytics Core SDK version `0.8.2`. * Product Analytics Autocapture SDK version `0.8.3`. Upgrade to CSQ SDK 1.+ Looking to upgrade from CSQ SDK 0.x to the latest? See the [upgrade guide](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-heap-and-cs-sdk/). ## 0.11.1 - 2026.03.03 * Update Experience Analytics SDK version to [`4.44.1`](https://docs.contentsquare.com/en/android/changelog/#4441---20260303). * Update Product Analytics [Core `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.10` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.10` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.11.0 - 2026.02.18 * Update Experience Analytics SDK version to [`4.44.0`](https://docs.contentsquare.com/en/android/changelog/#4440---20260217). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.10` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.10` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.6 - 2026.01.05 * Update Experience Analytics SDK version to [`4.43.8`](https://docs.contentsquare.com/en/android/changelog/#4438---20260105). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.5 - 2026.01.02 * Update Experience Analytics SDK version to [`4.43.7`](https://docs.contentsquare.com/en/android/changelog/#4437---20260102). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.4 - 2025.12.26 * Update Experience Analytics SDK version to [`4.43.6`](https://docs.contentsquare.com/en/android/changelog/#4436---20251226). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.3 - 2025.12.22 * Update Experience Analytics SDK version to [`4.43.5`](https://docs.contentsquare.com/en/android/changelog/#4435---20251219). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.2 - 2025.12.16 * Update Experience Analytics SDK version to [`4.43.4`](https://docs.contentsquare.com/en/android/changelog/#4434---20251216). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.1 - 2025.11.24 * Update Experience Analytics SDK version to [`4.43.2`](https://docs.contentsquare.com/en/android/changelog/#4432---20251124). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.9` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.10.0 - 2025.11.13 * Update Experience Analytics SDK version to [`4.43.0`](https://docs.contentsquare.com/en/android/changelog/#4430---20251113). * Update Product Analytics [Core `0.8.6` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.8` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.8` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.9.1 - 2025.10.07 * Update Experience Analytics SDK version to [`4.41.1`](https://docs.contentsquare.com/en/android/changelog/#4411---20251007). * Update Product Analytics [Core `0.8.5` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.8` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.8` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.8.0 - 2025.08.04 * Update Experience Analytics SDK version to [`4.40.0`](https://docs.contentsquare.com/en/android/changelog/#4400---20250801). * Update Product Analytics [Core `0.8.3` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.6` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.6` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.7.2 - 2025.07.09 * Update Experience Analytics SDK version to [`4.39.3`](https://docs.contentsquare.com/en/android/changelog/#4393---20250701). * Update Product Analytics [Core `0.8.2` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.3` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.3` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.7.1 - 2025.05.16 * Update Experience Analytics SDK version to [`4.38.2`](https://docs.contentsquare.com/en/android/changelog/#4382---20250516). * Update Product Analytics [Core `0.8.1` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.2` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.2` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.7.0 - 2025.05.09 * Update Experience Analytics SDK version to [`4.38.1`](https://docs.contentsquare.com/en/android/changelog/#4381---20250430). * Update Product Analytics [Core `0.8.1` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.2` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.2` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.6.0 - 2025.04.03 * Update Experience Analytics SDK version to [`4.37.0`](https://docs.contentsquare.com/en/android/changelog/#4370---20250402). * Update Product Analytics [Core `0.8.0` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.5.1 - 2025.03.13 * Update Experience Analytics SDK version to [`4.36.1`](https://docs.contentsquare.com/en/android/changelog/#4361---20250313). * Update Product Analytics [Core `0.7.6` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.7.7` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.7.7` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.5.0 - 2025.02.13 * Update Experience Analytics SDK version to [`4.36.0`](https://docs.contentsquare.com/en/android/changelog/#4360---20250210). * Update Product Analytics [Core `0.7.6` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.7.5` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.7.5` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.4.0 - 2025.01.07 * Update Experience Analytics SDK version to [`4.35.0`](https://docs.contentsquare.com/en/android/changelog/#4350---20250102). * Update Product Analytics [Core `0.7.5` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.7.3` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.7.3` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.3.0 - 2024.10.25 * Update Experience Analytics SDK version to [`4.34.0`](https://docs.contentsquare.com/en/android/changelog/#4340---20241025). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.7.1` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.7.1` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.2.0 - 2024.10.18 * Update Experience Analytics SDK version to [`4.33.2`](https://docs.contentsquare.com/en/android/changelog/#4332---20241018). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.7.1` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.7.1` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.1.1 - 2024.09.10 * Update Experience Analytics SDK version to [`4.32.1`](https://docs.contentsquare.com/en/android/changelog/#4321---20240910). * Update Product Analytics [Core `0.7.1` ↗](https://developers.heap.io/docs/android-changelog#android-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/android-changelog#android-view-autocapture-changelog). ## 0.1.0 - 2024.09.02 * This release marks the introduction of the CSQ SDK which brings together Product Analytics, Experience Analytics, and Monitoring features. From this version onwards, the SDK releases follow a new versioning scheme. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare Android SDK changelog","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/changelog/","inLanguage":"en","dateModified":"2026-07-08T17:11:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: SDK API reference - Android description: SDK commands reference including signature, parameter descriptions, and examples lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/command-reference/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-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). ```kotlin CSQ.optIn() ``` ### CSQ.optOut() **Added in:** `1.0.0` Revoke user consent, remove stored `userId`. Stop CSQ SDK, flush, and clear all data. ```kotlin CSQ.optOut() ``` #### Parameters * #### Context  object   Android [Context object ↗](https://developer.android.com/reference/android/content/Context) ### CSQ.identify() **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. 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`. ```kotlin CSQ.identify(identity: String) ``` #### Parameters * #### identity  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 equivalent to calling [`optOut()`](#csqoptout) then [`optIn()`](#csqoptin). ```kotlin CSQ.resetIdentity() ``` #### Parameters * No parameters. ### CSQ.sendUserIdentifier() **Added in:** `1.0.0` Associate a user identifier to the session. ```kotlin CSQ.sendUserIdentifier(identity: String) ``` #### Parameters * #### identity  String (<= 100 chars)   The string value representing the user identifier to be associated with the current session. Should be max 100 characters long. ### 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. This is an identifier from Product Analytics by default or Experience Analytics if Product Analytics is not active. ```kotlin 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. ```kotlin CSQ.metadata.sessionId ``` #### CSQ.metadata.projectId Project identifier for Experience Analytics. ```kotlin CSQ.metadata.projectId ``` #### CSQ.metadata.environmentId Environment identifier for Product Analytics. ```kotlin CSQ.metadata.environmentId ``` #### CSQ.metadata.sessionReplayUrl URL of current Session Replay. ```kotlin CSQ.metadata.sessionReplayUrl ``` #### CSQ.metadata.identity Identity associated with the user by calling [`identify()`](#csqidentify). ```kotlin CSQ.metadata.identity ``` ### CSQ.metadata.onChanged() **Added in:** `1.0.0` A block triggered each time user information is updated. For example when `sessionReplayUrl` becomes available or `userId` updates. Set this block to subscribe to the updates. Contentsquare will call this block with updated metadata. Note This may not trigger on changes to Product Analytics data. ```kotlin CSQ.metadata.onChanged = OnMetadataChanged { metadata -> // Handle information change } ``` #### Parameters * #### metadata  Metadata   Metadata associated with the current user and project. ## Logging ### CSQ.debug.setLogLevel() **Added in:** `1.0.0` Sets the current log level. ```kotlin CSQ.debug.logLevel = loglevel ``` #### Parameters * #### level  Enum (CSQ.Log.Level)   Possible values: `none`, `trace`, `debug`, `info`, `warn` or `error`. ### CSQ.debug.logChannel() **Added in:** `1.0.0` Add a `LogChannel` to which send log messages. ```kotlin CSQ.debug.logChannel = channel ``` #### Parameters * #### LogChannel  interface   The interface where log messages will be routed. ### LogChannel.printLog() **Added in:** `1.0.0` Routes SDK logs to another location such as Timber, Arbor, or similar logging libraries. The default implementation routes all logs through Logcat. ```kotlin LogChannel.printLog() ``` #### Parameters * No parameters. ## Property Tracking ### CSQ.addDynamicVar() Experience Analytics | **Added in:** `1.0.0` Adds one or multiple dynamic variables to the session properties. This method allows you to pass a `DynamicVar` object, representing a key-value pair that is scoped to the session. ```kotlin val var1 = DynamicVar("key1", "value1") val var2 = DynamicVar("key2", 10L) CSQ.addDynamicVar(var1) CSQ.addDynamicVar(var2) ``` #### Parameters * #### DynamicVar  object   The dynamic variable * #### key  String (<= 512 chars)   Dynamic variable key * #### value  String/Long   Dynamic variable value ### CSQ.addUserProperties() Product Analytics | **Added in:** `1.0.0` Add a collection of properties to be associated with the current user. ```kotlin CSQ.addUserProperties(properties: Map<String, Any>) ``` #### Parameters * #### properties  Map\<String, Any>   A map of user properties. ### CSQ.addEventProperties() Product Analytics | **Added in:** `1.0.0` Add a collection of properties to be associated with all future events. ```kotlin CSQ.addEventProperties(properties: Map<String, Any>) ``` #### Parameters * #### properties  Map\<String, Any>   A map of event properties. * #### key  String   the UserProperty key * #### value  Any   values can be any combination of any `Number`, `Boolean`, `String` or Java/Kotlin object that implements `Property` ### CSQ.removeEventProperty() Product Analytics | **Added in:** `1.0.0` Removes a single property from the collection of event-wide properties. ```kotlin CSQ.removeEventProperty(property: String) ``` #### Parameters * #### property  String   The key of the property to remove. ### CSQ.clearEventProperties() Product Analytics | **Added in:** `1.0.0` Removes all event-wide properties. ```kotlin CSQ.clearEventProperties() ``` ## View Tracking ### CSQ.excludeFromExposureMetric() Experience Analytics | **Added in:** `1.0.0` Exclude a scrollable view or subclass from Exposure Metric computations. Warning iOS-only, applicable on `UIScrollView` or a class inheriting from `UIScrollView`. Android-only application on `ScrollView` & `RecyclerView`. ```kotlin CSQ.excludeFromExposureMetric(View) ``` #### Parameters * #### View  View   The view to exclude from exposure metrics. ### CsqTag() Experience Analytics | **Added in:** `1.4.4` Jetpack Compose composable function for tagging composables that require special handling by SDK. It is used to enable support for material `ModalBottomSheetLayout` in Zoning and Heatmap analysis. ```kotlin enum class CsqTag { ModalBottomSheetLayout } @Composable fun CsqTag(tag: CsqTag, block: @Composable () -> Unit) ``` #### Parameters * #### tag  Enum (CsqTag)   indicates the type of special handling required by the SDK `CsqTag.ModalBottomSheetLayout` - enables the SDK to properly capture and analyze content within a material `ModalBottomSheetLayout` for Zoning and Heatmaps. * #### block  @Composable () -> Unit   the composable lambda representing the UI content to be tagged ## Interoperability ### CSQ.registerWebView() **Added in:** `1.0.0` Register a webview for tracking. ```kotlin CSQ.registerWebView(webView) ``` #### Parameters * #### webView  WebView   The webview to register for tracking. ### CSQ.unregisterWebView() **Added in:** `1.0.0` Unregister a webview for tracking. ```kotlin CSQ.unregisterWebView(webView) ``` #### Parameters * #### webView  WebView   The webview to unregister from tracking. ## Event Tracking ### CSQ.trackTransaction() Experience Analytics | **Added in:** `1.0.0` Send a transaction. ```kotlin CSQ.trackTransaction(Transaction) ``` #### Parameters * #### Transaction  Transaction   The transaction object to be sent. ### CSQ.trackScreenview() **Added in:** `1.0.0` Send a screen view with or without custom variables. ```kotlin CSQ.trackScreenview(name: String, cvars: List<CustomVar> = emptyList()) ``` #### Parameters * #### name  String   The name of the screen. * #### cvars  List\<CustomVar> (optional)   A list of custom variables to attach to the screen view. * #### index  Int (@IntRange(from = 0, to = 20))   A number identifying a CustomVar * #### name  String (<= 512 chars)   Custom variable key * #### value  String   Custom variable value ### CSQ.trackEvent() Product Analytics | **Added in:** `1.0.0` Creates an event message to be tracked and sent to the API. ```kotlin CSQ.trackEvent(name: String, properties: Map<String, Any> = mapOf()) ``` #### Parameters * #### name  String   The name of the event to be tracked. * #### properties  Map\<String, Any> (optional)   Optional properties to associate with the event. ### CSQ.trackMotionEvent() Experience Analytics | **Added in:** `1.0.0` Track a gesture manually. ```kotlin CSQ.trackMotionEvent(motionEvent: MotionEvent) ``` #### Parameters * #### motionEvent  MotionEvent   The [MotionEvent ↗](https://developer.android.com/reference/android/view/MotionEvent) to be tracked. ### TriggeredOnResume() Experience Analytics | **Added in:** `1.0.0` Helper function for Jetpack Compose to ensure only one screen view is triggered when a given screen is presented to the user. ```kotlin @Composable TriggeredOnResume(block: () -> Unit) ``` #### Parameters * #### block  Function   The block of code to run when the screen is resumed. ## Surveys ### CSQ.triggerSurvey() Experience Analytics Voice of Customer | **Added in:** `1.0.0` Triggers a survey by referencing a predefined trigger name. This method allows your mobile app to trigger surveys at specific moments in the user journey. Triggers act as flexible placeholders that are not bound to individual surveys, enabling your business team to assign or update surveys later without requiring code changes. ```kotlin CSQ.triggerSurvey(triggerName: String) ``` #### Parameters * #### triggerName  String   The name of the trigger associated with the survey. This should match the trigger name configured in the Contentsquare platform. #### Example ```kotlin // Trigger a survey after a purchase is completed CSQ.triggerSurvey("purchase-complete") ``` ## Error tracking ### CSQ.setUrlMaskingPatterns() Experience Analytics | **Added in:** `1.0.0` Sets URL masking patterns. ```kotlin CSQ.setUrlMaskingPatterns(patterns: List<String>) ``` #### Parameters * #### patterns  List\<String>   A list of URL patterns to mask. ### CSQ.trackNetworkMetric() Experience Analytics | **Added in:** `1.0.0` Track network metrics. ```kotlin CSQ.trackNetworkMetric(networkMetric: NetworkMetric) ``` #### Parameters * #### networkMetric  NetworkMetric   The network metric to be tracked. ### CsqOkHttpInterceptor() Experience Analytics | **Added in:** `1.0.0` Intercept every OkHttp call to manually collect API errors. ```kotlin val okhttpClient = OkHttpClient().newBuilder() .addInterceptor(CsqOkHttpInterceptor()) .build() ``` ## Personal Data/Masking ### CSQ.ignoreInteractions() **Added in:** `1.0.0` Ignore interactions for a specific view. ```kotlin CSQ.ignoreInteractions(view: View, includeSubtree: Boolean = true) ``` #### Parameters * #### view  View   The view for which interactions should be ignored. * #### includeSubtree  Boolean   Whether to include the view's subtree when ignoring interactions. ### View\.csqIgnoreInteractions **Added in:** `1.0.0` Kotlin extension function to ignore interactions for a specific view. ```kotlin View.csqIgnoreInteractions(includeSubtree: Boolean = true) ``` #### Parameters * #### includeSubtree  Boolean   Whether to include the view's subtree when ignoring interactions. ### CsqIgnoreInteraction() Jetpack Compose composable function to ignore interactions for a specific view. ```kotlin @Composable fun CsqIgnoreInteraction(ignore: Boolean, block: @Composable () -> Unit) ``` #### Parameters * #### ignore  Boolean   indicating whether interactions should be ignored or not * #### block  @Composable () -> Unit   composable lambda function representing the UI content to apply ignore condition ### CSQ.setDefaultMasking() Experience Analytics | **Added in:** `1.0.0` Set the default masking state. All Android View elements, their subclasses and Jetpack Compose components are fully masked by default. ```kotlin CSQ.setDefaultMasking(masked: Boolean) ``` #### Parameters * #### masked  Boolean   The masking state to be set. ### CSQ.mask(View) **Added in:** `1.0.0` Mask a view's content. ```kotlin CSQ.mask(view: View) ``` #### Parameters * #### View  View   The view which content will be masked. ### View\.csqMaskContents(enable: Boolean) **Added in:** `1.0.0` Kotlin extension function to mask the content of a view. ```kotlin View.csqMaskContents(enable: Boolean) ``` #### Parameters * #### enable  Boolean   Whether to mask the content of the view. ### CsqMask() Jetpack Compose composable function that applies masking to Compose UI content This will mask both Session Replay and analytics event.. ```kotlin @Composable CsqMask(enable: Boolean, block: @Composable () -> Unit) ``` #### Parameters * #### enable  Boolean   Whether to mask the content of the view. * #### block  @Composable () -> Unit   composable lambda function representing the content to apply masking condition ### CSQ.unmask(View) **Added in:** `1.0.0` Unmask a view's content. ```kotlin CSQ.unmask(view: View) ``` #### Parameters * #### View  View   The view whose content will be unmasked. ### CSQ.mask(Class\<?> type) Experience Analytics | **Added in:** `1.0.0` Mask content for views of a specific type. ```kotlin CSQ.mask(type: Class<*>) ``` #### Parameters * #### type  Class\<?>   The class type of the view whose content will be masked. ### CSQ.unmask(Class\<?> type) Experience Analytics | **Added in:** `1.0.0` Unmask content for views of a specific type. ```kotlin CSQ.unmask(type: Class<*>) ``` #### Parameters * #### type  Class\<?>   The class type of the view whose content will be unmasked. ### CSQ.maskTexts() **Added in:** `1.0.0` Mask text input fields. ```kotlin CSQ.maskTexts(mask: Boolean) ``` #### Parameters * #### mask  Boolean   Whether to mask text. ## SDK initialization and management ### CSQ.configureProductAnalytics() Deprecated Product Analytics | **Added in:** `1.0.0` SDK configuration method for Product Analytics. Use [`CSQ.start()`](#csqstart) instead, which combines configuration and initialization in a single call. ### CSQ.start() **Added in:** `1.0.0` Start the SDK. This method combines configuration and initialization in a single call. There are three overloads depending on whether you want Experience Analytics, Product Analytics, or CSQ Experience Platform. **Experience Analytics only:** ```kotlin CSQ.start(context = this) ``` **Product Analytics (optionally with Experience Analytics extension) with environmentId:** ```kotlin CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true ) ) ) ``` **CSQ Experience Platform with `dataSourceId`:** ```kotlin CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID" ) ) ``` #### Parameters * #### context  Context   Android [Context object ↗](https://developer.android.com/reference/android/content/Context) * #### startConfig  StartConfig (optional)   Configuration created via `StartConfig.withEnvironmentId(id, options)` or `StartConfig.withDataSourceId(id, options)`. Omit for Experience Analytics only. ### CSQ.stop() **Added in:** `1.0.0` Stop all activity from the SDK. Once run no requests, telemetry collection, or logs will be generated. ```kotlin CSQ.stop() ``` ### CSQ.pauseTracking() **Added in:** `1.0.0` Pause all tracking features. ```kotlin CSQ.pauseTracking() ``` ### CSQ.resumeTracking() **Added in:** `1.0.0` Resume all tracking features. ```kotlin CSQ.resumeTracking() ``` ### CSQ.startSessionReplay() **Added in:** `1.10.0` Enable and eventually start Session Replay independently of other CSQ SDK features, allowing for on-demand collection. To use this functionality, disable the automatic start of Session Replay at SDK initialization using the [`.sessionReplayAutoStart`](#sessionreplayautostart) option. ```kotlin CSQ.startSessionReplay() ``` ### CSQ.stopSessionReplay() **Added in:** `1.10.0` Stop Session Replay immediately. ```kotlin CSQ.stopSessionReplay() ``` ## SDK configuration options CSQ SDK options passed to [`CSQ.start()`](#csqstart). ```kotlin // optional: StartConfig.withEnvironmentId(id: String, options) | StartConfig.withDataSourceId(id: String) CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enableViewAutocapture = true, baseUri = URI.create("https://mh.ba.contentsquare.net"), // EU; https://mh.bf.contentsquare.net (default) uploadInterval = 15.0, disablePageviewAutocapture = false, enablePushNotificationAutocapture = true, enablePushNotificationTitleAutocapture = true, enablePushNotificationBodyAutocapture = false, sessionReplayAutoStart = false ) ) ) ``` ### `baseUri` The CSQ API endpoint to use: * `https://mh.ba.contentsquare.net` — EU-hosted environments * `https://mh.bf.contentsquare.net` — all other environments (default) ### `uploadInterval` Interval in seconds at which event batches are uploaded to the API. Defaults to 15 seconds. ### `disablePageviewAutocapture` Whether source pageview events will be auto-captured. Defaults to false. ### `enableViewAutocapture` Whether the SDK will auto capture UI interactions and source pageviews. Only for Android View system, no Compose support. Defaults to false. ### `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 set to `true`. Defaults to false. ### `enablePushNotificationBodyAutocapture` Whether capture the body text of the notification where an interaction was performed. `enablePushNotificationAutocapture` must be set to `true`. Defaults to false. ### `maximumDatabaseSize` 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. ### `messageBatchMessageLimit` 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. ### `maximumBatchCountPerUpload` The maximum number of batches to send per upload cycle. This can be used in conjunction with messageBatchMessageLimit to control the amount of data that is uploaded in a given cycle. ### `resumePreviousSession` Enables Contentsquare behavior of persisting non-expired sessions across app launch. ### `pruningLookBackWindow` The number of days to look back when pruning old data in days. Defaults to 6 days. Requires an entitlement to use. ### `sessionReplayAutoStart` Whether Session Replay starts automatically at SDK launch. Defaults to `true`. Set to `false` to disable automatic start and control Session Replay manually. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"SDK API reference","description":"SDK commands reference including signature, parameter descriptions, and examples","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/command-reference/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - Android description: Requirements and limitations to develop with the Contentsquare Android SDK lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/compatibility/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare Android SDK has specific language, platform, and version requirements for integration. * **Supported languages**: The Contentsquare SDK supports and tracks content written in Kotlin or Java. * **Minimum Android version**: Your app must be running Android 5.0 (Lollipop) or a later version (API Level 21+) to use the Contentsquare SDK. * **Compilation information**: The Contentsquare SDK is built and compiled using Android SDK version 34. Warning If your app supports Android devices running versions below 7.1, you must include the ISRG Root X1 certificate in your app to ensure Let's Encrypt certificates work correctly. For more details and guidance, check this link: [Let's Encrypt Cross-Sign Expiration ↗](https://letsencrypt.org/2023/07/10/cross-sign-expiration/). ## Java versions This version has been compiled on `Java 17` (Bytecode version 61). Note If you try to import the Contentsquare SDK while using a lower Java version in your project, you will get a `bad class file` error. Update your Java version to get rid of the error. ## Kotlin versions Contentsquare Android SDK is compiled with Kotlin version `1.8.22`. If you don't use the `1.8.22` Kotlin version and you have conflict issues; you must exclude the Kotlin `stdlib` from our SDK. * Kotlin ```kotlin implementation("com.contentsquare.android:sdk:1.12.1") { exclude(group = "org.jetbrains.kotlin", module = "kotlin-stdlib-jdk8") } ``` * Groovy ```groovy implementation("com.contentsquare.android:sdk:1.12.1") { exclude group: "org.jetbrains.kotlin", module: "kotlin-stdlib-jdk8" } ``` Compatibility modes We use [Kotlin Compatibility modes ↗](https://kotlinlang.org/docs/compatibility-modes.html) flags to be backward compatible with two previous Kotlin versions and one next version. For an in-depth understanding of compatibility modes, see this [quicksheet ↗](https://blog.mbonnin.net/kotlin-compatibility-quicksheet). ## Jetpack Compose versions Contentsquare Compose SDK `com.contentsquare.android:sdk-compose:1.12.1` is compiled using Jetpack Compose version `1.7.0` (`bom 2024.09.00`). | CSQ SDK Version | CS Compose version | Embedded Compose version | Minimum Compose version | Latest tested Compose version | | - | - | - | - | - | | 1.12.1 | 4.52.1 | 1.7.0 | 1.7.0 | 1.11.0 | | 1.12.0 | 4.52.0 | 1.7.0 | 1.7.0 | 1.11.0 | | 1.11.2 | 4.51.2 | 1.7.0 | 1.7.0 | 1.11.0 | | 1.11.1 | 4.51.1 | 1.7.0 | 1.7.0 | 1.11.0 | | 1.11.0 | 4.51.0 | 1.7.0 | 1.7.0 | 1.11.0 | | 1.10.1 | 4.45.0 | 1.7.0 | 1.7.0 | 1.10.0 | | 1.5.3 | 4.44.2 | 1.7.0 | 1.7.0 | 1.10.0 | | 1.5.2 | 4.44.1 | 1.7.0 | 1.7.0 | 1.10.0 | | 1.5.1 | 4.44.1 | 1.7.0 | 1.7.0 | 1.10.0 | | 1.5.0 | 4.44.0 | 1.7.0 | 1.7.0 | 1.10.0 | | 1.4.2 | 4.43.3 | 1.7.0 | 1.7.0 | 1.10.0-beta02 | | 1.4.1 | 4.43.2 | 1.7.0 | 1.7.0 | 1.10.0-beta02 | | 1.4.0 | 4.43.0 | 1.7.0 | 1.7.0 | 1.10.0-beta02 | | 1.3.0 | 4.42.0 | 1.7.0 | 1.7.0 | 1.9.0-beta02 | | 1.2.0 | 4.41.0 | 1.7.0 | 1.7.0 | 1.9.0-beta02 | | 1.1.0 | 4.40.0 | 1.7.0 | 1.7.0 | 1.9.0-beta02 | | 1.0.1 | 4.39.3 | 1.7.0 | 1.7.0 | 1.8.0-rc02 | | 1.0.0 | 4.39.2 | 1.7.0 | 1.7.0 | 1.8.0-rc02 | | 0.7.1 | 4.38.2 | 1.5.0 | 1.5.0 | 1.8.0-rc02 | | 0.7.0 | 4.38.1 | 1.5.0 | 1.5.0 | 1.8.0-rc02 | | | 4.38.0 | 1.5.0 | 1.5.0 | 1.8.0-rc02 | | 0.6.0 | 4.37.0 | 1.5.0 | 1.5.0 | 1.7.7 | | 0.5.1 | 4.36.1 | 1.5.0 | 1.5.0 | 1.7.7 | | 0.5.0 | 4.36.0 | 1.5.0 | 1.5.0 | 1.7.7 | | 0.4.0 | 4.35.0 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | 0.3.0 | 4.34.0 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | 0.2.0 | 4.33.2 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | | 4.33.1 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | | 4.33.0 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | 0.1.1 | 4.32.1 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | 0.1.0 | 4.32.0 | 1.5.0 | 1.5.0 | 1.7.0-beta06 | | | 4.31.0 | 1.5.4 | 1.5.0 | 1.7.0-beta06 | | | 4.30.0 | 1.5.4 | 1.5.0 | | | | 4.29.1 | 1.5.4 | 1.5.0 | | | | 4.28.0 | 1.5.4 | 1.5.0 | | | | 4.27.1 | 1.5.4 | 1.4.0 | | | | 4.26.0 | 1.5.4 | 1.4.0 | | | | 4.25.0 | 1.5.4 | 1.4.0 | | | | 4.24.1 | 1.5.4 | 1.4.0 | | | | 4.23.1 | 1.4.0 | 1.4.0 | | | | 4.22.0 | 1.4.0 | 1.4.0 | | | | 4.21.0 | 1.4.0 | 1.4.0 | | | | 4.20.0 | 1.4.0 | 1.4.0 | | Note If your project uses a lower Compose version than the one embedded in the Contentsquare Compose SDK, Gradle will automatically use the latter version. Update the Compose version to the one used by our SDK or later. ## Dependencies The Contentsquare SDK has a few dependencies. We try to be up-to-date as much as possible to avoid conflict issues. ### Handling conflicts We may sometimes have conflicts between your app dependencies VS SDK dependencies. In this case, you can exclude from our SDK any dependency we pull and use your version instead. #### Example with excluding `recyclerview` dependency If you have a version of the **`recyclerview`** in your app which is older than the one we use, you can use the following to exclude it in your Gradle file. * Kotlin ```kotlin implementation("com.contentsquare.android:sdk:1.12.1") { exclude(group = "androidx.recyclerview", module = "recyclerview") exclude(group = "androidx.swiperefreshlayout", module = "swiperefreshlayout") } ``` * Groovy ```groovy implementation("com.contentsquare.android:sdk:1.12.1") { exclude group: "androidx.recyclerview", module: "recyclerview" exclude group: "androidx.swiperefreshlayout", module: "swiperefreshlayout" } ``` By doing this, you skip the **`recyclerview`** and **`swiperefreshlayout`** dependencies provided by our SDK. ### Dependencies list The list of dependencies for each artifact is searchable on central.sonatype.com: * [`com.contentsquare.android:sdk` ↗](https://central.sonatype.com/artifact/com.contentsquare.android/sdk/dependencies) * [`com.contentsquare.android:sdk-compose` ↗](https://central.sonatype.com/artifact/com.contentsquare.android/sdk-compose/dependencies) ## Known limitations and recommendations ### Native UI Elements are not supported **Symptom:** 1. You capture screenshots but main elements of the screen are not appearing. 2. SDK does not log any gesture events when interacting with some native UI elements. **Explanation:** Native UI Elements such as Bottom Sheets, Dialogs, Menus are not supported by the SDK. ### Gestures not attached to the expected view (Layout visibility) **Symptom:** In some cases, we found that gestures tracked by the SDK are not attached to the right UI element of the screen. These gestures will be attached to an invisible view. **Explanation:** The reason for this is that when the SDK attaches the gesture to a UI element, it generates a path regarding the visibility of the view when traversing the view hierarchy. If a view is visible and it matches the coordinates on where the gesture was performed it will be taken into account. Most of the time, the issue is that a layout is still present on the screen even if there is no content. **Best Practice:** When designing your application UI, do not let any layout stray along if it is not used. If a layout contains widgets like progress bar, remember to set its visibility to `GONE` or `INVISIBLE` after its purpose is served. ### Taps will be assigned to the first clickable view **Symptom:** A tap is not assigned to the tapped view, but to a view higher in the view hierarchy. **Explanation:** When a tap is captured, the view hierarchy is traversed to find all views that match the tap coordinates. The tap is assigned to the first clickable view, starting at the tail of the view list, meaning the search starts at the lowest hierarchy level. If no clickable view is found, then the tap is assigned to the view at the tail of the list. Jetpack Compose example: ```kotlin Button( onClick = { ... } ) { Text(text = "Simple Button") } ``` A tap on the `Text` will be assigned to the `Button`, because the `Button` is clickable. **Best practice:** If the described behavior does not fit your needs, you may add click listeners to the corresponding views. In the example above, you may add an identical click listener to the `Text`. ### Heatmaps: Initial scroll position has to be 0 **Symptom:** The tap positions in the Tap Heatmap do not match the actual tap positions on the screen. **Explanation:** For lists with lazy item generation, we may be unable to determine the correct initial scroll position. This is because the top list items may not be generated yet. We expect the initial scroll position to always be 0. **Best practice:** Ensure that the initial scroll position is always 0 for RecyclerViews and Compose lazy lists and lazy grids. ### No gesture detection for WebViews embedded in scroll container **Symptom:** Swipe gestures are not detected for a WebView. **Explanation:** For WebViews, the gesture detection is completely covered by the CS Tag, not the native Android SDK. However, when a WebView is placed inside a scrollable container, for example a `ScrollView`, the WebView will expand to its full size and all scrolling will be done by the scrollable container. In this case, no swipe gestures will be detected. **Best practice:** Ensure that WebViews are not placed inside any scrollable containers. ### Long Screenshot: Large Capture Limitation **Symptom:** The Long Screenshot capture completes the creation process, but then fails at the very end without a clear error message. **Explanation:** Long Screenshots can produce a very large amount of data. For reliability and performance reasons, the server enforces a maximum payload size (\~75 MB). Very long or content-heavy screens may exceed this limit, causing the screenshot to be rejected. **Workaround:** Capture a shorter area (reduce the scroll length) and/or reduce the amount of on-screen content (for example fewer or lighter elements), then retry the Long Screenshot. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Contentsquare Android SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/compatibility/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Experience Analytics extension - Android description: Understand the benefits of upgrading to the CSQ SDK lastUpdated: 12 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/dxae-setup/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/dxae-setup/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use this page to set up the Mobile Experience Analytics extension for Contentsquare Product Analytics. This will supercharge the Product Analytics platform with: * Powerful Session Replay * Heatmaps * Analysis capabilities of Mobile API Errors and Crashes This guide assumes that you have already implemented the [CSQ SDK for Product Analytics](../). ## Enable the extension in the Product Analytics UI 1. In Product Analytics, navigate to **Account** > **Manage** > **Replays & Heatmaps**. 2. If this is your first time setting up Session Replay, select the checkbox to accept the terms and conditions. 3. Click **Add web or mobile app** to launch the setup wizard. There is one configuration per app. 4. Select **Mobile** as platform. 5. Give your app a name and choose a storage location (**US** or **EU**). 6. Set a sampling rate for how many sessions to record. 7. Configure replay settings: * **App ID**: enter the bundle ID of your app (for example, `com.companyname.appname`). * **Quality Settings**: choose the recording fidelity for Wi-Fi and Cellular connections. The default for both is Medium; keep Cellular equal to or lower than Wi-Fi. * **User Consent**: enable this if your app requires explicit opt-in before recording. See [Privacy docs](../privacy/#opt-in) for the opt-in API. 8. Click **Save and Continue** to finish the wizard. ## Add the Errors plugins Add the Contentsquare Network Gradle plugin to the plugins block in both your root-level and app-level Gradle files: * Kotlin **build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.network") version "1.9.0" apply false } ``` **app/build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.network") } ``` * Groovy **build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.network" version "1.9.0" apply false } ``` **app/build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.network" } ``` Once this is done, the SDK running on your app will immediately start collecting the required data to provide Session Replay and Errors / Crashes (if enabled) into the Product Analytics platform. ## Enable error and crash collection Error and crash collection is managed separately from the setup wizard. Navigate to **Account** > **Manage** > **Replays & Heatmaps**, click **Edit** next to your app configuration, then scroll to the relevant section under **General Settings**: * **Error Capture**: toggles for **API Errors** and **Custom Errors**. * **Crashes Capture**: toggle for **Crashes**. Click **Save** when finished. ## Session Replay masking The Session Replay feature replays every interaction of your users with your app. To respect the user's right to privacy, the Contentsquare SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our [Masking rules](#masking-rules) Warning If you decide to unmask elements leading to the collection of new data or use already collected data but for a different purpose, it is up to you to update your Google Play Data Safety declaration accordingly. Here are some common examples of data collected via unmasked Session Replay: Search history, Purchase history, Advertising data, and so on. See [Types of data and purpose](../privacy/). Contentsquare is not intended nor designed to collect sensitive personal data (such as health, financial, or racial data). It is the customer's responsibility not to send any sensitive personal data to Contentsquare. ### Masking mechanisms Every single UI element is converted into a highly pixelated image to reach a very low resolution. Text and images will appear very blurry so that the content cannot be identified. #### Original vs Replay fully masked  ### Masking rules Masking rules can be applied in two ways: 1. **Through remote masking configuration in the CSQ Console (for admin users):** These configurations are managed directly in the Console and take effect for all sessions as soon as the app is restarted or brought to the foreground See [How to customize masking rules from the Data Masking tab ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) in the Help Center. 2. **Using public masking APIs in the SDK (for mobile application developers):** These configurations require developer implementation and will be applied only after the mobile app has gone through its release cycle. Masking rules set via the CSQ Console or the public APIs are applied according to different priorities, as described below. The SDK determines whether a view is masked by evaluating the rules in the order specified below. Once a rule is triggered, the state is set, and subsequent rules are not applied: #### General case | Rule | Configured via | | - | - | | 1. The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text or Image masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. An [instance](#maskingun-masking-by-instance) is specifically masked or unmasked | API | | 4. A [type](#maskingun-masking-by-type) is masked or unmasked | API | | 5. A [parent](#masking-and-unmasking-behaviors-on-a-parent-view) is specifically masked or unmasked | API | | 6. A parent [type](#maskingun-masking-by-type) is masked or unmasked | API | | 7. Remote Text or Image unmasking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 8. Otherwise the [default masking state](#default-masking) is applied | API | #### Exception: Text input fields Special consideration is needed for text inputs, as the risk of leaking personal data is higher with these elements. As a result, the SDK applies slightly different rules to `EditText` and Jetpack Compose `TextField`: | Rule | Configured via | | - | - | | 1. The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text input masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. An `EditText` [instance](#maskingun-masking-by-instance) is specifically unmasked | API | | 4. The `EditText` [type](#maskingun-masking-by-type) is unmasked | API | | 5. Otherwise a text input field remains masked | default | Specifically, default masking and parent masking won't change the masking state of text inputs. ### Public masking APIs #### Default masking Warning You should not perform any call to Contentsquare APIs before the first visible Activity to be sure the SDK is initialized. If you perform a call too soon, it will be discarded and you will see the following log: ```plaintext CSLIB Contentsquare SDK: Unable to call the public API, make sure you are not opted out of the Contentsquare tracker and SDK was correctly initialized. ``` All Android View elements, their subclasses, and Jetpack Compose components are fully masked by default. Change the default masking state with: ```kotlin /** * Sets the default masking state for the Contentsquare's Session Replay features. * * @param masked A boolean value indicating whether masking should be enabled (true) or disabled (false). */ @JvmStatic fun setDefaultMasking(masked: Boolean) ``` Note Setting the default masking state to `false` does not affect `EditText` or `TextField` (Jetpack Compose). #### Masking/Un-masking by instance Warning Animations are not supported when masking by instance. * Views Use `mask(view: View)` and `unmask(view: View)` methods to mask or unmask a specific view instance. ```kotlin /** * Masks the contents of a specific view. * * @param view an instance of [View] to mask. */ @JvmStatic fun mask(view: View) ``` ```kotlin /** * Unmasks the contents of a specific view. * * @param view an instance of [View] to unmask. */ @JvmStatic fun unmask(view: View) ``` Alternatively, you can also apply the masking rule to a specific view instance directly with `View.csqMaskContents(enable: Boolean)` extension function. ```kotlin /** * [View] extension function to mask the contents of a view. * This extension function can be used as alternative to [CSQ.mask] and [CSQ.unmask]. * * @param enable A boolean value indicating whether masking should be enabled (true) or disabled (false) for this view. */ fun View.csqMaskContents(enable: Boolean) ``` Following the previous example, we have the views hierarchy in which all instances of TextView type are unmasked with the default masking state of all the views are masked by default.  In this example, if you want to mask a specific text view TextView1, call `mask(textView1)`. The view instance rule overrides the type rule and the default rule. * Jetpack Compose Use the `CsqMask(enable: Boolean, block: @Composable () -> Unit)` composable function to mask or unmask a composable. ```kotlin /** * A composable function that applies masking to Compose UI content. * * @param enable A boolean value indicating whether masking should be enabled (true) or disabled (false). * @param block A composable lambda function representing the content to apply masking condition. */ @Composable fun CsqMask(enable: Boolean, block: @Composable () -> Unit) ``` For example: ```kotlin CsqMask(true) { Text( text = "Text" ) } ``` #### Masking/Un-masking by type Although the SDK allows masking elements by type for convenience but it isn't the recommended masking mechanism because it impacts all screens of your application. Use this when you have a specific class for presenting user information or for displaying the user profile picture to make sure it always stays masked, for instance. Warning Animations are not supported when masking by type. * Views Use `mask(type: Class<*>)` and `unmask(type: Class<*>)` methods to mask or unmask a specific type. ```kotlin /** * Masks the contents of the view for all instances of a specific [Class] and subclass of a [View]. * This will be applied only for Session Replay feature. * * @param type a [Class] object representing the type to be masked. */ @JvmStatic fun mask(type: Class<*>) ``` ```kotlin /** * Unmasks the contents of the view for all instances of a specific [Class] and subclass of a [View] for * Session Replay feature. * * @param type a [Class] object representing the type to be unmasked. */ @JvmStatic fun unmask(type: Class<*>) ``` For example, given the views hierarchy:  The default masking state of all the views is masked and, for example, to unmask all **TextView** types, you can call `unmask(TextView.class)` then all instances of **TextView** type will be unmasked. In this example, the button is also impacted by the `unmask()` call because the button is also a **TextView** type (a subclass of **TextView**). The **EditText** is also a **TextView** type but isn't impacted by `unmask(TextView.class)` call because the **EditText** type is [masked by default](#masking-rules). * Jetpack Compose It is not possible to mask or unmask composables by type. Alternatively, you can mask or unmask a group of composables by wrapping multiple composables within the same parent, then applying the `CsqMask(enable: Boolean, block: @Composable () -> Unit)` on the parent. #### Masking and Unmasking behaviors on a parent view * Views You can mask ViewGroups (and subclasses such as RelativeLayout, LinearLayout, ConstraintLayout, and so on). When a parent view is masked all of its children inherit the masking state. The children's view masking state can be overridden by using a specific API to mask or unmask by instance or by type.  For example, given the view hierarchy with the default masking state. All the views are masked by default in the initial state and in this case, you may want to unmask all children's views of the parent view **LinearLayout1**, you can call `unmask(linearLayout1)` then all children views of the parent view **LinearLayout1** will be unmasked. As noticed here the **EditText** is not impacted from the parent call because the **EditText** type is [masked by default](#masking-rules). * Jetpack Compose You can mask a parent layout (such as `Column`, `Row`, or `Box`). If a parent composable is masked, then all of its children inherit the masking state from the parent. The children's masking state can be overridden by using the dedicated `CsqMask(enable: Boolean, block: @Composable () -> Unit)` function: ```kotlin CsqMask(true) { Column { Row { CsqMask(false) { // unmask this `Text` composable Text( text = "Text", ) } } Row { Text( // this `Text` composable will be masked, as it inherits the masking state from the parent text = "Text 2", ) } } } ``` #### Masking and Unmasking of Bottom Sheets, Dialogs, and Menus Contentsquare Android SDK 4.39.0 and earlier If you were using Contentsquare Android SDK versions before 4.39.0 in your mobile app, then masking is automatically enforced on all bottom sheets, dialogs, and menus, as these elements were not supported in earlier versions. To unmask any of these elements, contact your CSM to disable the forced masking and use the APIs described below. **Bottom Sheets** Bottom sheets can be masked or unmasked using the same APIs available for any other view, whether you're working with Android Views or Jetpack Compose. To apply the masking behavior, ensure that you call the appropriate API after the bottom sheet has been created. **AlertDialogs** * Views Dialogs, such as AlertDialog, TimePickerDialog, and DatePickerDialog, can be masked or unmasked using the APIs provided below. In addition, the masking behavior of individual components within these dialogs can be customized using the provided Kotlin extension functions. For instance, if an AlertDialog is fully masked by default, you can selectively unmask specific elements—such as the title or action buttons—using the extension functions provided below for more granular control. For example, given an AlertDialog with the default masking state, all views in the dialog are masked by default in the initial state. In this case, you may want to unmask the title and buttons of the dialog. To do that, we provide Kotlin extension functions to the Dialog API to make it easy. ```kotlin /** * Masks the entire [AlertDialog]. */ fun AlertDialog.csqMask() /** * Masks the title of the [AlertDialog]. */ fun AlertDialog.csqMaskTitle() /** * Masks the message of the [AlertDialog]. */ fun AlertDialog.csqMaskMessage() /** * Masks the positive button of the [AlertDialog]. */ fun AlertDialog.csqMaskPositiveButton() /** * Masks the negative button of the [AlertDialog]. */ fun AlertDialog.csqMaskNegativeButton() /** * Unmasks the entire [AlertDialog]. */ fun AlertDialog.csqUnMask() /** * Unmasks the title of the [AlertDialog]. */ fun AlertDialog.csqUnMaskTitle() /** * Unmasks the message of the [AlertDialog]. */ fun AlertDialog.csqUnMaskMessage() /** * Unmasks the positive button of the [AlertDialog]. */ fun AlertDialog.csqUnMaskPositiveButton() /** * Unmasks the negative button of the [AlertDialog]. */ fun AlertDialog.csqUnMaskNegativeButton() ``` Note The mask API for dialogs should be called immediately after the `show` method in the main thread. Example: ```kotlin val builder: AlertDialog.Builder = AlertDialog.Builder(context) builder.setMessage("This is a dialog. This text should be masked") builder.setTitle("Dialog Title") builder.setCancelable(true) builder.setPositiveButton("Close") { ... } builder.setNegativeButton("Idle") { ... } val alertDialog: AlertDialog = builder.create() alertDialog.show() alertDialog.csqUnMaskTitle() alertDialog.csqUnMaskPositiveButton() alertDialog.csqUnMaskNegativeButton() ``` * Jetpack Compose The AlertDialog composable in Jetpack Compose can be masked or unmasked using the same APIs applied to other composables. Simply use the appropriate `CsqMask` composables function on the elements you want to mask or unmask within the dialog. Example: ```kotlin AlertDialog( icon = { Icon(icon, contentDescription = "Example Icon") }, title = { Text(text = dialogTitle) }, text = { // Mask the dialog text CsqMask(true) { Text( text = dialogText ) } }, onDismissRequest = { onDismissRequest() }, confirmButton = { TextButton( onClick = { onConfirmation() } ) { // Unmask the dialog confirm button CsqMask(false) { Text( "Confirm" ) } } } ) ``` **TimePickerDialog and DatePickerDialog** * Views Time and date pickers function similarly to AlertDialogs but contain their own distinct UI components. These sections can be selectively masked or unmasked using the APIs provided below. To support masking on this dialogs we added the following APIs: ```kotlin /** * Masks the entire [DatePickerDialog]. */ fun DatePickerDialog.csqMask() /** * Masks the header of the DatePicker, which typically displays the selected date. * This affects the [DatePickerDialog]. */ fun DatePickerDialog.csqMaskHeader() /** * Masks the calendar view (day picker) of the [DatePickerDialog]. */ fun DatePickerDialog.csqMaskCalendar() /** * Masks the button panel of the [DatePickerDialog], typically containing "OK" and "Cancel" buttons. */ fun DatePickerDialog.csqMaskButtonPanel() /** * Unmasks the entire [DatePickerDialog]. */ fun DatePickerDialog.csqUnMask() /** * Unmasks the header of the DatePicker. * This affects the [DatePickerDialog]. */ fun DatePickerDialog.csqUnMaskHeader() /** * Unmasks the calendar view (day picker) of the DatePicker. * This affects the [DatePickerDialog]. */ fun DatePickerDialog.csqUnMaskCalendar() /** * Unmasks the button panel of the [DatePickerDialog]. */ fun DatePickerDialog.csqUnMaskButtonPanel() /** * Masks the entire TimePicker view within the [TimePickerDialog]. */ fun TimePickerDialog.csqMask() /** * Masks the header of the TimePicker, including the time display and input mode header. * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqMaskHeader() /** * Masks the radial picker (clock face) of the TimePicker. * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqMaskRadialPicker() /** * Masks the input mode view of the TimePicker (keyboard input for time). * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqMaskInputMode() /** * Masks the button panel of the [TimePickerDialog], including positive, negative, and toggle mode buttons. */ fun TimePickerDialog.csqMaskButtonPanel() /** * Unmasks the entire TimePicker view within the [TimePickerDialog]. */ fun TimePickerDialog.csqUnMask() /** * Unmasks the header of the TimePicker, including the time display and input mode header. * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqUnMaskHeader() /** * Unmasks the radial picker (clock face) of the TimePicker. * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqUnMaskRadialPicker() /** * Unmasks the input mode view of the TimePicker (keyboard input for time). * This affects the [TimePickerDialog]. */ fun TimePickerDialog.csqUnMaskInputMode() /** * Unmasks the button panel of the [TimePickerDialog], including positive, negative, and toggle mode buttons. */ fun TimePickerDialog.csqUnMaskButtonPanel() ``` * Jetpack Compose The Time and Picker composables in Jetpack Compose can be masked or unmasked using the same APIs applied to other composables. Simply use the appropriate `CsqMask` composables function on the elements you want to mask or unmask within the dialog. **Custom Dialogs** * Views If you're creating a custom dialog by extending the Dialog base class and inflating a layout using the setContentView method, you can mask or unmask individual views within your custom view hierarchy, using the masking APIs. * Jetpack Compose The custom dialogs in Jetpack Compose can be masked or unmasked using the same APIs applied to other composables. Simply use the appropriate `CsqMask` composables function on the elements you want to mask or unmask within the dialog. **Menu Items** * Views Menu items captured by Session Replay can be selectively masked or unmasked. For example, consider a context menu, including an action item and another item displaying the user's name (see XML example below). If masking is disabled by default, you may want to mask sensitive menu items to prevent personal data from appearing in Session Replays. Conversely, if masking is enabled by default, you may choose to unmask certain non-sensitive items to keep them visible. To achieve this, simply apply masking or unmasking to individual menu items as needed. ```xml <?xml version="1.0" encoding="utf-8"?> <menu xmlns:android="http://schemas.android.com/apk/res/android" xmlns:app="http://schemas.android.com/apk/res-auto"> <item android:id="@+id/action_settings" android:orderInCategory="10" android:title="@string/action_settings" app:showAsAction="never" /> <item android:id="@+id/profile_settings" android:orderInCategory="100" android:title="Name Placeholder" app:showAsAction="never" /> </menu> ``` Note This API does not need to be called strictly after menu inflation; it can be invoked earlier if necessary. As a best practice, apply it during or after menu inflation when you have clear context about what is being masked and where. ```kotlin override fun onCreateOptionsMenu(menu: Menu): Boolean { // Inflate the menu; this adds items to the action bar if it is present. menuInflater.inflate(R.menu.activity_main, menu) val item = menu.findItem(R.id.profile_settings) item.title = current_user.fullName // Unmask action menu item CSQ.unmaskMenuItem(R.id.action_settings) // Mask profile menu item that contains user's name CSQ.maskMenuItem(R.id.profile_settings) return true } ``` * Jetpack Compose The Menu components in Jetpack Compose can be masked or unmasked using the same APIs applied to other composables. Use the appropriate `CsqMask` composable function on the elements you want to mask or unmask within the menu. #### Handling Transparent Views The SDK processes [masked views first](#masking-rules), ensuring that if a view has transparency and is not masked, it will not expose any personal data since masked views have already been processed. This approach ensures the protection of sensitive information, even in UIs with transparent views. Warning If the view below the transparent view is a **WebView**, and you unmask the view on top of it (for example a dialog progress bar), it leaks the content of the WebView. This is a known limitation. On the left, a possible implementation of a payment screen in a WebView. On the right, the result in Session Replay.  ### Implementation recommendations #### Where to perform masking operations Masking operation should be performed before the first draw of the view and it should always be called on the UI thread. At the **Activity** level, call the masking API methods on the `onCreate` lifecycle method. At the **Fragment** level, call the masking API methods on the `onViewCreated` lifecycle method. Note The masking API stores the view element to be masked or unmasked inside a WeakHashMap, repeating the masking operation multiple times on the same element will override the old value that is already stored in the map. #### Keeping track of what is masked The SDK doesn't provide a list of what is currently masked, if you need to keep track, you probably will have to write your specific wrapper. #### Masking operations performance impact You can call `unmask(View view)` multiple times without impacting the SDK performance or your app. ### Masking limitations #### Maps You can mask or unmask a Map, that will then be captured as an image in the replay. However, you won't be able to mask or unmask specific elements within the Map. #### Navigate between fragments using animations Masking rules don't apply on Fragments using animations. So to mask this type of Fragment, mask the container view where the Fragment is inserted, rather than masking its content. This ensures that the Fragment content remains masked during transitions. Additionally, you can unmask some specific views within the Fragment content, by using `CSQ.unmask(view: View)`. #### Rotated or Scaled Views The masking solution relies on the bounding box reported by a view to determine the area that should be masked. In most cases, this approach is sufficient, as the bounding box accurately reflects the view's position and dimensions on the screen. However, when a view is rotated or scaled, the bounding box no longer represents the view's actual position or size after the transformation. To prevent any personal data from being leaked, we advise adopting one of the following approaches: * **Mask the Parent View**: Apply masking to the parent container of the transformed view. This ensures that the entire area encompassing the rotated or scaled view is covered, regardless of transformations. * **Mask the Entire Window**: In case of complex layouts, transformations, or critical scenarios where absolute certainty is required, mask the entire window to guarantee that no personal data is exposed. These approaches provide the highest level of confidence in preventing personal data leakage while working within the constraints of the current implementation. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Experience Analytics extension","description":"Understand the benefits of upgrading to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/dxae-setup/","inLanguage":"en","dateModified":"2026-06-12T11:40:35+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Hide sensitive data - Android description: Protect sensitive data in Contentsquare by disabling text capture, masking specific views, or ignoring interactions lastUpdated: 26 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/hide-sensitive-data/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/hide-sensitive-data/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Customers ("Customer(s)", "you," or "your"), as app developers and/or publishers, shall ensure compliance with applicable data privacy laws and regulatory guidelines while using Contentsquare SDK for your app. This section explains the data processing involved in the use of Contentsquare SDK and provides information to help you comply with data protection laws, including the GDPR, e-privacy directive, and the [French Data Protection authority (CNIL) guidelines on mobile applications ↗](https://www.cnil.fr/sites/cnil/files/2025-05/recommendation-mobiles-app.pdf). This section is for informational purposes only and is not legal advice. If you are not sure of how to comply with data protection laws that apply to you, refer to legal counsel. To learn about Contentsquare privacy practices, see our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Purpose of processing and categories of personal data processed ### Purpose of processing The CSQ SDK is designed to collect personal data from end-users interacting with your app, for analyzing end-user's multi-session journeys across your app, and other branded experiences to improve end-user's conversion and retention. ### Categories of personal data collected By default, the CSQ SDK processes the following categories of personal data to achieve the purpose set out above: * **Online identifier:** [Contentsquare User ID](../privacy/#contentsquare-user-id) * **Interaction data**, such as how an end-user has interacted with the app, view page, click, submit, change; time of engagement * **Technical data**, such as pages of an app an end-user visited, end-user's type of computer operating system, end-user's type of web browser, other backend technical data Additional types of personal data may be processed (for example username, email address, customer ID, account number), depending on your configuration of the SDK and the applicable order form you signed with Contentsquare. Note Contentsquare is not intended nor designed to collect sensitive personal data (for example health data, financial data, or racial data). **It is the customer's responsibility to not send any sensitive personal data to Contentsquare.** if you did send sensitive personal data to Contentsquare, contact your customer success manager immediately and we will promptly delete the sensitive personal data from our servers. ## Data retention and storage location ### Data retention By default, personal data is kept for 37 months, or more if Customer purchases additional data history amount and/or Connect feature. Personal data collected via Connect feature is kept for the duration of the agreement with Customer. ### Storage location End-users personal data is stored in Europe or in the US, depending on your configuration. For more details on applicable hosting locations, refer to our subprocessors list, [available here ↗](https://contentsquare.com/privacy-center/subprocessors/). ## Excluding personal data from autocapture When using autocapture, the CSQ SDK collects target text information about the element the end-user interacted with, and text data from UI elements further up in an element's ancestry. However, some of these elements might contain end-user's personal data, including sensitive data, that needs to be excluded from data capture. There are three options for hiding sensitive data: * Disabling text capture * Per-view text masking * Ignoring interactions for specific views ### Disabling all text capture You have the option to disable text capture for all events that are automatically captured. To do this, use the `CSQ.maskTexts()` API. ```kotlin CSQ.maskTexts(true) CSQ.start(this) ``` ### Masking text for specific views If you don't want to disable all text capture for your app, you can take a more targeted approach of only masking text for specific views in your app that you know might contain sensitive data. When text is masked for a view, it will still have target text, but the actual text will be replaced with `****`. * View ```kotlin val emailField = findViewById<EditText>(R.id.emailField) emailField.csqMaskContents(true) ``` * Jetpack Compose ```kotlin import com.contentsquare.api.compose.CsqMask @Composable fun EmailField(email: String) { CsqMask(enable = true) { Text(text = email) } } ``` Note Masking the visible text also masks the text in the accessibility label to ensure Personal Data isn't leaked when the visible text and the accessibility text are the same value. ### Ignoring all interactions for specific views If you find that certain interactions are prone to capturing sensitive data, or that a certain interaction might indicate sensitive information about a user during analysis, you have the option of ignoring all interactions on a per-view basis. * View ```kotlin val sensitiveButton = findViewById<Button>(R.id.sensitiveButton) sensitiveButton.csqIgnoreInteractions() ``` * Jetpack Compose ```kotlin import com.contentsquare.api.compose.CsqIgnoreInteraction @Composable fun SensitiveButton() { CsqIgnoreInteraction(ignore = true) { Button(onClick = { /* sensitive action */ }) { Text("Sensitive Button") } } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Hide sensitive data","description":"Protect sensitive data in Contentsquare by disabling text capture, masking specific views, or ignoring interactions","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/hide-sensitive-data/","inLanguage":"en","dateModified":"2026-06-26T14:14:55+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - Android description: Configure privacy settings and user consent management in your Android app with the CSQ SDK to ensure regulatory compliance lastUpdated: 28 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/privacy/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Customers ("Customer(s)", "you," or "your"), as app developers and/or publishers, shall ensure compliance with applicable data privacy laws and regulatory guidelines while using Contentsquare SDK for your app. This section explains the data processing involved in the use of Contentsquare SDK and provides information to help you comply with data protection laws, including the GDPR, e-privacy directive, and the [French Data Protection authority (CNIL) guidelines on mobile applications ↗](https://www.cnil.fr/sites/cnil/files/2025-05/recommendation-mobiles-app.pdf). This section is for informational purposes only and is not legal advice. If you are not sure of how to comply with data protection laws that apply to you, refer to legal counsel. To learn about Contentsquare privacy practices, see our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Purpose of processing and categories of personal data processed ### Purpose of processing The Contentsquare SDK is designed to collect personal data from end-users interacting with your app to analyze their digital behavior, visualize their journey, and improve digital user experience and your app performance. ### Categories of personal data collected By default, the SDK processes the following categories of personal data: * **Online identifier**: Contentsquare user ID * **Behavioral data**: touch gestures (taps, swipes), user journey (pages visited), time of engagement, transactions, and so on. * **Technical data**: device information (such as operating system, resolution, time zone, or language), API error messages and crashes Additional types of personal data may be processed (such as username, email address, customer ID, account number), depending on your configuration of the SDK and the applicable order form you signed with Contentsquare. Note Contentsquare is not designed to collect sensitive personal data (such as health, financial, or racial data). It is your responsibility to prevent any sensitive data from being sent to Contentsquare. If you accidentally send sensitive data, contact your customer success manager to immediately delete them from Contentsquare servers. ## User identifiers ### Contentsquare User ID The SDK generates a randomized hash unique user ID (UUID) that is specific to each end-user on a given device. Contentsquare cannot identify an end-user across devices with this UUID. This UUID is not persisted when the app is deleted and re-installed. The SDK generates a new UUID after install or re-install. ### "User identifier" feature Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier provided by the customer. See [User identifier feature](../../experience-analytics/session-replay/#send-user-identifier) for more information. ### Usage of App Set ID Contentsquare does not use App Set ID. ## Data retention and storage location ### Data retention By default, end-users personal data are kept for 13 months. The retention of end-users personal data collected via the Session Replay is customizable by customers, from 3 to 24 months. ### Storage location End-users personal data are stored in Europe or in the US, depending on your location. For more details on applicable hosting locations, refer to our [subprocessors list ↗](https://contentsquare.com/privacy-center/subprocessors/). ## Informing your end-user The Contentsquare SDK collects end-user's personal data on your app. As a data controller, app developers, or app publishers, it is your responsibility to provide appropriate information to your end-users on how their personal data is handled when using the CSQ SDK, for example via a privacy policy or cookie banner. Contentsquare provides a sample [description of the services ↗](https://contentsquare.com/privacy-center/sample-cookie-description/) (including Experience Analytics and Product Analytics) to help customers meet their transparency obligations. This description is for information only and is not legal advice. ## Handling User Consent Contentsquare collects usage data on your app. **By default, the SDK will consider every new user to be opted-out.** To start tracking, the SDK [Opt-in API](#opt-in) must be called. You are responsible for handling the UI asking end-users for their consent and allowing them to manage their privacy settings. Use the following APIs to pass the user decision to the Contentsquare SDK. Note If data protection laws that apply to you do not require end-user consent for your app, discuss it during implementation with your Contentsquare contact. ### Opt-in Use the Opt-in API to get user consent. Calling this API will generate a user ID and initiate tracking. * Product Analytics ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this, StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` * CSQ Experience Platform (Early Access) ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this, StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` ### Opt-Out When this API is called, tracking stops immediately, all settings are reset (Session number, Page number, and so on) and all files and directory including personal data collected via the SDK created by Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track and collect any data from the user's phone unless the Opt-in API is called again. ```kotlin import com.contentsquare.CSQ // To opt-out of CSQ Tracking CSQ.optOut() ``` ### Get Contentsquare User ID Since Contentsquare SDK does not collect by default any directly identifiable personal data about your end-user, we cannot help you respond to an end-user's data subject request without their Contentsquare User ID. Use this API to get the Contentsquare User ID of your end-user and forward the end-user's data subject request (such as data deletion or data access request) via Contentsquare's [portal ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ```kotlin import com.contentsquare.CSQ // Get CSQ User ID val userId = CSQ.metadata.userId ``` ### Pause / Resume Tracking Use pause and resume tracking APIs to completely pause data collection of your end-users on your app. When pause is called, the Contentsquare SDK pauses all tracking (Analytics, Session Replay, Errors) of your end-users. When resume is called, the Contentsquare SDK resumes all tracking (Analytics, Session Replay, Errors) and starts collecting your end-users personal data again with the same Contentsquare user ID. ```kotlin import com.contentsquare.CSQ // Pause tracking CSQ.pauseTracking() // Resume tracking CSQ.resumeTracking() ``` Note As this mechanism pauses the tracking, make sure that you call resume once your user exits the sensitive screen. Best practice would be to link these method calls to lifecycle events on activities/fragments. ### Stop automatic gesture tracking End-users' personal data, including behavioral data (such as taps, scrolls, swipes) are collected automatically by the Contentsquare SDK. In specific cases, you might want to stop the tracking of individual Views. To do so, use the following API: ```kotlin CSQ.ignoreInteractions(view, includeSubtree) ``` In case you still need to track these Activities or Views but the automatic gesture tracking does not work, we offer the possibility to do this manually by capturing and sending the gesture events via our public API method: ```kotlin class MainActivity : AppCompatActivity() { // ... override fun dispatchTouchEvent(motionEvent: MotionEvent): Boolean { CSQ.trackMotionEvent(motionEvent) return super.dispatchTouchEvent(motionEvent) } } ``` ### Disable user tracking across sessions If you don't want to link the different sessions of a user to the same userID, reset the userID at each app start: ```kotlin class MyApplication : Application() { override fun onCreate() { super.onCreate() // Start Contentsquare SDK CSQ.start(this) CSQ.optOut() CSQ.optIn(this) } } ``` Starting the SDK manually using `start()` will ensure that opt-out is called right after the start of the SDK (no event tracked in between). Calling `optOut()` will delete the previous userID. Calling `optIn()` will set a new one. Note If you are monitoring the network requests, you may see event requests being sent at app start. This is expected as there may be events from the previous session that haven't been sent yet. The opt-out API makes sure to send all data stored locally before stopping the tracking and wiping all data. ### Session Replay personal data masking mechanisms As part of Session Replay, Contentsquare provides masking mechanisms to prevent unwanted end-user's personal data from the Session Replay module from being transmitted to Contentsquare. See [Session Replay Personal data masking](../../experience-analytics/session-replay/#personal-data-masking) for more information. ## Permissions The Contentsquare SDK requires technical permissions to operate properly. Some of these permissions involve read and write operations within the meaning of the e-privacy directive and article 82 of the French Data Protection Act, which may require the end-user's specific consent. See [App permissions](../security/#app-permissions) for more information. ## Play Store Privacy Guidelines Compliance As customer app developers, it is your responsibility to comply with the [Play Store Privacy guidelines ↗](https://support.google.com/googleplay/android-developer/answer/10144311?visit_id=637574546075634450-3505282410\&rd=1). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Configure privacy settings and user consent management in your Android app with the CSQ SDK to ensure regulatory compliance","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/privacy/","inLanguage":"en","dateModified":"2026-04-28T22:12:27+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Security - Android description: Data transfer and security information lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/security/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/security/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Android SDK requires specific permissions to function and follows Android security guidelines for deep link handling. ## App permissions The SDK includes the following permissions, which are mandatory for the SDK to operate properly: **AndroidManifest.xml** ```xml <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.READ_BASIC_PHONE_STATE" /> <uses-permission-sdk-23 android:name="android.permission.SYSTEM_ALERT_WINDOW" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> ``` | Permission | Required to | Associated with read/write operations under e-privacy directive | | - | - | - | | `android.permission.INTERNET` | Send collected data to Contentsquare servers | Yes. The end-user's data is collected for analytics purposes. | | `android.permission.READ_BASIC_PHONE_STATE` | Retrieve non-sensitive device information such as carrier name for analytics purposes | Yes. The end-user's data is collected for analytics purposes. | | `android.permission.SYSTEM_ALERT_WINDOW` | Use Contentsquare in-app features | No. This permission is solely used to display Contentsquare UI elements in our customers' apps. | | `android.permission.ACCESS_NETWORK_STATE` | Check network availability before sending data | No. This permission is solely used to check the network status check. | Note Some of these permissions involve read and write operations within the meaning of the e-privacy directive and article 82 of the French Data Protection Act, which may require the end-user's specific consent as specified above. This requirement applies in particular to customers based in the EU or targeting end-users in the EU. For more information on how to combine technical permission and legal consent, refer to the [CNIL (French data protection authority) recommendations ↗](https://www.cnil.fr/fr/permissions-applications-mobiles-recommandations-de-la-cnil-pour-respecter-la-vie-privee). ## Deep links usage in Contentsquare SDK As outlined in the [Android Security Guidelines ↗](https://developer.android.com/privacy-and-security/risks/unsafe-use-of-deeplinks), there are security risks associated with using deep links. To address these concerns, the Contentsquare SDK implements robust data validation for deep links and safeguards to prevent deep link hijacking, following these guidelines. If you have specific security concerns and prefer to remove the Contentsquare SDK deep link declaration from your application, add the following code snippet to your `AndroidManifest.xml` file inside the `<application>` tag: ```xml <application> <activity android:name="com.contentsquare.android.analytics.internal.features.deeplink.DeepLinkActivity" tools:node="remove" /> </application> ``` Removing the deep link will disable the In-app feature within your application. ## Transmission and hosting Our server uses HTTPS to make sure that data is encrypted in transport. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Security","description":"Data transfer and security information","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/security/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track identity - Android description: Enhance user tracking with identify and addUserProperties APIs. Link anonymous and identified user data across sessions and devices for comprehensive analytics lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/track-identity/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/track-identity/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Product Analytics assigns every visitor a random user ID; call `identify` to merge anonymous and identified profiles, and `addUserProperties` to attach custom attributes. ## User Identities and Properties Contentsquare Product Analytics empowers you to use the rich information about your users to better understand how users interact with your site or app, and build charts to continually track engagement. There are two primary APIs for enriching user data in Product Analytics: * The [`CSQ.identify()`](../command-reference/#csqidentify) API allows you to attach a unique identity and maintain user histories across sessions and devices under a single profile, * The [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) API allows you to attach custom properties to your users, whether they are identified or still anonymous. ## Read This First: Key Considerations Before implementing our APIs, check the following explanations on how these APIs work and common implementation mistakes to avoid. ### Anonymous Users When a person interacts with your site or app, Product Analytics generates a random unique user ID and stores it in a cookie. In Product Analytics, these users will appear in the [Users ↗](https://developers.heap.io/docs/users) view as "User 123456" where the 123456 is their user ID. We refer to these users as anonymous users throughout this document. Tip Though this guide focuses on web use cases, the same principles apply to mobile. The user ID may be stored differently depending on the platform. If a user visits your website on their mobile device and their laptop, Product Analytics will recognize 2 different anonymous users because both devices will have different cookies. We can identify these users on both platforms and link the two anonymous users into a single identified user. Note While Product Analytics can track identified users across different domains, it will not track anonymous users across domains. For cross-domain tracking support, use our APIs to identify users. ### Identified Users You can use the `identify` API to attach your own unique identifier to a user. The `identify` API takes a single string value as an argument. Examples are provided further down in this guide in the [Examples section ↗](https://developers.heap.io/docs/using-identify#examples). Warning When a user is identified, their past sessions and event activity from when they were anonymous are now tied to that identity. This allows the user to use multiple devices/browsers to access your website with a single identity. ### User Properties The `addUserProperties` API can be used to attach properties to users' profiles. Product Analytics sets some of these properties automatically, such as Initial Location, Initial Referrer, Initial Marketing Channel, and more. A full list of all user properties captured by default is available in [Autocaptured Data ↗](https://help.heap.io/getting-started/how-heap-works/autocaptured-data/). The `addUserProperties` API allows you to attach any string or number as a user property that's not automatically captured. Some practical properties to use include: payment plan, marketing segment, or A/B experiment. Once set, these properties can be used in charts to [group by ↗](https://developers.heap.io/docs/group-bys) and [filter ↗](https://developers.heap.io/docs/filters) against. Check out some specific examples further down this page. ### Common Identify Implementation Errors Below we've listed the most common mistakes developers may make when implementing the `identify` API. #### Using a Non-Unique Identifier A common assumption is that a unique identifier attached via `CSQ.identify()` is required in order for the `addUserProperties` API to attach properties to a user. In cases where a unique identifier isn't available, we've seen people include a specific name, like 'guest', or 'Anonymous User'. This can cause irreversible behavior with how Product Analytics merges user profiles. You can call [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) at any time, whether the user has been given a unique identity. For this reason, the following identify calls are blocklisted: * `anonymous` * `guest` * `null` * `true` * `false` * `not_authenticated` * `NaN` * `' '` (empty string) * `0` * `None` * `none` * `Email` * `email` As an example of how this would impact your setup: let's say that you have a marketing campaign, and you want to associate it with a visitor when they visit your landing page. They aren't logged in, so you don't have a unique identifier. **Don't do this:** ```javascript CSQ.identify("guest"); CSQ.addUserProperties({ campaign: "Campaign Name" }); ``` This will merge all visitors into a single user profile called 'guest', which will break any metrics that rely on user flow, or the unique user count. **Instead, do this:** ```javascript CSQ.addUserProperties({ campaign: "Campaign Name" }); ``` Now the campaign property will be associated with the anonymous user, using the value of the JavaScript variable 'campaign'. ### Adding an Anonymous Unique Identifier of Your Own Some tools require a unique identifier to be provided to add user-level properties. This leads people to add their own unique identifier to all visitors. Product Analytics automatically assigns each unidentified user a unique user ID so that you aren't required to call `identify` to add user-level properties. Assigning an identity to a user when it isn't required can lead to undesirable, or unexpected behavior. Product Analytics does not allow you to change an already applied identity or assign multiple identities to the same user. If you call `identify` with an anonymized identity, such as a `uuid` or random hash, this will be their permanent identity in Product Analytics. If you call the identify API at another time for the same user with a different identity, such as an internal user ID or username, this will create a new user in Product Analytics, splitting this users into two identified users, one with the random `uuid` containing all of the historical events, and another with the user ID or username which has events going forward. Since Product Analytics automatically creates a randomized unique identifier, it's not necessary for you to send your own identifier unless you are certain it is a unique, permanent identifier for the user. If you want to add properties to a user using `addUserProperties`, you can do so without providing a unique identifier. Calling `CSQ.addUserProperties({property: 'value'})` will add this property to the anonymous user's Product Analytics profile automatically. ## When and Where to Call identify and addUserProperties The `identify` and `addUserProperties` APIs can be called anytime and anywhere the data is available about that user. The typical place for an identify call that includes a unique identifier is on any post-login or post-signup page. Make an identify call on each page load as opposed to only the first page load. When setting properties, it's OK to call the `addUserProperties` API on any page, though you should add user properties on identified users. This will greatly improve your experience when analyzing your user base. You can place a `CSQ.identify` call within the Product Analytics installation snippet or outside of it. If you're adding a `CSQ.identify` call within the snippet, it should be placed after `Heap.load` within that snippet. ### Identity Examples #### Anonymous to New Identity Let's say we have an internal user ID from our own database, and we want to identify a user based on that ID. We can do that like this: ```javascript // userId = '12345' CSQ.identify(userId); ``` Now, their profile in the **Users** view will look like this:  #### Anonymous to Existing Identity In the last example, we identified a user with the unique user ID of 12345. Let's say that this person visits your site from their mobile device for the first time. Product Analytics will generate a new, random, unique userID, in this case it's 5404281197559477. In Product Analytics' users view, this visitor looks like this:  When this person logs in, and you recognize that their internal user ID is 12345, you can call identify like this: ```javascript //userId = '12345' CSQ.identify(userId); ``` The previous user's profile with the random user ID of 1565941335949135 is merged, along with its previous sessions and events into the Product Analytics profile of the identified user with the identity of 12345. ### addUserProperties Examples #### Common User Properties User properties can be used to capture additional data about a user, such as first and last name, email address, time zone, and account plan. The following example covers how to add an account plan user property using the client-side `CSQ.addUserProperties()` API, and this can be modified to capture any of the previously mentioned user properties. #### Account Plan Many products include some sort of tiered pricing plan. Using the [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) API to attach this information to your visitors' profiles can help you compare and contrast usage between different segments. When someone visits Product Analytics, we pull their account tier from our database and inject that into an identify call like this: ```javascript CSQ.addUserProperties({ plan: "Startup" }); ``` This lets us build powerful charts, like this bar chart showing sign-ups split by plan type. ### Industry Recommendations Call `CSQ.addUserProperties()` in the part of your website flow where the data you want to capture is being presented. Below are some examples of places to call the API, based on industry. | Industry | API Use Case | API Call Placement | | - | - | - | | e-Commerce | Improve personalization and recommendation algorithms. | On user login or significant actions (such as a purchase). Attach properties like login info, purchase amount, and spender type. | | Social media platform | Enhance user engagement and content personalization. | When a user updates their profile, adds interests, or engages in specific types of content. Attach custom properties like user interests or content preferences. | | Subscription-based service | Understand user demographics and preferences to optimize its offerings. | When a user signs up, completes a survey, or changes subscription preferences. Attach custom properties such as geographical location, email, or subscription plan details. | ## What about the identity API? Once you have the identify API set up, you can use [CSQ.metadata.userId](../command-reference/#csqmetadatauserid) to find a specific user's identity. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track identity","description":"Enhance user tracking with identify and addUserProperties APIs. Link anonymous and identified user data across sessions and devices for comprehensive analytics","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/track-identity/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Core SDK + Contentsquare SDK to CSQ SDK - Android description: Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-from-heap-and-cs-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-from-heap-and-cs-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-android/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide provides a step-by-step upgrade process from your current installation of Contentsquare and Heap Mobile to the latest version of the CSQ SDK.  **Heap Core SDK** \+  **Contentsquare SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. ## Dependency upgrades Replace Heap and Contentsquare SDK dependencies by the CSQ SDK: * Kotlin **build.gradle.kts** ```diff implementation("io.heap.core:heap-android-core:0.8.+") implementation("io.heap.contentsquare.csbridge:contentsquare-bridge:0.8.+) implementation("io.heap.autocapture:heap-autocapture-view:0.8.+") implementation("io.heap.autocapture:heap-autocapture-compose:0.8.+") implementation("com.contentsquare.android:library:4.39.1") implementation("com.contentsquare.android:compose:4.39.1") implementation("com.contentsquare.android:sdk:1.12.1") implementation("com.contentsquare.android:sdk-compose:1.12.1") ``` * Groovy **build.gradle** ```diff implementation 'io.heap.core:heap-android-core:0.8.+' implementation 'io.heap.contentsquare.csbridge:contentsquare-bridge:0.8.+' implementation 'io.heap.autocapture:heap-autocapture-view:0.8.+' implementation 'io.heap.autocapture:heap-autocapture-compose:0.8.+' implementation 'com.contentsquare.android:library:4.39.1' implementation 'com.contentsquare.android:sdk-compose:4.39.1' implementation 'com.contentsquare.android:sdk:1.12.1' implementation 'com.contentsquare.android:sdk-compose:1.12.1' ``` ## Library imports Replace the Heap and Contentsquare dependency imports with a CSQ SDK import. ```diff import io.heap.core.Heap import io.heap.autocapture.ViewAutocaptureSDK import io.heap.contentsquare.csbridge.HeapContentsquareIntegration import com.contentsquare.android.Contentsquare import com.contentsquare.CSQ ``` ## SDK start Follow these steps to start the CSQ SDK with your current configuration. 1. Delete `Heap.startRecording()` and migrate configuration options to `CSQ.start()`. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() Heap.startRecording( context = this, "YOUR_ENVIRONMENT_ID", Options( // ...options ) ) CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() Heap.startRecording( context = this, "YOUR_ENVIRONMENT_ID", Options( // ...options ) ) CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options ) ) ) } } ``` Deprecated configuration options The following Heap SDK configuration options are not supported in the CSQ SDK: * `startSessionImmediately` * `disableInteractionTextCapture` * `disableInteractionAccessibilityLabelCapture` * `captureVendorId` * `captureAdvertiserId` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `resumePreviousSession` * `pruningLookBackWindow` * `maximumDatabaseSize` * `maximumBatchCountPerUpload` * `disableUploadsInBackground` See [supported options](../command-reference/#sdk-configuration-options) for more information. 2. Enable Autocapture with `enableViewAutocapture = true` and remove the call to `ViewAutocaptureSDK.register()` * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() ViewAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() ViewAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` 3. (Optional) For Autocapture Jetpack Compose, register the Compose Autocapture SDK. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import io.heap.autocapture.compose.ComposeAutocaptureSDK class MyApplication : Application() { override fun onCreate() { super.onCreate() ComposeAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import io.heap.autocapture.compose.ComposeAutocaptureSDK class MyApplication : Application() { override fun onCreate() { super.onCreate() ComposeAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` 4. Remove `HeapContentsquareIntegration.bind()`. Sending Heap screenviews to Contentsquare **MyApplication.kt** ```kotlin HeapContentsquareIntegration.bind( applicationContext, sendHeapPageviewsToContentsquare = true, sendContentsquareScreenviewsToHeap = false ) ``` Note Make sure you don't have calls to `CSQ.trackScreenview()` if you have Android View autocapture enabled. Sending Contentsquare screenviews to Heap * Product Analytics **MyApplication.kt** ```kotlin HeapContentsquareIntegration.bind( applicationContext, sendHeapPageviewsToContentsquare = false, sendContentsquareScreenviewsToHeap = true ) CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( disablePageviewAutocapture = true ) ) ) ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin HeapContentsquareIntegration.bind( applicationContext, sendHeapPageviewsToContentsquare = false, sendContentsquareScreenviewsToHeap = true ) CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( disablePageviewAutocapture = true ) ) ) ``` 5. (Optional) For Autocapture notifications, replace `NotificationAutocaptureSDK.register()` with these options: * Product Analytics **MyApplication.kt** ```kotlin NotificationAutocaptureSDK.register( captureTitleText = true, captureBodyText = true ) CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options enablePushNotificationAutocapture = true, enablePushNotificationTitleAutocapture = true, enablePushNotificationBodyAutocapture = true ) ) ) ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin NotificationAutocaptureSDK.register( captureTitleText = true, captureBodyText = true ) CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options enablePushNotificationAutocapture = true, enablePushNotificationTitleAutocapture = true, enablePushNotificationBodyAutocapture = true ) ) ) ``` 6. (Optional) If you have chosen to deactivate the autostart of the Contentsquare SDK, you can now remove the entry in the manifest, as the CSQ SDK doesn't have an autostart. **AndroidManifest.xml** ```xml <application> ... <meta-data android:name="com.contentsquare.android.autostart" android:value="false" /> ... </application> ``` ## Get user consent Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. * Product Analytics ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this, StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` * CSQ Experience Platform (Early Access) ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this, StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more. Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code. ## Transactions 1. Update your transaction imports: ```diff import com.contentsquare.android.api.model.Transaction import com.contentsquare.api.model.Transaction ``` 2. Update your currency imports: ```diff import com.contentsquare.android.api.Currencies import com.contentsquare.api.model.Currency ``` 3. Replace the currency type from `Int` to `Currency` enum: ```diff val currency: Int = Currencies.USD val currency: Currency = Currency.USD ``` 4. Replace `Transaction.builder` by `Transaction` and `Contentsquare.send()` by `CSQ.trackTransaction()`: ```diff val builder = Transaction.builder(100f, Currency.EUR).id("optionalId") Contentsquare.send(builder.build()) val transaction = Transaction(100f, Currency.EUR, "optionalId") CSQ.trackTransaction(transaction) ``` ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. ```diff Contentsquare.start(this) Heap.startRecording("YOUR_ENVIRONMENT_ID") CSQ.start(this, StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")) ``` The latest version of our CSQ SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. For more information on SDK methods, see the [SDK API reference](../command-reference/). ### Product Analytics ### GDPR / Identification | Heap Core SDK | CSQ SDK | | - | - | | `Heap.identify(identity: String)` | `CSQ.identify(identity: String)` | | `Heap.resetIdentity()` | `CSQ.resetIdentity()` | | `Heap.getUserId()` | `CSQ.metadata.userId` | | `Heap.getSessionId()` | `CSQ.metadata.sessionId` | | `Heap.getEnvironmentId()` | `CSQ.metadata.environmentId` | | `Heap.getIdentity()` | `CSQ.metadata.identity` | ### Logging | Heap Core SDK | CSQ SDK | | - | - | | `import io.heap.core.logs.LogLevel` | `import com.contentsquare.api.contract.LogLevel` | | `Heap.setLogLevel()` | `CSQ.debug.logLevel = LogLevel.{LEVEL}` Possible values: - `LogLevel.NONE` - `LogLevel.TRACE` - `LogLevel.DEBUG` - `LogLevel.INFO` - `LogLevel.WARN` - `LogLevel.ERROR` | | `import io.heap.core.logs.LogChannel` | `import com.contentsquare.api.contract.LogChannel` | | `Heap.setLogChannel(logChannel: LogChannel)` | `interface LogChannel` `CSQ.debug.logChannel = LogChannel()` | ### Property tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.addUserProperties(properties: Map<String, Any>)` | `CSQ.addUserProperties(properties: Map<String, Any>)` | | `Heap.addEventProperties(properties: Map<String, Any>)` | `CSQ.addEventProperties(properties: Map<String, Any>)` | | `Heap.removeEventProperty(name: String)` | `CSQ.removeEventProperty(name: String)` | | `Heap.clearEventProperties()` | `CSQ.clearEventProperties()` | | `import io.heap.core.api.contract.HeapProperty` | `import com.contentsquare.api.contract.Property` | ### Event tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.trackPageview()` | `CSQ.trackScreenview(name: String, customVars: List<CustomVar>)` | | `Heap.track()` | `CSQ.trackEvent(name: String, properties: Map<String, PropertyValue>?)` | ### Personal Data Handling and Masking | Heap Core SDK | CSQ SDK | | - | - | | `ViewAutocaptureSDK.ignoreInteractions(view: View)` | `CSQ.ignoreInteractions(view: View, includeSubtree: Boolean)` | | `ViewAutocaptureSDK.redactText(view: View)` | `CSQ.mask(view: View)` | | `view.setTag(R.id.heapRedactText, false)` | `CSQ.unmask(view: View)` | | Initialization options `disableInteractionTextCapture` and `disableInteractionAccessibilityLabelCapture` | `CSQ.maskTexts(mask: Boolean)` | Kotlin extension functions If you use Kotlin, the CSQ SDK comes with Extension functions for: * `CSQ.ignoreInteractions(view: View, includeSubtree: Boolean)` -> `View.csqIgnoreInteractions(includeSubtree: Boolean)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(true)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(false)` ### Jetpack compose | Heap Core SDK | CSQ SDK | | - | - | | ``` @Composable HeapRedact(redact: Boolean) ``` | ``` @Composable CsqMask(enable: Boolean) ``` | | ``` @Composable HeapIgnore(ignore: Boolean) ``` | ``` @Composable CsqIgnoreInteraction(ignore: Boolean) ``` | ### SDK initialization and manipulation | Heap Core SDK | CSQ SDK | | - | - | | `import io.heap.core.Options` | `import com.contentsquare.api.model.AnalyticsOptions` | | Heap SDK initialization options | `CSQ.start(context, StartConfig.withEnvironmentId(id = "envId", options = AnalyticsOptions()))` See [supported options](../command-reference/#sdk-configuration-options) for more information. | | `Heap.startRecording(context: Context, envId: String, options: Options)` | `CSQ.start(context, StartConfig.withEnvironmentId(id = "envId", options = AnalyticsOptions()))` | | `Heap.startRecording(context: Context, envId: String, options: Options)` with `resumePreviousSession = true` | `CSQ.resumeTracking()` | | `Heap.stopRecording()` | `CSQ.stop()` or `CSQ.pauseTracking()` | | `Heap.stopRecording(deleteUser = true)` | `CSQ.stop()` + `CSQ.optOut()` | ### Experience Analytics ### GDPR / Identification | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.optIn(context: Context)` | `CSQ.optIn()` | | `Contentsquare.optOut(context: Context)` | `CSQ.optOut()` | | `Contentsquare.getUserId()` | `CSQ.metadata.userId` | | `Contentsquare.getProjectId()` | `CSQ.metadata.projectId` | | `Contentsquare.getSessionNumber()` | `CSQ.metadata.sessionId` | | `Contentsquare.sendUserIdentifier(identifier: String)` | `CSQ.sendUserIdentifier(identifier: String)` | ### Property tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.send(key: String, value: Long)` | `CSQ.addDynamicVar(key: String, value: Long)` | | `Contentsquare.send(key: String, value: String)` | `CSQ.addDynamicVar(key: String, value: String)` | ### View tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.excludeFromExposureMetric(view: View)` | `CSQ.excludeFromExposureMetric(view: View)` | ### Interoperability | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.onSessionReplayLinkChange(callback: Consumer<String>)` | `CSQ.metadata.onChanged(metadata: Metadata)` | | `CsWebViewManager.injectEventTrackingInterface(webView: WebView)` | `CSQ.registerWebView(webView: WebView)` | | `CsWebViewManager.removeEventTrackingInterface(webView: WebView)` | `CSQ.unregisterWebView(webView: WebView)` | ### Event tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.send(transaction: Transaction)` | `CSQ.trackTransaction(transaction: Transaction)` | | `Contentsquare.send(screenName: String)` / `Contentsquare.send(screenName: String, customVars: Array<CustomVar>)` | `CSQ.trackScreenview(name: String, customVars: List<CustomVar>)` | | `Contentsquare.consumeEvent(motionEvent: MotionEvent)` | `CSQ.trackMotionEvent(motionEvent: MotionEvent)` | Jetpack compose | Contentsquare SDK | CSQ SDK | | - | - | | `import com.contentsquare.android.compose.analytics.TriggeredOnResume` `TriggeredOnResume(block: () -> Unit)` | `import com.contentsquare.api.compose.screen.TriggeredOnResume` `TriggeredOnResume(block: () -> Unit)` | ### Error tracking | Contentsquare SDK | CSQ SDK | | - | - | | `import com.contentsquare.android.error.analysis.network.ErrorAnalysisInterceptor` | `import com.contentsquare.api.contract.CsqOkHttpInterceptor` | | `import com.contentsquare.android.error.analysis.ErrorAnalysis` | `import com.contentsquare.api.model.NetworkMetric` | | `ErrorAnalysis.setUrlMaskingPatterns(patterns: List<String>)` | `CSQ.setUrlMaskingPatterns(patterns: List<String>)` | | `ErrorAnalysis.getInstance().newNetworkMetric(url: String, httpMethod: HttpMethod)` | `NetworkMetric(url: String, httpMethod: HttpMethod)` | | `ErrorAnalysisInterceptor()` | `CsqOkHttpInterceptor()` | ### Personal Data Handling and Masking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.doNotTrack(vararg activitiesClasses: Class<Activity?>)` | `CSQ.ignoreInteractions(view: View)` | | `Contentsquare.setDefaultMasking(masked: Boolean)` | `CSQ.setDefaultMasking(masked: Boolean)` | | `Contentsquare.mask(view: View)` | `CSQ.mask(view: View)` | | `Contentsquare.mask(type: Class<*>)` | `CSQ.mask(type: Class<*>)` | | `Contentsquare.unMask(view: View)` | `CSQ.unmask(view: View)` | | `Contentsquare.unmask(type: Class<*>)` | `CSQ.unmask(type: Class<*>)` | | `Contentsquare.maskMenuItem(resourceID: Int)` | `CSQ.maskMenuItem(resourceID: Int)` | | `Contentsquare.unMaskMenuItem(resourceID: Int)` | `CSQ.unmaskMenuItem(resourceID: Int)` | Kotlin extension functions If you use Kotlin, the CSQ SDK comes with Extension functions for: * `CSQ.ignoreInteractions(view: View, includeSubtree: Boolean)` -> `View.csqIgnoreInteractions(includeSubtree: Boolean)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(true)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(false)` ### Jetpack compose | Contentsquare SDK | CSQ SDK | | - | - | | `Modifier.sessionReplayMask(enableMasking: Boolean)` | `@Composable CsqMask(enable: Boolean) { }` | | `Modifier.excludeFromGestureRecognition()` | `@Composable CsqIgnoreInteraction(ignore: Boolean)` | ### SDK initialization and manipulation | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.start(context: Context)` | `CSQ.start(context: Context)` | | `Contentsquare.stopTracking()` | `CSQ.pauseTracking()` | | `Contentsquare.resumeTracking()` | `CSQ.resumeTracking()` | ## Number of sessions Session timeout definition changed: * **Before**: 30 minutes after app goes to background * **Now**: 30 minutes after last event This may affect session counts and aligns with web and market standards. ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that your build files no longer reference `io.heap.core:heap-android-core`, `io.heap.autocapture:heap-autocapture-view`, `com.contentsquare.android:library`, or `com.contentsquare.android:sdk-compose`. Your `import io.heap.core.Heap`, `import io.heap.autocapture.ViewAutocaptureSDK`, and `com.contentsquare.android.Contentsquare;` declarations have been updated to `import com.contentsquare.CSQ`. You no longer have references to `Heap.` (except if you are using webviews), `HeapContentsquareIntegration.`, or `Contentsquare.` methods in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK + Contentsquare SDK to CSQ SDK","description":"Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-from-heap-and-cs-sdk/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track events manually - Android description: Learn how to implement custom event tracking in your Android app with the CSQ SDK for capturing user interactions and business events lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/track-events-manually/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/track-events-manually/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. In addition to autocaptured events, use the `CSQ.trackEvent()` API to send custom events and attach properties to them for use in Product Analytics. ```kotlin import com.contentsquare.CSQ CSQ.trackEvent("purchase_completed") ``` It doesn't matter what you call your event, there are ways in Product Analytics to cross-track events regardless of name. See our [guide on combo events ↗](https://help.heap.io/hc/en-us/articles/37271999013009-How-to-combine-events-using-a-combo-event) to learn more. ## Adding Properties to Custom Events Custom events can be enhanced with a set of properties that will correspond to the tracked event when passed into the `CSQ.trackEvent()` API call. ```kotlin val properties = mapOf( "property1" to "sample value", "property2" to 10, "property3" to false ) CSQ.trackEvent("custom_event_with_properties", properties) ``` ## Adding Properties to All Events In some cases, you might want to add a property, or a collection of properties, to all events tracked by Product Analytics. Adding a global event property can be accomplished using `CSQ.addEventProperties()`. ```kotlin val globalProperties = mapOf( "property1" to "sample value", "property2" to 10, "property3" to false ) CSQ.addEventProperties(globalProperties) ``` Properties that are added using the `CSQ.addEventProperties()` API will be attached to all events tracked by Product Analytics, including any events that are automatically tracked by a CSQ autocapture SDK. ## Removing a Property Once a property is no longer needed in the global collection, use `CSQ.removeEventProperty()` to remove properties one at a time. ```kotlin CSQ.removeEventProperty("property1") ``` ## Removing All Properties On the other hand, if you want to remove all properties added with `CSQ.addEventProperties()` at once, you can achieve this by using `CSQ.clearEventProperties()`. ```kotlin CSQ.clearEventProperties() ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track events manually","description":"Learn how to implement custom event tracking in your Android app with the CSQ SDK for capturing user interactions and business events","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/track-events-manually/","inLanguage":"en","dateModified":"2026-05-04T12:00:05+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Core SDK to CSQ SDK - Android description: Learn how to migrate from the Heap Core SDK to the CSQ SDK lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-from-heap-core-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-from-heap-core-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-android/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide provides a step-by-step upgrade process from your current installation of Heap Mobile to the latest version of the CSQ SDK.  **Heap Core SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. ## Dependency upgrades Replace Heap SDK dependencies with the CSQ SDK: * Kotlin **build.gradle.kts** ```diff implementation("io.heap.core:heap-android-core:0.8.+") implementation("io.heap.core.web:webview-heapjs:0.8.+") implementation("io.heap.core.identifier:ad-id-google:0.8.+") implementation("io.heap.core.identifier:vendor-id-google:0.8.+") implementation("io.heap.autocapture:heap-autocapture-view:0.8.+") implementation("io.heap.autocapture:heap-autocapture-notification:0.8.+") implementation("io.heap.autocapture:heap-autocapture-compose:0.8.+") implementation("com.contentsquare.android:sdk:1.12.1") implementation("com.contentsquare.android:sdk-compose:1.12.1") ``` * Groovy **build.gradle** ```diff implementation 'io.heap.core:heap-android-core:0.8.+' implementation 'io.heap.core.web:webview-heapjs:0.8.+' implementation 'io.heap.core.identifier:ad-id-google:0.8.+' implementation 'io.heap.core.identifier:vendor-id-google:0.8.+' implementation 'io.heap.autocapture:heap-autocapture-view:0.8.+' implementation 'io.heap.autocapture:heap-autocapture-notification:0.8.+' implementation 'io.heap.autocapture:heap-autocapture-compose:0.8.+' implementation 'com.contentsquare.android:sdk:1.12.1' implementation 'com.contentsquare.android:sdk-compose:1.12.1' ``` Heap Gradle plugin If you're using autocapture, the Heap Gradle plugin must remain in your project configuration. * Kotlin **build.gradle.kts** ```kotlin plugins { id("io.heap.gradle") version "1.1.1" // ... } ``` * Groovy **build.gradle** ```groovy plugins { id 'io.heap.gradle' version "1.1.1" // ... } ``` ## Library imports Replace Heap Core and Autocapture SDK imports with the CSQ SDK import. ```diff import io.heap.core.Heap import io.heap.autocapture.ViewAutocaptureSDK import io.heap.autocapture.notification.NotificationAutocaptureSDK import com.contentsquare.CSQ ``` ## SDK start Follow these steps to start the CSQ SDK with your current configuration. 1. Delete `Heap.startRecording()` and migrate configuration options to `CSQ.start()`. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() Heap.startRecording( context = this, "YOUR_ENVIRONMENT_ID", Options( // ...options ) ) CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() Heap.startRecording( context = this, "YOUR_ENVIRONMENT_ID", Options( // ...options ) ) CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options ) ) ) } } ``` Deprecated configuration options The following Heap SDK configuration options are not supported in the CSQ SDK: * `startSessionImmediately` * `disableInteractionTextCapture` * `disableInteractionAccessibilityLabelCapture` * `captureVendorId` * `captureAdvertiserId` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `resumePreviousSession` * `pruningLookBackWindow` * `maximumDatabaseSize` * `maximumBatchCountPerUpload` * `disableUploadsInBackground` See [supported options](../command-reference/#sdk-configuration-options) for more information. 2. Enable Autocapture with `enableViewAutocapture = true` and remove the call to `ViewAutocaptureSDK.register()` * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() ViewAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() ViewAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` 3. (Optional) For Autocapture Jetpack Compose, register the Compose Autocapture SDK. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import io.heap.autocapture.compose.ComposeAutocaptureSDK class MyApplication : Application() { override fun onCreate() { super.onCreate() ComposeAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import io.heap.autocapture.compose.ComposeAutocaptureSDK class MyApplication : Application() { override fun onCreate() { super.onCreate() ComposeAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` ## Get user consent Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. * Product Analytics ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this, StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` * CSQ Experience Platform (Early Access) ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this, StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more. Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code. ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. ```diff Heap.startRecording("YOUR_ENVIRONMENT_ID") CSQ.start(this, StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")) ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### GDPR / Identification | Heap Core SDK | CSQ SDK | | - | - | | `Heap.identify(identity: String)` | `CSQ.identify(identity: String)` | | `Heap.resetIdentity()` | `CSQ.resetIdentity()` | | `Heap.getUserId()` | `CSQ.metadata.userId` | | `Heap.getSessionId()` | `CSQ.metadata.sessionId` | | `Heap.getEnvironmentId()` | `CSQ.metadata.environmentId` | | `Heap.getIdentity()` | `CSQ.metadata.identity` | ### Logging | Heap Core SDK | CSQ SDK | | - | - | | `import io.heap.core.logs.LogLevel` | `import com.contentsquare.api.contract.LogLevel` | | `Heap.setLogLevel()` | `CSQ.debug.logLevel = LogLevel.{LEVEL}` Possible values: - `LogLevel.NONE` - `LogLevel.TRACE` - `LogLevel.DEBUG` - `LogLevel.INFO` - `LogLevel.WARN` - `LogLevel.ERROR` | | `import io.heap.core.logs.LogChannel` | `import com.contentsquare.api.contract.LogChannel` | | `Heap.setLogChannel(logChannel: LogChannel)` | `interface LogChannel` `CSQ.debug.logChannel = LogChannel()` | ### Property tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.addUserProperties(properties: Map<String, Any>)` | `CSQ.addUserProperties(properties: Map<String, Any>)` | | `Heap.addEventProperties(properties: Map<String, Any>)` | `CSQ.addEventProperties(properties: Map<String, Any>)` | | `Heap.removeEventProperty(name: String)` | `CSQ.removeEventProperty(name: String)` | | `Heap.clearEventProperties()` | `CSQ.clearEventProperties()` | | `import io.heap.core.api.contract.HeapProperty` | `import com.contentsquare.api.contract.Property` | ### Event tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.trackPageview()` | `CSQ.trackScreenview(name: String, customVars: List<CustomVar>)` | | `Heap.track()` | `CSQ.trackEvent(name: String, properties: Map<String, PropertyValue>?)` | ### Personal Data Handling and Masking | Heap Core SDK | CSQ SDK | | - | - | | `ViewAutocaptureSDK.ignoreInteractions(view: View)` | `CSQ.ignoreInteractions(view: View, includeSubtree: Boolean)` | | `ViewAutocaptureSDK.redactText(view: View)` | `CSQ.mask(view: View)` | | `view.setTag(R.id.heapRedactText, false)` | `CSQ.unmask(view: View)` | | Initialization options `disableInteractionTextCapture` and `disableInteractionAccessibilityLabelCapture` | `CSQ.maskTexts(mask: Boolean)` | Kotlin extension functions If you use Kotlin, the CSQ SDK comes with Extension functions for: * `CSQ.ignoreInteractions(view: View, includeSubtree: Boolean)` -> `View.csqIgnoreInteractions(includeSubtree: Boolean)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(true)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(false)` ### Jetpack compose | Heap Core SDK | CSQ SDK | | - | - | | ``` @Composable HeapRedact(redact: Boolean) ``` | ``` @Composable CsqMask(enable: Boolean) ``` | | ``` @Composable HeapIgnore(ignore: Boolean) ``` | ``` @Composable CsqIgnoreInteraction(ignore: Boolean) ``` | ### SDK initialization and manipulation | Heap Core SDK | CSQ SDK | | - | - | | `import io.heap.core.Options` | `import com.contentsquare.api.model.AnalyticsOptions` | | Heap SDK initialization options | `CSQ.start(context, StartConfig.withEnvironmentId(id = "envId", options = AnalyticsOptions()))` See [supported options](../command-reference/#sdk-configuration-options) for more information. | | `Heap.startRecording(context: Context, envId: String, options: Options)` | `CSQ.start(context, StartConfig.withEnvironmentId(id = "envId", options = AnalyticsOptions()))` | | `Heap.startRecording(context: Context, envId: String, options: Options)` with `resumePreviousSession = true` | `CSQ.resumeTracking()` | | `Heap.stopRecording()` | `CSQ.stop()` or `CSQ.pauseTracking()` | | `Heap.stopRecording(deleteUser = true)` | `CSQ.stop()` + `CSQ.optOut()` | ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that your build files no longer reference `com.contentsquare.android:library`, `io.heap.core:heap-android-core`, or `io.heap.autocapture:heap-autocapture-view`. Your `io.heap.*` import declarations have been updated to `import com.contentsquare.CSQ`. You no longer have references to `Heap.` methods in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK to CSQ SDK","description":"Learn how to migrate from the Heap Core SDK to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-from-heap-core-sdk/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Classic SDK to CSQ SDK - Android description: Learn how to migrate from the Heap Classic SDK to the CSQ SDK lastUpdated: 07 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-from-heap-classic-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-from-heap-classic-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-android/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide provides a step-by-step upgrade process from your current installation of Heap Mobile to the latest version of the CSQ SDK.  **Heap Classic SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. Key differences from Heap Classic SDK * **Custom tracking first**: CSQ SDK starts with custom tracking APIs; you should use autocapture (vs Classic's autocapture-by-default approach) * **Different autocapture events**: Captures slider/date/time picker changes instead of menu/carousel/tab clicks, with enhanced UI hierarchy data * **Live View only**: Visual Labeler is no longer supported * **Opt-out by default**: Must call `CSQ.optIn()` to start tracking * **Separate storage**: Expect temporary spike in new users/installs during migration * **Removed properties**: No longer captures `ANDROID_ID`, `Build Type`, or `Build Flavor` ## Dependency upgrades Replace the Heap Classic SDK dependency by the CSQ SDK. * Kotlin **build.gradle.kts** ```diff implementation("com.heapanalytics.android:heap-android-client:1.10.+") implementation("com.contentsquare.android:sdk:1.12.1") ``` * Groovy **build.gradle** ```diff implementation 'com.heapanalytics.android:heap-android-client:1.10.+' implementation 'com.contentsquare.android:sdk:1.12.1' ``` ## Library imports Replace Heap Classic imports with a CSQ SDK import. ```diff import com.heapanalytics.android.Heap import com.contentsquare.CSQ ``` ## SDK start Follow these steps to start the CSQ SDK with your current configuration. 1. Migrate your app ID from `Heap.init()` to `CSQ.start()`. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() Heap.init(this, "YOUR_ENVIRONMENT_ID") CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID" ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() Heap.init(this, "YOUR_ENVIRONMENT_ID") CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID" ) ) } } ``` 2. To maintain autocapture functionality, add the `enableViewAutocapture` option: * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import com.contentsquare.api.model.AnalyticsOptions class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import com.contentsquare.api.model.AnalyticsOptions class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` 3. (Optional) For Autocapture Jetpack Compose, register the Compose Autocapture SDK. * Product Analytics **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import io.heap.autocapture.compose.ComposeAutocaptureSDK class MyApplication : Application() { override fun onCreate() { super.onCreate() ComposeAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` * CSQ Experience Platform (Early Access) **MyApplication.kt** ```kotlin import android.app.Application import com.contentsquare.CSQ import io.heap.autocapture.compose.ComposeAutocaptureSDK class MyApplication : Application() { override fun onCreate() { super.onCreate() ComposeAutocaptureSDK.register() CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( // ...options enableViewAutocapture = true ) ) ) } } ``` ## Get user consent Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. * Product Analytics ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this, StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` * CSQ Experience Platform (Early Access) ```kotlin import android.app.Application import com.contentsquare.CSQ class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(this, StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")) } } // ConsentActivity val optinButton: Button = findViewById(R.id.btn_accept_tracking) optinButton.setOnClickListener { CSQ.optIn() startActivity(Intent(this, MainActivity::class.java)) } ``` Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more. Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code. ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. ```diff Heap.init("YOUR_ENVIRONMENT_ID") CSQ.start(this, StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")) ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### GDPR / Identification | Heap Core SDK | CSQ SDK | | - | - | | `Heap.identify(identity: String)` | `CSQ.identify(identity: String)` | | `Heap.resetIdentity()` | `CSQ.resetIdentity()` | | `Heap.getUserId()` | `CSQ.metadata.userId` | | `Heap.getSessionId()` | `CSQ.metadata.sessionId` | | `Heap.getIdentity()` | `CSQ.metadata.identity` | ### Property tracking | Heap Classic SDK | CSQ SDK | | - | - | | `Heap.addUserProperties(properties: Map<String, String>)` | `CSQ.addUserProperties(properties: Map<String, Any>)` | | `Heap.addEventProperties(properties: Map<String, String>)` | `CSQ.addEventProperties(properties: Map<String, Any>)` | | `Heap.removeEventProperty(name: String)` | `CSQ.removeEventProperty(name: String)` | | `Heap.clearEventProperties()` | `CSQ.clearEventProperties()` | ### Event tracking | Heap Classic SDK | CSQ SDK | | - | - | | `Heap.track(event: String, properties: Map<String, String>)` | `CSQ.trackEvent(name: String, properties: Map<String, PropertyValue>?)` | ### Personal Data Handling and Masking | Heap Classic SDK | CSQ SDK | | - | - | | `Heap.ignore(view: View)` | `CSQ.ignoreInteractions(view: View, includeSubtree: Boolean)` | Kotlin extension functions If you use Kotlin, the CSQ SDK comes with Extension functions for: * `CSQ.ignoreInteractions(view: View, includeSubtree: Boolean)` -> `View.csqIgnoreInteractions(includeSubtree: Boolean)` * `CSQ.unmask(view: View)` -> `View.csqMaskContents(false)` ### SDK initialization and manipulation | Heap Classic SDK | CSQ SDK | | - | - | | `Heap.init(context: Context, id: String)` | `CSQ.start(context: Context)` | | `Heap.setTrackingEnabled(true)` | `CSQ.resumeTracking()` | | `Heap.setTrackingEnabled(false)` | `CSQ.pauseTracking()` | ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that your build files no longer reference `com.heapanalytics.android:heap-android-client`. Your `import com.heapanalytics.android.Heap` declarations have been updated to `import com.contentsquare.CSQ`. You no longer have references to `Heap.` methods in your codebase. All calls to the CSQ SDK use the `CSQ.` namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Classic SDK to CSQ SDK","description":"Learn how to migrate from the Heap Classic SDK to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-from-heap-classic-sdk/","inLanguage":"en","dateModified":"2026-08-07T08:07:46+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track push notifications - Android description: Learn how to track mobile notification interactions automatically with Contentsquare lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/track-push-notifications/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/track-push-notifications/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. After completing the setup process you will be able to: * Automatically track interactions on your mobile notifications * Define and analyze notification interaction events in Contentsquare ## Installing Notification Autocapture Notification autocapture is included in the CSQ SDK. You only need to install the Heap Gradle Plugin: * Kotlin **build.gradle.kts** ```kotlin plugins { // ... id("io.heap.gradle") version "1.1.1" } ``` * Groovy **build.gradle** ```groovy plugins { // ... id 'io.heap.gradle' version "1.1.1" } ``` ## Initializing Notification Autocapture Notification autocapture can be initialized with `enablePushNotificationAutocapture: true` in `CSQ.start()`. * Product Analytics ```kotlin CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enablePushNotificationAutocapture = true ) ) ) ``` * CSQ Experience Platform (Early Access) ```kotlin CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( enablePushNotificationAutocapture = true ) ) ) ``` Capture the title or body text of the notification where an interaction was performed using `enablePushNotificationTitleAutocapture` and `enablePushNotificationBodyAutocapture`. * Product Analytics ```kotlin CSQ.start( context = this, StartConfig.withEnvironmentId( id = "YOUR_ENVIRONMENT_ID", options = AnalyticsOptions( enablePushNotificationAutocapture = true, enablePushNotificationTitleAutocapture = true, enablePushNotificationBodyAutocapture = true ) ) ) ``` * CSQ Experience Platform (Early Access) ```kotlin CSQ.start( context = this, StartConfig.withDataSourceId( id = "YOUR_DATASOURCE_ID", options = AnalyticsOptions( enablePushNotificationAutocapture = true, enablePushNotificationTitleAutocapture = true, enablePushNotificationBodyAutocapture = true ) ) ) ``` Once registered, Contentsquare will begin collecting interaction events on notifications. ## What's Next? With notification data flowing, you'll want to jump into Product Analytics and start defining notification interaction events. These events will show up as a special "Notification Interaction" event type in Product Analytics and have several properties available to create definitions: * **Notification Title**: The title text of the notification. Capture can be enabled/disabled via a config option as described above. * **Notification Body**: The body text of the notification. Capture can be enabled/disabled via a config option as described above. * **Notification Action**: The text of the notification action that was interacted with, if any. * **Notification Source**: What caused the notification to fire. This could be a push service, a geofence, or unknown. * **Notification Handling Component**: The name of the component in code that handled the notification interaction. * **Notification Category**: This is the notification channel that the notification was delivered to. This typically denotes the type of notification that with which the interaction occurred. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track push notifications","description":"Learn how to track mobile notification interactions automatically with Contentsquare","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/track-push-notifications/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Upgrade your SDK - Android description: Understand the benefits of upgrading to the CSQ SDK lastUpdated: 12 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-your-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-your-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-android/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This section guides you through the upgrade from your current SDK implementation to our latest CSQ SDK. Upgrading has no impact on your current data collection (except for "Heap Classic SDK") and does not alter the data observed on the platform. It mainly consists of searching and replacing APIs according to the mappings provided in the upgrade guides. Get started by selecting the upgrade guide that corresponds to your current implementation: * **[Heap Core SDK](../upgrade-from-heap-core-sdk/)** - Upgrade from Heap Core SDK * **[Heap Classic SDK](../upgrade-from-heap-classic-sdk/)** - Upgrade from Heap Classic SDK * **[Heap SDK + Contentsquare SDK](../upgrade-from-heap-and-cs-sdk/)** - Upgrade from combined Heap and Contentsquare SDKs ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Upgrade your SDK","description":"Understand the benefits of upgrading to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-your-sdk/","inLanguage":"en","dateModified":"2026-05-12T12:05:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Agent skills for Android - Android description: Use AI coding assistants to integrate, upgrade, and configure the Contentsquare Android SDK with downloadable Agent skills lastUpdated: 16 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/using-agent-skills/ md: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/using-agent-skills/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use the Contentsquare wizard or skills to set up, update, and configure Android with your AI coding assistant. Disclaimer This skill guides your AI coding agent through the SDK installation and implementation. The agent you use (Cursor, Claude Code, Copilot) is your own tool and operates under your settings and permissions. Contentsquare is not responsible for how your agent interprets or applies the instructions contained in these files. ## Contentsquare wizard Run the wizard in your project directory. It configures your AI coding assistant, installs the matching Contentsquare integration, and verifies the installation. ```shell npx @contentsquare/wizard install ``` Supports GitHub Copilot, Cursor, and Claude Code. Requires Node.js ≥ 18 and an AI coding agent with MCP support. ## Manual setup Use this path when you prefer to configure your AI coding assistant yourself. ### 1. Add the Contentsquare skill Choose how to install the Contentsquare skill. * Copilot CLI Add the Contentsquare marketplace, then install the plugin for Android: ```shell copilot plugin marketplace add ContentSquare/agents copilot plugin install contentsquare-android@contentsquare ``` * Claude Code Add the Contentsquare marketplace, then install the plugin for Android: ```shell /plugin marketplace add ContentSquare/agents /plugin install contentsquare-android@contentsquare ``` * Cursor Install **contentsquare** from the [Cursor marketplace ↗](https://cursor.com/marketplace), or add the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents) directly. Cursor reads the `.cursor-plugin` catalog in the repository. * Other agents Install the Contentsquare skill pack with the open `skills.sh` ecosystem: ```shell npx skills add contentsquare/agents ``` * From source Download or clone the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents), then copy `skills/contentsquare-android-sdk` into the location your AI coding assistant scans for skills: | AI coding assistant | Skill location | | - | - | | GitHub Copilot | `.github/skills/` or `.agents/skills/` | | Cursor | `.cursor/rules/` or the project root | | Claude Code | `.claude/skills/` or the project root | | Other compatible agents | `.agents/skills/` | ### 2. Ask your AI coding assistant After installing the skill, paste this prompt into your AI coding assistant: ```text Install Contentsquare for Android. ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Agent skills for Android","description":"Use AI coding assistants to integrate, upgrade, and configure the Contentsquare Android SDK with downloadable Agent skills","url":"https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/using-agent-skills/","inLanguage":"en","dateModified":"2026-07-16T17:50:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Adobe Analytics - Flutter description: Leverage our native integration to use Adobe Analytics segments in Contentsquare, with the CSQ Flutter SDK lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/adobe-analytics/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/adobe-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Analyze your data from anywhere in the customer journey using your Adobe Analytics segments. Contentsquare allows you to use your Adobe Analytics segments in every Contentsquare feature (Journey Analysis, Page Comparator, Session Replay). Warning Sessions without at least one screenview will be discarded. You should implement your screen tracking plan first, to have your Adobe Analytics integration work. See [Track screens](../track-screens/). ## Prerequisites 1. Follow the instructions from [Adobe Analytics for mobile apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271665881745) 2. Add the [`flutter_aepedge` package ↗](https://pub.dev/packages/flutter_aepedge) to your project and follow its instructions. ## Code implementation Adobe SDK code requirements On the native Android and iOS parts of your Flutter project, make sure you have followed the instructions of [Usage of `flutter_aepedge` ↗](https://pub.dev/packages/flutter_aepedge#usage). **Why 30 minutes before sending a new csMatchingKey** * 30 minutes is Contentsquare default session duration. * Setting a value **higher** than 30 minutes would cause overlapping on our sessions, and would impact negatively the data import from Adobe. * Setting a value **lower** than 30 minutes would make you to send more data to Adobe. This could cause the variable to reach Adobe's threshold, causing Adobe to filter values, and potentially impact your billing. See [Low-traffic value in Adobe Analytics ↗](https://experienceleague.adobe.com/docs/analytics/technotes/low-traffic.html) Add the following code snippet in your application code. Add a call to the `sendCSMatchingKeyIfNeeded()` from within the `initState` of your application. Listen to `AppLifecycleState` change and call `sendCSMatchingKeyIfNeeded()` when the application resumed. ```dart import 'package:contentsquare/csq.dart'; import 'package:flutter_aepedge/flutter_aepedge.dart'; // ... others imports // TODO: Use your local storage. A package you can use is: https://pub.dev/packages/shared_preferences final localStorage = LocalStorageFake(); @override void initState() { // ... your code sendCSMatchingKeyIfNeeded(); WidgetsBinding.instance.addObserver(this); // ... your code } @override void dispose() { // ... your code WidgetsBinding.instance.removeObserver(this); super.dispose(); // ... your code } @override void didChangeAppLifecycleState(AppLifecycleState state) { super.didChangeAppLifecycleState(state); // Check if the app is in the foreground if (state == AppLifecycleState.resumed) { sendCSMatchingKeyIfNeeded(); } } Future<void> sendCSMatchingKeyIfNeeded() async { // TODO: Implement your local storage. A package you can use is: https://pub.dev/packages/shared_preferences final csMatchingKeyTimestampMap = await localStorage.getMap( 'csMatchingKey_creation_ts', ); final csMatchingKeyIsNotGenerated = csMatchingKeyTimestampMap == null; if (csMatchingKeyIsNotGenerated) { await _submitNewCsMatchingKey(); return; } final timestamp = DateTime.fromMillisecondsSinceEpoch( csMatchingKeyTimestampMap['timestamp'], ); if (DateTime.now().difference(timestamp).inMinutes > 30) { // if the key is not valid anymore, submit a new one await _submitNewCsMatchingKey(); } // if the key is still valid, do nothing } Future<void> _submitNewCsMatchingKey() async { // Generate the matching key and store it in the local storage final millisecondsSinceEpoch = DateTime.now().millisecondsSinceEpoch; final csMatchingKeyValue = '${Random().nextDouble()}_$millisecondsSinceEpoch'; await localStorage.setMap('csMatchingKey_creation_ts', { 'csMatchingKey': csMatchingKeyValue, 'timestamp': millisecondsSinceEpoch, }); // Submit the matching key to Adobe final experienceEvent = ExperienceEvent({ 'xdmData': {'eventType': 'csMatchingKey_state'}, 'data': {'csMatchingKey': csMatchingKeyValue} }); await Edge.sendEvent(experienceEvent); // Submit the matching key to CSQ await CSQ().addDynamicVar(DynamicVar.fromString( key: 'csMatchingKey', value: csMatchingKeyValue, )); } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Adobe Analytics","description":"Leverage our native integration to use Adobe Analytics segments in Contentsquare, with the CSQ Flutter SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/adobe-analytics/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: AutoRoute support - Flutter description: How to use the CSQNavigatorAutoRouteObserver with AutoRoute package lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/auto_route_support/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/auto_route_support/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To support automatic screen tracking when using the [AutoRoute package ↗](https://pub.dev/packages/auto_route), we provide the `CSQNavigatorAutoRouteObserver`. This observer extends the standard `CSQNavigatorObserver` to add compatibility with AutoRoute's navigation system, including support for tab navigation. Warning If you are using `AutoRoute`, use `CSQNavigatorAutoRouteObserver` instead the standard `CSQNavigatorObserver` for better compatibility and support for tab navigation. ## Installation Add `csq_navigator_auto_route_observer` as a **dev dependency**. ```shell flutter pub add -d csq_navigator_auto_route_observer ``` **pubspec.yaml** ```yaml dev_dependencies: csq_navigator_auto_route_observer: ^1.0.0 ``` ## Usage Once the package has been added, you'll need to add the `CSQNavigatorAutoRouteObserver` to the root navigator in your app. **main.dart** ```dart import 'package:csq_navigator_auto_route_observer/csq_navigator_auto_route_observer.dart'; return MaterialApp.router( routerConfig: _appRouter.config( navigatorObservers: () => [ CSQNavigatorAutoRouteObserver(), ], ), ); ``` Tip You should use [Routes ↗](https://api.flutter.dev/flutter/widgets/Route-class.html) with proper [names ↗](https://api.flutter.dev/flutter/widgets/RouteSettings/name.html) assigned to them. This will be used as a fallback value for the automatic screen name capturing. The `CSQNavigatorAutoRouteObserver` can be configured with the following arguments: * [ExcludeRouteFromTracking](#excluderoutefromtracking) * [ScreenNameProvider](#screennameprovider) * [CustomVarsProvider](#customvarsprovider) ### ExcludeRouteFromTracking An optional callback function that determines whether a specific route should be excluded from tracking. The function takes a `Route` as input and returns a `bool`. Use this function to selectively exclude certain routes from automatic tracking by returning true for those routes. ```dart import 'package:contentsquare/csq.dart'; CSQNavigatorAutoRouteObserver( excludeRouteFromTracking: (route) { // Exclude a specific route name if (route.settings.name == '/myRoute') return true; // Exclude popup routes (menus, popups, dialogs) if (route is PopupRoute) return true; // Exclude dialog routes (AlertDialog, showDialog) // Many dialogs inherit from PopupRoute, but this is extra safety: if (route.runtimeType.toString().contains('DialogRoute')) return true; // Exclude full-screen dialogs if (route is PageRoute && route.fullscreenDialog == true) return true; return false; }, ) ``` By default, all routes are tracked. Note `CSQNavigatorAutoRouteObserver` consider modal routes (like `showDialog`, `showModalBottomSheet`, etc.) and pop-ups (such as `showDialog`) as separate screens. If you don't want to track them as screens, you can use the `excludeRouteFromTracking` configuration option to exclude them. ### ScreenNameProvider An optional callback function used to customize the screen name for a given route. The function takes a `Route` as input and returns a `String` representing the desired screen name. Use this function to define custom screen names for specific routes. ```dart import 'package:contentsquare/csq.dart'; CSQNavigatorAutoRouteObserver( screenNameProvider: (route) { final screenName = _formatScreenName(route.settings.name); return screenName; }, ) ``` Tip If you use dart code obfuscation in your release builds, you should use the `screenNameProvider` to avoid obfuscated screen names being tracked. ### CustomVarsProvider An optional callback function used to provide a list of custom variables for a specific route. The function takes a `Route` as input and returns a `List<CustomVar>`. Use this function to attach custom variables to specific routes for tracking purposes. ```dart import 'package:contentsquare/csq.dart'; CSQNavigatorAutoRouteObserver( customVarsProvider: _customVarsForRouteProvider, ) List<CustomVar>? _customVarsForRouteProvider(Route<dynamic> route) { final routeName = route.settings.name; final productPageRegex = RegExp(r'/product/(\d)+'); if (routeName == null) { return []; } // Check for product detail routes if (productPageRegex.hasMatch(routeName)) { final productId = productPageRegex.firstMatch(routeName)?.group(1); if (productId != null) { return [ CustomVar(index: 1, name: 'productId', value: productId), ]; } } // Check for a specific screen if (routeName == '/profile') { return [ CustomVar(index: 2, name: 'screenType', value: 'profileScreen'), ]; } return null; } ``` ## Compatibility This package requires: * **AutoRoute**: Version 9.0.0 or later * **CSQ SDK**: Compatible with the latest CSQ SDK for Flutter Make sure your project meets these version requirements before integrating the `csq_navigator_auto_route_observer` package. ## Changelog ### 1.1.0 - 2026.03.20 * Add support for AutoRoute versions 10.x and 11.x (`>=10.1.0+1 <12.0.0`) ### 1.0.0 - 2025.12.09 * Initial release ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"AutoRoute support","description":"How to use the CSQNavigatorAutoRouteObserver with AutoRoute package","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/auto_route_support/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- 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://mh.ba.contentsquare.net'), // EU; https://mh.bf.contentsquare.net (default) 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` The CSQ API endpoint to use: * `https://mh.ba.contentsquare.net` — EU-hosted environments * `https://mh.bf.contentsquare.net` — all other environments (default) ### `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()`. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"SDK API reference","description":"SDK commands reference including signature, parameter descriptions, and examples","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/command-reference/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - Flutter description: The CSQ Flutter SDK changelog lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/changelog/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. 📬 Stay updated! ## Opt-in to CSQ Experience Platform Already using the CSQ SDK in standalone mode? Follow these steps to switch to CSQ Experience Platform and combine Experience Analytics and Product Analytics under a single data source. CSQ Experience Platform is currently an Early Access program. To gain access, contact your Customer Success Manager. CSQ Experience Platform guidance Throughout the documentation, code samples highlight differences between standalone and CSQ Experience Platform integrations.  1. [Update the SDK package to 4.2.0 or later](../#install-the-sdk). 2. Replace your current `CSQ().start(startConfig: StartConfig.withEnvironmentId(...))` call with the `dataSourceId` provided by your Customer Success Manager. This links your app to the CSQ Experience Platform data source. ```dart await CSQ().start(startConfig: StartConfig.withDatasourceId(id: "YOUR_DATASOURCE_ID")); ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 3. Review changes [introduced in 4.2.0](#420---20260508) which notably removes support for several Product Analytics options. ## 4.4.4 - 2026.08.12 * **Improvements:** * Improved zoning analysis and autocapture interaction performance. ## 4.4.3 - 2026.08.6 * **Improvements:** * Improved zoning analysis and autocapture interaction performance. ## 4.4.2 - 2026.07.21 * **Native SDKs:** * iOS: 1.11.0 → 1.11.1 * Re-signed the release artefacts with a new valid certificate to resolve a code-signing validation failure (`CSSMERR_TP_CERT_REVOKED`). No functional changes. ## 4.4.1 - 2026.07.07 * **Bug fix:** * Fixed an error in interaction `autocapture` while keeping events captured correctly. * Improved interaction `autocapture` performance during scroll interactions. * Improved zoning and heatmap stability. ## 4.4.0 - 2026.06.30 * **Added:** * Swift Package Manager (SPM) support for iOS. * **Improvements:** * Session Replay: improved capture of small, frequently-updating custom paint animations. * Extended Flutter version support to include 3.44.4. ## 4.3.1 - 2026.06.25 * **Bug fix:** * Fixed WebView tracking silently failing in apps with multiple Flutter engines. * Fixed WebView tracking not working on iOS scene-based apps. ## 4.3.0 - 2026.06.11 * **Bug fix:** * Fixed Long Snapshot for views containing WebViews on Android. * **Native SDKs:** * Android: 1.10.1 → 1.11.0 * iOS: 1.10.0 → 1.11.0 ## 4.2.2 - 2026.06.05 * **Bug fix** * Repackage obfuscated Android classes to avoid R8 `a.*` collisions with other AARs. ## 4.2.1 - 2026.05.19 * **Bug fix** * Event tracking: event property serialization on iOS was fixed. ## 4.2.0 - 2026.05.08 Experience Analytics The Session timeout definition changes from "30 minutes after being in background" to **30 minutes after last event**. See [Session definition](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/data-collection/#session-definition). Product Analytics ### Configuration **Deprecated:** `CSQ().configureProductAnalytics()` still exists, but is now deprecated in favor of `CSQ().start()` which combines SDK configuration and initialization in a single call: * Product Analytics **main.dart** ```dart await CSQ().configureProductAnalytics( environmentId: 'YOUR_ENVIRONMENT_ID', ); await CSQ().start(); await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', ), ); ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart await CSQ().configureProductAnalytics( environmentId: 'YOUR_ENVIRONMENT_ID', ); await CSQ().start(); await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', ), ); ``` ### Options **Added:** `AnalyticsOptions.sessionReplayAutoStart` — set to `false` to disable automatic Session Replay start and control it manually using `CSQ().startSessionReplay()` and `CSQ().stopSessionReplay()`. Defaults to `true`. ```dart await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: const AnalyticsOptions(sessionReplayAutoStart: false), ), ); ``` **Removed - Breaking:** `disableScreenviewForwardToDXA`, `disableScreenviewForwardToPA`, `resumePreviousSession`, `uploadInterval`, `captureVendorId`, `captureAdvertiserId`, `clearEventPropertiesOnNewUser`, `messageBatchMessageLimit`, `pruningLookBackWindow`, `maximumDatabaseSize`, and `maximumBatchCountPerUpload` options have been removed. Remove them from your `CSQ().start()` call if present: ```dart await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: const AnalyticsOptions( captureVendorId: true, captureAdvertiserId: true, clearEventPropertiesOnNewUser: true, messageBatchMessageLimit: 100, resumePreviousSession: true, pruningLookBackWindow: 6, maximumDatabaseSize: 10000000, maximumBatchCountPerUpload: 5, disableScreenviewForwardToDXA: true, disableScreenviewForwardToPA: true, ), ), ); ``` * **Native SDKs:** * Android: 1.5.0 → 1.10.1 * iOS: 1.6.0 → 1.10.0 ## 4.1.3 - 2026.04.27 * **Improvements:** * Session Replay fidelity was improved ## 4.1.2 - 2026.04.24 * **Improvements:** * Session Replay fidelity was improved * Multithread issues were fixed * Dialogs tracking was improved ## 4.1.1 - 2026.03.19 * **Improvements:** * Extend Flutter version support to include 3.27.0 and later (previously 3.27.4+). ## 4.1.0 - 2026.02.27 * **Analytics:** * Introduce the Long Screenshot feature to capture and analyze long screens in the app, such as product listing pages or user profiles. * **Native SDKs:** * Android: 4.43.8 → 4.44.0 * iOS: 4.45.3 → 4.46.0 * **🚨 Minimum Flutter version** * Contentsquare plugin now requires Flutter SDK `3.27.4` or later ## 4.0.3 - 2026.02.03 * **Native SDKs:** * Android: 1.4.2 → 1.4.7 ## 4.0.2 - 2026.01.29 * **Bug fix** * Session Replay: Fixed an issue that could cause `BackdropFilter` widgets to appear mispositioned in replays. * Interactions Autocapture: Improved performance when capturing interactions on complex widget trees. ## 4.0.1 - 2025.12.11 * **Bug fix** * SessionReplay: Fixed an issue that could cause white screens to appear on iOS. ## 4.0.0 - 2025.12.05 Initial release of the CSQ SDK. * Introduces the unified CSQ API, which combines `Product Analytics`, `Experience Analytics`, and `Monitoring` features into a single, cohesive library. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The CSQ Flutter SDK changelog","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/changelog/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - Flutter description: Requirements and limitations to develop with the Flutter SDK lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/compatibility/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Before implementing the SDK, make sure your app meets the following technical prerequisites to avoid integration issues and ensure optimal performance. ## Supported platforms Only Flutter application on the following platforms are supported by the CSQ Flutter SDK: * Android * iOS Calling the SDK on other platforms is safe but will not have any effect. If you need to use the SDK on another platform, contact our support team. Note Hybrid applications are not supported. By hybrid application, we mean iOS and Android apps that integrate Flutter as an [add-to-app module ↗](https://docs.flutter.dev/add-to-app). ## Compatibility matrix Each version of the CSQ Flutter SDK will be linked to specific, fixed versions of each native SDK. To make that clear, here is a compatibility table to consider when choosing your version of the bridge (refer to the Flutter SDK Changelog to know what the changes are for each version). Note If the Maximum Flutter Version is not specified, it means that the bridge is compatible with all versions of Flutter up to the latest one. | CSQ Flutter | CSQ iOS | CSQ Android | Minimum Flutter Version | Maximum Flutter Version | | - | - | - | - | - | | 4.4.4 | 1.11.1 | 1.11.0 | 3.27.0 | - | | 4.4.3 | 1.11.1 | 1.11.0 | 3.27.0 | - | | 4.4.2 | 1.11.1 | 1.11.0 | 3.27.0 | - | | 4.4.1 | 1.11.0 | 1.11.0 | 3.27.0 | - | | 4.4.0 | 1.11.0 | 1.11.0 | 3.27.0 | - | | 4.3.1 | 1.11.0 | 1.11.0 | 3.27.0 | - | | 4.3.0 | 1.11.0 | 1.11.0 | 3.27.0 | - | | 4.2.2 | 1.10.0 | 1.10.1 | 3.27.0 | - | | 4.2.1 | 1.10.0 | 1.10.1 | 3.27.0 | - | | 4.2.0 | 1.10.0 | 1.10.1 | 3.27.0 | - | | 4.1.3 | 1.6.0 | 1.5.0 | 3.27.0 | - | | 4.1.2 | 1.6.0 | 1.5.0 | 3.27.0 | - | | 4.1.1 | 1.6.0 | 1.5.0 | 3.27.0 | - | | 4.1.0 | 1.6.0 | 1.5.0 | 3.27.4 | - | | 4.0.3 | 1.5.2 | 1.4.7 | 3.22.3 | - | | 4.0.2 | 1.5.2 | 1.4.2 | 3.22.3 | - | | 4.0.1 | 1.5.2 | 1.4.2 | 3.22.3 | - | | 4.0.0 | 1.5.1 | 1.4.2 | 3.22.3 | - | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Flutter SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/compatibility/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Contentsquare CLI - Flutter description: How to use the Contentsquare CLI plugin lastUpdated: 07 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/contentsquare-cli/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/contentsquare-cli/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. A Dart plugin that offers a command-line interface for users of the Contentsquare package. ## Installation Add `contentsquare_cli` as a **dev dependency**. ```shell flutter pub add -d contentsquare_cli ``` **pubspec.yaml** ```yaml dev_dependencies: contentsquare_cli: ^1.1.0 ``` then run ```shell dart run contentsquare_cli ``` ## Usage ### upload-debug-files command This command enables you to upload debug files generated by the `flutter build` command to Contentsquare. This allows you to read the [Flutter errors](../error-analysis/#error-reporter) generated in an [obfuscated or de-symbolized](../error-analysis/#symbolization-and-de-obfuscation) app. #### Configuration To use the command, provide the following identification elements. These can be passed directly as arguments each time you run the command or set up in a configuration file within your project for a more streamlined command usage. The required information includes: * **The targeted platform** `ios` or `android`, corresponding to the `flutter build` command. * **The project ID** 1. Login to the Contentsquare platform on [https://app.contentsquare.com ↗](https://app.contentsquare.com) 2. Make sure to be on the right project 3. The project ID can be found in the URL query parameter `project`: `https://app.contentsquare.com/#/{MODULE_NAME}?project={PROJECT_ID}&hash={HASH}]` * **Valid API credentials** Follow the dedicated documentation from the Help Center to get the client ID and client Secret: [How to create API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593). * **The debug info directory** Provided to the `--split-debug-info` option during build command * **The obfuscation map path (optional)** If you use the `--obfuscate` option during the build process, you can specify the path for the obfuscation map by adding the build option `--extra-gen-snapshot-options=--save-obfuscation-map=[YOUR DESIRED FILE PATH]`. ##### Using the YAML configuration file You can supply this information by adding a `contentsquare_cli.yaml` file to the root of your project. **contentsquare\_cli.yaml** ```yaml contentsquare_cli: android: client_id: "[ANDROID CLIENT ID]" client_secret: "[ANDROID CLIENT SECRET]" project_id: "[ANDROID PROJECT ID]" debug_info_dir: "[PATH PROVIDED TO THE --split-debug-info option]" obfuscation_mapping_file: "[PATH TO THE OBFUSCATION MAP]" ios: client_id: "[IOS CLIENT ID]" client_secret: "[IOS CLIENT SECRET]" project_id: "[IOS PROJECT ID]" debug_info_dir: "[PATH PROVIDED TO THE --split-debug-info option]" obfuscation_mapping_file: "[PATH TO THE OBFUSCATION MAP]" ``` ##### Using the command line arguments Alternatively, this information can be provided directly as arguments on the command line. | Option | Description | | - | - | | --platform | The target platform for which the debug files are uploaded | | --client-id | The client ID of [API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593) | | --client-secret | The client SECRET of [API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593) | | --project-id | The Contentsquare project ID | | --debug-info-dir | The path from `--split-debug-info` option | | --obfuscation-mapping-file | The generated obfuscation map path | Note Use `--help` option for further information Tip You can combine these two approaches: for example, use the YAML file to store paths and the project ID, while providing the client identifier and secret as command-line arguments. #### Examples Let's take the case of debug files generated by this `flutter build` command: ```shell flutter build apk --release --split-debug-info=myDebugInfoDir --obfuscate --extra-gen-snapshot-options=--save-obfuscation-map=app.android.map.json ``` Using this configuration file: **contentsquare\_cli.yaml** ```yaml contentsquare_cli: android: client_id: "my-client-id-android" client_secret: "myClientSecretAndroid" project_id: "00000" debug_info_dir: "myDebugInfoDir" obfuscation_mapping_file: "app.android.map.json" ios: client_id: "my-client-id-ios" client_secret: "myClientSecretIos" project_id: "00001" debug_info_dir: "myDebugInfoDir" obfuscation_mapping_file: "app.ios.map.json" ``` You can invoke the upload-debug-files command as follows: ```shell dart run contentsquare_cli upload-debug-files --platform=android ``` If you prefer using the command line only: ```shell dart run contentsquare_cli upload-debug-files --platform=android --client-id=my-client-id-android --client-secret="myClientSecretAndroid" --project-id=00000 --debug-info-dir=./myDebugInfoDir --obfuscation-mapping-file=./app.android.map.json ``` Note For automatic execution, integrate this command in a release script or in a CI/CD pipeline. ## Changelog ### 1.1.0 - 2026.08.06 * Update dependencies ### 1.0.1 - 2024.12.10 * Update package metadata ### 1.0.0 - 2024.11.05 * Introduce the `upload-debug-files` command ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Contentsquare CLI","description":"How to use the Contentsquare CLI plugin","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/contentsquare-cli/","inLanguage":"en","dateModified":"2026-08-07T10:21:42+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Data collection - Flutter description: Understand how the Flutter SDK loads, tracks, and send data lastUpdated: 02 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/data-collection/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/data-collection/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The SDK starts automatically at launch, fetches its configuration, and sends collected analytics events in batches; a session ends after 30 minutes of inactivity. ## Configuration Once started, our SDK fetches it configuration from our servers. Then depending on the segmentation size (defined by our team when you sign a contract) and the user consent status, it will start collecting analytics data from system and user events it detects from the runtime. ## Data collection ### Analytics data collection The SDK monitors the application, lifecycle events, the view hierarchy, and generates data from the behavior of the app, the content of the screen and the user interactions. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. ### Session Replay data collection See [Session Replay Initialization](../data-collection/#data-collection) to learn how Session Replay data collection works. ## Sending data ### Sending analytics data Analytics data are sent in batches of maximum 50 events. Requests are triggered when network conditions allow for the server to be reached and: * The current batch of events has reached 50 * Or the app is put in background ### Sending Session Replay Data See [Session Replay Requests](../session-replay/#requests) to learn more about how Session Replay data is sent. ## Session definition A session is one continuous period of user interaction. It starts upon app launch and persists through state changes, including putting the app in the background or terminating and restarting it. As long as users interact at least once every 30 minutes, it remains the same session. ## Collected data points * The events are in JSON format, which lists the properties and their description in comment. * Events are sent to the server in batches. * A batch is a subset of events originating from one session. A session can send events in more than one batch. * The batch size is defined in a run configuration file specific to each app (50 events by default). ### Requests meta data Each batch has a common header, a set of device specific, and repeatable information and an array of events, which is immutable. The header is composed at the moment of sending, so it has to be constant info ONLY. The array in the payload is data stored at the moment of collection. The structure of the batches of events will have the following format: ```javascript { pid:8, // int - ProjectId - represented in the mobile config format uid:"ac1529a7-59f6-49d9-b254-6f0a22f57284", // String - uuid Unique user ID dt:4, // int - device type (loosely enforced enum - [sdk-phone : 4, sdk-tablet :5]) dma:"Samsung", // String - device manufacturer. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. dmo:"SG", // String - device model. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. os:"10.0", // String - os version (Android version name 8.0, 9.0, 10.0) l:"en_US", // String - Language in iso-639 format https://www.ibabbleon.com/iOS-Language-Codes-ISO-639.html tz:"Europe/Paris", // String - timezone https://en.wikipedia.org/wiki/List_of_tz_database_time_zones now:1522159618000, // long - timestamp when the batch was sent to:{ // object - type origin of the event an:"appname" // String - application name st:"sdk-android", // String - type of sdk sf:"release", // string - sdk flavor/variant [release/debug/god] }, r:{ // Device - resolution. w:1080, // int - width h:1920 // int - height d: 1.5 // The device density as float. Its values can vary between (0.75 and 10) }, pl:[] // JSON array payload - list of event objects, see below } ``` ### Events meta data All events have a common first part (don't confuse it with the header explained above). This common section is data which is common for all events by type but is gathered at the moment the event occurred. This common section is a part of the actual event payload. ```javascript { upt:1522, // long - system update in milliseconds euid:"euid", // String - event UUID url:"app-and://identifier/mainPath/secondaryPath?title=screeName", // String - screenName is passed in the title query Parameter scn:4, // int - the number of screens already shown in the session c:3, // int - connectivity type [-1 - offline, 0 - error, 1 - wifi, 2 - 2g, 3 - 3g, 4 - 4g] ci:"verizon", // String - carrier_id when user is on mobile network o:1, // int - orientation [0 = portrait, 1 = landscape] vo:{ // object - version origin of the event sv:"2.1", // string version of the sdk sb:4, // int - sdk build number av:"appVersion", // String - application version af:"appFlavor" // String - application string - [release/debug/god] ab:1 // int - application build number }, sn:1, // int - session id (positive int) t:12894726459435 // long - timestamp of the event (in milliseconds) } ``` All event specific properties are appended to this JSON object. ### App Start This event describes the absolute start of the app. The trigger for this event is the absolute start of the app. This is the first event sent when the SDK is invoked. ```javascript ea: 0; // int - event action - defined above ``` ### App Show This event is sent when the user brings the app in the foreground (switching from another app, exiting lock screen, etc.). This event means the app is focused. ```javascript ea: 1; // int - event action - defined above ``` ### App Hide This event is sent when the user exits (minimizes) the app, or switches to something else. This event means the app is not focused and the session might end, but we have not completely ended the session yet, as the user might return. ```javascript ea: 2; // int - event action - defined above ``` ### Screenview Everything starts with a View event. This is an event which describes the equivalent of a "page view" on the web. This event is sent when the Track Screen API is called. ```javascript ea:4 // int - event action - defined above st:"title", // String - screen title sl:34543 // int - (load time) screen load time (diff between last action and this event) ``` ### Tap Single Finger gesture event, when the user is interacting with a loaded screen. This is an event which describes the equivalent of a "click" in the web. This event is defined by the following sequence of touch events: * Touch Down -> N x Touch Move -> Touch Up ```javascript ea:6 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ur: true, // boolean - was this a "responsive" touch event (the target view had a handler) ``` ### Long press Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Duration: > 500ms * Distance: < 24 dp ```javascript ea:8 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ``` ### Drag (Slow Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity < 100 dp/s ```javascript ea:9 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance dragged tvv:100 // int - target view velocity while dragging dp/s ``` ### Flick (Fast Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity > 100 dp/s ```javascript ea:10 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view graph path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance scrolled tvv:100 // int - target view velocity while scrolling dp/s ``` ### Transaction To track transactions we provide a public API which can send a transaction object (see section [Track Transactions](../track-transactions/)). This object must contain the following parameters: ```javascript ea:16, // int - event action - defined above tr:{ // a json object with different properties defining the transaction made vl: 20.0, // mandatory - float - the value of the transaction cu: 978, // mandatory - int - the ISO 4217 code of the currency of the transaction id: "32akjkljklJ575775" // optional - string - an id for the transaction } ``` ### Dynamic variables To track dynamic variables we provide a public API (see section [Dynamic variables](../track-dynamic-variables/)). **Event with a string value** ```javascript ea:18, // int - event action - defined above k:"key", // String - Custom key assigned by client. v:"value" // String - Custom value assigned by client. ``` **Event with a number value** ```javascript ea:19, // int - event action - defined above k:"key", // String - Custom key assigned by client. v: 2344 // Integer - Custom value assigned by client. ``` ## Reliable targets Limitations * For now, reliable targets are available for UIKit only. * If the view doesn't qualify to be a reliable target then we use our current mechanism for zoning * Reliable identifier must be unique per screen In the Zoning Analysis module, reliable targets are assigned to zones to ensure that a `UIView` remains accessible in the view hierarchy, even if it has been moved within the same page.\ Having a reliable target for a view or a container of views enables the analysis of data across various Screenshots from different dates and versions, including layouts or A/B testing variations. One of the following properties must be assigned for a view to have a reliable target.\ Our SDK will check the properties in this order: 1. [`accessibilityIdentifier` ↗](https://developer.apple.com/documentation/uikit/uiaccessibilityidentification/1623132-accessibilityidentifier) 2. [`restorationIdentifier` ↗](https://developer.apple.com/documentation/uikit/uiviewcontroller/1621499-restorationidentifier) 3. [`tag` ↗](https://developer.apple.com/documentation/uikit/uiview/1622493-tag) ### accessibility Identifier if the view has `accessibilityIdentifier` it uses it as first priority and provides a short reliable target. Example: ```swift /* [SalesViewController] ViewOne | viewTwo / | \ viewThree viewFour viewFive */ let viewOne = UIView() viewOne.accessibilityIdentifier = "rootView" let viewTwo = UIView() viewTwo.restorationIdentifier = "dichotomy" let viewThree = UIButton() viewThree.accessibilityIdentifier = "on_sale" let viewFour = UIButton() viewFour.accessibilityIdentifier = "new_arrivals" let viewFive = UIButton() viewFive.accessibilityIdentifier = "for_kids" viewTwo.addSubview(viewThree) viewTwo.addSubview(viewFour) viewTwo.addSubview(viewFive) viewOne.addSubview(viewTwo) // viewThree target would be: UIButton[ai:SalesViewController.on_sale] // viewFour target would be: UIButton[ai:SalesViewController.new_arrivals] // We change the view hierarchy viewThree.removeFromSuperview() viewFour.addSubview(viewThree) // viewThree target would be: UIButton[ai:SalesViewController.on_sale] // viewFour target would be: UIButton[ai:SalesViewController.new_arrivals] ``` ### restoration Identifier If the view has `restorationIdentifier` and no `accessibilityIdentifier` then it provides a long reliable target. ```swift /* [SalesViewController] ViewOne / viewTwo / \ viewThree viewFour */ let viewOne = UIView() viewOne.restorationIdentifier = "trichotomy" let viewTwo = UIView() viewTwo.restorationIdentifier = "dichotomy" let viewThree = UIView() let viewFour = UIView() viewTwo.addSubview(viewThree) viewTwo.addSubview(viewFour) viewOne.addSubview(viewTwo) // viewThree target would be: [root]>UIView[ri:SalesViewController.trichotomy]>UIView[ri:SalesViewController.dichotomy]>UIView:eq(0) // viewFour target would be: [root]>UIView[ri:SalesViewController.trichotomy]>UIView[ri:SalesViewController.dichotomy]>UIView:eq(1) ``` ### tag If the view has no `accessibilityIdentifier` and no `restorationIdentifier` then our SDK will use the `tag` that has been set, and will provide a long reliable target as well. tag yields the same identifiers as accessibility with a different tag ex: `[root]>UIView[tg:444]>UIView[tg:223]>UIView:eq(1)` ### Workaround for SwiftUI: using `.overlay` to get Reliable Target Identifiers SwiftUI views do not expose stable, introspectable identifiers at runtime. This presents a challenge when attempting to programmatically identify or interact with SwiftUI components - especially for use cases such as analytics tracking, UI testing, or runtime introspection. To work around this limitation, you can inject a transparent overlay that contains a `UIView` with a defined `accessibilityIdentifier`. This allows tooling to detect and reference the view reliably at runtime. Warning Since this approach adds an actual `UIView` on top of your SwiftUI view, it intercepts user interactions. As a result, interactive components below the overlay (like buttons) will no longer receive touches unless they are explicitly layered above it. ```swift struct AccessibleView: UIViewRepresentable { let accessibilityIdentifier: String func makeUIView(context: Context) -> UIView { let view = UIView() view.accessibilityIdentifier = accessibilityIdentifier return view } func updateUIView(_ uiView: UIView, context: Context) { uiView.accessibilityIdentifier = accessibilityIdentifier } } ``` This component embeds a transparent `UIView` with the desired `accessibilityIdentifier`, which becomes visible to accessibility, UI testing, or tracking layers. **Example:** Identifying a *non-interactive* list cell. Here is a typical usage pattern where the overlay is applied to a *non-interactive* cell. Any interactive elements (like a button) are rendered above the overlay to remain functional: ```swift var body: some View { ZStack(alignment: .topTrailing) { VStack { Image(product.imageName) .resizable() .aspectRatio(contentMode: .fit) .frame(width: 100, height: 100) Text(product.title) } // This overlay makes the view identifiable at runtime .overlay(AccessibleView(accessibilityIdentifier: "reliableID")) // This button is placed above the overlay so it remains tappable Button("Tap Me") { // Perform action } .padding([.top, .trailing], 8) } .padding() } ``` This pattern can be used when you want to identify list rows, cards, or containers that do not react to taps, but still need to be tagged for runtime analysis or inspection. Recommendations * Only use `.overlay(AccessibleView(accessibilityIdentifier:...))` on *non-interactive* containers. * Ensure interactive elements are layered above the overlay if interaction is needed. * Generate identifiers in a stable, unique per screen and predictable way, e.g.: ```swift let reliableID = "section-\(sectionIndex)-product-\(product.id)" ``` ## Exposure Metrics In the Zoning Analysis module, Exposure Metrics provide information on the size of the display zone in the application, and data about content exposure in scrolling elements. ### Behavior for scrollable elements Exposure Metrics data for scrolling is only calculated on the first scrollable element on the screen. Other scrolling elements in the view hierarchy are not taken into account. This event is defined by the following content: ```javascript ea:23, // int - event action dx:10, // int - normalized x content offset dy:10, // int - normalized y content offset du: 5, // int - duration of the movement (in milliseconds) ``` #### Exclude `UIScrollView` type object from Exposure Metrics Limitations * Exclusion mechanism is available for UIKit only, for objects inheriting from `UIScrollView`. ```swift let scrollView = UIScrollView() // or UICollectionView, UITableView or any class inheriting from UIScrollView scrollView.excludeFromExposureMetrics() ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Data collection","description":"Understand how the Flutter SDK loads, tracks, and send data","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/data-collection/","inLanguage":"en","dateModified":"2026-06-02T10:48:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Error Analysis - Flutter description: How to use CSQ Error Analysis in your Flutter apps lastUpdated: 15 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/error-analysis/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/error-analysis/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Error Analysis automatically captures API errors and network failures in your Flutter app and surfaces them in the Contentsquare platform. ## Prerequisites ### CSQ SDK is included You must include the [CSQ SDK](../) first using the same integration method and understand [how the SDK works](../data-collection/). ### Updating to latest SDK version To enable Error Analysis in your application and ensure optimal stability, make sure to always use the last SDK version. ### Screen tracking implemented Tracking will start at the 1st screenview event, it is required to have screen tracking implemented. Make sure to follow the [Flutter Track screens](../track-screens/) sections. ### Reminder about User consent If you are in the process of implementing the SDK for the 1st time, or if you choose to take this update as an opportunity to review your privacy-related implementation, ensure that you follow the [Flutter Privacy](../privacy/) section and use the [Opt-in API](../privacy/#opt-in) to get the user consent, otherwise no data will be collected. ## Get Started ### Start the SDK You do not need to do anything to start the Error Analysis SDK, it will start itself with CSQ SDK. ### Validate SDK integration When the SDK starts, you should see a log like this one: ```plaintext // success case CSLIB ℹ️ Info: Contentsquare Error Analysis [SDKVersionNumber] starting in app : [your.app.packageName] // fail case // << No public fail log ``` ## API Errors ### Automatic network inspection API Errors automatically collects failed network requests. ### Removing Personal Data in request URL path By default, the API Errors feature collects the URL path of the failed API requests. To prevent the collection of Personal Data in the URL path, you can rewrite the request URL path with the `CSQ().setURLMaskingPatterns` SDK API. Replace a step of the path - meaning between two slashes (/) - containing Personal Data with a variable: * `:user_id` becomes CS\_ANONYMIZED\_USER\_ID * `:address` becomes CS\_ANONYMIZED\_ADDRESS #### Example ```dart import 'package:contentsquare/csq.dart'; CSQ().setURLMaskingPatterns(patterns: [ 'https://www.contentsquare.com/users/:user_id/address/:address', ]); ``` ##### Result | URL before masking | URL after masking | | - | - | | `https://www.contentsquare.com/users/123/address/castle+black` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS` | | `https://www.contentsquare.com/users/123/address/castle+black/reset-token/abcdef123456` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS/reset-token/abcdef123456` | ### Debugging and Logging If in-app features are enabled, a info log should appear with the details of the event (see [Flutter Debugging and Logging](../in-app-features/#debugging-and-logging) section): ```plaintext CSLIB ℹ️ Info: API Error - GET 401 https://api.client.com ``` ### How API Errors works #### Initialization Our SDK automatically starts upon application launch and seamlessly captures failed network requests. #### Configuration Once started, our SDK fetches its config from our servers. It will start collecting data from network events if the API Errors setting is enabled in the config (this is handled by the Contentsquare team). #### Tracking The SDK monitors only API Errors with a 4xx or 5xx response code, and generates analytics data. These events are then locally stored, and eventually sent to our servers in batches. Warning To ensure that API Errors occurring at app launch are accurately tracked, ensure the session is being tracked (the user is included in tracked users and has not opted out), and a first screenview event has been sent. Warning During the initialization, the CSQ SDK overrides the `HttpOverrides.global` property. If you have to override `HttpOverrides.global` in your app - [use a custom HttpOverrides](#use-a-custom-httpoverrides). #### Sending data For each network error, a new event will be sent in Analytics and Session Replay data. Check the following sections to learn more about how data is processed and sent: * [Analytics requests](../data-collection/#sending-data) * [Session Replay requests](../session-replay#requests) ### API Troubleshooting Details API Errors troubleshooting details feature enhances your ability to collect additional information about API errors, facilitating faster troubleshooting. With this feature, you can view three types of additional API error details in the Event Stream of Session Replay: * The HTTP headers of the request and the response. * The body (the data sent by the request or received in the response). * The query parameters of the request endpoint (of the URL of the information you request for). Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. See [API Troubleshooting Details ↗](https://support.contentsquare.com/hc/en-us/articles/37271885035537) for more details. ### Collected data points Only network calls in error (4xx or 5xx response codes) will be collected. Here is the exhaustive list of data collected: * URL (without query strings) * HTTP method * Response code * Timestamp of the request * Timestamp of the response * HTTP headers of the request * HTTP headers of the response * HTTP body of the request * HTTP body of the response * Query parameters ### Known limitations and recommendations #### Conflict with Firebase Performance Monitoring ##### Android CSQ Error Analysis is not compatible with Firebase Performance Monitoring auto-collection. Only one of the two will log events, and usually, the events will be automatically logged by the Contentsquare Error Analysis. To log events to Firebase Performance Monitoring, we suggest [logging it manually ↗](https://rnfirebase.io/perf/usage#http-request-tracing). ##### iOS CSQ Error Analysis is compatible with Firebase Performance auto-collection, but the HTTP body from the response won't be collected by the Error Analysis SDK. CSQ Error Analysis may not be compatible with other network auto-collection tools. ### Use a custom HttpOverrides Use `CSQHttpOverrides` if you need to override the global `HttpOverrides`. ```dart import 'dart:io'; import 'package:contentsquare/csq.dart' show CSQHttpOverrides; class YourCustomHttpOverrides extends HttpOverrides { @override HttpClient createHttpClient(SecurityContext? context) { return super.createHttpClient(context); } } void main() { HttpOverrides.global = CSQHttpOverrides( httpOverrides: YourCustomHttpOverrides(), ); } ``` Note Your custom `HttpOverrides` will function as expected under the normal conditions. The `CSQHttpOverrides` will operate exclusively as a proxy. Note If during the initialization it is observed that another `HttpOverrides` is being used globally and it is not `CSQHttpOverrides`, it will be automatically replaced with `CSQHttpOverrides`, as illustrated in the example. ## Error Reporter ### Handle the Flutter errors You can collect unhandled errors from the framework by using the [FlutterError.onError ↗](https://api.flutter.dev/flutter/foundation/FlutterError/onError.html) callback. However, errors that occur outside of Flutter's callbacks, such as asynchronous errors, will not be captured. To handle these, consider implementing the [PlatformDispatcher.onError ↗](https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/onError.html) or [runZonedGuarded ↗](https://api.flutter.dev/flutter/dart-async/runZonedGuarded.html) callbacks. #### Example * Using PlatformDispatcher.onError ```dart import 'package:contentsquare/csq.dart'; void main() async { WidgetsFlutterBinding.ensureInitialized(); FlutterError.onError = (FlutterErrorDetails details) { // Collects Flutter errors CSQ().collectFlutterError(details: details); }; WidgetsBinding.instance.platformDispatcher.onError = (exception, stackTrace) { // Collects all unhandled errors from the root isolate, including platform-level errors CSQ().collectError(error: exception, stackTrace: stackTrace); return false; }; runApp(MyApp()); } ``` * Using runZonedGuarded ```dart import 'package:contentsquare/csq.dart'; void main() async { runZonedGuarded(() { FlutterError.onError = (FlutterErrorDetails details) { // Collects Flutter errors CSQ().collectFlutterError(details: details); }; runApp(MyApp()); }, (error, stack) { // Collects all unhandled errors in the zone CSQ().collectError(error: error, stackTrace: stack); }); } ``` #### Flutter error presentation CSQ automatically [presents ↗](https://api.flutter.dev/flutter/foundation/FlutterError/presentError.html) the Flutter errors. You can disable it by using the optional `presentErrorDetails` parameter in `collectFlutterError` API. ```dart import 'package:contentsquare/csq.dart'; CSQ().collectFlutterError(details: details, presentErrorDetails: false); ``` #### Compatibility with Firebase Crashlytics Integrating Crashlytics as an additional error reporting solution is straightforward: include the corresponding instruction within each callback. ##### Example with Firebase Crashlytics ```dart import 'package:contentsquare/csq.dart'; void main() async { WidgetsFlutterBinding.ensureInitialized(); await Firebase.initializeApp(); FlutterError.onError = (FlutterErrorDetails details) { CSQ().collectFlutterError(details: details, presentErrorDetails: false); FirebaseCrashlytics.instance.recordFlutterError(details); }; WidgetsBinding.instance.platformDispatcher.onError = (exception, stackTrace) { CSQ().collectError(error: exception, stackTrace: stackTrace); FirebaseCrashlytics.instance.recordError(exception, stackTrace); return false; }; runApp(MyApp()); } ``` ### Validate integration 1. Enable the [in-app features](../in-app-features/#enable-in-app-features). 2. Run your application. You should see a log printed in the console: ```plaintext ┌─────────────────────────────────────────────────────────────────────────────── │ ℹ️ INFO ℹ️ (CSLIB) ├─────────────────────────────────────────────────────────────────────────────── │ Errors Reporter module has started. └─────────────────────────────────────────────────────────────────────────────── ``` #### Validate error reporting With [in-app features](../in-app-features/#enable-in-app-features) enabled, any errors occurring in your application should generate a log in the console: ```plaintext ┌─────────────────────────────────────────────────────────────────────────────── │ ℹ️ INFO ℹ️ (CSLIB) ├─────────────────────────────────────────────────────────────────────────────── │ Error was collected. │ Exception: type 'String' is not a subtype of type 'int' in type cast └─────────────────────────────────────────────────────────────────────────────── ``` ### Symbolization and de-obfuscation Note The following step are only needed if you are using the `--split-debug-info` or `--obfuscate` options with the `flutter build` commands To be able to read errors from an application built with Flutter obfuscation and/or de-symbolisation, you will need to upload the debug files to Contentsquare. 1. [Enable the `contentsquare_cli` plugin](../contentsquare-cli/#installation) 2. [Run the upload command](../contentsquare-cli/#upload-debug-files-command) The upload command must be executed immediately after the Flutter build. Automating the upload As Flutter overwrites debug files for the same platform with each build, if you fail to upload the debug files in time, you won't be able to read errors from the previous release. You should run the upload command within your CI/CD pipeline or build script after every release build. #### Minimum required Flutter version * Android: 3.10.6 * iOS: 3.13.0 ### How Error Reporter works #### Initialization Error Reporter is started automatically and begins to collect the reported errors when your application is launched #### Configuration Once started, our SDK fetches its configuration from our servers. It will start reporting errors if the Error Reporter setting is enabled (this is handled by the Contentsquare team). You have to implement an error handler strategy and collect the received errors. See [Flutter errors](#handle-the-flutter-errors) for examples #### Reporting When an error occurs, a report is created and stored locally in the device. The report is sent to our servers as soon as possible and then removed from the local storage. Warning To make sure errors are correctly tracked, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent. See [Track screens](../track-screens/) for more details. #### Sending error data For each error, a new event will be sent to analytics and Session Replay data when the network conditions allow for the server to be reached. ### Native crashes Crashes from the native parts of your application can be captured with additional setup. See 📚 [iOS Crash Reporter](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/error-analysis/#crash-reporter). See 📚 [Android Crash Reporter](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/error-analysis/#crash-reporter). ### WebView errors Errors occurring in web pages loaded in WebViews can be collected if Webview tracking is setup in your app. See 📚 [Webview Tracking implementation](https://docs.contentsquare.com/en/webview-tracking-tag/). Once WebView tracking is implemented, errors collection can be set up. See 📚 [Errors (in WebView)](https://docs.contentsquare.com/en/webview-tracking-tag/error-analysis/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Error Analysis","description":"How to use CSQ Error Analysis in your Flutter apps","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/error-analysis/","inLanguage":"en","dateModified":"2026-05-15T10:41:37+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Experimental annotation - Flutter description: What is experimental in the CSQ Flutter SDK lastUpdated: 02 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/experimental/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/experimental/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. In our continuous effort to enhance the Contentsquare Flutter SDK, there are instances where we develop new features that we want to make available to our customers ahead of their official global release. These features are marked as **experimental** to indicate their status. ## What is the Experimental Annotation? The `@experimental` annotation is an annotation we apply to certain features within the SDK.\ This annotation indicates that while the feature is accessible for use, it is not yet fully stable and may undergo changes.\ The experimental status allows us to share innovative capabilities with our clients earlier, but it also serves as a caution that the feature is still under evaluation. Note The experimental annotation is not a guarantee that the feature will be included in the SDK stable release. ## Why Do We Use the Experimental Annotation? Marking an experimental API is crucial for several reasons: * **API Stability:** Although thoroughly tested internally, the API might still evolve based on customer feedback. * **Client Needs:** We want to ensure that the feature fully addresses our clients needs before it becomes a permanent part of the SDK. * **Transparency:** We want to be transparent about the status of the feature and its potential for change. ## What Does It Mean for You? Adopting an experimental feature means you are using a feature that could be modified or removed at any time, even without a change in the SDK major version number. While these features grant early access to new functionality, there are important points to consider: * **Logs**: When using an experimental feature, you will see a log message indicating that the feature is experimental. * **Risk of Breaking Changes:** As these features are still under development, they may undergo significant changes without prior notice. Note Experimental warning log might be visible even when SDK is not started. This does not submit any data to remote. It is only information notifying you that an experimental feature is used. Note * **Documentation and Support:** We will provide up-to-date documentation, including examples of how to use the experimental feature. * **Changelog Updates:** Any introduction of or changes to an experimental feature will be documented in the changelog, ensuring transparency. ## Experimental Feature Lifecycle Experimental features follow one of three potential paths: ### 1. Positive Outcome If the feature proves successful and meets client needs, it will graduate from experimental status. The annotation will be removed, and the feature will be integrated into the SDK as a stable component.\ The documentation and the patch note will be updated to reflect this change. ### 2. Negative Outcome If the feature is determined to be unnecessary or ineffective, it will quickly move toward deprecation. This process involves marking the feature as `@deprecated` in the upcoming release, signaling to clients that the feature will no longer be supported. The feature will then be fully removed in the following minor version of the SDK. The documentation will be updated to clearly communicate the deprecation and eventual removal of the feature. ### 3. Work in Progress If further development is needed, the feature will remain experimental, with ongoing adjustments to its API, behavior, and scope. ## Providing Feedback on Experimental Features We highly value your input on experimental features, as your feedback plays a crucial role in shaping the final version of these features.\ If you're using an experimental feature, we encourage you to share your experiences, including any issues you encounter, suggestions for improvement, or use cases that the feature supports well. The most direct way to provide feedback is by submitting a support ticket. When doing so, mention that you are using an experimental feature and provide any relevant details. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Experimental annotation","description":"What is experimental in the CSQ Flutter SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/experimental/","inLanguage":"en","dateModified":"2026-06-02T10:48:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Impact on performance - Flutter description: Metrics to evaluate the performance impact of Contentsquare Flutter SDK on your apps lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/impact-on-performance/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/impact-on-performance/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The CSQ SDK strives to be non-intrusive and transparent to client app developers. The following are the technical specifics we can share on performance. The following performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | iPhone 11 Pro | | iOS version | 16.5 | | Test App built using Xcode version | 15.3 | | Test App built with Swift version | 5.8 | We conducted the tests using a default `Master-Detail` app built using ad hoc distribution with no app thinning and with Swift symbols stripped. In the app, the SDK was making calls to the public APIs, running, and collecting data in its default state. Note The numbers provided below will vary depending on the user's device, iOS version, SDK version, and if you use Swift or not, which Swift version you use if you do, if you enabled bitcode or not and which options you used when building your IPA for App Store distribution. | Property | Value | | - | - | | SDK size (installed size, no Bitcode) | \~15Mb | | Max RAM usage | <2Mb | | Max SDK CPU peak on event | <3% | | Data transmitted over network for a default batch size of 50 events The size of the batch can be customized if needed | \~29kb | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Impact on performance","description":"Metrics to evaluate the performance impact of Contentsquare Flutter SDK on your apps","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/impact-on-performance/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: In-app features - Flutter description: Enable testing and debugging capabilities within your Flutter app using in-app features for enhanced development workflow lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/in-app-features/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/in-app-features/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Alongside its tracking capabilities, the SDK embeds some features aimed at Contentsquare users such as Screenshot Capture and SDK Logs. To allow Contentsquare users to enable in-app features in your Flutter app, the implementation depends on the native platform. ## Android To enable in-app features within your app, you have to **first make sure your app is launched in the background**. To do so, start it and press the Android home button. Then, follow the appropriate method described as follows. ### On a device: scan the QR code If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code with your phone.  Note On Android, some devices have a built-in QR code reader feature in the default camera app. If that is not the case for you, use [QR & Barcode Reader by TeaCapps ↗](https://play.google.com/store/apps/details?id=com.teacapps.barcodescanner\&hl=en\&gl=US). ### On an emulator: use the ADB command If you are using an emulator, you can use the ADB command to enable in-app features. If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and select "Copy this ADB command".  It will look like this: ```shell adb shell am start -W -a android.intent.action.VIEW -d "cs-{{packageName}}://contentsquare.com?activationKey={{uniqueActivationKey}}\&userId={{userId}}" ``` If you don't have access to the Contentsquare platform, you can ask the Contentsquare team to share the link with you. ## iOS To allow Contentsquare users to enable in-app features, you must perform 2 implementation tasks: 1. [Add the custom URL scheme in your app Info](#add-the-custom-url-scheme-in-your-app-info) 2. [Call the SDK when the app is launched via a deeplink](#call-the-sdk-when-the-app-is-launched-via-a-deeplink) ### Add the custom URL scheme in your app Info You have to allow your app to be opened via a custom URL scheme which can be done using one of the following methods: #### Xcode 1. Open your project settings 2. Select the app target 3. Select the `Info` settings 4. Scroll to `URL Types` 5. Set the URL scheme to `cs-$(PRODUCT_BUNDLE_IDENTIFIER)` #### Text editor 1. Open the `Info.plist` of your project 2. Add the following snippet: **Info.plist** ```xml <key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>cs-$(PRODUCT_BUNDLE_IDENTIFIER)</string> </array> </dict> </array> ``` ### Call the SDK when the app is launched via a deeplink Depending on the project, there are multiple ways to handle the deeplink opening. Choose the method matching your project structure: * AppDelegate In your `AppDelegate` class, complete or implement the function `application(app, open url:, options:)` with: `CSQ.handle(url: url)` * SceneDelegate In your `WindowSceneDelegate` class, you need to: 1. Update `func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions)` with: ```swift if let url = connectionOptions.urlContexts.first?.url { CSQ.handle(url: url) } ``` 2. Complete or implement `func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>)` with: ```swift if let url = URLContexts.first?.url { CSQ.handle(url: url) } ``` * SwiftUI In the `body` of your main App struct, add the `onOpenURL` modifier and call the `Contentsquare` SDK to handle the URL: ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { MyView() .onOpenURL { url in CSQ.handle(url: url) } } } } ``` ### Enable in-app features Once the implementation is done, in-app features can be enabled in different ways: #### Scan the QR code If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code displayed with your iPhone.  #### Use the custom link for simulator If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and select "Copy link" (to copy the deeplink) and paste it in Safari on your Simulator to trigger the in-app features.  Note If you don't have access to the Contentsquare platform, you can ask the Contentsquare team to share the link with you. #### Using the Terminal In a Terminal console, open an URL in your current simulator with the following command (replacing `CUSTOM_LINK` with yours): ```shell xcrun simctl openurl booted "CUSTOM_LINK" ``` ## Debugging and Logging Contentsquare provides Logging capabilities that allow you to see the raw event data logged by your app in the macOS Console App, Xcode, or in the Contentsquare platform. Use this for validation purposes during the instrumentation phase of development and can help you discover errors and mistakes in your analytics implementation and confirm that all events are being logged correctly. ### Viewing local logs By default, almost all logs are disabled. There is only one log that is always visible to notify that the SDK has started: ```plaintext ┌─────────────────────────────────────────────────────────────────────────────── │ 🔔 IMPORTANT 🔔 (CSLIB 4.4.4) ├─────────────────────────────────────────────────────────────────────────────── │ Contentsquare Flutter SDK 4.4.4 starting in app: │ com.example.testapp └─────────────────────────────────────────────────────────────────────────────── ``` To enable all logs, activate [in-app features](#enable-in-app-features). Logging is directly linked to in-app features state: it starts when in-app features are enabled and stops when you disable in-app features. ### Viewing logs in the Contentsquare platform To view logs directly on the platform, you can use Log visualizer. Log visualizer is a helper tool to see SDK logs without logging tools. It requires having platform access for your project and enabling in-app features. See the [SDK Log Visualizer Help Center Article ↗](https://support.contentsquare.com/hc/en-us/articles/37271699876625) for more information. ### Screenshot capture To unlock the full data-visualization capabilities of Contentsquare, the SDK provides a way to capture screenshots of your app screens. These screenshots can only be taken by Contentsquare's users on their device. They are not captured from your end-users device. It means your Personal Data is safe, as long as you use a test user account. Warning For screenshot capture to work, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. Note Screenshots require a screenview event to be triggered before they can be captured.  Screenshots are used in the **Zoning Analysis** module to look at zone-level metrics (Tap rate, Swipe rate...):  ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"In-app features","description":"Enable testing and debugging capabilities within your Flutter app using in-app features for enhanced development workflow","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/in-app-features/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - Flutter description: Configure privacy settings and user consent management in your Flutter app with the CSQ SDK to ensure regulatory compliance lastUpdated: 28 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/privacy/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Customers ("Customer(s)", "you," or "your"), as app developers and/or publishers, shall ensure compliance with applicable data privacy laws and regulatory guidelines while using Contentsquare SDK for your app. This section explains the data processing involved in the use of Contentsquare SDK and provides information to help you comply with data protection laws, including the GDPR, e-privacy directive, and the [French Data Protection authority (CNIL) guidelines on mobile applications ↗](https://www.cnil.fr/sites/cnil/files/2025-05/recommendation-mobiles-app.pdf). This section is for informational purposes only and is not legal advice. If you are not sure of how to comply with data protection laws that apply to you, refer to legal counsel. To learn about Contentsquare privacy practices, see our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Purpose of processing and categories of personal data collected Here is the list of categories of personal data Contentsquare collects by default that are part of our [privacy manifests](../privacy/#privacy-manifest). All collected personal data listed below is linked to the end-user via the [Contentsquare User ID](#contentsquare-user-id) we generate. Warning The Contentsquare SDK provides features that allow you to send to Contentsquare additional types of personal data (such as username, email address, customer ID, account number): [Dynamic variables](../../experience-analytics/track-dynamic-variables/), [Custom variables](../../experience-analytics/track-custom-variables/), [User identifier](../../experience-analytics/session-replay/#send-user-identifier), [Screen names](../../experience-analytics/track-screens/), [Session Replay (unmasking elements)](../../experience-analytics/session-replay/#personal-data-masking). If you decide to use these features to collect new types of personal data or use already collected data but for a different purpose, it is up to you to describe these privacy practices in your app manifest. | Categories | Data type | Purposes | | - | - | - | | Identifiers | User ID | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Product Interaction such as touch gestures (taps, swipes), user journey (pages visited), time of engagement, or transactions | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Other usage data (any other data about end-user activity in the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Other Data types | Other Data types (technical data, any other data inputted by customers in the dynamic variables, data used as part of the Session Replay feature where applicable) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Diagnostics | Crashes, such as crash logs | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Diagnostics | Performance data, such as launch time, freeze rate, or energy use | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Diagnostics | Other diagnostic data (any other data collected for the purposes of measuring technical diagnostics related to the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Search History | Information about searches performed by an end-user in the app | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Session Replay module](../../experience-analytics/session-replay/)) | | Purchase History | Transaction data about an end-user (such as order reference, amount, bought items) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | See how the data types and purposes are reflected in the [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy). Note Contentsquare is not designed to collect sensitive personal data (such as health, financial, or racial data). It is your responsibility to prevent any sensitive data from being sent to Contentsquare. If you accidentally send sensitive data, contact your customer success manager to immediately delete them from Contentsquare servers. ## User identifiers ### Contentsquare User ID The SDK generates a unique user ID (UUID) (random hash) which is specific to users on their device. Contentsquare cannot identify a user across devices. This user ID and all collected data are stored for 13 months. We don't persist the UUID when the app is deleted and re-installed. The SDK generates a new UUID after install or re-install. Contentsquare does not share this user ID with any third parties. ### IDFA Contentsquare does not collect the **IDFA** (Advertising ID) or any ad related information to identify the user. Check out our page about [10 Things to know about the Contentsquare solution's data processing ↗](https://contentsquare.com/privacy-center/10-things-to-know-cs-data-processing/). ### "User identifier" feature Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier provided by the customer. See [User identifier feature](../../experience-analytics/session-replay/#send-user-identifier) for more information. ## Data retention and storage location ### Data retention By default, end-users personal data are kept for 13 months. The retention of end-users personal data collected via the Session Replay is customizable by customers, from 3 to 24 months. ### Storage location End-users personal data are stored in Europe or in the US, depending on your location. For more details on applicable hosting locations, refer to our [subprocessors list ↗](https://contentsquare.com/privacy-center/subprocessors/). ## Informing your End-User The Contentsquare SDK collects end-user's personal data on your app. As a data controller, app developers, or app publishers, it is your responsibility to provide appropriate information to your end-users on how their personal data is handled when using the CSQ SDK, for example via a privacy policy or cookie banner. Contentsquare provides a sample [description of the services ↗](https://contentsquare.com/privacy-center/sample-cookie-description/) (including Experience Analytics and Product Analytics) to help customers meet their transparency obligations. This description is for information only and is not legal advice. ## Handling User Consent Contentsquare collects usage data on your app. **By default, the SDK will consider every new user to be opted-out.** To start tracking, the SDK [Opt-in API](#opt-in) must be called. You are responsible for handling the UI asking end-users for their consent and allowing them to manage their privacy settings. Use the following APIs to pass the user decision to the Contentsquare SDK. Note If data protection laws that apply to you do not require end-user consent for your app, discuss it during implementation with your Contentsquare contact (as this would go against Apple Privacy guidelines). ### Opt-in Use the Opt-in API to get end-user consent. Calling this API will generate a user ID and initiate tracking. * Experience Analytics ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start() CSQ.optIn() // Continue with post-consent navigation or UI update } ``` * CSQ Experience Platform (Early Access) ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` ### Opt-Out When this API is called, tracking stops immediately, all settings are reset (Session number, Page number, and so on) and all files and directory including personal data collected via the SDK created by Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track and collect any data from the user's phone unless the Opt-in API is called again. ```swift CSQ.optOut() ``` ### Handling your end-user's data subject requests In case Contentsquare receives a request from an individual that identifies as an end-user of your app, Contentsquare will promptly refer such individual directly to you, as the data controller and will support you with any means available to resolve such request. Contentsquare has launched a portal for managing data subject requests to its customers respond to data subjects within the legal deadlines. Therefore, you can forward any data subject request (such as data deletion or data access request) you receive to Contentsquare via this Data Subject Portal at [https://contentsquare.com/privacy-center/data-subject-request-portal/ ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ### Get Contentsquare User ID Since Contentsquare SDK does not collect by default any directly identifiable personal data about your end-user, we cannot help you respond to an end-user's data subject request without their Contentsquare User ID. Use this API to get the Contentsquare User ID of your end-user and forward the end-user's data subject request (such as data deletion or data access request) via Contentsquare's [portal ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ```swift CSQ.metadata.userID ``` Note You are able to get an ID only if the user is not Opted-out. ### Enrichment API [The Enrichment API](https://docs.contentsquare.com/en/api/enrichment/) allows for enriching the behavioural data tracked by Contentsquare client-side, with other session-based data that can be sent server-side. During a visit on an app, you can interact with Contentsquare's SDK to pull those identifiers with the following SDK APIs: ```swift let projectID = CSQ.metadata.projectID let sessionId = CSQ.metadata.sessionID // store these Contentsquare session identifiers in your backend ``` ### Pause / Resume Tracking To completely stop data collection of your end-users of your app, use the pause and resume tracking APIs. When `stop/pause` is called, the Contentsquare SDK pauses all tracking (Analytics, Session Replay, Errors) of your end-users. When `resume` is called, the Contentsquare SDK resumes all tracking (Analytics, Session Replay, Errors) and starts collecting your end-users personal data again with the same Contentsquare user ID. ```swift CSQ.stop() // ... CSQ.resumeTracking() ``` Note As this mechanism pauses the tracking, make sure that you call resume once your user exits the sensitive screen. Best practice would be to link these method calls to lifecycle events on UIView/UIViewControllers. ## Disable user tracking across sessions If you don't want to link the different sessions of a user to the same userID, reset the userID at each app start: ```swift func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) { CSQ.start() CSQ.optOut() CSQ.optIn() // ... } ``` Starting the SDK manually using `start()` will ensure that opt-out is called right after the start of the SDK (no event tracked in between). Calling `optOut()` will delete the previous userID. Calling `optIn()` will set a new one. Note If you are monitoring the network requests, you may see event requests being sent at app start. This is expected as there may be events from the previous session that haven't been sent yet. The [opt-out API](#opt-out) makes sure to send all data stored locally before stopping the tracking and wiping all data. ### Session Replay privacy APIs As part of Session Replay capabilities, Contentsquare provides masking mechanisms to prevent unwanted end-user's personal data from the Session Replay module from being transmitted to Contentsquare. See [Session Replay Personal data masking](../../experience-analytics/session-replay/#personal-data-masking) for more information. ## App Store Privacy Guidelines Compliance As customer app developers, it is your responsibility to comply with the [App Store Privacy guidelines ↗](https://developer.apple.com/app-store/review/guidelines/#privacy). ### Privacy manifest The Contentsquare SDK includes a [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy) describing the types of end-users personal data collected, the purpose of processing and the reasons for using APIs. [See Apple's website for more information ↗](https://developer.apple.com/app-store/app-privacy-details/) ### Tracking and App Tracking Transparency (ATT) App Store (Apple) requests App developers to receive end-users' permission to track them or access Advertising ID using the [AppTrackingTransparency framework ↗](https://developer.apple.com/documentation/apptrackingtransparency) (ATT). **It is not required to ask for end-users' permission through the ATT when using Contentsquare, as it does not fall under the** ["tracking" definition of Apple ↗](https://developer.apple.com/app-store/app-privacy-details/#user-tracking). The data collected by the Contentsquare SDK is not linked with Third-Party Data (as defined by Apple) for targeted advertising or advertising measurement purposes, nor shared with a data broker. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Configure privacy settings and user consent management in your Flutter app with the CSQ SDK to ensure regulatory compliance","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/privacy/","inLanguage":"en","dateModified":"2026-04-28T22:02:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Reliable Targets - Flutter description: Reliable targets enables the analysis of data across various Screenshots from different dates and versions, including layouts or A/B testing variations lastUpdated: 14 January 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/reliable-targets/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/reliable-targets/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. CSQ SDK uses zoning identifiers that relies heavily on the structure of the widget tree. Consequently, changes to the widget tree, such as moving, nesting, or removing a widget, may result in the loss of tracking data. Consider the widget tree of a Flutter app as illustrated below: **main.dart** ```dart Widget _buildMyAwesomeContent() { return Column( children: const [ Text('Answer to the Ultimate Question of Life, The Universe, and Everything'), Text('is'), Text('42'), ], ); } ``` In many cases, maintaining a `Reliable Target`, despite changes in its position within the tree, is essential. This consistency ensures reliable analysis of data across different `Screenshots`, dates, and versions, including variations in layouts or A/B testing. Having a `Reliable Target` for a widget enables the analysis of data across various `Screenshots` from different dates and versions, including layouts or A/B testing variations. Here are some scenarios where the Reliable Targets feature proves beneficial: | Scenario | Example use case | | - | - | | Tracking elements capable of dynamically shifting on a page | Customizable profile page | | Monitoring elements across various app versions, even if their positions change | Carousel transitioning from top to bottom | | Tracking elements amidst A/B testing | Testing old and new product pages within the same version | | Monitoring elements used across multiple pages | Search bar | | Ensuring a unique identifier for a call to action regardless of its location on the screen | "Add to Cart" button | To facilitate this, the CSQ Flutter SDK offers a `ReliableTarget` widget, designed to encapsulate the widget intended for reliable tracking. The widget requires a unique `name` argument for identifying the component to track across all versions of your app: **main.dart** ```dart import 'package:contentsquare/csq.dart'; Widget _buildMyAwesomeContent() { return ReliableTarget( name: '42_is_the_answer', child: Column( children: const [ Text('Answer to the Ultimate Question of Life, The Universe, and Everything'), Text('is'), Text('42'), ], ), ); } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Reliable Targets","description":"Reliable targets enables the analysis of data across various Screenshots from different dates and versions, including layouts or A/B testing variations","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/reliable-targets/","inLanguage":"en","dateModified":"2026-01-14T10:09:04-08:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Security - Flutter description: Data transfer and security information lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/security/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/security/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Flutter SDK is designed with security and privacy in mind. ## Transmission and hosting All data is encrypted in transport over HTTPS. Our hosting solution is a PCI DSS Level 1 Service Provider. ## What is not collected * Passwords from password fields * Geo location information * Information from contacts, emails, or any other user identifiable information. * Text from labels, buttons, and any other widget which contains text * Accessibility information from any widget which the user interacts with * Labels printed on the screen of any kind. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Security","description":"Data transfer and security information","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/security/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Session Replay - Flutter description: Learn how to integrate and configure Session Replay capabilities in your Flutter app with the CSQ SDK lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/session-replay/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/session-replay/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Session Replay enables replaying real sessions to observe how users interact with your product, by capturing screen content - including text and images - as users navigate your mobile app. For more details, see [Introduction to Session Replay for Apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) in the Help Center. ## Starter guide ### Prerequisites #### Update to latest SDK version To enable Session Replay in your app and get the most stable version, it is required to [upgrade the SDK](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/#install-the-sdk) to its latest version. #### Implement screen tracking Ensure screen tracking is implemented, since Session Replay collection starts at the first screenview event. See [Track screens](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-screens/). #### Handle User consent Ensure user consent is handled for Contentsquare data collection, especially if you're implementing the SDK for the first time. See [Privacy](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/privacy/) section. Note Mandatory data collection settings are configured by Contentsquare in your project parameters. [Learn more about Data collection configurations ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) on the Help Center. ### Configure Session Replay masking #### Masking behavior By default, the CSQ SDK is configured to mask all content displayed on the user interface (UI) to prevent unnecessary data collection. For more details, see what a fully masked screen looks like in [Masking mechanisms](#masking-mechanisms). **For testing purposes**, use this setup: * Either unmasking all the content by setting the [default masking](#default-masking) status to false. * Or unmasking most content with the [Text and Image unmasking configuration ↗](https://support.contentsquare.com/hc/en-us/articles/37271682878353-Data-masking-in-Session-Replay-Mobile-Apps) in your Console parameters. **For more granular control in deployment mode**, you can use the [Text and Image unmasking configuration ↗](https://support.contentsquare.com/hc/en-us/articles/37271682878353-Data-masking-in-Session-Replay-Mobile-Apps) in your Console parameters in combination with [SDK public masking APIs](#public-masking-apis) to fine-tune exactly which elements remain masked. Warning Always keep sensitive data masked to ensure compliance with privacy regulations and to protect users' personal data. ### Configure Event-Triggered Replays (optional) If Event-Triggered Replays is included in your contract, you can set up ETR events to enable specific screen and session collection in Session Replay. See [Event-Triggered Replays (ETR)](#event-triggered-replays-etr). ### Configure Webviews (optional) If your mobile app includes Webviews, specific implementation steps are required to ensure they are properly reflected in Session Replay: * Implement [Webview tracking](https://docs.contentsquare.com/en/webview-tracking-tag/) * Handle [personal data within WebViews](https://docs.contentsquare.com/en/webview-tracking-tag/session-replay/#personal-data-handling) ### Test your setup #### Enable Session Replay on your device If the Session Replay sampling rate is less than 100%, only a portion of sessions are collected. To ensure data collection on your device for testing and debugging purposes, you can force it from the In-app Features settings by following these steps: 1. [Enable in-app features](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/in-app-features/) 2. Open in-app features settings with a long press on the screenshot button 3. Under "Session Replay", toggle "Enable Session Replay" on 4. Kill the app 5. Upon restarting the app, a new session will start with Session Replay enabled. ##### iOS example  #### How do I know if Session Replay is enabled? There are 2 places where you can verify if Session Replay is enabled: **In the logs:** The log `Session Recording is starting` will confirm that Session Replay is enabled. **In in-app features settings:** Below the "Enable (will start at next app start) *(see below [Access the replay](#access-the-replay))*, you will either see: * `No replay link available` which means Session Replay is not running for the current session * `Get Replay link` which means Session Replay is running for the current session #### Access the Replay The session can be accessed by tapping on `Get replay link` button from the in-app features settings:  The replay will be **available within 5 minutes**. Only the *concluded* screen views are processed, and we identify a screenview has *concluded* when we begin receiving data for the subsequent screenview or if the session has ended. This means that you will be able to replay your session up to the previous screenview if the session is still ongoing. ## Control Session Replay manually By default, Session Replay starts automatically when the SDK starts. You can disable this and control it programmatically using `sessionReplayAutoStart`. ### Disable automatic start Set `sessionReplayAutoStart: false` in `AnalyticsOptions` when starting the SDK: **main.dart** ```dart import 'package:contentsquare/csq.dart'; await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: const AnalyticsOptions( sessionReplayAutoStart: false, ), ), ); ``` ### Start Session Replay on demand Call [`CSQ().startSessionReplay()`](../command-reference/#csqstartsessionreplay) to begin collection at any point after the SDK has started: ```dart import 'package:contentsquare/csq.dart'; await CSQ().startSessionReplay(); ``` ### Stop Session Replay on demand Call [`CSQ().stopSessionReplay()`](../command-reference/#csqstopsessionreplay) to stop collection: ```dart import 'package:contentsquare/csq.dart'; await CSQ().stopSessionReplay(); ``` Note `startSessionReplay()` and `stopSessionReplay()` are available from SDK version 4.2.0. When `sessionReplayAutoStart` is `true` (the default), calling these APIs has no effect. ## Personal Data Masking The Session Replay feature replays every interaction of your users with your app. To respect the user's right to privacy, the CSQ SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our [Masking rules](#masking-rules) Warning When using Contentsquare with Flutter, if you decide to use unmasked elements leading to collection of new data or use already collected data but for a different purpose, it is up to you to update your app's privacy documentation accordingly. Here are some common examples of data collected via unmasked Session Replay: Search history, purchase history, advertising data, etc. See [Types of data and purpose](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/privacy/) for details about the data collected by the Contentsquare Flutter SDK. **Important:** Contentsquare is not intended nor designed to collect sensitive personal data (such as health, financial, racial data). It is the customer's responsibility not to send any sensitive personal data to Contentsquare. ### Masking mechanisms Masking depends on the type of element: * **Images**: A blurred representation is sent in place of the original content. * **SVG images**: A blurred representation is sent in place of the original content. * **CustomPaint**: custom-made `CustomPaint` elements are not collected. Instead, a blurred representation is sent in place of the original content. [Framework specific decorative `CustomPaint`](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/session-replay/#unmaskable-framework-specific-custompaint-classes) that do not contain sensitive data are still collected. * **Text**: Replaced by \* (asterisk) characters, matching the original character count. Whitespace characters (spaces, tabs, line breaks) are preserved. For instance, `the lazy fox` is collected as `*** **** ***`. All other visual properties (text color, background color, alignment, etc.) are collected. * **TextFields**: Same as Text * **TextField with `obscureText`**: Both the obscured text and the briefly revealed character are replaced by • (bullet). * **Other types**: no specific data is collected but visual properties are collected. * **Icons**: Single characters belonging to the Private Use Area `U+E000..U+F8FF` are collected. If you believe a particular element might disclose personal data through any of these properties, you must mask it using one of the methods outlined below. A reliable method to assess how a view is rendered in a replay is to navigate to the desired view with the CS SDK active, then use the [quick replay link](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/session-replay/#access-the-replay). #### Masking example Here's an illustration of a masked view: `Original` -> `Replay fully unmasked` -> `Replay fully masked`  ### Masking rules Masking rules can be applied in two ways: 1. **Through remote masking configuration in the CSQ Console (for admin users):** These configurations are managed directly in the Console and take effect for all sessions as soon as the app is restarted or brought to the foreground. See [How to customize masking rules from the Data Masking tab ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) on the Help Center. 2. **Using public masking APIs in the SDK (for mobile application developers):** These configurations require developer implementation and will be applied only after the mobile app has gone through its release cycle. Masking rules set via the CSQ Console or the public APIs are applied according to different priorities, as described below. The SDK determines whether a view is masked by evaluating the rules in the order specified below. Once a rule is triggered, the state is set, and subsequent rules are not applied: When using `CSQMask` and `CSQMaskingConfig`, it's essential to understand the priority of masking rules in the widget tree. The masking rules specified in a `CSQMask` widget will affect its descendants, and if nested scopes are used, the innermost (closest) scope takes precedence. Once a rule is triggered, the state is set, and subsequent rules are not applied: | Rule | Configured via | | - | - | | 1. The app or plugin version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text or Image masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. The `CSQMaskingConfig` object provided to the `start()` method sets the masking rules for the entire app. | API | | 4. The `CSQMaskingConfig` object provided to a `CSQMask` widget sets the masking rules for its child and descendants. | API | | 5. Remote Text or Image unmasking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 6. Otherwise the widget remains masked except for `CustomPaints` and `SvgImages` | default | ### Public Masking APIs #### Default masking By default all images, text, and Text fields will be masked. SVGs and CustomPaints are not masked. #### Masking/Un-masking in Flutter `CSQMask` is a Flutter widget that applies specified masking rules to its descendant widgets. This can be used when you want to mask sensitive information during Session Replays, such as user data or private texts. `CSQMaskingConfig` is a class that determines what type of content should be masked during Session Replays. You can customize the masking behavior by setting the masking options for texts, text fields, and images. #### Handle masking To mask or unmask content, wrap the desired widgets with the `CSQMask` widget and provide a `CSQMaskingConfig` object to configure the masking rules. Here's an example of how to use `CSQMask`: ```dart import 'package:contentsquare/csq.dart'; CSQMask( maskingConfig: CSQMaskingConfig.maskAll(), child: const Text('Hello world'), ); ``` In this example, `CSQMaskingConfig.maskAll()` is used to mask the `Text` widget. You can also use nested `CSQMask` widgets to apply different masking rules to different parts of your widget tree. Here's an example: ```dart import 'package:contentsquare/csq.dart'; CSQMask( maskingConfig: CSQMaskingConfig.maskAll(), child: Column( children: [ const Text('This text will be masked'), CSQMask( maskingConfig: CSQMaskingConfig(maskTexts: false), child: Text('This text will NOT be masked'), ), ], ), ); ``` In this example, the first `Text` widget will be masked, while the second one will not be masked due to the `maskTexts: false` option in the nested `CSQMask`. #### How to use `CSQMaskingConfig` `CSQMaskingConfig` allows you to configure the masking behavior for different types of content: * `maskTexts`: If set to `true`, any widget that creates a `RenderParagraph` (example: `Text`, `RichText`) will be masked. * `maskTextFields`: If set to `true`, any widget that creates a `RenderEditable` (example: `TextFormField`, `TextField`) will be masked. * `maskImages`: If set to `true`, any widget that creates an image (example: `Image`, `BoxDecoration.image`) will be masked. * `maskSvgImages`: If set to `true`, any widget that creates an SVG image through `flutter_svg` will be masked. * `maskCustomPaints`: If set to `true`, any custom-made widget that creates a `CustomPaint` will be masked. [Framework specific decorative `CustomPaint`](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/session-replay/#unmaskable-framework-specific-custompaint-classes) not containing any sensitive data are not masked. * `maskCharts`: If set to `true`, any widget that creates a chart using the [`fl_chart` ↗](https://pub.dev/packages/fl_chart) package will be masked. You can create a custom `CSQMaskingConfig` object by using the constructor: ```dart import 'package:contentsquare/csq.dart'; const CSQMaskingConfig({ bool? maskTexts, bool? maskImages, bool? maskTextFields, bool? maskSvgImages, bool? maskCharts, bool? maskCustomPaints, }) ``` For easier readability and convenience, you can use the following factory constructors: * `CSQMaskingConfig.maskAll()`: Returns a `CSQMaskingConfig` object with all values set to `true`, meaning everything will be masked. * `CSQMaskingConfig.unMaskAll()`: Returns a `CSQMaskingConfig` object with all values set to `false`, meaning nothing will be masked. If any masking parameter is omitted in the `CSQMaskingConfig` object, its value is inherited from the nearest `SessionMaskingScope` widget in the widget tree. Note By default, CSQ masks all types of content (texts, text fields, and images) except the SVG images and CustomPaints during Session Replays. It achieves this by providing a default `CSQMaskingConfig` object if none is specified. The default configuration masks everything, ensuring that sensitive information is protected. However, you can override the default masking behavior by providing your own `CSQMaskingConfig` object when calling the `start()` method. This allows you to customize the masking rules for your app according to your requirements. Note If you did not include any sensitive content in `CustomPaint`s or SVG images, prefer to use `CSQMaskingConfig` with `maskCustomPaints` and `maskSvgImages` set to false, to avoid unnecessary masking and guarantee the best Session Replay fidelity. ## Event-Triggered Replays (ETR) Event-Triggered Replays (ETR) is an add-on feature that allows you to selectively collect specific screens or sessions for Session Replay, based on predefined custom events. Once configured, ETR events can be used to filter specific replays, or view these events as they happen in the player event stream. To enable ETR, contact your CSM or Implementation Manager. For more information, see [Event-Triggered Replays ↗](https://support.contentsquare.com/hc/en-us/articles/4412027865874) in the Help Center. Note When ETR is enabled, the SDK collects data for the entire session even if none of the ETR methods described below are called. After collection, only the sessions or screens that match the global replay sampling rate or are associated with ETR events are retained. As a result, you may notice a network activity during all sessions, regardless of whether ETR has been triggered or not. Warning To protect end-user personal data, ensure that appropriate masking configurations are applied to all screens even the ones that are not associated with ETR events. ### Trigger Replay for the Session Use the following function to trigger Session Replay for the entire current session, with the parameter `name` as "ETR event". ```dart import 'package:contentsquare/csq.dart'; await CSQ().triggerReplayForCurrentSession(name: name) ``` ### Trigger Replay for the Screen Use the following function to trigger Session Replay for the entire current screen, with the parameter `name` as "ETR event". ```dart import 'package:contentsquare/csq.dart'; await CSQ().triggerReplayForCurrentScreen(name: name) ``` ## Advanced features for Experience Monitoring Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. ### Send user identifier Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier: email, phone number, customer ID… As these values are typically personal data, from the moment the SDK is collecting the `User Identifier`, we immediately encode the value using a hashing algorithm so that the information is hidden and can never be accessed. Use the following code to send a user identifier: ```dart import 'package:contentsquare/csq.dart'; await CSQ().sendUserIdentifier(userIdentifier: 'the_neo@one.com'); ``` When called, the native SDK will log: ```plaintext CSLIB ℹ️ Info: User identifier hashed sent {value} ``` ### Sending a user identifier for each session You may consider sending the user identifier for each session. Although triggering the user identifier at app launch will cover most cases, it may not be adequate in all scenarios. For instance, a session might start when the app is brought to the foreground after being in the background for more than 30 minutes. For further details, refer to the [Session definition](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/data-collection/#session-definition) section. That is why we also recommend sending the user identifier every time the app enters foreground. ### Limitations * User identifier max length is 100 characters (if the limit is exceeded, the user identifier will not be handled and you will see an error message in the native Console/Logcat) * Only the first 15 user identifiers per view will be processed on server side * The SDK will trim and lowercase user identifier * User identifier event are not visible in `LogVisualizer` ## Session Replay Quality ### Quality Levels Session Replay is designed by reconstructing the app's tree structure from selected frames. To minimize performance impact during a session, different quality levels are dynamically applied. Each quality level determines whether certain styles are preserved or omitted while maintaining the overall screen structure and appearance. #### High Quality Level  At this level, all supported styles are captured every 200ms, provided a new frame is available. This ensures a comprehensive reproduction of the session's visual fidelity. #### Low Quality Level This level captures supported styles only when user interaction ceases, such as during screen scrolling. images are reduced to their average color representation. ### Quality Level Adjustment Our plugin continuously monitors its performance while running. Upon detecting a performance issue, the quality level is automatically reduced to mitigate any potential impact on the application. The quality level may increase when navigating to a new screen, provided the performance issue is resolved. Quality levels are visibly indicated in the Session Player event stream.  ## Integrations Contentsquare provides the ability to retrieve the link of the replay to be attached to other vendors such as Voice of Customer or Crash reporting tools. ### Get current replay Link Generate a link to the replay of the current session. This link can be pushed to any internal or 3rd-party tool as a custom property/variable. For instance, you can add the replay link to: * Each user request sent to your customer service tool * Each user voting in your Voice of Customer tool * Each user session in your App Performance, Observability tool * ... Note The replay link can also be accessed from the in-app features settings. See [Access the Replay](#access-the-replay). Warning For the API to return a valid replay link, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before it's called, since Session Replay only starts after the first screenview event. #### Function signature You can listen for the replay link that is part of `Metadata` changes using the following function: ```dart import 'package:contentsquare/csq.dart'; CSQ().metadata.onChange(void Function(Metadata metadata) handler); ``` #### Parameters `void Function(Metadata metadata) handler`: A callback function that receives the updated `Metadata` object, which contains the `sessionReplayUrl` property. #### Key Features * Real-Time Updates: The callback is triggered every time there is a change in the `Metadata` object. If during the method call current `metadata` is available, the callback will be triggered immediately. * Single Callback Registration: Only one callback can be active at a time. If the API is called multiple times, the most recent callback registration overrides the previous one. * `onChange` returns a `StreamSubscription<Metadata>` object that can be used to manage the subscription. Use the following code to retrieve a Session Replay link each time it changes: ```dart import 'package:contentsquare/csq.dart'; CSQ().metadata.onChange(_onCSQMetadataChanged); void _onCSQMetadataChanged(Metadata metadata) { final sessionReplayUrl = metadata.sessionReplayUrl; print('Session Replay URL: $sessionReplayUrl'); } ``` To unregister the current callback, cancel the `StreamSubscription`: ```dart import 'package:contentsquare/csq.dart'; StreamSubscription<Metadata>? _csqMetadataSubscription; _csqMetadataSubscription = CSQ().metadata.onChange(_onCSQMetadataChanged); _csqMetadataSubscription?.cancel(); ``` When a new link is available, the SDK will also log: ```plaintext CSLIB: SessionReplay link: https://app.contentsquare.com/quick-playback/index.html?pid={projectId}&uu={userId}&sn={sessionNumber}&recordingType=cs ``` Warning You can only have one callback at a time. Calling this API multiple times will override the previous callback. The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay the session up to the previous screenview if the session is still running. ## How Session Replay works ### Initialization Sessions can be collected for Session Replay if the Session Replay feature has been enabled for your project and the session matches the collection criteria. The following conditions will have an impact on which sessions will be collected: * **User consent**: The users have provided their **consent** (if required) * **Collection rate**: The session is **designated for collection** (see [Collection Rate](#collection-rate)) * **Compatibility**: The **OS version** is supported. * **App version**: The **app version** is not included in the block list (see [App Version Block List](#app-version-block-list)) Note When Session Replay is disabled, no content specific to Session Replay is collected. Additionally, be aware that standard Contentsquare analytics tracking remains unaffected by this. #### Collection Rate Session Replay collection is based on a percentage of the total sessions. By default Session Replay collection is disabled. During the early access phase, the percentage of collected sessions will be set to 1% at the beginning. It will then be adjusted based on: * The traffic on your app * The volume of collected sessions set in the contract #### Compatibility See the [Compatibility matrix](https://docs.contentsquare.com/en/flutter/compatibility/#compatibility-matrix). #### App Version Block List The Contentsquare team can include versions of your app in the block list to prevent Session Replay from initiating on these versions. This functionality proves valuable when a problem is identified on a particular version of your app, such as a situation where masking for Personal Data was not implemented. By employing this feature, Session Replay can continue to operate on other app versions, particularly those with necessary fixes implemented. ### Collection The SDK monitors the application lifecycle events and the view hierarchy, capturing Session Replay data based on app behavior, screen content, and user interaction. These events are initially stored locally and later sent to our servers in batches. Subsequently, we aggregate this data to generate actionable visual insights in our Web Application, facilitating your ability to gather insights. Tip Session collection begins when the first screenview event is triggered. ### Network and Storage By default, Session Replay data can be sent over **cellular network**. However, if your app's context or user preferences necessitate minimal impact on cellular data usage, you can opt to disable data transmission over cellular networks entirely. Once disabled, data will only be sent when the device is connected to Wi-Fi. To make this adjustment in your project's configuration, contact your Contentsquare representative. #### Storage Before being sent, data is stored in local files on disk up to 30MB on iOS and 20MB on Android. If the limit is reached, Session Replay is halted. It will resume at the next app launch once the SDK can transmit the data. ### Requests The maximum request size is 1 MByte. #### iOS Requests are sent: * Every 10 seconds * At app hide * When [Replay Link API](#access-the-replay) is called #### Android Requests are sent: * On screen change * When [Replay Link API](#access-the-replay) is called ## Performance impact We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. ### Performance impact mitigation Most operations related to Session Collection are performed on background threads, for the impact on the main thread to be minimal. We also set up mechanisms that adapts and stop the Session Collection if we detect the feature is using too much memory. We defined our network strategy to have the lesser impact on CPU and battery of the users devices. We measure these impacts, using Apple Dev Tools, for each release of our SDK. Session Collection will also stop if we use up to 30Mbytes of local storage. ### Performance Benchmarks We have conducted performance tests on the SDK to ensure that it has a minimal impact on the app's performance. The tests were conducted on a variety of devices and operating systems to ensure that the SDK performs well across different platforms. These tests use the [Flutter Gallery ↗](https://github.com/flutter/gallery) app as a reference and simulate an intensive normal user interaction with the app during 60 seconds (scrolling, tapping, etc.) using the Session Replay feature. #### iOS For iPhone 14 with iOS 16.3 | Metric | Value | | - | - | | CPU Usage Delta | < 3% | | Memory Usage Delta | < 2% | | Network Usage | < 80kb | #### Android For Pixel 6 with Android 13 | Metric | Value | | - | - | | CPU Usage Delta | < 25% | | Memory Usage Delta | < 20% | | Network Usage | < 80kb | ## Known limitations Session Replay is designed by reconstructing your app's tree structure from selected frames, rather than collecting the screen pixel-by-pixel. Most standard Flutter content — text, text fields, images, SVG images, `CustomPaint`, charts, and clip shapes — is captured faithfully. Some content, however, cannot be reproduced exactly: content rendered outside the Flutter view (such as platform views and native maps) is not collected; Webviews require specific implementation steps to be properly reflected in Session Replay; custom shapes are sent as rectangles; and for unsupported element types (for example, custom `RenderObject` subclasses that paint directly), no specific content is collected but their visual properties — position, size, background — still are. Because the replay is reconstructed from selected frames, animations are captured at intervals rather than frame-by-frame, so fast or subtle motion may appear stepped. * Content rendered outside the Flutter view — platform views, native maps, and other embedded native content — is not collected. * Webviews require specific implementation steps to be properly reflected in Session Replay. See [Track WebViews](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-webviews/). * Custom shapes are sent as rectangles. * For unsupported element types (for example, custom `RenderObject` subclasses that paint directly), no specific content is collected, but visual properties are. The standard `CustomPaint` widget is supported. * Animations are reconstructed from selected frames, not captured frame-by-frame, so fast or subtle motion may appear stepped. * Blur style is not supported when the app is [obfuscated ↗](https://docs.flutter.dev/deployment/obfuscate). * Overlays shown without a Flutter context (for example, native toasts) may not appear in the replay, particularly on Android. * In debug mode, the stability and performance of Session Replay are not guaranteed. For a reliable and high-performing experience, use release or profile builds. * In the event stream of the Session Replay, a tapped element is displayed as `unknown` if it has a transparent parent. * Masking applied to parent widgets does not apply to the [Draggable.feedback ↗](https://api.flutter.dev/flutter/widgets/Draggable/feedback.html) widget. To ensure proper masking while dragging, wrap the Draggable.feedback widget within its own `CSQMask`. If your app relies on a third-party library that you'd like to see supported in Session Replay, feel free to reach out to us. ## Unmaskable Framework specific `CustomPaint` classes * `CupertinoActivityIndicator` * `CupertinoTextSelectionToolbar` * `BottomNavigationBar` * `DatePickerDialog` * `DropdownButton` * `InputDecorator` * `PhysicalShape` * `LinearProgressIndicator` * `CircularProgressIndicator` * `Stepper` * `TabBar` * `TextSelectionToolbar` * `AnimatedIcon` * `GridPaper` * `GlowingOverscrollIndicator` * `Placeholder` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Session Replay","description":"Learn how to integrate and configure Session Replay capabilities in your Flutter app with the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/session-replay/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Product Analytics data capture - Flutter description: Access to acquisition analysis and lifetime metrics by implementing the Product Analytics data capture using the CSQ SDK lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/set-up-product-analytics-data-capture/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/set-up-product-analytics-data-capture/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This page instructs how to set up Product Analytics data capture in combination with Experience Analytics. 1. Initialize the CSQ SDK with your environment ID. * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', ), ); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', ), ); } ``` Find your environment ID `YOUR_ENVIRONMENT_ID` is either provided to you by Contentsquare or you can find it in **Account** > **Manage** > **Projects** > \[Select your project] > **Environments** within the [Product Analytics web app ↗](https://heapanalytics.com/app/). 2. Recommended To capture screen views automatically, add the `CSQNavigatorObserver` to your app's navigator observers: **main.dart** ```dart import 'package:contentsquare/csq.dart'; MaterialApp( navigatorObservers: [ CSQNavigatorObserver(), ], home: MyHomePage(), ) ``` More details in [Track screens](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-screens/). 3. Recommended To enable automatic capture of user interactions, add the option `enableInteractionsAutocapture: true` to your `AnalyticsOptions` configuration: * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( enableInteractionsAutocapture: true, ), ), ); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( enableInteractionsAutocapture: true, ), ), ); } ``` 4. (Optional) If your Product Analytics environment is hosted in the EU, set the `baseUrl` option to `https://mh.ba.contentsquare.net`. * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( baseUrl: Uri.parse('https://mh.ba.contentsquare.net'), ), ), ); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( baseUrl: Uri.parse('https://mh.ba.contentsquare.net'), ), ), ); } ``` 5. Add the `disablePageviewAutocapture: true` option to the configuration. * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( disablePageviewAutocapture: true, ), ), ); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( disablePageviewAutocapture: true, ), ), ); } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Product Analytics data capture","description":"Access to acquisition analysis and lifetime metrics by implementing the Product Analytics data capture using the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/set-up-product-analytics-data-capture/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Third-party libraries license - Flutter description: Contentsquare Flutter SDK includes several third-party libraries, which are licensed under their own respective licenses lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/third-party-libraries-license/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/third-party-libraries-license/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Flutter SDK delegates to native Android and iOS SDKs; see their respective license pages below. *  ### [Android](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/third-party-libraries-license/) *  ### [iOS](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/third-party-libraries-license/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Third-party libraries license","description":"Contentsquare Flutter SDK includes several third-party libraries, which are licensed under their own respective licenses","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/third-party-libraries-license/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track custom variables - Flutter description: Track custom variables with the CSQ Flutter SDK lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-custom-variables/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-custom-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Custom variables attach additional information about the screen, user, or session to screenview events. For example, they can include information on the current layout of a screen, like day/night mode. ## Defining custom variables To define and send custom variables, follow this implementation: ```dart import 'package:contentsquare/csq.dart'; final customVar1 = CustomVar( index: 1, name: 'customName_1', value: 'customValue_1', ); final customVar2 = CustomVar( index: 2, name: 'customName_2', value: 'customValue_2', ); CSQ().trackScreenview( screenName: 'myAwesomeScreenName', customVars: [customVar1, customVar2], ); ``` Warning For consistent analytics, use the same index/name pair values across your application: **Screen A** ```dart import 'package:contentsquare/csq.dart'; const cVar4 = CustomVar( index: 4, key: 'hero_banner_type', value: 'carousel', ); CSQ().trackScreenview('ScreenA', [cVar4]); ``` **Screen B** ```dart import 'package:contentsquare/csq.dart'; const cVar4 = CustomVar( index: 4, key: 'hero_banner_type', value: 'slider', ); CSQ().trackScreenview('ScreenB', [cVar4]); ``` ## Limits ### On the server side * A maximum of 20 distinct custom variables per screenview can be stored. If more are received, only the first 20 custom variables, based on their `index` value, will be retained. * The `index` value of the custom variable determines which ones will be retained. Only index values from 1 to 20 (inclusive) will be considered. ### On the SDK side * Every custom variable is composed of `index`, `name` and `value`. * If the same `index` is used twice in the same screen, only the first (`name`, `value`) pair associated with the `index` will be kept. * A maximum of 20 custom variables can be stored on the same screenview. * If the maximum character length is reached for `name` (512 characters) or `value` (255 characters), the SDK will automatically truncate the additional characters automatically. * If `name` or `value` are empty, the SDK will instead send the literal string `"cs-empty"`. * Maintain a consistent index for a given custom variable throughout the application. For example, if the "screen layout" is collected with an `index` of 3, use the slot 3 for this information on every screen of the application. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track custom variables","description":"Track custom variables with the CSQ Flutter SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-custom-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track dynamic variables - Flutter description: Learn how to track and analyze variable metrics over time in your Flutter app using the CSQ SDK lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-dynamic-variables/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-dynamic-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Dynamic variables are additional information on the session that can be used to segment sessions. For example, they can include information on the A/B Test variations displayed to the current user. ## Defining dynamic variables To define and send a dynamic variable, you just need to use the following API. ```dart import 'package:contentsquare/csq.dart'; final userTypeVar = DynamicVar.fromString(key: 'accountType', value: 'Premium'); CSQ().addDynamicVar(userTypeVar); final friendCountVar = DynamicVar.fromInt(key: 'numberOfFriends', value: 15); CSQ().addDynamicVar(friendCountVar); ``` * For `int`, you will be able to do some algebra. Example: sessions with dynamic variable key = "numberOfFriends" and value >= 10 * For `String`, auto-completion and Regular Expression will be available. Example: sessions with dynamic variable key = "accountType" and value is "Premium" ## Sending a dynamic variable for each session You may want to send a dynamic variable for each session (like the user's country or store). While **triggering the dynamic variable at app launch will cover most cases, it will not be enough**. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See [Session definition](../data-collection/#session-definition) section for more information. That is why we also recommend **sending such dynamic variable every time the app enters foreground**. You can use [`didChangeAppLifecycleState` method ↗](https://api.flutter.dev/flutter/widgets/WidgetsBindingObserver/didChangeAppLifecycleState.html) to detect foreground and trigger a dynamic variable. ## Limits ### On the server side * It is possible to save up to 40 distinct dynamic variable keys per screen view. If more are received, only the first 40 keys will be kept. * If you are using the same key twice, the last value associated with the key will be collected. ### On the SDK side * Every dynamic variable is composed of a pair of key (max. 50 characters) and value (max. 255 characters string or number of type Long between 0 and 232 - 1). In case these maximums length are reached, the SDK will automatically trim the exceeding characters. * If key or value are empty, the SDK will instead send the literal string "cs-empty". ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track dynamic variables","description":"Learn how to track and analyze variable metrics over time in your Flutter app using the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-dynamic-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track Screens - Flutter description: Learn how to implement screen tracking in your Flutter app with CSQ SDK to capture user navigation patterns and screen interactions lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-screens/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-screens/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare aggregates user behavior and engagement at the screen level. To leverage our full range of features, you must implement effective screen tracking. You can set this up: * [Manually](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-screens/#track-screens-manually), by calling a dedicated API. * [Automatically](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-screens/#track-screens-automatically), by using our observer to track screens based on changes in the navigation stack. Warning Sessions without at least one screenview will be discarded. ## Track screens automatically Automatic screen view tracking can be done using the `CSQNavigatorObserver`. This will observe the navigation stack of the application and log screen events accordingly. This observer can be attached to any `WidgetApp` (like `MaterialApp`, `CupertinoApp`) or to a `RouterConfig` * MaterialApp ```dart import 'package:contentsquare/csq.dart'; MaterialApp( navigatorObservers: [ CSQNavigatorObserver(), ], ); ``` * Navigator ```dart import 'package:contentsquare/csq.dart'; Navigator( observers: [ CSQNavigatorObserver(), ], ); ``` * GoRouter ```dart import 'package:contentsquare/csq.dart'; final _goRouter = GoRouter( observers: [ CSQNavigatorObserver(), ], routes: [...], ); MaterialApp.router( routerConfig: _goRouter, ); ``` Tip You should use [Routes ↗](https://api.flutter.dev/flutter/widgets/Route-class.html) with proper [names ↗](https://api.flutter.dev/flutter/widgets/RouteSettings/name.html) assigned to them. This will be used as a fallback value for the automatic screen name capturing. The `CSQNavigatorObserver` can be configured with the following arguments: ### ExcludeRouteFromTracking An optional callback function that determines whether a specific route should be excluded from tracking. The function takes a `Route` as input and returns a `bool`. Use this function to selectively exclude certain routes from automatic tracking by returning true for those routes. ```dart import 'package:contentsquare/csq.dart'; CSQNavigatorObserver( excludeRouteFromTracking: (route) { // Exclude a specific route name if (route.settings.name == '/myRoute') return true; // Exclude popup routes (menus, popups, dialogs) if (route is PopupRoute) return true; // Exclude dialog routes (AlertDialog, showDialog) // Many dialogs inherit from PopupRoute, but this is extra safety: if (route.runtimeType.toString().contains('DialogRoute')) return true; // Exclude full-screen dialogs if (route is PageRoute && route.fullscreenDialog == true) return true; return false; }, ) ``` By default, all routes are tracked. Note `CSQNavigatorObserver` consider modal routes (like `showDialog`, `showModalBottomSheet`, etc.) and pop-ups (such as `showDialog`) as separate screens. If you don't want to track them as screens, you can use the `excludeRouteFromTracking` configuration option to exclude them. ### ScreenNameProvider An optional callback function used to customize the screen name for a given route. The function takes a `Route` as input and returns a `String` representing the desired screen name. Use this function to define custom screen names for specific routes. ```dart import 'package:contentsquare/csq.dart'; CSQNavigatorObserver( screenNameProvider: (route) { final screenName = _formatScreenName(route.settings.name); return screenName; }, ) ``` Tip If you use dart code obfuscation in your release builds, you should use the `screenNameProvider` to avoid obfuscated screen names being tracked. ### CustomVarsProvider An optional callback function used to provide a list of custom variables for a specific route. The function takes a `Route` as input and returns a `List<CustomVar>`. Use this function to attach custom variables to specific routes for tracking purposes. ```dart import 'package:contentsquare/csq.dart'; CSQNavigatorObserver( customVarsProvider: _customVarsForRouteProvider, ) List<CustomVar>? _customVarsForRouteProvider(Route<dynamic> route) { final routeName = route.settings.name; final productPageRegex = RegExp(r'/product/(\d)+'); if (routeName == null) { return []; } // Check for product detail routes if (productPageRegex.hasMatch(routeName)) { final productId = productPageRegex.firstMatch(routeName)?.group(1); if (productId != null) { return [ CustomVar(index: 1, name: 'productId', value: productId), ]; } } // Check for a specific screen if (routeName == '/profile') { return [ CustomVar(index: 2, name: 'screenType', value: 'profileScreen'), ]; } return null; } ``` ## Track screens manually Call the `trackScreenview(screenName: String)` API when a screen appears to track screens manually. When you call the API, the SDK logs a screenview event which identifies the new screen with the screen name you provided. ```dart import 'package:contentsquare/csq.dart'; await CSQ().trackScreenview(screenName: 'ScreenName'); ``` ### Back navigation handling Back navigation is not automatically tracked by the SDK. When back navigation occurs the `trackScreenview` method should be manually invoked with the screen name of the previous screen. #### Example with a custom navigation observer ```dart import 'package:contentsquare/csq.dart'; class CustomNavigationObserver extends NavigatorObserver { @override void didPop(Route route, Route? previousRoute) { ... final previousScreenName = // get the previous screen name CSQ().trackScreenview(screenName: previousScreenName); ... } } ``` ### Screen name handling The screen name length is not limited on the SDK side. However, it's important to there is a limit of 2083 characters on the server side. Ensure that screen names do not exceed this limit to prevent any issues with data transmission and processing. ### Handling Screen Views When App Returns from Background The Contentsquare SDK automatically triggers a screen view when the app is moved to the background and subsequently brought back to the foreground. This occurs provided that a screen view with a screen name has been triggered previously. In such cases, the SDK will use the last screen name that was set. ### Implementation recommendations From a functional standpoint, we expect a screenview to be sent: * When the screen becomes visible * When a screen is popped, returning the user to the previous screen * If you consider a modal or pop-up as screens, than when they become visible and when they are closed Achieving this can be facilitated through a [NavigatorObserver ↗](https://api.flutter.dev/flutter/widgets/NavigatorObserver-class.html). This observer can be used to listen to route changes and send screenviews accordingly. ### How to name screens As a general rule, aim to keep distinct screen names under 100 characters. Choose names that provide a comprehensive understanding of the screen's content or purpose. This will help you to identify the screen in the Contentsquare interface. Tip We advise against relying on the `runtimeType` of the class, as in the release version, the class name may be obfuscated, rendering the name meaningless. #### Separate words with space, dash, or underscore characters If you want to create screen names with multiple words, it's best to separate them using spaces, dashes, or underscores. Contentsquare will handle the formatting automatically. **Example:** For a sub-category list of a retail app, use `Home and Living - Home Furnishings` instead of ~~`homeLivingHomeFurnishings`~~. ### Screen name limitations Casing sensitivity Screen names are not case sensitive and will appear in lowercase on the Contentsquare platform. ```dart import 'package:contentsquare/csq.dart'; CSQ().trackScreenview(screenName: 'ScreenName') // screenname CSQ().trackScreenview(screenName: 'Screen Name') // screen name CSQ().trackScreenview(screenName: 'screen_name') // screen_name CSQ().trackScreenview(screenName: 'screenname') // screenname ``` #### Use screen template/layout names As a general guideline, opt for names that describe the screen template or layout rather than focusing on specific content (data). This approach will minimize the number of unique screen names, making Contentsquare easier to use and reducing the potential for Personal Data transmission. Examples of screen types falling into this category include Product Detail, Event Detail, Conversation/Chat, and User Profile. ### Screens with multiple states/layouts Screens can have different layouts or states depending on the user context. In this case, append its value to the screen name. **Home screen** | State | Screen name | | - | - | | App landing layout | `Home` | | Women products layout | `Home - Women` | | Men products layout | `Home - Men` | | Sales layout | `Home - Sales` | **Product Detail screen (PDP)** | State | Screen name | | - | - | | Users on a Top for Women PDP | `PDP - Clothing - Women - Tops` | | Users on a Microwave PDP | `PDP - Kitchenware - Electrics - Microwave` | | Users on a Hotel details screen | `PDP - Holiday type - Season - Board` | **User account screen** | State | Screen name | | - | - | | Overview | `My Account - Dashboard` | | Order history | `My Account - Order history` | | Returns | `My Account - Returns` | **Search screen** | State | Screen name | | - | - | | Search | `Search` | | Search results for "Skincare" products | `Search - Skincare` | | Search results error screen | `Search - Error` | **Cart screen** | State | Screen name | | - | - | | Empty cart | `Cart - Empty` | | Items have been added to the cart | `Cart - Populated` | | Issues with availability or pricing | `Cart - Error` | **Checkout screen** | State | Screen name | | - | - | | User provides name, surname, and date of birth | `Checkout - User Details` | | User provides shipping address | `Checkout - Shipping Details` | | User inputs their credit card information | `Checkout - Payment` | ## Troubleshooting ### AutoRoute package support If you're using the [AutoRoute package ↗](https://pub.dev/packages/auto_route), refer to the [CSQNavigatorAutoRouteObserver](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/auto_route_support/) documentation for automatic screen tracking support, including tab navigation. ### Pageview widget `PageView` widgets sometimes are used to build swipeable screens such as onboarding flows, multi-step forms, or carousels. However, because `PageView` navigation does not push new routes to the navigation stack, navigator observers are not triggered when pages change. To ensure correct tracking, each page transition must be tracked manually using the `onPageChanged` callback. For example, when using `PageView.builder`, you can track each page as an individual screen: ```dart import 'package:contentsquare/csq.dart'; class PageViewTrackingExample extends StatelessWidget { const PageViewTrackingExample({super.key}); final _controller = PageController(); // Define meaningful screen names for each page final _pageNames = const <String>[ 'onboarding_step_1', 'onboarding_step_2', 'onboarding_step_3', ]; @override Widget build(BuildContext context) { return PageView.builder( controller: _controller, itemCount: _pageNames.length, onPageChanged: (index) { // Track screen view manually for each page change CSQ().trackScreenview(screenName: _pageNames[index]); }, itemBuilder: (_, index) { return OnboardingPage(step: index); }, ); } } ``` ### PageBuilder If you use a `pageBuilder` in your routes, make sure to set the page `.name`. Example using `GoRoute`: ```dart import 'package:contentsquare/csq.dart'; GoRoute( path: 'checkout', name: 'Checkout Screen', pageBuilder: (context, state) => MaterialPage( name: 'Checkout Screen', key: ValueKey(state.pathParameters), fullscreenDialog: true, child: const CheckoutScreen(), ), ), ``` ### TabBar `TabBar` views are commonly tracked as individual screens. However, most `TabBar` implementations push the route to the navigation stack only during initialization, which can make it challenging to properly track navigation events for each tab change. To track tab changes correctly, you need to manually call `trackScreenview` when the active tab changes. Here's an example using `TabController`: ```dart import 'package:contentsquare/csq.dart'; class TabBarExample extends StatefulWidget { const TabBarExample({super.key}); @override State<TabBarExample> createState() => _TabBarExampleState(); } class _TabBarExampleState extends State<TabBarExample> with SingleTickerProviderStateMixin { late TabController _tabController; // Define meaningful screen names for each tab final _tabNames = const <String>[ 'home_tab', 'search_tab', 'profile_tab', ]; @override void initState() { super.initState(); _tabController = TabController(length: _tabNames.length, vsync: this); // Track initial tab CSQ().trackScreenview(screenName: _tabNames[_tabController.index]); // Listen to tab changes _tabController.addListener(() { if (!_tabController.indexIsChanging) { CSQ().trackScreenview(screenName: _tabNames[_tabController.index]); } }); } @override void dispose() { _tabController.dispose(); super.dispose(); } @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( bottom: TabBar( controller: _tabController, tabs: const [ Tab(icon: Icon(Icons.home), text: 'Home'), Tab(icon: Icon(Icons.search), text: 'Search'), Tab(icon: Icon(Icons.person), text: 'Profile'), ], ), ), body: TabBarView( controller: _tabController, children: const [ HomeTab(), SearchTab(), ProfileTab(), ], ), ); } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track Screens","description":"Learn how to implement screen tracking in your Flutter app with CSQ SDK to capture user navigation patterns and screen interactions","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-screens/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track WebViews - Flutter description: Track webviews with the CSQ Flutter SDK lastUpdated: 12 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-webviews/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-webviews/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. WebView tracking links the CSQ SDK to the JavaScript tag running inside the WebView. ## Usage To enable WebView tracking, few steps are required: 1. Inject the Contentsquare Tracking Tag in WebView mode in the web pages loaded in your app's WebViews. For more information on this step, refer to [📚 Mobile Apps WebView Tracking Documentation](https://docs.contentsquare.com/en/webview-tracking-tag/). 2. Make sure JavaScript is enabled in your WebViews. 3. Wrap your WebView widget with `CSQWebViewWrapper` widget and implement it as explained below. ## Implementation Warning Our implementation will work if and only if the WebView widget you are using in your app is relying on an underlying instance of `android.webkit.WebView` on Android and WebKit's `WKWebView` on iOS. The implementation can be done in two different ways depending on how your WebView allows the injection of scripts. These two different ways relies of two subtypes of `WebViewWrapperDelegate`: * `UserScriptWebViewWrapperDelegate` to inject the required Contentsquare script through User Scripts. Choose this if you use the `flutter_inappwebview` package. * `JSChannelWebViewWrapperDelegate` to inject the required Contentsquare script through JavaScript channel. Choose this if you use packages like `webview_flutter` or `flutter_webview_plugin`. ### Examples * Using UserScriptWebViewWrapperDelegate This example uses the [flutter\_inappwebview ↗](https://pub.dev/packages/flutter_inappwebview) `InAppWebView` widget. ```dart import 'package:contentsquare/csq.dart'; CSQWebViewWrapper( delegate: UserScriptWebViewWrapperDelegate( builder: (BuildContext context, String userScript) { return InAppWebView( initialOptions: InAppWebViewGroupOptions( crossPlatform: InAppWebViewOptions( javaScriptEnabled: true, ), ), initialUrlRequest: URLRequest( url: Uri.parse(url), ), initialUserScripts: UnmodifiableListView([ UserScript( // Inject the script properly // by setting the `userScript` as source source: userScript, // Set the injectionTime as AT_DOCUMENT_START injectionTime: UserScriptInjectionTime.AT_DOCUMENT_START, ), ]), ); }, ), ) ``` Note You should always set the property `injectionTime` of `UserScript` to `UserScriptInjectionTime.AT_DOCUMENT_START`. `UnmodifiableListView` is imported from `dart:collection`. * Using JSChannelWebViewWrapperDelegate This example uses the [webview\_flutter ↗](https://pub.dev/packages/webview_flutter) `WebViewWidget` widget. ```dart import 'package:contentsquare/csq.dart'; webViewController.setJavaScriptMode(JavaScriptMode.unrestricted); CSQWebViewWrapper( delegate: JSChannelWebViewWrapperDelegate( addJavaScriptChannel: (WebViewJSChannelHandler handler) { webViewController.addJavaScriptChannel( handler.channelName, onMessageReceived: (jsMessage) { handler.onMessageReceived(jsMessage.message); }, ); }, builder: (context) { return WebViewWidget(controller: webViewController); }, ), ); ``` Note You should always set the channel name to `handler.channelName` and call `handler.onMessageReceived(...)` in the JavaScript channel message callback. **Optional: detect the WebView context on dual-context pages** If the same page is served both in a regular browser and inside your app's WebView (dual-context tracking), the page usually selects which Contentsquare tag to load with an `isWebView()` guard. That guard must detect the WebView context **before** the page's tag script runs — otherwise the browser tag loads instead of the WebView tag (a tag "race condition") and native and web tracking are not linked. With `JSChannelWebViewWrapperDelegate` (for example when using `webview_flutter`), the SDK cannot inject a document-start script, so the reliable early signal is the user agent. Apply `handler.userAgent` to the controller **before** loading the URL: ```dart addJavaScriptChannel: (WebViewJSChannelHandler handler) { // Set the user agent before loading the page so the page // can detect the WebView context early. webViewController.setUserAgent(handler.userAgent); webViewController.addJavaScriptChannel( handler.channelName, onMessageReceived: (jsMessage) { handler.onMessageReceived(jsMessage.message); }, ); }, ``` Warning `WebViewController.setUserAgent(...)` **replaces the entire user agent** — it does not append to it. If your app relies on a custom user agent, applying `handler.userAgent` will overwrite it. In that case, either append the Contentsquare token to your own user agent (for example `setUserAgent('<your user agent> ${handler.userAgent}')`), or use `UserScriptWebViewWrapperDelegate` (for example with `flutter_inappwebview`), where the Contentsquare script that sets `window.CS_isWebView` is injected at document start, so no user agent change is needed. ## Validate WebView tracking To validate the tracking of WebViews, refer to the platform-specific instructions. * [📚 Android documentation](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-webviews/#validating-the-implementation-on-the-web-side) * [📚 iOS documentation](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-webviews/#on-the-web-side) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track WebViews","description":"Track webviews with the CSQ Flutter SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-webviews/","inLanguage":"en","dateModified":"2026-08-12T09:38:55+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track transactions - Flutter description: Track transactions with the CSQ Flutter SDK lastUpdated: 05 December 2025 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-transactions/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-transactions/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To associate a user's session with their potential purchases (and corresponding revenue), you must send the transaction via a dedicated API. ```dart import 'package:contentsquare/csq.dart'; final transaction = CustomerTransaction( price: 430.99, // required currency: Currency.EUR, // required transactionId: "order_12345", // optional ); CSQ().trackTransaction(transaction); ``` Warning **Each transaction must only be sent once**. A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track transactions","description":"Track transactions with the CSQ Flutter SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-transactions/","inLanguage":"en","dateModified":"2025-12-05T17:32:03+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Troubleshooting - Flutter description: Need help? We share probable causes and recommended fixes lastUpdated: 03 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/troubleshooting/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/troubleshooting/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. When the SDK is not sending data as expected, use this page to identify probable causes and apply recommended fixes. Start by upgrading To narrow down the root cause and eliminate potential issues, upgrade to the [latest version of the SDK](../). If your issue persists after the upgrade and using this section, contact us. ## Sessions are not tracked For sessions to be tracked: * [A first screenview has to be sent](../track-screens/) * [The current user has to opt-in to have their actions tracked](../privacy/#handling-user-consent) ## SDK is not working on my hybrid app The CSQ SDK [is not compatible](../compatibility/#compatibility-matrix) with hybrid applications. ## Cannot see in-app features on iOS See the [specific configuration](../in-app-features/#ios) to benefit from in-app features on iOS. ## I lost some zoning data after changing my widget tree The CSQ SDK uses zoning identifier that relies heavily on the structure of the widget tree. Changes to the widget tree such as moving, nesting, or removing a widget may result in the loss of tracking data. The CSQ Flutter SDK provides the [`ReliableTarget` widget](../reliable-targets/), designed to encapsulate the widget intended for reliable tracking. ## Transactions are sent multiple times A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ## Cannot see images and texts are incomprehensible in Session Replay By default, the `ContentsquareRoot` widget masks all types of content (texts, text fields, and images) during replays. It achieves this by providing a default `MaskingConfig` object if none is specified.\ The default configuration masks everything, ensuring that sensitive information is protected.\ However, you can override the default masking behavior by providing your own `MaskingConfig` object when creating a `ContentsquareRoot` widget. This allows you to customize the masking rules for your app according to your requirements. See [MaskingConfig](../session-replay/#handle-masking) for more information. ## Masking / Unmasking Session Replay using in-app features settings is not reflected in the player The masking / unmasking of Session Replay through the in-app features settings is not yet supported by the Flutter SDK. This setting is intended for debugging purposes only. See [MaskingConfig](../session-replay/#handle-masking) for more information. ## Session Replay is enabled but I see nothing when connecting to the URL Put your app in background to trigger the sending of the session to the server.\ Session Replay is not instantaneous and takes from 5 minutes to 30 minutes to be available. For Session Replay to work, sessions must be tracked: * [A first screenview has to be sent](../track-screens/) * [The current user has to opt-in to have their actions tracked](../privacy/#handling-user-consent) ## My replays not an exact rendering of my app There is no collection of the user's screen, but rather a reconstruction interactions based on the data collected by the SDK.\ The rendering may not be pixel-perfect, but it should give you a good idea of how users interact with your app. There are some [known limitations](../session-replay/#known-limitations) to the Session Replay feature. If you notice a limitation that is not referenced in our documentation, contact us. ## Session Replay requests are not sent from an Android emulator / iOS simulator If you struggle to watch a replay collected on an emulator/simulator, it may be due to some network constraints applied on your computer (VPN, company network restrictions, etc.). Check your configuration and/or use a real device. For more information about our endpoints and requests, see: * [Android - Requests are failing](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/troubleshooting/#requests-are-failing) * [iOS - Requests are failing](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/troubleshooting/#requests-are-failing) ## Replays are extremely long It is important to remember that **an app kill does not end a session**.\ See [Session definition](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/data-collection/#session-definition) for more information. If you leave the simulator/emulator running with the app in foreground, the session will not end, even if you are inactive. To better reflect actual end user behavior and avoid unusually long sessions (last hours), put the app in background or kill it. ## I use an HttpOverrides.global does not work During the initialization, the CSQ SDK overrides the `HttpOverrides.global` property. If you have to override `HttpOverrides.global` in your app - [use a custom HttpOverrides](../error-analysis/#use-a-custom-httpoverrides). ## SwiftContentsquarePlugin was registered twice There is a known issue with the [`background_locator` ↗](https://pub.dev/packages/background_locator) plugin which causes Contentsquare plugin to be registered twice. This issue has been mitigated and you can ignore this warning. If you are not using the `background_locator` plugin and encounter this warning, contact us. ## Requests are failing In order for Contentsquare to work, you need to make sure the following endpoints are not blocked by your network (VPN): | Request | Endpoint | Detail | | - | - | - | | Config file | `https://mobile-production.content-square.net` | See [Configuration](../data-collection/#configuration) | | Experience Analytics data (EU) | `https://m.csqtrk.net` `https://m.ba.contentsquare.net` `https://m.aa.contentsquare.net` | See [Sending data](../data-collection/#sending-data) | | Experience Analytics data (US) | `https://m-aus1.contentsquare.net` `https://m.bf.contentsquare.net` `https://m.af.contentsquare.net` | See [Sending data](../data-collection/#sending-data) | | Product Analytics data | `https://mh.bf.contentsquare.net` | See [Product Analytics](../../product-analytics/) | | Monitoring | `https://l.contentsquare.net` | Used by the SDK to send SDK monitoring analysis in JSON format over HTTPS. | | Session Replay data (EU) | `https://ka-aeu1.contentsquare.net` `https://ka.ba.contentsquare.net` `https://ka.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Session Replay data (US) | `https://ka-aus1.contentsquare.net` `https://ka.bf.contentsquare.net` `https://ka.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Screenshot (EU) | `https://s.contentsquare.net` `https://b.ba.contentsquare.net` `https://b.aa.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Screenshot (US) | `https://s-aus1.contentsquare.net` `https://b.bf.contentsquare.net` `https://b.af.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Resources manager (EU) | `https://srm.ba.contentsquare.net` `https://srm.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Resources manager (US) | `https://srm.bf.contentsquare.net` `https://srm.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | ## App with multiple `RenderView`s The CSQ SDK does not support the use of multiple `RenderViews` within the same application. Using multiple `RenderViews` may cause the SDK to behave incorrectly. ## Webview heatmap support The CSQ SDK does not support `Heatmap` for webviews. ### Long Screenshot: Large Capture Limitation **Symptom:** The Long Screenshot capture completes the creation process, but then fails at the very end without a clear error message. **Explanation:** Long Screenshots can produce a very large amount of data. For reliability and performance reasons, the server enforces a maximum payload size (\~75 MB). Very long or content-heavy screens may exceed this limit, causing the screenshot to be rejected. **Workaround:** Capture a shorter area (reduce the scroll length) and/or reduce the amount of on-screen content (for example fewer or lighter elements), then retry the Long Screenshot. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Troubleshooting","description":"Need help? We share probable causes and recommended fixes","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/troubleshooting/","inLanguage":"en","dateModified":"2026-07-03T12:11:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Upgrade your SDK - Flutter description: Understand the benefits of upgrading to the CSQ SDK lastUpdated: 12 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-your-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-your-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-flutter/experience-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This section guides you through the upgrade from your current SDK implementation to our latest CSQ SDK. Upgrading has no impact on your current data collection and does not alter the data observed on the platform. It mainly consists of searching and replacing APIs according to the mappings provided in the upgrade guides. Get started by selecting the upgrade guide that corresponds to your current implementation: * **[Contentsquare SDK](../upgrade-from-cs-sdk/)** - Upgrade from the legacy Contentsquare SDK * **[Heap SDK + Contentsquare SDK](../upgrade-from-heap-and-cs-sdk/)** - Upgrade from combined Heap and Contentsquare SDKs ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Upgrade your SDK","description":"Understand the benefits of upgrading to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-your-sdk/","inLanguage":"en","dateModified":"2026-05-12T12:05:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Contentsquare SDK to CSQ SDK - Flutter description: Migrate to the CSQ SDK lastUpdated: 29 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-flutter/experience-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide provides a step-by-step upgrade process from your current installation of Contentsquare Mobile SDK to the latest version of the CSQ SDK.  **Contentsquare SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. Migration script Contentsquare provides a migration path using a script that automates most of the common API replacements from your current project to CSQ SDK 4.0. Follow these steps: 1. Back up your project. 2. Download and save the [migration script](https://docs.contentsquare.com/csq_flutter_4.0.0_migration.dart) on your machine. 3. Open your terminal and navigate to the script directory: ```shell cd </path/to/directory/with/migration/script> ``` 4. Run the script with your Flutter project path as an argument: ```shell dart migration.dart <path_to_your_flutter_project> ``` 5. Once the script completes, you'll need to: **Review all generated comments** - The script adds comments (marked with `//`) where manual updates are required **Fix compilation errors** - Address any errors that the automated migration couldn't handle **Test your application thoroughly** - Verify that all functionality works as expected **Update custom implementations** - Review and update any custom code that may have been affected by the migration This script does is provided as-is and does not cover all pattens or edge cases including: * Custom wrapper implementations around legacy SDKs * Complex conditional logic using deprecated APIs * Dynamic method calls or reflection-based usage * Platform-specific custom implementations beyond standard patterns Support tickets regarding this migration path will not be considered. ## Dependency upgrades Increment the Contentsquare SDK in `pubspec.yaml` to the latest version. ```diff dependencies: contentsquare: ^3.19.1 contentsquare: ^4.0.0 ``` Sync your dependencies by running `flutter pub get`. ## Imports updates Replace the Contentsquare SDK import with a CSQ SDK import. ```diff import 'package:contentsquare/contentsquare.dart'; import 'package:contentsquare/csq.dart'; ``` Warning After updating the import, some APIs used in your development environment may show errors. The next steps in this guide will help you update them to the latest versions. ## SDK start 1. `Optional`: If you were using `ContentsquareRoot` widget - remove it from your widget tree. **main.dart** ```dart void main() { runApp(const MyApp()); } class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return ContentsquareRoot( child: MaterialApp( return MaterialApp( title: 'My Flutter App', home: Home(), ), ); } } ``` 2. Start the CSQ SDK manually. If you were using before manual start by calling `Contentsquare().start()`, replace it with `CSQ().start()`: **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await Contentsquare().start(); await CSQ().start(); } ``` If you were relying on `ContentsquareRoot`, you need from now on always start the SDK manually. Ideally the SDK should be started as soon as possible, for example from the `main()` function: ```dart import title="main.dart" 'package:contentsquare/csq.dart'; void main() async { await CSQ().start(); } ``` 3. (Optional) If you were relying on the Contentsquare SDK autostart, remove the `CSDisableAutostart` property and calls to `Contentsquare.start()`. **Info.plist** ```xml <key>CSDisableAutostart</key> <true/> ``` **AppDelegate.swift** ```swift Contentsquare.start() ``` 4. (Optional) If you have chosen to deactivate the autostart of the Contentsquare SDK, you can now remove the entry in the manifest, as the CSQ SDK doesn't have an autostart. **AndroidManifest.xml** ```xml <application> ... <meta-data android:name="com.contentsquare.android.autostart" android:value="false" /> ... </application> ``` ## Get user consent Implement the [`optIn()`](../command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. The CSQ SDK treats users as opted-out by default. It can be done immediately after `start` is called: **main.dart** ```dart void main() async { // ... await CSQ().start(); await CSQ().optIn(); // ... } ``` Alternatively, you can call `optIn()` in response to a user action, such as tapping an "I agree" button: ```dart class UserConsentScreen extends StatelessWidget { @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: Text('User Consent'), ), body: Center( child: ElevatedButton( onPressed: () async { await CSQ().optIn(); }, child: Text('Agree with Terms and Conditions'), ), ), ); } } ``` ## Number of sessions Session timeout definition changed: * **Before**: 30 minutes after app goes to background * **Now**: 30 minutes after last event This may affect session counts and aligns with web and market standards. ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. In most cases, this process consists in updating the namespace and method names, with no changes to parameters. ```diff Contentsquare().start() CSQ().start() ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### GDPR / Identification | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare().optIn()` | `CSQ().optIn()` | | `Contentsquare().optOut()` | `CSQ().optOut()` | | `Contentsquare().sendUserIdentifier()` | `CSQ().sendUserIdentifier()` | | `Contentsquare().getUserId()` | `CSQ().metadata.userID` | Removed **Contentsquare().forgetMe()** You can use `CSQ().optOut()` instead to forget user id and stop tracking. If needed call `CSQ().optIn()` when you want to resume tracking. ### Property tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare().sendDynamicVar(key: String, intValue: int)`. | `CSQ().addDynamicVar(DynamicVar.fromIn(key: String, value: int))` | | `Contentsquare().sendDynamicVar(key: String, stringValue: String)`. | `CSQ().addDynamicVar(DynamicVar.fromString(key: String, value: String))` | ### CSInApp (iOS only) | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.handle(url: URL)` | `CSQ.handle(url: URL)` | | `Contentsquare.csInApp` | `CSQ.csInApp` | ### Interoperability | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare().onSessionReplayLinkChange(callback)` | `CSQ().metadata.onChange(Metadata)` | | `Contentsquare().currentSessionReplayUrl` | `CSQ().metadata.onChange(Metadata)` | | `Contentsquare().setURLMaskingPatterns()` | `CSQ().setURLMaskingPatterns()` | | `ContentsquareNavigatorObserver()`. | `CSQNavigatorObserver()` | | `ContentsquareWebViewWrapper()`. | `CSQWebViewWrapper()` | ### Event tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.sendTransaction(double, String, String, String?)` | `CSQ.trackTransaction(Transaction(price: double, currency: Currency, id: String))` | | `Contentsquare.send(String)` | `CSQ.trackScreenview(screenName: String)` | | `Contentsquare.send(String, List<CustomVar>?)` | `CSQ.trackScreenview(screenName: String, customVars: List<CustomVar>)` | ### Error tracking | Contentsquare SDK | CSQ SDK | | - | - | | `ContentsquareHttpOverrides()` | `CSQHttpOverrides()` | | `Contentsquare().collectFlutterError(details: FlutterErrorDetails, presentErrorDetails: bool)` | `CSQ().collectFlutterError(details: FlutterErrorDetails, presentErrorDetails: bool)`. | | `Contentsquare().collectError(error: Object, stackTrace: StackTrace)` | `CSQ().collectError(error: Object, stackTrace: StackTrace)` | ### Personal Data Handling and Masking | Contentsquare SDK | CSQ SDK | | - | - | | `MaskingConfig()` | `CSQMaskingConfig()` | | `SessionReplayMaskingScope` | `CSQMask` | ### SDK initialization and manipulation | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare().start()` | `CSQ().start()` | | `Contentsquare().stopTracking()` | `CSQ().pauseTracking()` | | `Contentsquare().resumeTracking()` | `CSQ().resumeTracking()` | | `Contentsquare().triggerReplayForCurrentSession(name: String)` | `CSQ().triggerReplayForCurrentSession(name: String)` | | `Contentsquare().triggerReplayForCurrentScreen(name: String)` | `CSQ().triggerReplayForCurrentScreen(name: String)` | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Contentsquare SDK to CSQ SDK","description":"Migrate to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/","inLanguage":"en","dateModified":"2026-06-29T13:09:27+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Core SDK + Contentsquare SDK to CSQ SDK - Flutter description: Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-heap-and-cs-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-heap-and-cs-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-flutter/experience-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide walks you through migrating from the Heap Core SDK and Contentsquare SDK to the CSQ SDK. This guide provides a step-by-step upgrade process from your current installation of Contentsquare and Heap Mobile to the latest version of the CSQ SDK.  **Heap Core SDK** \+  **Contentsquare SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. Migration script Contentsquare provides a migration path using a script that automates most of the common API replacements from your current project to CSQ SDK 4.0. Follow these steps: 1. Back up your project. 2. Download and save the [migration script](https://docs.contentsquare.com/csq_flutter_4.0.0_migration.dart) on your machine. 3. Open your terminal and navigate to the script directory: ```shell cd </path/to/directory/with/migration/script> ``` 4. Run the script with your Flutter project path as an argument: ```shell dart migration.dart <path_to_your_flutter_project> ``` 5. Once the script completes, you'll need to: **Review all generated comments** - The script adds comments (marked with `//`) where manual updates are required **Fix compilation errors** - Address any errors that the automated migration couldn't handle **Test your application thoroughly** - Verify that all functionality works as expected **Update custom implementations** - Review and update any custom code that may have been affected by the migration This script does is provided as-is and does not cover all pattens or edge cases including: * Custom wrapper implementations around legacy SDKs * Complex conditional logic using deprecated APIs * Dynamic method calls or reflection-based usage * Platform-specific custom implementations beyond standard patterns Support tickets regarding this migration path will not be considered. ## Dependency upgrades Increment the Contentsquare SDK in `pubspec.yaml` to the latest version. ```diff dependencies: heap_flutter_bridge: ^0.4.0 heap_flutter_autocapture: ^0.6.0 contentsquare: ^3.19.1 contentsquare: ^4.0.0 ``` Sync your dependencies by running `flutter pub get`. Replace the Contentsquare SDK import with a CSQ SDK import. ```diff import 'package:heap_flutter_bridge/heap_flutter_bridge.dart'; import 'package:heap_flutter_autocapture/heap_flutter_autocapture.dart'; import 'package:contentsquare/contentsquare.dart'; import 'package:contentsquare/csq.dart'; ``` Warning After updating the import, some APIs used in your development environment may show errors. The next steps in this guide will help you update them to the latest versions. ## SDK start 1. `Optional`: If you were using `ContentsquareRoot` widget - remove it from your widget tree. **main.dart** ```dart void main() { runApp(const MyApp()); } class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return ContentsquareRoot( child: MaterialApp( return MaterialApp( title: 'My Flutter App', home: Home() ), ); } } ``` 2. Delete `Heap().startRecording()` and migrate options to `CSQ().start()`. * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await Heap().startRecording('YOUR_ENVIRONMENT_ID', { // ...options }); await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( // ...options ), ), ); await Contentsquare().start(); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await Heap().startRecording('YOUR_ENVIRONMENT_ID', { // ...options }); await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( // ...options ), ), ); await Contentsquare().start(); } ``` 3. Remove `HeapAutocapture` registration: ```dart await HeapAutocapture.register(); ``` 4. Update pageview autocapture setup **main.dart** ```dart import 'package:contentsquare/csq.dart'; await HeapAutocapture.register(); MaterialApp( navigatorObservers: [ HeapNavigatorObserver(), CSQNavigatorObserver(), ], home: MyHomePage(), ) ``` 5. Recommended To enable automatic capture of user interactions, add the option `enableInteractionsAutocapture: true` to your `AnalyticsOptions` configuration: * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( enableInteractionsAutocapture: true, ), ), ); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( enableInteractionsAutocapture: true, ), ), ); } ``` 6. (Optional) If you were relying on the Contentsquare SDK autostart, remove the `CSDisableAutostart` property and calls to `Contentsquare.start()`. **Info.plist** ```xml <key>CSDisableAutostart</key> <true/> ``` **AppDelegate.swift** ```swift Contentsquare.start() ``` 7. (Optional) If you have chosen to deactivate the autostart of the Contentsquare SDK, you can now remove the entry in the manifest, as the CSQ SDK doesn't have an autostart. **AndroidManifest.xml** ```xml <application> ... <meta-data android:name="com.contentsquare.android.autostart" android:value="false" /> ... </application> ``` 8. Remove Heap Android dependencies **android/app/build.gradle** ```kotlin dependencies { implementation("io.heap.core:heap-android-core:+") implementation("io.heap.contentsquare.csbridge:contentsquare-bridge:+") } ``` 9. Remove Heap iOS dependencies: CocoaPods support is ending CocoaPods trunk becomes read-only on December 2, 2026. After this date, Contentsquare will no longer publish new SDK versions via CocoaPods. [Migrate to Swift Package Manager (SPM)](https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/) to continue receiving updates. 1. In Xcode, navigate to your project settings. 2. Select your app target, then go to the **Frameworks, Libraries, and Embedded Content** section. 3. Find `HeapContentsquareIntegrationSDK` in the list and click the **-** button to remove it. 4. Go to **File → Packages → Resolve Package Versions** to update your package dependencies. 10. Remove Initializing Integration: * Kotlin ```kotlin HeapContentsquareIntegration.bind( applicationContext, sendHeapPageviewsToContentsquare = false, sendContentsquareScreenviewsToHeap = true ) ``` * Swift ```swift HeapContentsquareIntegration.bind( sendHeapPageviewsToContentsquare: false, sendContentsquareScreenviewsToHeap: true ) ``` ## Get user consent Implement the [`optIn()`](../command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. The CSQ SDK treats users as opted-out by default. It can be done immediately after `start` is called: **main.dart** ```dart void main() async { // ... await CSQ().start(); await CSQ().optIn(); // ... } ``` Alternatively, you can call `optIn()` in response to a user action, such as tapping an "I agree" button: ```dart class UserConsentScreen extends StatelessWidget { @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: Text('User Consent'), ), body: Center( child: ElevatedButton( onPressed: () async { await CSQ().optIn(); }, child: Text('Agree with Terms and Conditions'), ), ), ); } } ``` ## Number of sessions Session timeout definition changed: * **Before**: 30 minutes after app goes to background * **Now**: 30 minutes after last event This may affect session counts and aligns with web and market standards. ## 4.2.0 breaking changes Breaking changes in 4.2.0 The following `AnalyticsOptions` options were removed in version 4.2.0. Remove them from your `CSQ().start()` call if present: * `disableScreenviewForwardToDXA` * `disableScreenviewForwardToPA` * `resumePreviousSession` * `uploadInterval` * `captureVendorId` * `captureAdvertiserId` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `pruningLookBackWindow` * `maximumDatabaseSize` * `maximumBatchCountPerUpload` ## Update API Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. In most cases, this process consists in updating the namespace and method names, with no changes to parameters. ```diff Contentsquare().start() CSQ().start() ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### Update Contentsquare SDK APIs ### GDPR / Identification | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare().optIn()` | `CSQ().optIn()` | | `Contentsquare().optOut()` | `CSQ().optOut()` | | `Contentsquare().sendUserIdentifier()` | `CSQ().sendUserIdentifier()` | | `Contentsquare().getUserId()` | `CSQ().metadata.userID` | Removed **Contentsquare().forgetMe()** You can use `CSQ().optOut()` instead to forget user id and stop tracking. If needed call `CSQ().optIn()` when you want to resume tracking. ### Property tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare().sendDynamicVar(key: String, intValue: int)`. | `CSQ().addDynamicVar(DynamicVar.fromIn(key: String, value: int))` | | `Contentsquare().sendDynamicVar(key: String, stringValue: String)`. | `CSQ().addDynamicVar(DynamicVar.fromString(key: String, value: String))` | ### CSInApp (iOS only) | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.handle(url: URL)` | `CSQ.handle(url: URL)` | | `Contentsquare.csInApp` | `CSQ.csInApp` | ### Interoperability | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare().onSessionReplayLinkChange(callback)` | `CSQ().metadata.onChange(Metadata)` | | `Contentsquare().currentSessionReplayUrl` | `CSQ().metadata.onChange(Metadata)` | | `Contentsquare().setURLMaskingPatterns()` | `CSQ().setURLMaskingPatterns()` | | `ContentsquareNavigatorObserver()`. | `CSQNavigatorObserver()` | | `ContentsquareWebViewWrapper()`. | `CSQWebViewWrapper()` | ### Event tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.sendTransaction(double, String, String, String?)` | `CSQ.trackTransaction(Transaction(price: double, currency: Currency, id: String))` | | `Contentsquare.send(String)` | `CSQ.trackScreenview(screenName: String)` | | `Contentsquare.send(String, List<CustomVar>?)` | `CSQ.trackScreenview(screenName: String, customVars: List<CustomVar>)` | ### Error tracking | Contentsquare SDK | CSQ SDK | | - | - | | `ContentsquareHttpOverrides()` | `CSQHttpOverrides()` | | `Contentsquare().collectFlutterError(details: FlutterErrorDetails, presentErrorDetails: bool)` | `CSQ().collectFlutterError(details: FlutterErrorDetails, presentErrorDetails: bool)`. | | `Contentsquare().collectError(error: Object, stackTrace: StackTrace)` | `CSQ().collectError(error: Object, stackTrace: StackTrace)` | ### Personal Data Handling and Masking | Contentsquare SDK | CSQ SDK | | - | - | | `MaskingConfig()` | `CSQMaskingConfig()` | | `SessionReplayMaskingScope` | `CSQMask` | ### SDK initialization and manipulation | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare().start()` | `CSQ().start()` | | `Contentsquare().stopTracking()` | `CSQ().pauseTracking()` | | `Contentsquare().resumeTracking()` | `CSQ().resumeTracking()` | | `Contentsquare().triggerReplayForCurrentSession(name: String)` | `CSQ().triggerReplayForCurrentSession(name: String)` | | `Contentsquare().triggerReplayForCurrentScreen(name: String)` | `CSQ().triggerReplayForCurrentScreen(name: String)` | ### Update Heap Core SDK APIs ### GDPR / Identification | Heap SDK | CSQ SDK | | - | - | | `Heap().identify(string)` | `CSQ().identify(userIdentifier: String)` | | `Heap().resetIdentity()` | `CSQ().resetIdentity()` | | `Heap().getUserId()` | `CSQ().metadata.userId` | | `Heap().getSessionId()` | `CSQ().metadata.sessionId` | | `Heap().getEnvironmentId()` | `CSQ().metadata.environmentId` | | `Heap().getIdentity()` | `CSQ().metadata.identity` | ### Logging | Heap SDK | CSQ SDK | | - | - | | `Heap().setLogLevel(LogLevel)` | `CSQ().debug.logLevel { get set }` | ### Property tracking | Heap SDK | CSQ SDK | | - | - | | `Heap().addUserProperties(Map<String, dynamic>)` | `CSQ().addUserProperties(properties: Map<String, dynamic>)` | | `Heap().addEventProperties(Map<String, dynamic>)` | `CSQ().addEventProperties(properties: Map<String, dynamic>)` | | `Heap().removeEventProperty(name: String)` | `CSQ().removeEventProperty(name: String)` | | `Heap().clearEventProperties()` | `CSQ().clearEventProperties()` | ### Event tracking | Heap SDK | CSQ SDK | | - | - | | `Heap().track(String, [Map<String, dynamic>])` | `CSQ().trackEvent(eventName: String, properties: Map<String, dynamic>?)` | ### Personal Data Handling and Masking | Heap SDK | CSQ SDK | | - | - | | `HeapRedact(redact: bool)` | `CSQMask(config: CSQMaskingConfig(maskTexts: true))` | | `HeapIgnore(ignore: bool)` | `CSQMask(config: CSQMaskingConfig(maskInteractions: true))` | ### SDK initialization and manipulation | Heap SDK | CSQ SDK | | - | - | | `Heap().startRecording(id, options)` | `CSQ().start(startConfig: StartConfig.withEnvironmentId(id: String, options: AnalyticsOptions))` | | `Heap().stopRecording(deleteUser = true)` | `CSQ().stop()` | | `Heap().stopRecording(deleteUser = false)` | `CSQ().pauseTracking()` | Deprecated **CSQ().configureProductAnalytics()** Deprecated in 4.2.0. Use `CSQ().start(startConfig: StartConfig.withEnvironmentId(...))` instead. Will be removed in August 2026. See [`CSQ().configureProductAnalytics()`](../command-reference/#csqconfigureproductanalytics) in the command reference. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK + Contentsquare SDK to CSQ SDK","description":"Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-heap-and-cs-sdk/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Agent skills for Flutter - Flutter description: Use AI coding assistants to integrate, upgrade, and configure the Contentsquare Flutter SDK with downloadable Agent skills lastUpdated: 16 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/using-agent-skills/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/using-agent-skills/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use the Contentsquare wizard or skills to set up, update, and configure Flutter with your AI coding assistant. Disclaimer This skill guides your AI coding agent through the SDK installation and implementation. The agent you use (Cursor, Claude Code, Copilot) is your own tool and operates under your settings and permissions. Contentsquare is not responsible for how your agent interprets or applies the instructions contained in these files. ## Contentsquare wizard Run the wizard in your project directory. It configures your AI coding assistant, installs the matching Contentsquare integration, and verifies the installation. ```shell npx @contentsquare/wizard install ``` Supports GitHub Copilot, Cursor, and Claude Code. Requires Node.js ≥ 18 and an AI coding agent with MCP support. ## Manual setup Use this path when you prefer to configure your AI coding assistant yourself. ### 1. Add the Contentsquare skill Choose how to install the Contentsquare skill. * Copilot CLI Add the Contentsquare marketplace, then install the plugin for Flutter: ```shell copilot plugin marketplace add ContentSquare/agents copilot plugin install contentsquare-flutter@contentsquare ``` * Claude Code Add the Contentsquare marketplace, then install the plugin for Flutter: ```shell /plugin marketplace add ContentSquare/agents /plugin install contentsquare-flutter@contentsquare ``` * Cursor Install **contentsquare** from the [Cursor marketplace ↗](https://cursor.com/marketplace), or add the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents) directly. Cursor reads the `.cursor-plugin` catalog in the repository. * Other agents Install the Contentsquare skill pack with the open `skills.sh` ecosystem: ```shell npx skills add contentsquare/agents ``` * From source Download or clone the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents), then copy `skills/contentsquare-flutter-sdk` into the location your AI coding assistant scans for skills: | AI coding assistant | Skill location | | - | - | | GitHub Copilot | `.github/skills/` or `.agents/skills/` | | Cursor | `.cursor/rules/` or the project root | | Claude Code | `.claude/skills/` or the project root | | Other compatible agents | `.agents/skills/` | ### 2. Ask your AI coding assistant After installing the skill, paste this prompt into your AI coding assistant: ```text Install Contentsquare for Flutter. ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Agent skills for Flutter","description":"Use AI coding assistants to integrate, upgrade, and configure the Contentsquare Flutter SDK with downloadable Agent skills","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/using-agent-skills/","inLanguage":"en","dateModified":"2026-07-16T17:50:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - Flutter description: The Contentsquare Flutter SDK changelog lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/changelog/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. 📬 Stay updated! ## Opt-in to CSQ Experience Platform Already using the CSQ SDK in standalone mode? Follow these steps to switch to CSQ Experience Platform and combine Experience Analytics and Product Analytics under a single data source. CSQ Experience Platform is currently an Early Access program. To gain access, contact your Customer Success Manager. CSQ Experience Platform guidance Throughout the documentation, code samples highlight differences between standalone and CSQ Experience Platform integrations.  1. [Update the SDK package to 4.2.0 or later](../#install-the-sdk). 2. Replace your current `CSQ().start(startConfig: StartConfig.withEnvironmentId(...))` call with the `dataSourceId` provided by your Customer Success Manager. This links your app to the CSQ Experience Platform data source. ```dart await CSQ().start(startConfig: StartConfig.withDatasourceId(id: "YOUR_DATASOURCE_ID")); ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 3. Review changes [introduced in 4.2.0](#420---20260508) which notably removes support for several Product Analytics options. ## 4.4.4 - 2026.08.12 * **Improvements:** * Improved zoning analysis and autocapture interaction performance. ## 4.4.3 - 2026.08.6 * **Improvements:** * Improved zoning analysis and autocapture interaction performance. ## 4.4.2 - 2026.07.21 * **Native SDKs:** * iOS: 1.11.0 → 1.11.1 * Re-signed the release artefacts with a new valid certificate to resolve a code-signing validation failure (`CSSMERR_TP_CERT_REVOKED`). No functional changes. ## 4.4.1 - 2026.07.07 * **Bug fix:** * Fixed an error in interaction `autocapture` while keeping events captured correctly. * Improved interaction `autocapture` performance during scroll interactions. * Improved zoning and heatmap stability. ## 4.4.0 - 2026.06.30 * **Added:** * Swift Package Manager (SPM) support for iOS. * **Improvements:** * Session Replay: improved capture of small, frequently-updating custom paint animations. * Extended Flutter version support to include 3.44.4. ## 4.3.1 - 2026.06.25 * **Bug fix:** * Fixed WebView tracking silently failing in apps with multiple Flutter engines. * Fixed WebView tracking not working on iOS scene-based apps. ## 4.3.0 - 2026.06.11 * **Bug fix:** * Fixed Long Snapshot for views containing WebViews on Android. * **Native SDKs:** * Android: 1.10.1 → 1.11.0 * iOS: 1.10.0 → 1.11.0 ## 4.2.2 - 2026.06.05 * **Bug fix** * Repackage obfuscated Android classes to avoid R8 `a.*` collisions with other AARs. ## 4.2.1 - 2026.05.19 * **Bug fix** * Event tracking: event property serialization on iOS was fixed. ## 4.2.0 - 2026.05.08 Experience Analytics The Session timeout definition changes from "30 minutes after being in background" to **30 minutes after last event**. See [Session definition](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/data-collection/#session-definition). Product Analytics ### Configuration **Deprecated:** `CSQ().configureProductAnalytics()` still exists, but is now deprecated in favor of `CSQ().start()` which combines SDK configuration and initialization in a single call: * Product Analytics **main.dart** ```dart await CSQ().configureProductAnalytics( environmentId: 'YOUR_ENVIRONMENT_ID', ); await CSQ().start(); await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', ), ); ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart await CSQ().configureProductAnalytics( environmentId: 'YOUR_ENVIRONMENT_ID', ); await CSQ().start(); await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', ), ); ``` ### Options **Added:** `AnalyticsOptions.sessionReplayAutoStart` — set to `false` to disable automatic Session Replay start and control it manually using `CSQ().startSessionReplay()` and `CSQ().stopSessionReplay()`. Defaults to `true`. ```dart await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: const AnalyticsOptions(sessionReplayAutoStart: false), ), ); ``` **Removed - Breaking:** `disableScreenviewForwardToDXA`, `disableScreenviewForwardToPA`, `resumePreviousSession`, `uploadInterval`, `captureVendorId`, `captureAdvertiserId`, `clearEventPropertiesOnNewUser`, `messageBatchMessageLimit`, `pruningLookBackWindow`, `maximumDatabaseSize`, and `maximumBatchCountPerUpload` options have been removed. Remove them from your `CSQ().start()` call if present: ```dart await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: const AnalyticsOptions( captureVendorId: true, captureAdvertiserId: true, clearEventPropertiesOnNewUser: true, messageBatchMessageLimit: 100, resumePreviousSession: true, pruningLookBackWindow: 6, maximumDatabaseSize: 10000000, maximumBatchCountPerUpload: 5, disableScreenviewForwardToDXA: true, disableScreenviewForwardToPA: true, ), ), ); ``` * **Native SDKs:** * Android: 1.5.0 → 1.10.1 * iOS: 1.6.0 → 1.10.0 ## 4.1.3 - 2026.04.27 * **Improvements:** * Session Replay fidelity was improved ## 4.1.2 - 2026.04.24 * **Improvements:** * Session Replay fidelity was improved * Multithread issues were fixed * Dialogs tracking was improved ## 4.1.1 - 2026.03.19 * **Improvements:** * Extend Flutter version support to include 3.27.0 and later (previously 3.27.4+). ## 4.1.0 - 2026.02.27 * **Analytics:** * Introduce the Long Screenshot feature to capture and analyze long screens in the app, such as product listing pages or user profiles. * **Native SDKs:** * Android: 4.43.8 → 4.44.0 * iOS: 4.45.3 → 4.46.0 * **🚨 Minimum Flutter version** * Contentsquare plugin now requires Flutter SDK `3.27.4` or later ## 4.0.3 - 2026.02.03 * **Native SDKs:** * Android: 1.4.2 → 1.4.7 ## 4.0.2 - 2026.01.29 * **Bug fix** * Session Replay: Fixed an issue that could cause `BackdropFilter` widgets to appear mispositioned in replays. * Interactions Autocapture: Improved performance when capturing interactions on complex widget trees. ## 4.0.1 - 2025.12.11 * **Bug fix** * SessionReplay: Fixed an issue that could cause white screens to appear on iOS. ## 4.0.0 - 2025.12.05 Initial release of the CSQ SDK. * Introduces the unified CSQ API, which combines `Product Analytics`, `Experience Analytics`, and `Monitoring` features into a single, cohesive library. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare Flutter SDK changelog","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/changelog/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: AutoRoute support - Flutter description: How to use the CSQNavigatorAutoRouteObserver with AutoRoute package lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/auto_route_support/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/auto_route_support/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To support automatic screen tracking when using the [AutoRoute package ↗](https://pub.dev/packages/auto_route), we provide the `CSQNavigatorAutoRouteObserver`. This observer extends the standard `CSQNavigatorObserver` to add compatibility with AutoRoute's navigation system, including support for tab navigation. Warning If you are using `AutoRoute`, use `CSQNavigatorAutoRouteObserver` instead the standard `CSQNavigatorObserver` for better compatibility and support for tab navigation. ## Installation Add `csq_navigator_auto_route_observer` as a **dev dependency**. ```shell flutter pub add -d csq_navigator_auto_route_observer ``` **pubspec.yaml** ```yaml dev_dependencies: csq_navigator_auto_route_observer: ^1.0.0 ``` ## Usage Once the package has been added, you'll need to add the `CSQNavigatorAutoRouteObserver` to the root navigator in your app. **main.dart** ```dart import 'package:csq_navigator_auto_route_observer/csq_navigator_auto_route_observer.dart'; return MaterialApp.router( routerConfig: _appRouter.config( navigatorObservers: () => [ CSQNavigatorAutoRouteObserver(), ], ), ); ``` Tip You should use [Routes ↗](https://api.flutter.dev/flutter/widgets/Route-class.html) with proper [names ↗](https://api.flutter.dev/flutter/widgets/RouteSettings/name.html) assigned to them. This will be used as a fallback value for the automatic screen name capturing. The `CSQNavigatorAutoRouteObserver` can be configured with the following arguments: * [ExcludeRouteFromTracking](#excluderoutefromtracking) * [ScreenNameProvider](#screennameprovider) ### ExcludeRouteFromTracking An optional callback function that determines whether a specific route should be excluded from tracking. The function takes a `Route` as input and returns a `bool`. Use this function to selectively exclude certain routes from automatic tracking by returning true for those routes. ```dart import 'package:contentsquare/csq.dart'; CSQNavigatorAutoRouteObserver( excludeRouteFromTracking: (route) { // Exclude a specific route name if (route.settings.name == '/myRoute') return true; // Exclude popup routes (menus, popups, dialogs) if (route is PopupRoute) return true; // Exclude dialog routes (AlertDialog, showDialog) // Many dialogs inherit from PopupRoute, but this is extra safety: if (route.runtimeType.toString().contains('DialogRoute')) return true; // Exclude full-screen dialogs if (route is PageRoute && route.fullscreenDialog == true) return true; return false; }, ) ``` By default, all routes are tracked. Note `CSQNavigatorAutoRouteObserver` consider modal routes (like `showDialog`, `showModalBottomSheet`, etc.) and pop-ups (such as `showDialog`) as separate screens. If you don't want to track them as screens, you can use the `excludeRouteFromTracking` configuration option to exclude them. ### ScreenNameProvider An optional callback function used to customize the screen name for a given route. The function takes a `Route` as input and returns a `String` representing the desired screen name. Use this function to define custom screen names for specific routes. ```dart import 'package:contentsquare/csq.dart'; CSQNavigatorAutoRouteObserver( screenNameProvider: (route) { final screenName = _formatScreenName(route.settings.name); return screenName; }, ) ``` Tip If you use dart code obfuscation in your release builds, you should use the `screenNameProvider` to avoid obfuscated screen names being tracked. ## Compatibility This package requires: * **AutoRoute**: Version 9.0.0 or later * **CSQ SDK**: Compatible with the latest CSQ SDK for Flutter Make sure your project meets these version requirements before integrating the `csq_navigator_auto_route_observer` package. ## Changelog ### 1.1.0 - 2026.03.20 * Add support for AutoRoute versions 10.x and 11.x (`>=10.1.0+1 <12.0.0`) ### 1.0.0 - 2025.12.09 * Initial release ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"AutoRoute support","description":"How to use the CSQNavigatorAutoRouteObserver with AutoRoute package","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/auto_route_support/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- 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/product-analytics/command-reference/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-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://mh.ba.contentsquare.net'), // EU; https://mh.bf.contentsquare.net (default) 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` The CSQ API endpoint to use: * `https://mh.ba.contentsquare.net` — EU-hosted environments * `https://mh.bf.contentsquare.net` — all other environments (default) ### `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()`. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"SDK API reference","description":"SDK commands reference including signature, parameter descriptions, and examples","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/command-reference/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - Flutter description: Requirements and limitations to develop with the Contentsquare Flutter SDK lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/compatibility/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Before implementing the SDK, make sure your app meets the following technical prerequisites to avoid integration issues and ensure optimal performance. ## Supported platforms Only Flutter application on the following platforms are supported by the CSQ Flutter SDK: * Android * iOS Calling the SDK on other platforms is safe but will not have any effect. If you need to use the SDK on another platform, contact our support team. Note Hybrid applications are not supported. By hybrid application, we mean iOS and Android apps that integrate Flutter as an [add-to-app module ↗](https://docs.flutter.dev/add-to-app). ## Compatibility matrix Each version of the CSQ Flutter SDK will be linked to specific, fixed versions of each native SDK. To make that clear, here is a compatibility table to consider when choosing your version of the bridge (refer to the Flutter SDK Changelog to know what the changes are for each version). Note If the Maximum Flutter Version is not specified, it means that the bridge is compatible with all versions of Flutter up to the latest one. | CSQ Flutter | CSQ iOS | CSQ Android | Minimum Flutter Version | Maximum Flutter Version | | - | - | - | - | - | | 4.4.4 | 1.11.1 | 1.11.0 | 3.27.0 | - | | 4.4.3 | 1.11.1 | 1.11.0 | 3.27.0 | - | | 4.4.2 | 1.11.1 | 1.11.0 | 3.27.0 | - | | 4.4.1 | 1.11.0 | 1.11.0 | 3.27.0 | - | | 4.4.0 | 1.11.0 | 1.11.0 | 3.27.0 | - | | 4.3.1 | 1.11.0 | 1.11.0 | 3.27.0 | - | | 4.3.0 | 1.11.0 | 1.11.0 | 3.27.0 | - | | 4.2.2 | 1.10.0 | 1.10.1 | 3.27.0 | - | | 4.2.1 | 1.10.0 | 1.10.1 | 3.27.0 | - | | 4.2.0 | 1.10.0 | 1.10.1 | 3.27.0 | - | | 4.1.3 | 1.6.0 | 1.5.0 | 3.27.0 | - | | 4.1.2 | 1.6.0 | 1.5.0 | 3.27.0 | - | | 4.1.1 | 1.6.0 | 1.5.0 | 3.27.0 | - | | 4.1.0 | 1.6.0 | 1.5.0 | 3.27.4 | - | | 4.0.3 | 1.5.2 | 1.4.7 | 3.22.3 | - | | 4.0.2 | 1.5.2 | 1.4.2 | 3.22.3 | - | | 4.0.1 | 1.5.2 | 1.4.2 | 3.22.3 | - | | 4.0.0 | 1.5.1 | 1.4.2 | 3.22.3 | - | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Contentsquare Flutter SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/compatibility/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Customize autocaptured screens - Flutter description: Customize screen names collected via autocapture in Flutter apps lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/customize-autocaptured-screens/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/customize-autocaptured-screens/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. You can customize the screen names collected via autocapture to match your app's navigation structure. ## Track screens automatically Automatic screen view tracking can be done using the `CSQNavigatorObserver`. This will observe the navigation stack of the application and log screen events accordingly. This observer can be attached to any `WidgetApp` (like `MaterialApp`, `CupertinoApp`) or to a `RouterConfig` * MaterialApp ```dart import 'package:contentsquare/csq.dart'; MaterialApp( navigatorObservers: [ CSQNavigatorObserver(), ], ); ``` * Navigator ```dart import 'package:contentsquare/csq.dart'; Navigator( observers: [ CSQNavigatorObserver(), ], ); ``` * GoRouter ```dart import 'package:contentsquare/csq.dart'; final _goRouter = GoRouter( observers: [ CSQNavigatorObserver(), ], routes: [...], ); MaterialApp.router( routerConfig: _goRouter, ); ``` Tip You should use [Routes ↗](https://api.flutter.dev/flutter/widgets/Route-class.html) with proper [names ↗](https://api.flutter.dev/flutter/widgets/RouteSettings/name.html) assigned to them. This will be used as a fallback value for the automatic screen name capturing. The `CSQNavigatorObserver` can be configured with the following arguments: ### ExcludeRouteFromTracking An optional callback function that determines whether a specific route should be excluded from tracking. The function takes a `Route` as input and returns a `bool`. Use this function to selectively exclude certain routes from automatic tracking by returning true for those routes. ```dart import 'package:contentsquare/csq.dart'; CSQNavigatorObserver( excludeRouteFromTracking: (route) { // Exclude a specific route name if (route.settings.name == '/myRoute') return true; // Exclude popup routes (menus, popups, dialogs) if (route is PopupRoute) return true; // Exclude dialog routes (AlertDialog, showDialog) // Many dialogs inherit from PopupRoute, but this is extra safety: if (route.runtimeType.toString().contains('DialogRoute')) return true; // Exclude full-screen dialogs if (route is PageRoute && route.fullscreenDialog == true) return true; return false; }, ) ``` By default, all routes are tracked. Note `CSQNavigatorObserver` consider modal routes (like `showDialog`, `showModalBottomSheet`, etc.) and pop-ups (such as `showDialog`) as separate screens. If you don't want to track them as screens, you can use the `excludeRouteFromTracking` configuration option to exclude them. ### ScreenNameProvider An optional callback function used to customize the screen name for a given route. The function takes a `Route` as input and returns a `String` representing the desired screen name. Use this function to define custom screen names for specific routes. ```dart import 'package:contentsquare/csq.dart'; CSQNavigatorObserver( screenNameProvider: (route) { final screenName = _formatScreenName(route.settings.name); return screenName; }, ) ``` Tip If you use dart code obfuscation in your release builds, you should use the `screenNameProvider` to avoid obfuscated screen names being tracked. ## Troubleshooting ### AutoRoute package support If you're using the [AutoRoute package ↗](https://pub.dev/packages/auto_route), refer to the [CSQNavigatorAutoRouteObserver](https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/auto_route_support/) documentation for automatic screen tracking support, including tab navigation. ### Pageview widget `PageView` widgets sometimes are used to build swipeable screens such as onboarding flows, multi-step forms, or carousels. However, because `PageView` navigation does not push new routes to the navigation stack, navigator observers are not triggered when pages change. To ensure correct tracking, each page transition must be tracked manually using the `onPageChanged` callback. For example, when using `PageView.builder`, you can track each page as an individual screen: ```dart import 'package:contentsquare/csq.dart'; class PageViewTrackingExample extends StatelessWidget { const PageViewTrackingExample({super.key}); final _controller = PageController(); // Define meaningful screen names for each page final _pageNames = const <String>[ 'onboarding_step_1', 'onboarding_step_2', 'onboarding_step_3', ]; @override Widget build(BuildContext context) { return PageView.builder( controller: _controller, itemCount: _pageNames.length, onPageChanged: (index) { // Track screen view manually for each page change CSQ().trackScreenview(screenName: _pageNames[index]); }, itemBuilder: (_, index) { return OnboardingPage(step: index); }, ); } } ``` ### PageBuilder If you use a `pageBuilder` in your routes, make sure to set the page `.name`. Example using `GoRoute`: ```dart import 'package:contentsquare/csq.dart'; GoRoute( path: 'checkout', name: 'Checkout Screen', pageBuilder: (context, state) => MaterialPage( name: 'Checkout Screen', key: ValueKey(state.pathParameters), fullscreenDialog: true, child: const CheckoutScreen(), ), ), ``` ### TabBar `TabBar` views are commonly tracked as individual screens. However, most `TabBar` implementations push the route to the navigation stack only during initialization, which can make it challenging to properly track navigation events for each tab change. To track tab changes correctly, you need to manually call `trackScreenview` when the active tab changes. Here's an example using `TabController`: ```dart import 'package:contentsquare/csq.dart'; class TabBarExample extends StatefulWidget { const TabBarExample({super.key}); @override State<TabBarExample> createState() => _TabBarExampleState(); } class _TabBarExampleState extends State<TabBarExample> with SingleTickerProviderStateMixin { late TabController _tabController; // Define meaningful screen names for each tab final _tabNames = const <String>[ 'home_tab', 'search_tab', 'profile_tab', ]; @override void initState() { super.initState(); _tabController = TabController(length: _tabNames.length, vsync: this); // Track initial tab CSQ().trackScreenview(screenName: _tabNames[_tabController.index]); // Listen to tab changes _tabController.addListener(() { if (!_tabController.indexIsChanging) { CSQ().trackScreenview(screenName: _tabNames[_tabController.index]); } }); } @override void dispose() { _tabController.dispose(); super.dispose(); } @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( bottom: TabBar( controller: _tabController, tabs: const [ Tab(icon: Icon(Icons.home), text: 'Home'), Tab(icon: Icon(Icons.search), text: 'Search'), Tab(icon: Icon(Icons.person), text: 'Profile'), ], ), ), body: TabBarView( controller: _tabController, children: const [ HomeTab(), SearchTab(), ProfileTab(), ], ), ); } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Customize autocaptured screens","description":"Customize screen names collected via autocapture in Flutter apps","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/customize-autocaptured-screens/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Experience Analytics extension - Flutter description: Understand the benefits of upgrading to the CSQ SDK lastUpdated: 12 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/dxae-setup/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/dxae-setup/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use this page to set up the Mobile Experience Analytics extension for Contentsquare Product Analytics. This will supercharge the Product Analytics platform with: * Powerful Session Replay * Analysis capabilities of Mobile API Errors and Crashes This guide assumes that you have already implemented the [CSQ SDK for Product Analytics](../). ## Enable the extension in the Product Analytics UI 1. In Product Analytics, navigate to **Account** > **Manage** > **Replays & Heatmaps**. 2. If this is your first time setting up Session Replay, select the checkbox to accept the terms and conditions. 3. Click **Add web or mobile app** to launch the setup wizard. There is one configuration per app. 4. Select **Mobile** as platform. 5. Give your app a name and choose a storage location (**US** or **EU**). 6. Set a sampling rate for how many sessions to record. 7. Configure replay settings: * **App ID**: enter the bundle ID of your app (for example, `com.companyname.appname`). * **Quality Settings**: choose the recording fidelity for Wi-Fi and Cellular connections. The default for both is Medium; keep Cellular equal to or lower than Wi-Fi. * **User Consent**: enable this if your app requires explicit opt-in before recording. See [Privacy docs](../privacy/#opt-in) for the opt-in API. 8. Click **Save and Continue** to finish the wizard. Two configurations required Flutter apps require two separate mobile configurations — one for iOS and one for Android. Repeat the steps above for each platform, entering the appropriate bundle ID each time. ## Enable error and crash collection Error and crash collection is managed separately from the setup wizard. Navigate to **Account** > **Manage** > **Replays & Heatmaps**, click **Edit** next to your app configuration, then scroll to the relevant section under **General Settings**: * **Error Capture**: toggles for **API Errors** and **Custom Errors**. * **Crashes Capture**: toggle for **Crashes & Flutter Errors**. Click **Save** when finished. ## Session Replay masking The Session Replay feature replays every interaction of your users with your app. To respect the user's right to privacy, the CSQ SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our [Masking rules](#masking-rules) Warning When using Contentsquare with Flutter, if you decide to use unmasked elements leading to collection of new data or use already collected data but for a different purpose, it is up to you to update your app's privacy documentation accordingly. Here are some common examples of data collected via unmasked Session Replay: Search history, purchase history, advertising data, etc. See [Types of data and purpose](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/privacy/) for details about the data collected by the Contentsquare Flutter SDK. **Important:** Contentsquare is not intended nor designed to collect sensitive personal data (such as health, financial, racial data). It is the customer's responsibility not to send any sensitive personal data to Contentsquare. ### Masking mechanisms Masking depends on the type of element: * **Images**: A blurred representation is sent in place of the original content. * **SVG images**: A blurred representation is sent in place of the original content. * **CustomPaint**: custom-made `CustomPaint` elements are not collected. Instead, a blurred representation is sent in place of the original content. [Framework specific decorative `CustomPaint`](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/session-replay/#unmaskable-framework-specific-custompaint-classes) that do not contain sensitive data are still collected. * **Text**: Replaced by \* (asterisk) characters, matching the original character count. Whitespace characters (spaces, tabs, line breaks) are preserved. For instance, `the lazy fox` is collected as `*** **** ***`. All other visual properties (text color, background color, alignment, etc.) are collected. * **TextFields**: Same as Text * **TextField with `obscureText`**: Both the obscured text and the briefly revealed character are replaced by • (bullet). * **Other types**: no specific data is collected but visual properties are collected. * **Icons**: Single characters belonging to the Private Use Area `U+E000..U+F8FF` are collected. If you believe a particular element might disclose personal data through any of these properties, you must mask it using one of the methods outlined below. A reliable method to assess how a view is rendered in a replay is to navigate to the desired view with the CS SDK active, then use the [quick replay link](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/session-replay/#access-the-replay). #### Masking example Here's an illustration of a masked view: `Original` -> `Replay fully unmasked` -> `Replay fully masked`  ### Masking rules Masking rules can be applied in two ways: 1. **Through remote masking configuration in the CSQ Console (for admin users):** These configurations are managed directly in the Console and take effect for all sessions as soon as the app is restarted or brought to the foreground. See [How to customize masking rules from the Data Masking tab ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) on the Help Center. 2. **Using public masking APIs in the SDK (for mobile application developers):** These configurations require developer implementation and will be applied only after the mobile app has gone through its release cycle. Masking rules set via the CSQ Console or the public APIs are applied according to different priorities, as described below. The SDK determines whether a view is masked by evaluating the rules in the order specified below. Once a rule is triggered, the state is set, and subsequent rules are not applied: When using `CSQMask` and `CSQMaskingConfig`, it's essential to understand the priority of masking rules in the widget tree. The masking rules specified in a `CSQMask` widget will affect its descendants, and if nested scopes are used, the innermost (closest) scope takes precedence. Once a rule is triggered, the state is set, and subsequent rules are not applied: | Rule | Configured via | | - | - | | 1. The app or plugin version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text or Image masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. The `CSQMaskingConfig` object provided to the `start()` method sets the masking rules for the entire app. | API | | 4. The `CSQMaskingConfig` object provided to a `CSQMask` widget sets the masking rules for its child and descendants. | API | | 5. Remote Text or Image unmasking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 6. Otherwise the widget remains masked except for `CustomPaints` and `SvgImages` | default | ### Public Masking APIs #### Default masking By default all images, text, and Text fields will be masked. SVGs and CustomPaints are not masked. #### Masking/Un-masking in Flutter `CSQMask` is a Flutter widget that applies specified masking rules to its descendant widgets. This can be used when you want to mask sensitive information during Session Replays, such as user data or private texts. `CSQMaskingConfig` is a class that determines what type of content should be masked during Session Replays. You can customize the masking behavior by setting the masking options for texts, text fields, and images. #### Handle masking To mask or unmask content, wrap the desired widgets with the `CSQMask` widget and provide a `CSQMaskingConfig` object to configure the masking rules. Here's an example of how to use `CSQMask`: ```dart import 'package:contentsquare/csq.dart'; CSQMask( maskingConfig: CSQMaskingConfig.maskAll(), child: const Text('Hello world'), ); ``` In this example, `CSQMaskingConfig.maskAll()` is used to mask the `Text` widget. You can also use nested `CSQMask` widgets to apply different masking rules to different parts of your widget tree. Here's an example: ```dart import 'package:contentsquare/csq.dart'; CSQMask( maskingConfig: CSQMaskingConfig.maskAll(), child: Column( children: [ const Text('This text will be masked'), CSQMask( maskingConfig: CSQMaskingConfig(maskTexts: false), child: Text('This text will NOT be masked'), ), ], ), ); ``` In this example, the first `Text` widget will be masked, while the second one will not be masked due to the `maskTexts: false` option in the nested `CSQMask`. #### How to use `CSQMaskingConfig` `CSQMaskingConfig` allows you to configure the masking behavior for different types of content: * `maskTexts`: If set to `true`, any widget that creates a `RenderParagraph` (example: `Text`, `RichText`) will be masked. * `maskTextFields`: If set to `true`, any widget that creates a `RenderEditable` (example: `TextFormField`, `TextField`) will be masked. * `maskImages`: If set to `true`, any widget that creates an image (example: `Image`, `BoxDecoration.image`) will be masked. * `maskSvgImages`: If set to `true`, any widget that creates an SVG image through `flutter_svg` will be masked. * `maskCustomPaints`: If set to `true`, any custom-made widget that creates a `CustomPaint` will be masked. [Framework specific decorative `CustomPaint`](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/session-replay/#unmaskable-framework-specific-custompaint-classes) not containing any sensitive data are not masked. * `maskCharts`: If set to `true`, any widget that creates a chart using the [`fl_chart` ↗](https://pub.dev/packages/fl_chart) package will be masked. You can create a custom `CSQMaskingConfig` object by using the constructor: ```dart import 'package:contentsquare/csq.dart'; const CSQMaskingConfig({ bool? maskTexts, bool? maskImages, bool? maskTextFields, bool? maskSvgImages, bool? maskCharts, bool? maskCustomPaints, }) ``` For easier readability and convenience, you can use the following factory constructors: * `CSQMaskingConfig.maskAll()`: Returns a `CSQMaskingConfig` object with all values set to `true`, meaning everything will be masked. * `CSQMaskingConfig.unMaskAll()`: Returns a `CSQMaskingConfig` object with all values set to `false`, meaning nothing will be masked. If any masking parameter is omitted in the `CSQMaskingConfig` object, its value is inherited from the nearest `SessionMaskingScope` widget in the widget tree. Note By default, CSQ masks all types of content (texts, text fields, and images) except the SVG images and CustomPaints during Session Replays. It achieves this by providing a default `CSQMaskingConfig` object if none is specified. The default configuration masks everything, ensuring that sensitive information is protected. However, you can override the default masking behavior by providing your own `CSQMaskingConfig` object when calling the `start()` method. This allows you to customize the masking rules for your app according to your requirements. Note If you did not include any sensitive content in `CustomPaint`s or SVG images, prefer to use `CSQMaskingConfig` with `maskCustomPaints` and `maskSvgImages` set to false, to avoid unnecessary masking and guarantee the best Session Replay fidelity. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Experience Analytics extension","description":"Understand the benefits of upgrading to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/dxae-setup/","inLanguage":"en","dateModified":"2026-06-12T11:40:35+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - Flutter description: Configure privacy settings and user consent management in your Flutter app with the CSQ SDK to ensure regulatory compliance lastUpdated: 28 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/privacy/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Customers ("Customer(s)", "you," or "your"), as app developers and/or publishers, shall ensure compliance with applicable data privacy laws and regulatory guidelines while using Contentsquare SDK for your app. This section explains the data processing involved in the use of Contentsquare SDK and provides information to help you comply with data protection laws, including the GDPR, e-privacy directive, and the [French Data Protection authority (CNIL) guidelines on mobile applications ↗](https://www.cnil.fr/sites/cnil/files/2025-05/recommendation-mobiles-app.pdf). This section is for informational purposes only and is not legal advice. If you are not sure of how to comply with data protection laws that apply to you, refer to legal counsel. To learn about Contentsquare privacy practices, see our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Purpose of processing and categories of personal data collected Here is the list of categories of personal data Contentsquare collects by default that are part of our [privacy manifests](../privacy/#privacy-manifest). All collected personal data listed below is linked to the end-user via the [Contentsquare User ID](#contentsquare-user-id) we generate. Warning The Contentsquare SDK provides features that allow you to send to Contentsquare additional types of personal data (such as username, email address, customer ID, account number): [Dynamic variables](../../experience-analytics/track-dynamic-variables/), [Custom variables](../../experience-analytics/track-custom-variables/), [User identifier](../../experience-analytics/session-replay/#send-user-identifier), [Screen names](../../experience-analytics/track-screens/), [Session Replay (unmasking elements)](../../experience-analytics/session-replay/#personal-data-masking). If you decide to use these features to collect new types of personal data or use already collected data but for a different purpose, it is up to you to describe these privacy practices in your app manifest. | Categories | Data type | Purposes | | - | - | - | | Identifiers | User ID | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Product Interaction such as touch gestures (taps, swipes), user journey (pages visited), time of engagement, or transactions | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Other usage data (any other data about end-user activity in the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Other Data types | Other Data types (technical data, any other data inputted by customers in the dynamic variables, data used as part of the Session Replay feature where applicable) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Diagnostics | Crashes, such as crash logs | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Diagnostics | Performance data, such as launch time, freeze rate, or energy use | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Diagnostics | Other diagnostic data (any other data collected for the purposes of measuring technical diagnostics related to the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Search History | Information about searches performed by an end-user in the app | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Session Replay module](../../experience-analytics/session-replay/)) | | Purchase History | Transaction data about an end-user (such as order reference, amount, bought items) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | See how the data types and purposes are reflected in the [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy). Note Contentsquare is not designed to collect sensitive personal data (such as health, financial, or racial data). It is your responsibility to prevent any sensitive data from being sent to Contentsquare. If you accidentally send sensitive data, contact your customer success manager to immediately delete them from Contentsquare servers. ## User identifiers ### Contentsquare User ID The SDK generates a unique user ID (UUID) (random hash) which is specific to users on their device. Contentsquare cannot identify a user across devices. This user ID and all collected data are stored for 13 months. We don't persist the UUID when the app is deleted and re-installed. The SDK generates a new UUID after install or re-install. Contentsquare does not share this user ID with any third parties. ### IDFA Contentsquare does not collect the **IDFA** (Advertising ID) or any ad related information to identify the user. Check out our page about [10 Things to know about the Contentsquare solution's data processing ↗](https://contentsquare.com/privacy-center/10-things-to-know-cs-data-processing/). ### "User identifier" feature Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier provided by the customer. See [User identifier feature](../../experience-analytics/session-replay/#send-user-identifier) for more information. ## Data retention and storage location ### Data retention By default, end-users personal data are kept for 13 months. The retention of end-users personal data collected via the Session Replay is customizable by customers, from 3 to 24 months. ### Storage location End-users personal data are stored in Europe or in the US, depending on your location. For more details on applicable hosting locations, refer to our [subprocessors list ↗](https://contentsquare.com/privacy-center/subprocessors/). ## Informing your End-User The Contentsquare SDK collects end-user's personal data on your app. As a data controller, app developers, or app publishers, it is your responsibility to provide appropriate information to your end-users on how their personal data is handled when using the CSQ SDK, for example via a privacy policy or cookie banner. Contentsquare provides a sample [description of the services ↗](https://contentsquare.com/privacy-center/sample-cookie-description/) (including Experience Analytics and Product Analytics) to help customers meet their transparency obligations. This description is for information only and is not legal advice. ## Handling User Consent Contentsquare collects usage data on your app. **By default, the SDK will consider every new user to be opted-out.** To start tracking, the SDK [Opt-in API](#opt-in) must be called. You are responsible for handling the UI asking end-users for their consent and allowing them to manage their privacy settings. Use the following APIs to pass the user decision to the Contentsquare SDK. Note If data protection laws that apply to you do not require end-user consent for your app, discuss it during implementation with your Contentsquare contact (as this would go against Apple Privacy guidelines). ### Opt-in Use the Opt-in API to get end-user consent. Calling this API will generate a user ID and initiate tracking. * Product Analytics ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` * CSQ Experience Platform (Early Access) ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` ### Opt-Out When this API is called, tracking stops immediately, all settings are reset (Session number, Page number, and so on) and all files and directory including personal data collected via the SDK created by Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track and collect any data from the user's phone unless the Opt-in API is called again. ```swift CSQ.optOut() ``` ### Handling your end-user's data subject requests In case Contentsquare receives a request from an individual that identifies as an end-user of your app, Contentsquare will promptly refer such individual directly to you, as the data controller and will support you with any means available to resolve such request. Contentsquare has launched a portal for managing data subject requests to its customers respond to data subjects within the legal deadlines. Therefore, you can forward any data subject request (such as data deletion or data access request) you receive to Contentsquare via this Data Subject Portal at [https://contentsquare.com/privacy-center/data-subject-request-portal/ ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ### Get Contentsquare User ID Since Contentsquare SDK does not collect by default any directly identifiable personal data about your end-user, we cannot help you respond to an end-user's data subject request without their Contentsquare User ID. Use this API to get the Contentsquare User ID of your end-user and forward the end-user's data subject request (such as data deletion or data access request) via Contentsquare's [portal ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ```swift CSQ.metadata.userID ``` Note You are able to get an ID only if the user is not Opted-out. ### Enrichment API [The Enrichment API](https://docs.contentsquare.com/en/api/enrichment/) allows for enriching the behavioural data tracked by Contentsquare client-side, with other session-based data that can be sent server-side. During a visit on an app, you can interact with Contentsquare's SDK to pull those identifiers with the following SDK APIs: ```swift let projectID = CSQ.metadata.projectID let sessionId = CSQ.metadata.sessionID // store these Contentsquare session identifiers in your backend ``` ### Pause / Resume Tracking To completely stop data collection of your end-users of your app, use the pause and resume tracking APIs. When `stop/pause` is called, the Contentsquare SDK pauses all tracking (Analytics, Session Replay, Errors) of your end-users. When `resume` is called, the Contentsquare SDK resumes all tracking (Analytics, Session Replay, Errors) and starts collecting your end-users personal data again with the same Contentsquare user ID. ```swift CSQ.stop() // ... CSQ.resumeTracking() ``` Note As this mechanism pauses the tracking, make sure that you call resume once your user exits the sensitive screen. Best practice would be to link these method calls to lifecycle events on UIView/UIViewControllers. ## Disable user tracking across sessions If you don't want to link the different sessions of a user to the same userID, reset the userID at each app start: ```swift func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) { CSQ.start() CSQ.optOut() CSQ.optIn() // ... } ``` Starting the SDK manually using `start()` will ensure that opt-out is called right after the start of the SDK (no event tracked in between). Calling `optOut()` will delete the previous userID. Calling `optIn()` will set a new one. Note If you are monitoring the network requests, you may see event requests being sent at app start. This is expected as there may be events from the previous session that haven't been sent yet. The [opt-out API](#opt-out) makes sure to send all data stored locally before stopping the tracking and wiping all data. ### Session Replay privacy APIs As part of Session Replay capabilities, Contentsquare provides masking mechanisms to prevent unwanted end-user's personal data from the Session Replay module from being transmitted to Contentsquare. See [Session Replay Personal data masking](../../experience-analytics/session-replay/#personal-data-masking) for more information. ## App Store Privacy Guidelines Compliance As customer app developers, it is your responsibility to comply with the [App Store Privacy guidelines ↗](https://developer.apple.com/app-store/review/guidelines/#privacy). ### Privacy manifest The Contentsquare SDK includes a [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy) describing the types of end-users personal data collected, the purpose of processing and the reasons for using APIs. [See Apple's website for more information ↗](https://developer.apple.com/app-store/app-privacy-details/) ### Tracking and App Tracking Transparency (ATT) App Store (Apple) requests App developers to receive end-users' permission to track them or access Advertising ID using the [AppTrackingTransparency framework ↗](https://developer.apple.com/documentation/apptrackingtransparency) (ATT). **It is not required to ask for end-users' permission through the ATT when using Contentsquare, as it does not fall under the** ["tracking" definition of Apple ↗](https://developer.apple.com/app-store/app-privacy-details/#user-tracking). The data collected by the Contentsquare SDK is not linked with Third-Party Data (as defined by Apple) for targeted advertising or advertising measurement purposes, nor shared with a data broker. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Configure privacy settings and user consent management in your Flutter app with the CSQ SDK to ensure regulatory compliance","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/privacy/","inLanguage":"en","dateModified":"2026-04-28T22:02:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Hide sensitive data - Flutter description: Protect sensitive data in Contentsquare by disabling text capture, masking specific views, or ignoring interactions lastUpdated: 08 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/privacy-and-sensitive-data/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/privacy-and-sensitive-data/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. When using autocapture, Product Analytics collects target text information about the element that was interacted with, and text data from UI elements further up in an element's ancestry. However, some of these elements might contain sensitive user information, or Personal Data, that needs to be excluded from data capture. There are three options for hiding sensitive data: * Disabling text capture * Per-view text masking * Ignoring interactions for specific views ## Disabling all text capture You have the option to disable text capture for all events that are automatically captured. To do this, use the `CSQMaskingConfig` API when starting the SDK. **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main(){ await CSQ().start( maskingConfig: CSQMaskingConfig( maskTexts: true, ), ); } ``` ## Masking text for specific views If you don't want to disable all text capture for your app, you can take a more targeted approach of only masking text for specific views in your app that you know might contain sensitive data. When text is masked for a view, it will still have target text, but the actual text will be replaced with `****`. ```dart import 'package:flutter/material.dart'; import 'package:contentsquare/csq.dart'; class MyWidget extends StatelessWidget { @override Widget build(BuildContext context) { return Container( child: CSQMask( config: CSQMaskingConfig(maskTexts: true), child: Text('Sensitive Information'), ) ); } } ``` Using the `CSQMask` widget, you can wrap any view that might contain sensitive data to ensure that its text content is masked when captured by the SDK. Its usage will impact all child views contained within the masked view. ```dart import 'package:flutter/material.dart'; import 'package:contentsquare/csq.dart'; class MyWidget extends StatelessWidget { @override Widget build(BuildContext context) { return CSQMask( config: CSQMaskingConfig(maskTexts: true), child: Column( children: [ Text('Sensitive Information'), ElevatedButton( onPressed: () {}, child: Text('Submit'), ), ], ), ); } } ``` In this example, both the `Text` and `ElevatedButton` views will have their text content masked when interacted with, as they are both children of the `CSQMask` widget. In case of need you can also combine multiple masking configurations by nesting `CSQMask` widgets. ```dart import 'package:flutter/material.dart'; import 'package:contentsquare/csq.dart'; class MyWidget extends StatelessWidget { @override Widget build(BuildContext context) { return CSQMask( config: CSQMaskingConfig(maskTexts: true), child: Column( children: [ Text('Sensitive Information'), CSQMask( config: CSQMaskingConfig(maskTexts: false), child: ElevatedButton( onPressed: () {}, child: Text('Submit'), ), ), ], ), ); } } ``` In this example, only the `Text` view will have its text content masked, while the `ElevatedButton` view will retain its original text, as it is wrapped in a nested `CSQMask` with `maskTexts` set to `false`. Note Masking the visible text also masks the text in the accessibility label to ensure Personal Data isn't leaked when the visible text and the accessibility text are the same value. ## Ignoring all interactions You have the option to disable all interaction capturing. To do this, use the `CSQMaskingConfig` API when starting the SDK. **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main(){ await CSQ().start( maskingConfig: CSQMaskingConfig( maskInteractions: true, ), ); } ``` ## Ignoring interactions for specific views If you don't want to disable interactions for your app, you can take a more targeted approach of only masking interactions for specific views in your app. ```dart import 'package:flutter/material.dart'; import 'package:contentsquare/csq.dart'; class MyWidget extends StatelessWidget { @override Widget build(BuildContext context) { return Container( child: CSQMask( config: CSQMaskingConfig(maskInteractions: true), child: ElevatedButton( onPressed: () {}, child: Text('Submit'), ), ) ); } } ``` Using the `CSQMask` widget, you can wrap any view that you want to ignore interactions for. Its usage will impact all child views contained within the masked view. ```dart import 'package:flutter/material.dart'; import 'package:contentsquare/csq.dart'; class MyWidget extends StatelessWidget { @override Widget build(BuildContext context) { return CSQMask( config: CSQMaskingConfig(maskInteractions: true), child: Column( children: [ ElevatedButton( onPressed: () {}, child: Text('Submit'), ), ElevatedButton( onPressed: () {}, child: Text('Cancel'), ), ], ), ); } } ``` In this example, both the `ElevatedButton` views will have their interactions masked, as they are both children of the `CSQMask` widget. In case of need you can also combine multiple masking configurations by nesting `CSQMask` widgets. ```dart import 'package:flutter/material.dart'; import 'package:contentsquare/csq.dart'; class MyWidget extends StatelessWidget { @override Widget build(BuildContext context) { return CSQMask( config: CSQMaskingConfig(maskInteractions: true), child: Column( children: [ ElevatedButton( onPressed: () {}, child: Text('Cancel'), ), CSQMask( config: CSQMaskingConfig(maskInteractions: false), child: ElevatedButton( onPressed: () {}, child: Text('Submit'), ), ), ], ), ); } } ``` In this example, only the `Cancel` `ElevatedButton` view will have its interactions masked, while the `Submit` `ElevatedButton` view will retain its original interactions, as it is wrapped in a nested `CSQMask` with `maskInteractions` set to `false`. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Hide sensitive data","description":"Protect sensitive data in Contentsquare by disabling text capture, masking specific views, or ignoring interactions","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/privacy-and-sensitive-data/","inLanguage":"en","dateModified":"2026-05-08T11:00:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track events manually - Flutter description: Learn how to track custom events in your Flutter app using the CSQ SDK lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/track-events-manually/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/track-events-manually/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. In addition to autocaptured events, use the `CSQ().trackEvent()` API to send custom events and attach properties to them for use in Product Analytics. ```dart await CSQ().trackEvent(eventName: 'product_purchased'); ``` It doesn't matter what you call your event, there are ways in Product Analytics to cross-track events regardless of name. See our [guide on combo events ↗](https://help.heap.io/hc/en-us/articles/37271999013009-How-to-combine-events-using-a-combo-event) to learn more. ## Adding properties to custom events Custom events can be enhanced with a set of properties that will correspond to the tracked event when passed into the `CSQ().trackEvent()` call. ```dart await CSQ().trackEvent( eventName: 'product_purchased', properties: { 'product_id': 'SKU123', 'product_name': 'Premium Subscription', 'price': 29.99, 'currency': 'USD', 'is_discounted': true, }, ); ``` Here are more examples showing different event types and property combinations: ```dart // Content interaction event await CSQ().trackEvent( eventName: 'video_played', properties: { 'video_id': 'vid_789', 'video_title': 'Getting Started Tutorial', 'duration_seconds': 245, 'is_premium_content': false, }, ); // User engagement event await CSQ().trackEvent( eventName: 'article_shared', properties: { 'article_id': 'art_456', 'share_method': 'email', 'article_category': 'technology', 'read_progress': 0.75, }, ); // Search and discovery event await CSQ().trackEvent( eventName: 'search_performed', properties: { 'search_query': 'flutter tutorials', 'result_count': 24, 'filter_applied': true, }, ); ``` ## Adding properties to all events In some cases, you might want to add a property, or a collection of properties, to all events tracked by Product Analytics. Adding a global event property can be accomplished using `CSQ().addEventProperties()`. ```dart await CSQ().addEventProperties(properties: { 'user_tier': 'premium', 'app_version': '2.1.4', 'platform': 'mobile', 'is_beta_user': false, 'session_count': 42, }); ``` Properties that are added using the `csq.addEventProperties()` API will be attached to all events tracked by Product Analytics, including any events that are automatically tracked by a CSQ autocapture SDK. Once a property is no longer needed in the global collection, use this API to remove properties one at a time. ```dart await CSQ().removeEventProperty(name: 'is_beta_user'); ``` On the other hand, if you want to remove all properties added with `CSQ().addEventProperties()` at once, you can achieve this by using `CSQ().clearEventProperties()`. ```dart await CSQ().clearEventProperties(); ``` However, neither of these methods will affect events that have already been processed. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track events manually","description":"Learn how to track custom events in your Flutter app using the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/track-events-manually/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track identity - Flutter description: Enhance user tracking with identify and addUserProperties APIs. Link anonymous and identified user data across sessions and devices for comprehensive analytics lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/track-identity/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/track-identity/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Product Analytics assigns every visitor a random user ID; call `identify` to merge anonymous and identified profiles, and `addUserProperties` to attach custom attributes. ## User Identities and Properties CSQ Product Analytics empowers you to use the rich information about your users to better understand how users interact with your site or app, and build charts to continually track engagement. There are two primary APIs for enriching user data in Product Analytics: * The [`CSQ().identify()`](../command-reference/#csqidentify) API allows you to attach a unique identity and maintain user histories across sessions and devices under a single profile, * The [`CSQ().addUserProperties()`](../command-reference/#csqadduserproperties) API allows you to attach custom properties to your users, whether they are identified or still anonymous. ## Read This First: Key Considerations Before implementing our APIs, check the following explanations on how these APIs work and common implementation mistakes to avoid. ### Anonymous Users When a person interacts with your site or app, Product Analytics generates a random unique user ID and stores it in a cookie. In Product Analytics, these users will appear in the [Users ↗](https://developers.heap.io/docs/users) view as "User 123456" where the 123456 is their user ID. We refer to these users as anonymous users throughout this document. Tip Though this guide focuses on web use cases, the same principles apply to mobile. The user ID may be stored differently depending on the platform. If a user visits your website on their mobile device and their laptop, Product Analytics will recognize 2 different anonymous users because both devices will have different cookies. We can identify these users on both platforms and link the two anonymous users into a single identified user. Note While Product Analytics can track identified users across different domains, it will not track anonymous users across domains. For cross-domain tracking support, you should using our APIs to identify users. ### Identified Users You can use the `identify` API to attach your own unique identifier to a user. The `identify` API takes a single string value as an argument. Examples are provided further down in this guide in the [Examples section ↗](https://developers.heap.io/docs/using-identify#examples). Warning When a user is identified, their past sessions and event activity from when they were anonymous are now tied to that identity. This allows the user to use multiple devices/browsers to access your website with a single identity. ### User Properties The [`CSQ().addUserProperties()`](../command-reference/#csqadduserproperties) API can be used to attach properties to users' profiles. Product Analytics sets some of these properties automatically, such as Initial Location, Initial Referrer, Initial Marketing Channel, and more. A full list of all user properties captured by default is available in [Autocaptured Data ↗](https://help.heap.io/getting-started/how-heap-works/autocaptured-data/). The [`CSQ().addUserProperties()`](../command-reference/#csqadduserproperties) API allows you to attach any string or number as a user property that's not automatically captured. Some practical properties to use include: payment plan, marketing segment, or A/B experiment. Once set, these properties can be used in charts to [group by ↗](https://developers.heap.io/docs/group-bys) and [filter ↗](https://developers.heap.io/docs/filters) against. Check out some specific examples further down this page. ### Common Identify Implementation Errors Below we've listed the most common mistakes developers may make when implementing the `identify` API. #### Using a Non-Unique Identifier A common assumption is that a unique identifier attached via [`CSQ().identify()`](../command-reference/#csqidentify) is required in order for the [`CSQ().addUserProperties()`](../command-reference/#csqadduserproperties) API to attach properties to a user. In cases where a unique identifier isn't available, we've seen people include a specific name, like 'guest', or 'Anonymous User'. This can cause irreversible behavior with how Product Analytics merges user profiles. You can call [`CSQ().addUserProperties()`](../command-reference/#csqadduserproperties) at any time, whether the user has been given a unique identity. For this reason, the following identify calls are blocklisted: * `anonymous` * `guest` * `null` * `true` * `false` * `not_authenticated` * `NaN` * `' '` (empty string) * `0` * `None` * `none` * `Email` * `email` As an example of how this would impact your setup: let's say that you have a marketing campaign, and you want to associate it with a visitor when they visit your landing page. They aren't logged in, so you don't have a unique identifier. **Don't do this:** ```dart await CSQ().identify(userIdentifier: 'guest') await CSQ().addUserProperties(properties: {'campaign': 'Campaign Name'}) ``` This will merge all visitors into a single user profile called 'guest', which will break any metrics that rely on user flow, or the unique user count. **Instead, do this:** ```dart await CSQ().addUserProperties(properties: {"campaign": "Campaign Name"}) ``` Now the campaign property will be associated with the anonymous user, using the value of the JavaScript variable 'campaign'. ### Adding an Anonymous Unique Identifier of Your Own Some tools require a unique identifier to be provided to add user-level properties. This leads people to add their own unique identifier to all visitors. in Product Analytics automatically assigns each unidentified user a unique user ID so that you aren't required to call `identify` to add user-level properties. Assigning an identity to a user when it isn't required can lead to undesirable, or unexpected behavior. Product Analytics does not allow you to change an already applied identity or assign multiple identities to the same user. If you call `identify` with an anonymized identity, such as a `uuid` or random hash, this will be their permanent identity in Product Analytics. If you call the identify API at another time for the same user with a different identity, such as an internal user ID or username, this will create a new user in Product Analytics, splitting this users into two identified users, one with the random `uuid` containing all of the historical events, and another with the user ID or username which has events going forward. Since Product Analytics automatically creates a randomized unique identifier, it's not necessary for you to send your own identifier unless you are certain it is a unique, permanent identifier for the user. If you want to add properties to a user using [`CSQ().addUserProperties()`](../command-reference/#csqadduserproperties), you can do so without providing a unique identifier. Calling `CSQ().addUserProperties({property: 'value'})` will add this property to the anonymous user's Product Analytics profile automatically. ## When and Where to Call `identify` and `addUserProperties` The [`CSQ().identify()`](../command-reference/#csqidentify) and [`CSQ().addUserProperties()`](../command-reference/#csqadduserproperties) APIs can be called anytime and anywhere the data is available about that user. The typical place for an identify call that includes a unique identifier is on any post-login or post-signup page. You should making an identify call on each page load as opposed to only the first page load. When setting properties, it's OK to call the [`CSQ().addUserProperties()`](../command-reference/#csqadduserproperties) API on any page, though you should that you add user properties on identified users. This will greatly improve your experience when analyzing your user base. You can place a [`CSQ().identify()`](../command-reference/#csqidentify) call within the Product Analytics installation snippet or outside of it. If you're adding a `CSQ().identify()` call within the snippet, it should be placed after `CSQ().start()` within that snippet. ### Identity Examples #### Anonymous to New Identity Let's say we have an internal user ID from our own database, and we want to identify a user based on that ID. We can do that like this: ```dart final userID = '12345'; await CSQ().identify(userIdentifier: userID); ``` Now, their profile in the **Users** view will look like this:  #### Anonymous to Existing Identity In the last example, we identified a user with the unique user ID of `12345`. Let's say that this person visits your site from their mobile device for the first time. Product Analytics will generate a new, random, unique userID, in this case it's `5404281197559477`. In Product Analytics' users view, this visitor looks like this:  When this person logs in, and you recognize that their internal user ID is `12345`, you can call identify like this: ```dart final userID = '12345'; await CSQ().identify(userIdentifier: userID); ``` The previous user's profile with the random user ID of `1565941335949135` is merged, along with its previous sessions and events into the Product Analytics profile of the identified user with the identity of `12345`. ### addUserProperties Examples #### Common User Properties User properties can be used to capture additional data about a user, such as first and last name, email address, time zone, and account plan. The following example covers how to add an account plan user property using the [`CSQ().addUserProperties()`](../command-reference/#csqadduserproperties) API, and this can be modified to capture any of the previously mentioned user properties. #### Account Plan Many products include some sort of tiered pricing plan. Using the [`CSQ().addUserProperties()`](../command-reference/#csqadduserproperties) API to attach this information to your visitors' profiles can help you compare and contrast usage between different segments. When someone visits Product Analytics, we pull their account tier from our database and inject that into an identify call like this: ```dart await CSQ().addUserProperties(properties: {"plan": "Startup"}); ``` This lets us build powerful charts, like this bar chart showing sign-ups split by plan type. ### Industry Recommendations Call `CSQ().addUserProperties()` in the part of your website flow where the data you want to capture is being presented. Below are some examples of places to call the API, based on industry. | Industry | API Use Case | API Call Placement | | - | - | - | | e-Commerce | Improve personalization and recommendation algorithms. | On user login or significant actions (such as a purchase). Attach properties like login info, purchase amount, and spender type. | | Social media platform | Enhance user engagement and content personalization. | When a user updates their profile, adds interests, or engages in specific types of content. Attach custom properties like user interests or content preferences. | | Subscription-based service | Understand user demographics and preferences to optimize its offerings. | When a user signs up, completes a survey, or changes subscription preferences. Attach custom properties such as geographical location, email, or subscription plan details. | ## What about the identity API? Once you have the identify API set up, you can use [CSQ().metadata.identity](../command-reference/#csqmetadataidentity) to find a specific user's identity. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track identity","description":"Enhance user tracking with identify and addUserProperties APIs. Link anonymous and identified user data across sessions and devices for comprehensive analytics","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/track-identity/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track push notifications - Flutter description: Learn how to track mobile notification interactions automatically with CSQ lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/track-push-notifications/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/track-push-notifications/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. After completing the setup process you will be able to: * Automatically track interactions on your mobile notifications * Define and analyze notification interaction events in CSQ ## Initializing Notification Autocapture Notification autocapture can be initialized with `enablePushNotificationAutocapture: true` in `CSQ().start()`. * Product Analytics **main.dart** ```dart await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( enablePushNotificationAutocapture: true, ), ), ); ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( enablePushNotificationAutocapture: true, ), ), ); ``` Capture the title or body text of the notification where an interaction was performed using `enablePushNotificationTitleAutocapture` and `enablePushNotificationBodyAutocapture`. * Product Analytics **main.dart** ```dart await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( enablePushNotificationAutocapture: true, enablePushNotificationTitleAutocapture: true, enablePushNotificationBodyAutocapture: true, ), ), ); ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( enablePushNotificationAutocapture: true, enablePushNotificationTitleAutocapture: true, enablePushNotificationBodyAutocapture: true, ), ), ); ``` Once registered, CSQ will begin collecting interaction events on notifications. ## What's Next? With notification data flowing, you'll want to jump into the Product Analytics app and start defining notification interaction events. These events will show up as a special "Notification Interaction" event type in Product Analytics and have several properties available to create definitions: * **Notification Title**: The title text of the notification. Capture can be enabled/disabled via a config option as described above. * **Notification Body**: The body text of the notification. Capture can be enabled/disabled via a config option as described above. * **Notification Action**: The text of the notification action that was interacted with, if any. * **Notification Source**: What caused the notification to fire. This could be a push service, a geofence, or unknown. * **Notification Handling Component**: The name of the component in code that handled the notification interaction. * **Notification Category**: This is the notification channel that the notification was delivered to. This typically denotes the type of notification that with which the interaction occurred. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track push notifications","description":"Learn how to track mobile notification interactions automatically with CSQ","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/track-push-notifications/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Core SDK + Contentsquare SDK to CSQ SDK - Flutter description: Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/upgrade-from-heap-and-cs-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/upgrade-from-heap-and-cs-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-flutter/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide walks you through migrating from the Heap Core SDK and Contentsquare SDK to the CSQ SDK. This guide provides a step-by-step upgrade process from your current installation of Contentsquare and Heap Mobile to the latest version of the CSQ SDK.  **Heap Core SDK** \+  **Contentsquare SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. Migration script Contentsquare provides a migration path using a script that automates most of the common API replacements from your current project to CSQ SDK 4.0. Follow these steps: 1. Back up your project. 2. Download and save the [migration script](https://docs.contentsquare.com/csq_flutter_4.0.0_migration.dart) on your machine. 3. Open your terminal and navigate to the script directory: ```shell cd </path/to/directory/with/migration/script> ``` 4. Run the script with your Flutter project path as an argument: ```shell dart migration.dart <path_to_your_flutter_project> ``` 5. Once the script completes, you'll need to: **Review all generated comments** - The script adds comments (marked with `//`) where manual updates are required **Fix compilation errors** - Address any errors that the automated migration couldn't handle **Test your application thoroughly** - Verify that all functionality works as expected **Update custom implementations** - Review and update any custom code that may have been affected by the migration This script does is provided as-is and does not cover all pattens or edge cases including: * Custom wrapper implementations around legacy SDKs * Complex conditional logic using deprecated APIs * Dynamic method calls or reflection-based usage * Platform-specific custom implementations beyond standard patterns Support tickets regarding this migration path will not be considered. ## Dependency upgrades Increment the Contentsquare SDK in `pubspec.yaml` to the latest version. ```diff dependencies: heap_flutter_bridge: ^0.4.0 heap_flutter_autocapture: ^0.6.0 contentsquare: ^3.19.1 contentsquare: ^4.0.0 ``` Sync your dependencies by running `flutter pub get`. Replace the Contentsquare SDK import with a CSQ SDK import. ```diff import 'package:heap_flutter_bridge/heap_flutter_bridge.dart'; import 'package:heap_flutter_autocapture/heap_flutter_autocapture.dart'; import 'package:contentsquare/contentsquare.dart'; import 'package:contentsquare/csq.dart'; ``` Warning After updating the import, some APIs used in your development environment may show errors. The next steps in this guide will help you update them to the latest versions. ## SDK start 1. `Optional`: If you were using `ContentsquareRoot` widget - remove it from your widget tree. **main.dart** ```dart void main() { runApp(const MyApp()); } class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return ContentsquareRoot( child: MaterialApp( return MaterialApp( title: 'My Flutter App', home: Home() ), ); } } ``` 2. Delete `Heap().startRecording()` and migrate options to `CSQ().start()`. * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await Heap().startRecording('YOUR_ENVIRONMENT_ID', { // ...options }); await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( // ...options ), ), ); await Contentsquare().start(); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await Heap().startRecording('YOUR_ENVIRONMENT_ID', { // ...options }); await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( // ...options ), ), ); await Contentsquare().start(); } ``` 3. Remove `HeapAutocapture` registration: ```dart await HeapAutocapture.register(); ``` 4. Update pageview autocapture setup **main.dart** ```dart import 'package:contentsquare/csq.dart'; await HeapAutocapture.register(); MaterialApp( navigatorObservers: [ HeapNavigatorObserver(), CSQNavigatorObserver(), ], home: MyHomePage(), ) ``` 5. Recommended To enable automatic capture of user interactions, add the option `enableInteractionsAutocapture: true` to your `AnalyticsOptions` configuration: * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( enableInteractionsAutocapture: true, ), ), ); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( enableInteractionsAutocapture: true, ), ), ); } ``` 6. (Optional) If you were relying on the Contentsquare SDK autostart, remove the `CSDisableAutostart` property and calls to `Contentsquare.start()`. **Info.plist** ```xml <key>CSDisableAutostart</key> <true/> ``` **AppDelegate.swift** ```swift Contentsquare.start() ``` 7. (Optional) If you have chosen to deactivate the autostart of the Contentsquare SDK, you can now remove the entry in the manifest, as the CSQ SDK doesn't have an autostart. **AndroidManifest.xml** ```xml <application> ... <meta-data android:name="com.contentsquare.android.autostart" android:value="false" /> ... </application> ``` 8. Remove Heap Android dependencies **android/app/build.gradle** ```kotlin dependencies { implementation("io.heap.core:heap-android-core:+") implementation("io.heap.contentsquare.csbridge:contentsquare-bridge:+") } ``` 9. Remove Heap iOS dependencies: CocoaPods support is ending CocoaPods trunk becomes read-only on December 2, 2026. After this date, Contentsquare will no longer publish new SDK versions via CocoaPods. [Migrate to Swift Package Manager (SPM)](https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/) to continue receiving updates. 1. In Xcode, navigate to your project settings. 2. Select your app target, then go to the **Frameworks, Libraries, and Embedded Content** section. 3. Find `HeapContentsquareIntegrationSDK` in the list and click the **-** button to remove it. 4. Go to **File → Packages → Resolve Package Versions** to update your package dependencies. 10. Remove Initializing Integration: * Kotlin ```kotlin HeapContentsquareIntegration.bind( applicationContext, sendHeapPageviewsToContentsquare = false, sendContentsquareScreenviewsToHeap = true ) ``` * Swift ```swift HeapContentsquareIntegration.bind( sendHeapPageviewsToContentsquare: false, sendContentsquareScreenviewsToHeap: true ) ``` ## Get user consent Implement the [`optIn()`](../command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. The CSQ SDK treats users as opted-out by default. It can be done immediately after `start` is called: **main.dart** ```dart void main() async { // ... await CSQ().start(); await CSQ().optIn(); // ... } ``` Alternatively, you can call `optIn()` in response to a user action, such as tapping an "I agree" button: ```dart class UserConsentScreen extends StatelessWidget { @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: Text('User Consent'), ), body: Center( child: ElevatedButton( onPressed: () async { await CSQ().optIn(); }, child: Text('Agree with Terms and Conditions'), ), ), ); } } ``` ## Number of sessions Session timeout definition changed: * **Before**: 30 minutes after app goes to background * **Now**: 30 minutes after last event This may affect session counts and aligns with web and market standards. ## 4.2.0 breaking changes Breaking changes in 4.2.0 The following `AnalyticsOptions` options were removed in version 4.2.0. Remove them from your `CSQ().start()` call if present: * `disableScreenviewForwardToDXA` * `disableScreenviewForwardToPA` * `resumePreviousSession` * `uploadInterval` * `captureVendorId` * `captureAdvertiserId` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `pruningLookBackWindow` * `maximumDatabaseSize` * `maximumBatchCountPerUpload` ## Update API Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. In most cases, this process consists in updating the namespace and method names, with no changes to parameters. ```diff Contentsquare().start() CSQ().start() ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### Update Contentsquare SDK APIs ### GDPR / Identification | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare().optIn()` | `CSQ().optIn()` | | `Contentsquare().optOut()` | `CSQ().optOut()` | | `Contentsquare().sendUserIdentifier()` | `CSQ().sendUserIdentifier()` | | `Contentsquare().getUserId()` | `CSQ().metadata.userID` | Removed **Contentsquare().forgetMe()** You can use `CSQ().optOut()` instead to forget user id and stop tracking. If needed call `CSQ().optIn()` when you want to resume tracking. ### Property tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare().sendDynamicVar(key: String, intValue: int)`. | `CSQ().addDynamicVar(DynamicVar.fromIn(key: String, value: int))` | | `Contentsquare().sendDynamicVar(key: String, stringValue: String)`. | `CSQ().addDynamicVar(DynamicVar.fromString(key: String, value: String))` | ### CSInApp (iOS only) | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.handle(url: URL)` | `CSQ.handle(url: URL)` | | `Contentsquare.csInApp` | `CSQ.csInApp` | ### Interoperability | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare().onSessionReplayLinkChange(callback)` | `CSQ().metadata.onChange(Metadata)` | | `Contentsquare().currentSessionReplayUrl` | `CSQ().metadata.onChange(Metadata)` | | `Contentsquare().setURLMaskingPatterns()` | `CSQ().setURLMaskingPatterns()` | | `ContentsquareNavigatorObserver()`. | `CSQNavigatorObserver()` | | `ContentsquareWebViewWrapper()`. | `CSQWebViewWrapper()` | ### Event tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.sendTransaction(double, String, String, String?)` | `CSQ.trackTransaction(Transaction(price: double, currency: Currency, id: String))` | | `Contentsquare.send(String)` | `CSQ.trackScreenview(screenName: String)` | | `Contentsquare.send(String, List<CustomVar>?)` | `CSQ.trackScreenview(screenName: String, customVars: List<CustomVar>)` | ### Error tracking | Contentsquare SDK | CSQ SDK | | - | - | | `ContentsquareHttpOverrides()` | `CSQHttpOverrides()` | | `Contentsquare().collectFlutterError(details: FlutterErrorDetails, presentErrorDetails: bool)` | `CSQ().collectFlutterError(details: FlutterErrorDetails, presentErrorDetails: bool)`. | | `Contentsquare().collectError(error: Object, stackTrace: StackTrace)` | `CSQ().collectError(error: Object, stackTrace: StackTrace)` | ### Personal Data Handling and Masking | Contentsquare SDK | CSQ SDK | | - | - | | `MaskingConfig()` | `CSQMaskingConfig()` | | `SessionReplayMaskingScope` | `CSQMask` | ### SDK initialization and manipulation | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare().start()` | `CSQ().start()` | | `Contentsquare().stopTracking()` | `CSQ().pauseTracking()` | | `Contentsquare().resumeTracking()` | `CSQ().resumeTracking()` | | `Contentsquare().triggerReplayForCurrentSession(name: String)` | `CSQ().triggerReplayForCurrentSession(name: String)` | | `Contentsquare().triggerReplayForCurrentScreen(name: String)` | `CSQ().triggerReplayForCurrentScreen(name: String)` | ### Update Heap Core SDK APIs ### GDPR / Identification | Heap SDK | CSQ SDK | | - | - | | `Heap().identify(string)` | `CSQ().identify(userIdentifier: String)` | | `Heap().resetIdentity()` | `CSQ().resetIdentity()` | | `Heap().getUserId()` | `CSQ().metadata.userId` | | `Heap().getSessionId()` | `CSQ().metadata.sessionId` | | `Heap().getEnvironmentId()` | `CSQ().metadata.environmentId` | | `Heap().getIdentity()` | `CSQ().metadata.identity` | ### Logging | Heap SDK | CSQ SDK | | - | - | | `Heap().setLogLevel(LogLevel)` | `CSQ().debug.logLevel { get set }` | ### Property tracking | Heap SDK | CSQ SDK | | - | - | | `Heap().addUserProperties(Map<String, dynamic>)` | `CSQ().addUserProperties(properties: Map<String, dynamic>)` | | `Heap().addEventProperties(Map<String, dynamic>)` | `CSQ().addEventProperties(properties: Map<String, dynamic>)` | | `Heap().removeEventProperty(name: String)` | `CSQ().removeEventProperty(name: String)` | | `Heap().clearEventProperties()` | `CSQ().clearEventProperties()` | ### Event tracking | Heap SDK | CSQ SDK | | - | - | | `Heap().track(String, [Map<String, dynamic>])` | `CSQ().trackEvent(eventName: String, properties: Map<String, dynamic>?)` | ### Personal Data Handling and Masking | Heap SDK | CSQ SDK | | - | - | | `HeapRedact(redact: bool)` | `CSQMask(config: CSQMaskingConfig(maskTexts: true))` | | `HeapIgnore(ignore: bool)` | `CSQMask(config: CSQMaskingConfig(maskInteractions: true))` | ### SDK initialization and manipulation | Heap SDK | CSQ SDK | | - | - | | `Heap().startRecording(id, options)` | `CSQ().start(startConfig: StartConfig.withEnvironmentId(id: String, options: AnalyticsOptions))` | | `Heap().stopRecording(deleteUser = true)` | `CSQ().stop()` | | `Heap().stopRecording(deleteUser = false)` | `CSQ().pauseTracking()` | Deprecated **CSQ().configureProductAnalytics()** Deprecated in 4.2.0. Use `CSQ().start(startConfig: StartConfig.withEnvironmentId(...))` instead. Will be removed in August 2026. See [`CSQ().configureProductAnalytics()`](../command-reference/#csqconfigureproductanalytics) in the command reference. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK + Contentsquare SDK to CSQ SDK","description":"Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/upgrade-from-heap-and-cs-sdk/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Core SDK to CSQ SDK - Flutter description: Steps to migrate from a Heap Core install to the CSQ SDK lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/upgrade-from-heap-core-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/upgrade-from-heap-core-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-flutter/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide provides a step-by-step upgrade process from your current installation of Heap Mobile to the latest version of the CSQ SDK.  **Heap Core SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. Migration script Contentsquare provides a migration path using a script that automates most of the common API replacements from your current project to CSQ SDK 4.0. Follow these steps: 1. Back up your project. 2. Download and save the [migration script](https://docs.contentsquare.com/csq_flutter_4.0.0_migration.dart) on your machine. 3. Open your terminal and navigate to the script directory: ```shell cd </path/to/directory/with/migration/script> ``` 4. Run the script with your Flutter project path as an argument: ```shell dart migration.dart <path_to_your_flutter_project> ``` 5. Once the script completes, you'll need to: **Review all generated comments** - The script adds comments (marked with `//`) where manual updates are required **Fix compilation errors** - Address any errors that the automated migration couldn't handle **Test your application thoroughly** - Verify that all functionality works as expected **Update custom implementations** - Review and update any custom code that may have been affected by the migration This script does is provided as-is and does not cover all pattens or edge cases including: * Custom wrapper implementations around legacy SDKs * Complex conditional logic using deprecated APIs * Dynamic method calls or reflection-based usage * Platform-specific custom implementations beyond standard patterns Support tickets regarding this migration path will not be considered. ## Dependency upgrades Increment the Contentsquare SDK in `pubspec.yaml` to the latest version. ```diff dependencies: heap_flutter_bridge: ^0.4.0 heap_flutter_autocapture: ^0.6.0 contentsquare: ^4.0.0 ``` Sync your dependencies by running `flutter pub get`. ## Imports updates Replace the Contentsquare SDK import with a CSQ SDK import. ```diff import 'package:heap_flutter_bridge/heap_flutter_bridge.dart'; import 'package:heap_flutter_autocapture/heap_flutter_autocapture.dart'; import 'package:contentsquare/csq.dart'; ``` Warning After updating the import, some APIs used in your development environment may show errors. The next steps in this guide will help you update them to the latest versions. ## SDK start 1. Delete `Heap().startRecording()` and migrate options to `CSQ().start()`. * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await Heap().startRecording('YOUR_ENVIRONMENT_ID', { // ...options }); await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( // ...options ), ), ); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await Heap().startRecording('YOUR_ENVIRONMENT_ID', { // ...options }); await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( // ...options ), ), ); } ``` 2. Remove `HeapAutocapture` registration: ```dart await HeapAutocapture.register(); ``` 3. Recommended To enable automatic capture of user interactions, add the option `enableInteractionsAutocapture: true` to your `AnalyticsOptions` configuration: * Product Analytics **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withEnvironmentId( id: 'YOUR_ENVIRONMENT_ID', options: AnalyticsOptions( enableInteractionsAutocapture: true, ), ), ); } ``` * CSQ Experience Platform (Early Access) **main.dart** ```dart import 'package:contentsquare/csq.dart'; void main() async { await CSQ().start( startConfig: StartConfig.withDatasourceId( id: 'YOUR_DATASOURCE_ID', options: AnalyticsOptions( enableInteractionsAutocapture: true, ), ), ); } ``` 4. Recommended To capture screen views automatically, add the `CSQNavigatorObserver` to your app's navigator observers: **main.dart** ```dart import 'package:contentsquare/csq.dart'; MaterialApp( navigatorObservers: [ CSQNavigatorObserver(), ], home: MyHomePage(), ) ``` More details in [Track screens](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-screens/). ## Get user consent Implement the [`optIn()`](../command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. The CSQ SDK treats users as opted-out by default. It can be done immediately after `start` is called: **main.dart** ```dart void main() async { // ... await CSQ().start(); await CSQ().optIn(); // ... } ``` Alternatively, you can call `optIn()` in response to a user action, such as tapping an "I agree" button: ```dart class UserConsentScreen extends StatelessWidget { @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: Text('User Consent'), ), body: Center( child: ElevatedButton( onPressed: () async { await CSQ().optIn(); }, child: Text('Agree with Terms and Conditions'), ), ), ); } } ``` ## 4.2.0 breaking changes Breaking changes in 4.2.0 The following `AnalyticsOptions` options were removed in version 4.2.0. Remove them from your `CSQ().start()` call if present: * `disableScreenviewForwardToDXA` * `disableScreenviewForwardToPA` * `resumePreviousSession` * `uploadInterval` * `captureVendorId` * `captureAdvertiserId` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `pruningLookBackWindow` * `maximumDatabaseSize` * `maximumBatchCountPerUpload` ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. In most cases, this process consists in updating the namespace and method names, with no changes to parameters. ```diff Heap().startRecording('YOUR_ENVIRONMENT_ID') CSQ().start(startConfig: StartConfig.withEnvironmentId(id: 'YOUR_ENVIRONMENT_ID')) ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### GDPR / Identification | Heap SDK | CSQ SDK | | - | - | | `Heap().identify(string)` | `CSQ().identify(userIdentifier: String)` | | `Heap().resetIdentity()` | `CSQ().resetIdentity()` | | `Heap().getUserId()` | `CSQ().metadata.userId` | | `Heap().getSessionId()` | `CSQ().metadata.sessionId` | | `Heap().getEnvironmentId()` | `CSQ().metadata.environmentId` | | `Heap().getIdentity()` | `CSQ().metadata.identity` | ### Logging | Heap SDK | CSQ SDK | | - | - | | `Heap().setLogLevel(LogLevel)` | `CSQ().debug.logLevel { get set }` | ### Property tracking | Heap SDK | CSQ SDK | | - | - | | `Heap().addUserProperties(Map<String, dynamic>)` | `CSQ().addUserProperties(properties: Map<String, dynamic>)` | | `Heap().addEventProperties(Map<String, dynamic>)` | `CSQ().addEventProperties(properties: Map<String, dynamic>)` | | `Heap().removeEventProperty(name: String)` | `CSQ().removeEventProperty(name: String)` | | `Heap().clearEventProperties()` | `CSQ().clearEventProperties()` | ### Event tracking | Heap SDK | CSQ SDK | | - | - | | `Heap().track(String, [Map<String, dynamic>])` | `CSQ().trackEvent(eventName: String, properties: Map<String, dynamic>?)` | ### Personal Data Handling and Masking | Heap SDK | CSQ SDK | | - | - | | `HeapRedact(redact: bool)` | `CSQMask(config: CSQMaskingConfig(maskTexts: true))` | | `HeapIgnore(ignore: bool)` | `CSQMask(config: CSQMaskingConfig(maskInteractions: true))` | ### SDK initialization and manipulation | Heap SDK | CSQ SDK | | - | - | | `Heap().startRecording(id, options)` | `CSQ().start(startConfig: StartConfig.withEnvironmentId(id: String, options: AnalyticsOptions))` | | `Heap().stopRecording(deleteUser = true)` | `CSQ().stop()` | | `Heap().stopRecording(deleteUser = false)` | `CSQ().pauseTracking()` | Deprecated **CSQ().configureProductAnalytics()** Deprecated in 4.2.0. Use `CSQ().start(startConfig: StartConfig.withEnvironmentId(...))` instead. Will be removed in August 2026. See [`CSQ().configureProductAnalytics()`](../command-reference/#csqconfigureproductanalytics) in the command reference. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK to CSQ SDK","description":"Steps to migrate from a Heap Core install to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/upgrade-from-heap-core-sdk/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Upgrade your SDK - Flutter description: Understand the benefits of upgrading to the CSQ SDK lastUpdated: 12 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/upgrade-your-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/upgrade-your-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-flutter/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This section guides you through the upgrade from your current SDK implementation to our latest CSQ SDK. Upgrading has no impact on your current data collection and does not alter the data observed on the platform. It mainly consists of searching and replacing APIs according to the mappings provided in the upgrade guides. Get started by selecting the upgrade guide that corresponds to your current implementation: * **[Heap Core SDK](../upgrade-from-heap-core-sdk/)** - Upgrade from Heap Core SDK * **[Heap SDK + Contentsquare SDK](../upgrade-from-heap-and-cs-sdk/)** - Upgrade from combined Heap and Contentsquare SDKs ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Upgrade your SDK","description":"Understand the benefits of upgrading to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/upgrade-your-sdk/","inLanguage":"en","dateModified":"2026-05-12T12:05:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Agent skills for Flutter - Flutter description: Use AI coding assistants to integrate, upgrade, and configure the Contentsquare Flutter SDK with downloadable Agent skills lastUpdated: 16 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/using-agent-skills/ md: https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/using-agent-skills/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use the Contentsquare wizard or skills to set up, update, and configure Flutter with your AI coding assistant. Disclaimer This skill guides your AI coding agent through the SDK installation and implementation. The agent you use (Cursor, Claude Code, Copilot) is your own tool and operates under your settings and permissions. Contentsquare is not responsible for how your agent interprets or applies the instructions contained in these files. ## Contentsquare wizard Run the wizard in your project directory. It configures your AI coding assistant, installs the matching Contentsquare integration, and verifies the installation. ```shell npx @contentsquare/wizard install ``` Supports GitHub Copilot, Cursor, and Claude Code. Requires Node.js ≥ 18 and an AI coding agent with MCP support. ## Manual setup Use this path when you prefer to configure your AI coding assistant yourself. ### 1. Add the Contentsquare skill Choose how to install the Contentsquare skill. * Copilot CLI Add the Contentsquare marketplace, then install the plugin for Flutter: ```shell copilot plugin marketplace add ContentSquare/agents copilot plugin install contentsquare-flutter@contentsquare ``` * Claude Code Add the Contentsquare marketplace, then install the plugin for Flutter: ```shell /plugin marketplace add ContentSquare/agents /plugin install contentsquare-flutter@contentsquare ``` * Cursor Install **contentsquare** from the [Cursor marketplace ↗](https://cursor.com/marketplace), or add the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents) directly. Cursor reads the `.cursor-plugin` catalog in the repository. * Other agents Install the Contentsquare skill pack with the open `skills.sh` ecosystem: ```shell npx skills add contentsquare/agents ``` * From source Download or clone the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents), then copy `skills/contentsquare-flutter-sdk` into the location your AI coding assistant scans for skills: | AI coding assistant | Skill location | | - | - | | GitHub Copilot | `.github/skills/` or `.agents/skills/` | | Cursor | `.cursor/rules/` or the project root | | Claude Code | `.claude/skills/` or the project root | | Other compatible agents | `.agents/skills/` | ### 2. Ask your AI coding assistant After installing the skill, paste this prompt into your AI coding assistant: ```text Install Contentsquare for Flutter. ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Agent skills for Flutter","description":"Use AI coding assistants to integrate, upgrade, and configure the Contentsquare Flutter SDK with downloadable Agent skills","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/product-analytics/using-agent-skills/","inLanguage":"en","dateModified":"2026-07-16T17:50:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Adobe Analytics - iOS description: Leverage our native integration to use Adobe Analytics segments in Contentsquare, with the CSQ iOS SDK lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/adobe-analytics/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/adobe-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Analyze your data from anywhere in the customer journey using your Adobe Analytics segments. Contentsquare allows you to use your Adobe Analytics segments in every Contentsquare feature (Journey Analysis, Page Comparator, Session Replay). Warning Sessions without at least one screenview will be discarded. You should implement your screen tracking plan first, to have your Adobe Analytics integration work. See [Track screens](../track-screens/). ## Prerequisites 1. Follow the instructions from [Adobe Analytics for mobile apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271665881745) 2. Add the [AEPAnalytics iOS SDK ↗](https://github.com/adobe/aepsdk-analytics-ios) to your project ## Code implementation Note **Adobe SDK code requirements** * Make sure you register at least `AEPIdentity` and `AEPAnalytics` extensions before starting `AEPCore`. Check the [Getting Started with Adobe Analytics iOS Extension ↗](https://github.com/adobe/aepsdk-analytics-ios/blob/main/Documentation/AEPAnalytics.md) repository for that. **Why 30 minutes before sending a new csMatchingKey** * 30 minutes is Contentsquare default session duration. * Setting a value **higher** than 30 minutes would cause overlapping on our sessions, and would impact negatively the data import from Adobe. * Setting a value **lower** than 30 minutes would make you to send more data to Adobe. This could cause the variable to reach Adobe's threshold, causing Adobe to filter values, and potentially impact your billing. See [Low-traffic value in Adobe Analytics ↗](https://experienceleague.adobe.com/docs/analytics/technotes/low-traffic.html) **AppDelegate.swift** ```swift var canSendCSMatchingKey = false func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // ... your existing code .. MobileCore.registerExtensions([Identity.self, Analytics.self, ....], { // ... your existing code .. self.canSendCSMatchingKey = true self.sendCSMatchingKeyIfNeeded() }) // When going back to foreground, more than 30 minutes may have elapsed. // In this situation Contentsquare SDK may create a new session // This is why `sendCSMatchingKeyIfNeeded` must be called in this situation NotificationCenter.default.addObserver(self, selector: #selector(sendCSMatchingKeyIfNeeded), name: UIApplication.didBecomeActiveNotification, object: nil) // ... your existing code .. } @objc func sendCSMatchingKeyIfNeeded() { guard canSendCSMatchingKey else { return } let csMatchingKeyTimestampKey = "csMatchingKey_ts" let csMatchingKeyValidityMs = 1_800_000 // 30 minutes let currentTimestamp = Int(Date().timeIntervalSince1970 * 1000) let csMatchingKeyIsPreviousTimestamp = UserDefaults.standard.integer(forKey: csMatchingKeyTimestampKey) guard (currentTimestamp - csMatchingKeyIsPreviousTimestamp) > csMatchingKeyValidityMs else { return } UserDefaults.standard.set(currentTimestamp, forKey: csMatchingKeyTimestampKey) let csMatchingKey = "csMatchingKey" let csMatchingKeyValue = "\(Double.random(in: 0..<1))_\(currentTimestamp)" CSQ.addDynamicVar(dynamicVar: DynamicVar(key: csMatchingKey, value: csMatchingKeyValue)) MobileCore.track(state: "csMatchingKey_state", data: [csMatchingKey: csMatchingKeyValue]) } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Adobe Analytics","description":"Leverage our native integration to use Adobe Analytics segments in Contentsquare, with the CSQ iOS SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/adobe-analytics/","inLanguage":"en","dateModified":"2026-05-04T11:50:50+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - iOS description: The Contentsquare iOS changelog lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/changelog/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. 📬 Stay updated! ## Opt-in to CSQ Experience Platform Already using the CSQ SDK in standalone mode? Follow these steps to switch to CSQ Experience Platform and combine Experience Analytics and Product Analytics under a single data source. CSQ Experience Platform is currently an Early Access program. To gain access, contact your Customer Success Manager. CSQ Experience Platform guidance Throughout the documentation, code samples highlight differences between standalone and CSQ Experience Platform integrations.  1. [Update the SDK package to 1.10.0 or later](../#install-the-sdk). 2. Replace your current `CSQ.start()` or `CSQ.start(environmentID:)` call with the `dataSourceID` provided by your Customer Success Manager. This links your app to the CSQ Experience Platform data source. **AppDelegate.swift** ```swift CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 3. Review changes [introduced in 1.10.0](#1100---20260504) which notably removes support for several Product Analytics options. ## 1.12.2 - 2026.08.06 Experience Analytics * Update Experience Analytics SDK version to `4.52.1`: * **Analytics** * Improved reliability of exposure rate and scroll rate. * **Session Replay** * **Bug fix:** fixed SwiftUI image foreground color issues. * **Bug fix:** fixed an issue where the keyboard was sometimes not displayed. * **Bug fix:** fixed a rare crash related to SwiftUI. ## 1.12.0 - 2026.07.31 Experience Analytics * Update Experience Analytics SDK version to `4.52.0`: * Bug fixes and performance improvements. Product Analytics * Update Product Analytics Core SDK version to `0.9.2` * Update Product Analytics Autocapture SDK version to `0.10.2` ## 1.11.2 - 2026.07.27 Experience Analytics Deprecated version This version is deprecated. Upgrade to the [latest version](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/). * Update Experience Analytics SDK version to `4.51.2`: * **Webviews** * **Bug fix:** fixed a synchronisation issue that could result in a "Webview Not Tracked" in the Session Replay Player * **Bug fix:** fixed an issue where coming back from background into a webview would result in a "Webview Not Tracked" in the Session Replay Player ## 1.11.1 - 2026.07.20 Experience Analytics Deprecated version This version is deprecated. Upgrade to the [latest version](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/). * Update Experience Analytics SDK version to `4.51.1`: * Re-signed the release artefacts with a new valid certificate to resolve a code-signing validation failure (`CSSMERR_TP_CERT_REVOKED`). No functional changes. ## 1.11.0 - 2026.06.05 Experience Analytics * Update Experience Analytics SDK version to `4.51.0`: * **Session Replay** * Improve stability when calling APIs from background threads. * Fix harmonized masking behavior for fully SwiftUI-based apps. * Use the unified SDK version for full masking rules. * **Analytics** * A more explicit message is displayed when the screenshot size exceeds server-side limit Product Analytics * Update Product Analytics Core SDK version to `0.9.1` ## 1.10.0 - 2026.05.04 Experience Analytics * Update Experience Analytics SDK version to `4.50.0`: * The Session timeout definition changes from "30 minutes after being in background" to **30 minutes after last event**. See [Session definition](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/data-collection/#session-definition). Product Analytics * Update Product Analytics Autocapture SDK version to `0.11.0` * Update Product Analytics Core SDK version to `0.9.0` * Update Product Analytics Notification SDK version to `0.9.0` ### Configuration **API update:** `CSQ.configureProductAnalytics()` is now deprecated in favor of use `CSQ.start()` which combines SDK configuration and initialization in a single call: **AppDelegate.swift** ```swift CSQ.configureProductAnalytics( environmentID: "YOUR_ENVIRONMENT_ID", additionalOptions: [ // ... ] ) CSQ.start() CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ... ] ) ``` ### Options **Added:** `.sessionReplayAutoStart` — set to `false` to disable automatic Session Replay start and control it manually. Defaults to `true`. ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .sessionReplayAutoStart: false ] ) ``` **Renamed:** `.enableUIKitAutocapture` is now `.enableNativeAutocapture`: ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .enableUIKitAutocapture: true, .enableNativeAutocapture: true, ] ) ``` **Removed:** `.captureVendorID`, `.captureAdvertiserID`, `.clearEventPropertiesOnNewUser`, `.messageBatchByteLimit`, `.messageBatchMessageLimit`, `.resumePreviousSession`, `.pruningLookBackWindow`, `.disableScreenviewForwardToDXA`, `.disableScreenviewForwardToPA`, `.interactionHierarchyCaptureLimit`, `.disableInteractionTextCapture`, and `.disableInteractionAccessibilityLabelCapture` are no longer available. Remove them from your `CSQ.start()` call if present: ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .captureVendorID: true, .captureAdvertiserID: true, .clearEventPropertiesOnNewUser: true, .messageBatchByteLimit: 200_000, .messageBatchMessageLimit: 100, .resumePreviousSession: true, .pruningLookBackWindow: 6, .disableScreenviewForwardToDXA: true, .disableScreenviewForwardToPA: true, .interactionHierarchyCaptureLimit: 5, .disableInteractionTextCapture: true, .disableInteractionAccessibilityLabelCapture: true, ] ) ``` ## 1.6.4 - 2026.07.20 Experience Analytics * Update Experience Analytics SDK version to `4.46.4`: * Re-signed the release artefacts with a new valid certificate to resolve a code-signing validation failure (`CSSMERR_TP_CERT_REVOKED`). No functional changes. ## 1.6.3 - 2026.04.10 Experience Analytics * Update Experience Analytics SDK version to `4.46.3`: **Session Replay** * Improved performance of view hierarchy processing, reducing CPU usage. * Fixed a threading issue that could cause occasional crashes. * Fixed an issue where some images could be missing in replays. **Analytics** * Improved runtime stability **Errors** * Enhanced tracking of initial crashes after application installation. ## 1.6.2 - 2026.03.23 Experience Analytics * Update Experience Analytics SDK version to `4.46.2`: **Session Replay** * Fixed a crash related to SVG images when harmonized masking is enabled **Analytics** * Fixed an issue where a screenshot capture would cause the app to become unresponsive ## 1.6.1 - 2026.03.05 Experience Analytics * Update Experience Analytics SDK version to `4.46.1`: **Analytics** * Zoning / Heatmap: Add support for SwiftUI `drawingGroup` **Session Replay** * Fix a protobuf serialization crash * Fix a crash related to `NSAttributedString` encoding ## 1.6.0 - 2026.02.19 Experience Analytics * Update Experience Analytics SDK version to `4.46.0`: **Session Replay** * Improved session synchronization between Session Replay and Product Analytics * Enhance playback reliability when using `stopTracking()` followed by `resumeTracking()` * Strengthen playback stability when `optOut()` is triggered * Fix nil replay link when callback is subscribed before `start()` * Enhance stability when using `csMasking` SwiftUI modifier * Improve robustness against race conditions involving weak SwiftUI component references * Optimize handling of collections with unusually long durations **Errors** * Improve API error handling by ensuring URLs remain visible when invalid masking patterns are provided via `ErrorAnalysis.setURLMaskingPatterns()` **Analytics** * Improved Zoning metrics accuracy for some custom SwiftUI components * Fixed an issue where a screenshot captures would fail for React Native applications Product Analytics * Update Product Analytics Notification SDK version to `0.8.3` ## 1.5.5 - 2025.12.29 Experience Analytics * Update Experience Analytics SDK version to `4.45.6`: **Session Replay** * Fix a crash due to infinite recursion when a sublayer references the parent view as delegate (issue observed in CorePlot) ## 1.5.4 - 2025.12.22 Experience Analytics * Update Experience Analytics SDK version to `4.45.5`: ## 1.5.3 - 2025.12.12 Experience Analytics * Update Experience Analytics SDK version to `4.45.4`: ## 1.5.2 - 2025.12.08 Experience Analytics * Update Experience Analytics SDK version to `4.45.3` Product Analytics * Update Product Analytics Autocapture SDK version to `0.10.1` * Update Product Analytics Core SDK version to `0.8.8`: * Update Product Analytics Notification SDK version to `0.8.1`: ## 1.5.1 - 2025.11.27 Experience Analytics * Update Experience Analytics SDK version to `4.45.1`: ## 1.5.0 - 2025.11.14 Experience Analytics * Update Experience Analytics SDK version to `4.45.0`: **Analytics** * Fixed a crash related to Zoning and Heatmap data collection on iOS 26 devices **Session Replay** * Fixed a crash related to gesture capture on iOS 26 devices * Fixed an issue where the background color of an Image wouldn’t be correctly rendered * Fixed a protobuf serialization crash on iOS 26 devices * Performance improvement on iOS 26 devices ## 1.4.2 - 2025.10.29 Experience Analytics * Update Experience Analytics SDK version to `4.44.3`: **Session Replay** * Fixed a rare crash related to gesture. ## 1.4.1 - 2025.10.28 Experience Analytics * Update Experience Analytics SDK version to `4.44.2`: **Session Replay** * Fixed a crash related to `AVPlayerViewController`. Product Analytics * Update Product Analytics Autocapture SDK version to `0.9.1`: * Fixed a crash when calling `AttributedString(localized:)` with an interpolated string. * Taps inside `WKWebView` are now ignored by default because they don't contain meaningful data and produce noise when integrating with tag capture. To restore capture on a specific view, use `webView.heapIgnoreInteractions = false`. ## 1.4.0 - 2025.10.22 **Webviews** The One WebView Tag feature is now available in controlled general availability. It brings key Product Analytics features — Identity, User Properties, Hierarchy, and Target Text — to WebViews, enabling unified Product Analytics and Experience Analytics. To gain access, contact your Customer Success Manager to be added to the eligibility list. ## 1.3.1 - 2025.10.17 Experience Analytics * Update Experience Analytics SDK version to `4.44.1`: **Core SDK** * Fix an issue with the SDK internal Codable conformance extension for NSTextAlignment. **Analytics** * Heatmaps: Fix an issue where some taps would be inaccurate on iOS 26 devices ## 1.3.0 - 2025.10.14 Experience Analytics * Update Experience Analytics SDK version to `4.44.0`: **Analytics** * Improved iOS 26 support for Zoning and Heatmap analysis * ⚠️ Starting with iOS 26: Reliable targets are compatible with UIKit `accessibilityIdentifier` only. Read more at [Reliable targets](https://docs.contentsquare.com/en/ios/collected-data-points/#reliable-targets) * Improved data collection on segmented controls **Session Replay** * Improved iOS 26 support to display correctly text and images on SwiftUI views for apps built with Xcode 26 * Fix a crash related to bitmap rendering Product Analytics * Update Product Analytics Core SDK version to `0.8.7`: * SDK is now built with Xcode 16.0. * Internal improvements for autocapture. ## 1.2.1 - 2025.09.24 Experience Analytics * Update Experience Analytics SDK version to `4.43.3`: **Session Replay** * Fixed a bug where gradient backgrounds were not properly collected for React Native **Analytics** * Heatmaps: Fixed a crash related to frame computations ## 1.2.0 - 2025.09.12 Product Analytics * Update Product Analytics Autocapture SDK version to `0.9.0`: * **SwiftUI Autocapture** * Our Autocapture SDK now includes support for SwiftUI Experience Analytics * Update Experience Analytics SDK version to `4.43.2`: * **Core SDK** * Improved internal feature flag stability * **Session Replay** * Fixed an issue where SwiftUI images were missing from the replay on iOS 26 devices. ## 1.1.0 - 2025.08.06 Experience Analytics * Update Experience Analytics SDK version to `4.43.0`: * **Session Replay** * Image/Text masking configuration in the CSQ Console * Support Event Triggered Replay ## 1.0.1 - 2025.07.22 Experience Analytics * Update Experience Analytics SDK version to `4.42.4`: * **Session Replay** * Fix an issue related to CSInApp on iPad * Support for React Native New Architecture Text * Improved Session Replay screen change consistency on Capacitor apps * **WebView** * Fix an issue related to config ## 1.0.0 - 2025.06.26 Initial release of the CSQ SDK. * Introduces the unified CSQ API, which combines Product Analytics, Experience Analytics, and Monitoring features into a single, cohesive library. * This initial release includes: * Experience Analytics SDK version `4.42.1`. * Product Analytics Core SDK version `0.8.6`. * Product Analytics Autocapture SDK version `0.8.0`. * Product Analytics Notification Autocapture SDK version `0.8.0`. Upgrade to CSQ SDK 1.+ Looking to upgrade from CSQ SDK 0.x to the latest? See the [upgrade guide](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-heap-and-cs-sdk/). ## 0.11.4 - 2026.07.20 * Update Experience Analytics SDK to [`4.46.4`](https://docs.contentsquare.com/en/ios/changelog/#4464---20260720). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.3` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.11.3 - 2026.04.10 * Update Experience Analytics SDK to [`4.46.3`](https://docs.contentsquare.com/en/ios/changelog/#4463---20260410). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.3` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.11.2 - 2026.03.23 * Update Experience Analytics SDK to [`4.46.2`](https://docs.contentsquare.com/en/ios/changelog/#4462---20260320). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.3` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.11.1 - 2026.03.05 * Update Experience Analytics SDK to [`4.46.1`](https://docs.contentsquare.com/en/ios/changelog/#4461---20260305). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.3` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.11.0 - 2026.02.16 * Update Experience Analytics SDK to [`4.46.0`](https://docs.contentsquare.com/en/ios/changelog/#4460---20260213). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.10.4 - 2025.12.29 * Update Experience Analytics SDK to [`4.45.6`](https://docs.contentsquare.com/en/ios/changelog/#4456---20251230). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.10.3 - 2025.12.22 * Update Experience Analytics SDK to [`4.45.5`](https://docs.contentsquare.com/en/ios/changelog/#4455---20251219). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.10.2 - 2025.12.12 * Update Experience Analytics SDK to [`4.45.4`](https://docs.contentsquare.com/en/ios/changelog/#4454---20251212). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.10.1 - 2025.12.10 * Update Experience Analytics SDK to [`4.45.3`](https://docs.contentsquare.com/en/ios/changelog/#4453---20251205). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.10.0 - 2025.11.14 * Update Experience Analytics SDK to [`4.45.0`](https://docs.contentsquare.com/en/ios/changelog/#4450---20251114). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.9.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.9.2 - 2025.10.28 * Update Experience Analytics SDK to [`4.44.2`](https://docs.contentsquare.com/en/ios/changelog/#4442---20251024). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.9.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.9.1 - 2025.10.17 * Update Experience Analytics SDK to [`4.44.1`](https://docs.contentsquare.com/en/ios/changelog/#4441---20251017). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.9.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.9.0 - 2025.10.07 * Update Experience Analytics SDK to [`4.44.0`](https://docs.contentsquare.com/en/ios/changelog/#4440---20251006). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.9.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.8.1 - 2025.09.25 * Update Experience Analytics SDK to [`4.43.3`](https://docs.contentsquare.com/en/ios/changelog/#4433---20250924). * Update Product Analytics [Core `0.8.6` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.9.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.8.0 - 2025.09.11 * Update Experience Analytics SDK to [`4.43.2`](https://docs.contentsquare.com/en/ios/changelog/#4432---20250819). * Update Product Analytics [Core `0.8.6` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.9.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) (includes SwiftUI Autocapture) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.7.0 - 2025.08.01 * Update Experience Analytics SDK to [`4.43.0`](https://docs.contentsquare.com/en/ios/changelog/#4430---20250731). * Update Product Analytics [Core `0.8.6` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.6.3 - 2025.06.20 * Update Experience Analytics SDK to [`4.42.1`](https://docs.contentsquare.com/en/ios/changelog/#4421---20250617). * Update Product Analytics [Core `0.8.5` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.6.2 - 2025.05.22 * Update Product Analytics [Core `0.8.5` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.6.1 - 2025.05.19 * Update Experience Analytics SDK to [`4.41.3`](https://docs.contentsquare.com/en/ios/changelog/#4413---20250516). * Update Product Analytics [Core `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.6.0 - 2025.04.02 * Update Experience Analytics SDK to [`4.41.0`](https://docs.contentsquare.com/en/ios/changelog/#4410---20250402). * Update Product Analytics [Core `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.5.2 - 2025.03.12 * Update Experience Analytics SDK to [`4.40.2`](https://docs.contentsquare.com/en/ios/changelog/#4402---20250220). * Update Product Analytics [Core `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.5.1 - 2025.02.21 * Update Experience Analytics SDK to [`4.40.1`](https://docs.contentsquare.com/en/ios/changelog/#4401---20250218). * Update Product Analytics [Core `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.5.0 - 2025.02.14 * Update Experience Analytics SDK to [`4.40.0`](https://docs.contentsquare.com/en/ios/changelog/#4400---20250212). * Update Product Analytics [Core `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.4.0 - 2025.01.15 * Update Experience Analytics SDK to [`4.39.0`](https://docs.contentsquare.com/en/ios/changelog/#4390---20250109). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.3.1 - 2024.12.06 * Update Experience Analytics SDK to [`4.38.2`](https://docs.contentsquare.com/en/ios/changelog/#4382---20241128). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.3.0 - 2024.10.25 * Update Experience Analytics SDK to [`4.38.0`](https://docs.contentsquare.com/en/ios/changelog/#4380---20241025). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.2.3 - 2024.10.25 * Update Experience Analytics SDK to [`4.37.3`](https://docs.contentsquare.com/en/ios/changelog/#4373---20241022). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.2.2 - 2024.10.18 * Update Experience Analytics SDK to [`4.37.2`](https://docs.contentsquare.com/en/ios/changelog/#4372---20241015). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.2.1 - 2024.10.14 * Update Experience Analytics SDK to [`4.37.1`](https://docs.contentsquare.com/en/ios/changelog/#4371---20241001). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.2.0 - 2024.10.11 * Update Experience Analytics SDK to [`4.37.0`](https://docs.contentsquare.com/en/ios/changelog/#4370---20240927). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.1.1 - 2024.09.27 * Update Experience Analytics SDK to [`4.36.1`](https://docs.contentsquare.com/en/ios/changelog/#4361---20240920). * Update Product Analytics [Core `0.7.1` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.1.0 - 2024.09.06 This release marks the introduction of the CSQ SDK which brings together Product Analytics, Experience Analytics, and Monitoring features. From this version onwards, the SDK releases follow a new versioning scheme. * Update Experience Analytics SDK to [`4.36.0`](https://docs.contentsquare.com/en/ios/changelog/#4360---20240906). * Update Product Analytics [Core `0.7.1` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare iOS changelog","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/changelog/","inLanguage":"en","dateModified":"2026-07-08T17:11:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: SDK API reference - iOS description: SDK commands reference including signature, parameter descriptions, and examples lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/command-reference/ md: https://docs.contentsquare.com/en/csq-sdk-ios/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). ```swift 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. ```swift 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`. ```swift CSQ.identify("userIdentity") ``` #### Parameters * #### identity  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. ```swift 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. This is an identifier from Product Analytics by default or Experience Analytics if PA is not active. ```swift let 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. ```swift let sessionID = CSQ.metadata.sessionID ``` #### CSQ.metadata.projectID Project identifier for Experience Analytics. ```swift let projectID = CSQ.metadata.projectID ``` #### CSQ.metadata.environmentID Environment identifier for Product Analytics. ```swift let environmentID = CSQ.metadata.environmentID ``` #### CSQ.metadata.sessionReplayURL URL of current Session Replay. ```swift let sessionReplayURL = CSQ.metadata.sessionReplayURL ``` #### CSQ.metadata.identity Identity associated with the user by calling [`identify()`](#csqidentify). ```swift let identity = CSQ.metadata.identity ``` ### CSQ.metadata.onChange { metadata in } **Added in:** `1.0.0` A block triggered each time user information is updated. For example when `sessionReplayURL` becomes available or `userID` updates. Set this block to subscribe to the updates. Contentsquare will call this block with updated metadata. Note This may not trigger on changes to Product Analytics data. ```swift CSQ.metadata.onChange { metadata in // Handle information change } ``` #### Parameters * #### metadata  Metadata   Metadata associated with the current user and project. ## Logging ### CSQ.debug.logLevel **Added in:** `1.0.0` Gets or sets the current log level. ```swift CSQ.debug.logLevel = .debug ``` #### Parameters * #### level  Enum (CSQ.Log.Level)   Possible values: `none`, `trace`, `debug`, `info`, `warn`, `error`, or `important`. ### CSQ.debug.logChannel Product Analytics | **Added in:** `1.0.0` Gets or sets the `LogChannel` to which send log messages. ```swift CSQ.debug.logChannel = customLogChannel ``` #### Parameters * #### LogChannel  interface   The interface where log messages will be routed. ### LogChannel.printLog() Product Analytics | **Added in:** `1.0.0` Implement this function to route SDK logs to another location such as CocoaLumberjack, SwiftyBeaver, or similar logging libraries.\ The default implementation routes all logs through `os_log`. ```swift class CustomLogChannel: LogChannel { func printLog(logLevel: Log.Level, message: () -> String, source: String?, file: String, line: UInt) { // your implementation } } ``` #### Parameters * No parameters. ## 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` object, representing a key-value pair that is scoped to the session. ```swift let var1 = DynamicVar(key: "key1", value: "value1") let var2 = DynamicVar(key: "key2", value: 2) CSQ.addDynamicVar(var1) CSQ.addDynamicVar(var2) ``` #### Parameters * #### dVar  DynamicVar   The dynamic variable * #### key  String (<= 512 chars)   Dynamic variable key * #### intValue  UInt32   Dynamic variable integer value * #### stringValue  String   Dynamic variable string value ### CSQ.addUserProperties() Product Analytics | **Added in:** `1.0.0` Add a collection of properties to be associated with the current user. ```swift CSQ.addUserProperties(["propertyKey"": "propertyValue"]) ``` #### Parameters * #### properties  \[String: PropertyValue]   A dictionary of user properties. `PropertyValue` can be `String`, `Substring`, `Bool`, `Double`, `Float`, `Int`, `Int64`, `Int32`, `Int16` or `Int8`. ### CSQ.addEventProperties() Product Analytics | **Added in:** `1.0.0` Add a collection of properties to be associated with all future events. ```swift CSQ.addEventProperties(["propertyKey": "propertyValue"]) ``` #### Parameters * #### properties  \[String: PropertyValue]   A dictionary of event properties. `PropertyValue` can be `String`, `Substring`, `Bool`, `Double`, `Float`, `Int`, `Int64`, `Int32`, `Int16` or `Int8`. ### CSQ.removeEventProperty() Product Analytics | **Added in:** `1.0.0` Removes a single property from the collection of event-wide properties. ```swift CSQ.removeEventProperty("propertyKey") ``` #### Parameters * #### key  String   The key of the property to remove. ### CSQ.clearEventProperties() Product Analytics | **Added in:** `1.0.0` Removes all event-wide properties. ```swift CSQ.clearEventProperties() ``` ## View Tracking ### UIScrollView\.excludeFromExposureMetrics() Experience Analytics | **Added in:** `1.0.0` Exclude a scrollable view or subclass from Exposure Metric computations. ```swift let scrollView = UIScrollView() scrollView.excludeFromExposureMetrics() ``` ## CSInApp ### CSQ.handle() Experience Analytics | **Added in:** `1.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](../../experience-analytics/in-app-features/). ```swift CSQ.handle(url: <CSInAppURL>)) ``` #### Parameters * #### url  URL   See [https://developer.apple.com/documentation/foundation/url ↗](https://developer.apple.com/documentation/foundation/url) ### CSQ.csInApp Experience Analytics | **Added in:** `1.0.0` Boolean to manually activate or deactivate in-app features. When `CSQ.csInApp = true`, the in-app function is activated automatically at app start. ```swift CSQ.csInApp = true ``` ## Interoperability ### CSQ.registerWebView() Experience Analytics | **Added in:** `1.0.0` Register a webview for tracking. ```swift let webView = WKWebView() CSQ.registerWebView(webView) ``` #### Parameters * #### webView  WKWebView   The webview to register for tracking. ### CSQ.unregisterWebView() **Added in:** `1.0.0` Unregister a webview for tracking. ```swift CSQ.unregisterWebView(webView) ``` #### Parameters * #### webView  WKWebView   The webview to unregister from tracking. ## Event Tracking ### CSQ.trackTransaction() Experience Analytics | **Added in:** `1.0.0` Send a transaction. ```swift let transaction = Transaction(id: "transactionId", total: 100.0, currency: .usd) CSQ.trackTransaction(transaction) ``` #### Parameters * #### Transaction  Transaction   The transaction object to be sent. Initialized with id, total, and ISO 4217 currency enum. ### CSQ.trackScreenview() **Added in:** `1.0.0` Send a screen view with or without custom variables. Requires Experience Analytics to be started. ```swift CSQ.trackScreenview(name: "ScreenName", cvars: [CustomVar(index: 1, name: "name", value: "value")]) ``` #### Parameters * #### name  String   The name of the screen. * #### cvars  CustomVar\[] (optional)   An array of custom variables to attach to the screen view. * #### index  UInt32   Custom variable index * #### key  String (<= 512 chars)   Custom variable key * #### 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. ```swift CSQ.trackEvent(name: String, properties: ["propertyKey": "propertyValue"]?) ``` #### Parameters * #### name  String   The name of the event to be tracked. * #### properties  \[String: PropertyValue>] (optional)   Optional properties to associate with the event. `PropertyValue` can be `String`, `Substring`, `Bool`, `Double`, `Float`, `Int`, `Int64`, `Int32`, `Int16` or `Int8`. ## Surveys ### CSQ.triggerSurvey() Experience Analytics Voice of Customer | **Added in:** `1.0.0` Triggers a survey by referencing a predefined trigger name. This method allows your mobile app to trigger surveys at specific moments in the user journey. Triggers act as flexible placeholders that are not bound to individual surveys, enabling your business team to assign or update surveys later without requiring code changes. ```swift CSQ.triggerSurvey(triggerName) ``` #### Parameters * #### triggerName  String   The name of the trigger associated with the survey. This should match the trigger name configured in the Contentsquare platform. #### Example ```swift // Trigger a survey after a purchase is completed CSQ.triggerSurvey("purchase-complete") ``` ## Error tracking ### CSQ.setUrlMaskingPatterns() Experience Analytics | **Added in:** `1.0.0` Sets URL masking patterns. ```swift CSQ.setUrlMaskingPatterns(["pattern1", "pattern2"]) ``` #### Parameters * #### patterns  \[String]   A list of URL patterns to mask. ### CSQ.onCrashReporterStart() Experience Analytics | **Added in:** `1.0.0` Trigger a callback when the Contentsquare Crash Reporter is initialized. ```swift CSQ.onCrashReporterStart { enabled in // do your work here, e.g. start Firebase Crashlytics } ``` #### Parameters * #### onCrashReporterStart  (enabled: Bool -> Void)   Closure triggered when crash reporter is started. Passes a boolean indicating if crash reporter is actually enabled. ### CSQ.sendUserIdentifier() Experience Analytics | **Added in:** `1.0.0` Associate the user identifier to the session. ```swift CSQ.sendUserIdentifier("any_identifier") ``` #### Parameters * #### userIdentifier  String   The user identifier to track. Should be max 100 characters long. ### CSQ.trackNetworkMetric() Experience Analytics | **Added in:** `1.0.0` Track network metrics. ```swift let networkMetric = NetworkMetric(url: "https://example.com", httpMethod: "GET") CSQ.trackNetworkMetric(networkMetric) ``` #### Parameters * #### networkMetric  NetworkMetric   NetworkMetric object for a network request to collect HTTP network errors. ## Personal Data/Masking ### CSQ.ignoreInteractions() **Added in:** `1.0.0` Ignore interactions for a specific view. ```swift CSQ.ignoreInteractions(view) ``` #### Parameters * #### view  UIView   [https://developer.apple.com/documentation/uikit/uiview ↗](https://developer.apple.com/documentation/uikit/uiview) ### UIView\.csqIgnoreInteractions UIKit IBInspectable | **Added in:** `1.0.0` Ignore interactions for a specific view. ```swift view.csqIgnoreInteractions = true ``` #### Parameters * No parameters. ### View\.csqIgnoreInteractions() Product Analytics SwiftUI | **Added in:** `1.2.0` Ignore interactions for a specific view. ```swift Text("Hello World!").csqIgnoreInteractions(shouldIgnore: true) ``` #### Parameters * #### shouldIgnore  Bool   Whether to ignore interactions. ### CSQ.setDefaultMasking() Experience Analytics | **Added in:** `1.0.0` Set the default masking state.\ All UIView elements, their subclasses and SwiftUI components are fully masked by default. ```swift CSQ.setDefaultMasking(true) ``` #### Parameters * #### masked  Bool   The default masking state to be set. ### CSQ.mask(UIView) **Added in:** `1.0.0` Mask a view's content. ```swift CSQ.mask(view) ``` #### Parameters * #### view  UIView   The view which content will be masked. ### CSQ.unmask(UIView) **Added in:** `1.0.0` Unmask a view's content. ```swift CSQ.unmask(view) ``` #### Parameters * #### view  UIView   The view which content will be unmasked. ### UIView\.csqMaskContents UIKit IBInspectable | **Added in:** `1.0.0` Mask the content of a view. ```swift view.csqMaskContents = true ``` #### Parameters * No parameters. ### View\.csqMaskContents SwiftUI | **Added in:** `1.0.0` Mask the content of a view. ```swift Text("Hello World!").csqMaskContents(true) ``` #### Parameters * #### enable  Bool   Whether to mask the content of the view. ### CSQ.mask(`viewsOfType: UIView.Type`) Experience Analytics | **Added in:** `1.0.0` Mask content for views of a specific type. ```swift CSQ.mask(viewsOfType: UIView.Type) ``` #### Parameters * #### viewsOfType  UIView\.Type   The class type of the view whose content will be masked. ### CSQ.unmask(`viewsOfType: UIView.Type`) **Added in:** `1.0.0` Unmask content for views of a specific type. ```swift CSQ.unmask(viewsOfType: UIView.self) ``` #### Parameters * #### viewsOfType  UIView\.Type   The class type of the view whose content will be unmasked. ### CSQ.maskTexts() **Added in:** `1.0.0` Mask all texts. ```swift CSQ.maskTexts(true) ``` #### Parameters * #### mask  Bool   Whether to mask text. ### CSQ.maskImages() Experience Analytics | **Added in:** `1.0.0` Mask images. ```swift CSQ.maskImages(true) ``` #### Parameters * #### mask  Bool   Whether to mask images. ### CSQ.maskTextInputs() Experience Analytics | **Added in:** `1.0.0` Mask text input fields. ```swift CSQ.maskTextInputs(true) ``` #### Parameters * #### mask  Bool   Whether to mask text inputs. ### UIView\.csqIgnoreInnerHierarchy Product Analytics UIKit IBInspectable | **Added in:** `1.0.0` If set on a view or view controller, all touches inside that control will be attributed to it rather than child views. This can be helpful in blocking sensitive parts of an interaction and keeping implementation details out of a view hierarchy. For example, Contentsquare uses this property internally to suppress inner touches on `UIDatePicker`. ```swift let view = UIView() view.csqIgnoreInnerHierarchy = true ``` ## SDK Initialization and Management ### CSQ.configureProductAnalytics() Deprecated Product Analytics | **Added in:** `1.0.0` SDK configuration method for Product Analytics. Use [`CSQ.start()`](#csqstart) instead, which combines configuration and initialization in a single call. ### CSQ.start() **Added in:** `1.0.0` Start the SDK. This method combines configuration and initialization in a single call. There are three overloads depending on whether you want Experience Analytics, Product Analytics, or CSQ Experience Platform. **Experience Analytics only:** ```swift CSQ.start() ``` **Product Analytics (optionally with Experience Analytics extension) with `environmentID`:** ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .enableNativeAutocapture: true ] ) ``` **CSQ Experience Platform with `dataSourceID`:** ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ .enableNativeAutocapture: true ] ) ``` #### Parameters * #### environmentID  String (optional)   Your Product Analytics environment ID. * #### dataSourceID  String (optional)   Your CSQ Experience Platform data source ID. Enables both Product Analytics and Experience Analytics with a single identifier. * #### options  \[AnalyticsOption: Any] (optional)   SDK [configuration options](#sdk-configuration-options). ### CSQ.stop() **Added in:** `1.0.0` Stop all activity from the SDK.\ Once run no requests, telemetry collection, or logs will be generated. ```swift CSQ.stop() ``` ### CSQ.pauseTracking() **Added in:** `1.0.0` Pause all tracking features. ```swift CSQ.pauseTracking() ``` ### CSQ.resumeTracking() **Added in:** `1.0.0` Resume all tracking features. ```swift CSQ.resumeTracking() ``` #### Parameters * No parameters. ### CSQ.startSessionReplay() **Added in:** `1.10.0` Enable and eventually start Session Replay independently of other CSQ SDK features, allowing for on-demand collection. To use this functionality, disable the automatic start of Session Replay at SDK initialization using the [`.sessionReplayAutoStart`](#sessionreplayautostart) option. ```swift CSQ.startSessionReplay() ``` ### CSQ.stopSessionReplay() **Added in:** `1.10.0` Stop Session Replay immediately. ```swift CSQ.stopSessionReplay() ``` ## SDK configuration options CSQ SDK options passed to [`CSQ.start()`](#csqstart). ```swift CSQ.start( // optional: environmentID: String | dataSourceID: String options: [ .uploadInterval: TimeInterval, .baseURL: URL, // EU: "https://mh.ba.contentsquare.net"; https://mh.bf.contentsquare.net (default) .disablePageviewAutocapture: Bool, .disablePageviewTitleAutocapture: Bool, .disableInteractionAutocapture: Bool, .enableNativeAutocapture: Bool, .enablePushNotificationAutocapture: Bool, .enablePushNotificationTitleAutocapture: Bool, .enablePushNotificationBodyAutocapture: Bool, .sessionReplayAutoStart: Bool ] ) ``` ### `uploadInterval` The interval in seconds between event batch uploads. Accepts a `TimeInterval` (Double) value. ### `baseURL` The CSQ API endpoint to use: * `https://mh.ba.contentsquare.net` — EU-hosted environments * `https://mh.bf.contentsquare.net` — all other environments (default) ### `disablePageviewAutocapture` Whether source pageview events will be auto-captured. Defaults to `false`. ### `disablePageviewTitleAutocapture` Whether autocapture of pageview titles is disabled. Defaults to `false`. ### `disableInteractionAutocapture` Disables autocapture of touch events on UIKit views. Defaults to `false`. ### `enableNativeAutocapture` Whether to enable autocapture of native UIKit view interaction events. Defaults to `false`. ### `enablePushNotificationAutocapture` Whether the SDK will auto capture interaction events on notifications. Defaults to `false`. ### `enablePushNotificationTitleAutocapture` Whether to capture the title of the notification where an interaction was performed. `enablePushNotificationAutocapture` must be set to `true`. Defaults to `false`. ### `enablePushNotificationBodyAutocapture` Whether to capture the body text of the notification where an interaction was performed. `enablePushNotificationAutocapture` must be set to `true`. 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. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"SDK API reference","description":"SDK commands reference including signature, parameter descriptions, and examples","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/command-reference/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Error Analysis - iOS description: How to use Contentsquare Error Analysis in your iOS apps lastUpdated: 07 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/error-analysis/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/error-analysis/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. Error Analysis automatically captures API errors and network failures in your app and surfaces them in the Contentsquare platform. ## Prerequisites ### Screen tracking implemented Tracking will start at the 1st screenview event, it is required to have screen tracking implemented. Make sure to follow the [iOS Track](../track-screens/) screens sections. ### Reminder about User consent If you are in the process of implementing the SDK for the 1st time (or choose to take this update as an opportunity to review your Privacy related implementation), make sure to follow the [iOS Privacy](../privacy/) section and use the [Opt-in API](../privacy/#opt-in) to get the user consent, otherwise no data will be collected. ## API errors ### Automatic collection API errors automatically collects failed network requests that use `URLSession`. ### Disable automatic collection Automatic collection can be disabled by setting `CSDisableAPIErrorsAutoCollection` to `YES` in the Info.plist. ### Add custom monitoring for specific network requests The API errors automatically collects most network requests for your app. However, some requests might not be collected or you might use a different library to make network requests. In these cases, you can use the following API `HTTPMetric` to manually collect data. ```swift guard let url = URL(string: "https://www.apple.com") else { return } let request: URLRequest = URLRequest(url: url) let metric = HTTPMetric(request: request) let session = URLSession(configuration: .default) let dataTask = session.dataTask(with: request) { (urlData, response, error) in if let httpResponse = response as? HTTPURLResponse { metric.setStatusCode(httpResponse.statusCode) } CSQ.trackNetworkMetric(metric) } dataTask.resume() ``` ### Removing Personal Data in request URL path By default, the API Errors feature collects the URL path of the failed API requests. To prevent the collection of Personal Data in the URL path, you can rewrite the request URL path with the `setURLMaskingPatterns` SDK API. ```swift /// This API must be called at App launch. public static func setURLMaskingPatterns(_ patterns: [String]) ``` Replace a step of the path - meaning between two slashes (/) - containing Personal Data with a variable: * `:user_id` becomes CS\_ANONYMIZED\_USER\_ID * `:address` becomes CS\_ANONYMIZED\_ADDRESS #### Example ```swift ErrorAnalysis.setURLMaskingPatterns([ "https://www.contentsquare.com/users/:user_id/address/:address" ]) ``` | URL before masking | URL after masking | | - | - | | `https://www.contentsquare.com/users/123/address/castle+black` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS` | | `https://www.contentsquare.com/users/123/address/castle+black/reset-token/abcdef123456` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS/reset-token/abcdef123456` | ### Validate API error integration #### Validate API error collection is enabled If in-app features are enabled, a log should appear indicating if API errors is enabled or disabled: ```plaintext CSLIB ℹ️ Info: API Errors is enabled ``` #### Validate API error collection If you have [logging enabled](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/in-app-features/#debugging-and-logging), you will see API errors: * Displayed in [Contentsquare Log Visualizer](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/in-app-features/#viewing-logs-in-the-contentsquare-platform). * As an Info log: ```plaintext CSLIB ℹ️ Info: API Error - GET 401 https://api.client.com ``` ### How API errors works #### Initialization The way our SDK works is by auto-starting with the application launch and automatically collects failed network requests that use `URLSession`. #### Configuration Once started, our SDK fetches its config from our servers. It will start collecting data from network events if the API errors setting is enabled in the config (this is handled by the Contentsquare team). #### API errors collection The SDK monitors only the API errors with response code equal or above 400, and generates analytics data. These events are then locally stored, and eventually sent to our servers in batches. Warning To make sure API errors occurring at app launch are correctly tracked, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. See [when to send your first screenview](../track-screens/#when-to-send-your-first-screenview) for more details. #### Sending API errors data For each network error, a new event will be sent in analytics and Session Replay data. Check the following sections to learn more about how data is processed and sent: * [Analytics requests](../data-collection/#sending-data) * [Session Replay requests](../session-replay#requests) ### API Troubleshooting Details API errors troubleshooting details enables you to collect more information about API errors so you can troubleshoot errors faster. With this feature you will be able to see three types of additional API error details in the Event Stream of Session Replay. * The HTTP headers of the request and the response. * The body (the data sent by the request or received in the response). * The query parameters of the request endpoint (of the URL of the information you request for). Note This feature is only available for Experience Monitoring Mobile customers.\ Contact your CSM for more details on the validation and implementation process. See [API Troubleshooting Details ↗](https://support.contentsquare.com/hc/en-us/articles/37271885035537) for more details. ### Collected data points Only network calls with error (response code above 400) will be collected. Here is the list of data collected: * URL (without query strings) * HTTP method * Response code * Timestamp of the request * Timestamp of the response * HTTP headers of the request * HTTP headers of the response * HTTP body of the request * HTTP body of the response * Query parameters of the request endpoint ### Known limitations and recommendations #### Automatic collection limitations The auto collection doesn't work for the following methods: ```swift func data(for request: URLRequest) async throws -> (Data, URLResponse) func data(from url: URL) async throws -> (Data, URLResponse) func upload(for request: URLRequest, from bodyData: Data) async throws -> (Data, URLResponse) func upload(for request: URLRequest, fromFile fileURL: URL) async throws -> (Data, URLResponse) func download(for request: URLRequest) async throws -> (URL, URLResponse) func download(from url: URL) async throws -> (URL, URLResponse) func downloadTask(withResumeData: Data) -> URLSessionDownloadTask func downloadTask(withResumeData: Data, completionHandler: (URL?, URLResponse?, Error?) -> Void) -> URLSessionDownloadTask func streamTask(withHostName: String, port: Int) -> URLSessionStreamTask func streamTask(with: NetService) -> URLSessionStreamTask func webSocketTask(with: URL) -> URLSessionWebSocketTask func webSocketTask(with: URLRequest) -> URLSessionWebSocketTask func webSocketTask(with: URL, protocols: [String]) -> URLSessionWebSocketTask ``` **Workaround:** For the `async` methods, use the corresponding Contentsquare methods: ```swift try await URLSession.shared.cs.data(for: request) try await URLSession.shared.cs.data(from: url) try await URLSession.shared.cs.upload(for: request, from: data) try await URLSession.shared.cs.upload(for: request, fromFile: file) try await URLSession.shared.cs.download(for: request) try await URLSession.shared.cs.download(from: url) ``` For other methods, use the custom monitoring APIs. #### Conflict with Firebase Performance SDK on auto-collection API errors is compatible with Firebase Performance auto-collection, but the HTTP body from the response won't be collected by the Error Analysis SDK. **Workaround**: [Disable auto collection](#disable-automatic-collection) and use [API `HTTPMetric`](#add-custom-monitoring-for-specific-network-requests) to manually collect data. It may also not be compatible with other network auto collection tools. ## Crash Reporter ### Setup Firebase Crashlytics compatibility mode The Contentsquare Crash Reporter is compatible with [Firebase Crashlytics ↗](https://firebase.google.com/docs/crashlytics). You must initialize it before Firebase Crashlytics to make sure all crashes are reported. #### Basic Setup Call `onCrashReporterStart()` to launch Firebase Crashlytics after the Contentsquare Crash Reporter starts: ```swift CSQ.onCrashReporterStart { _ in FirebaseApp.configure() } ``` #### Integration with Firebase Crashlytics and Firebase Performance When using Firebase Crashlytics, [Firebase Performance ↗](https://firebase.google.com/docs/perf-mon), and the Contentsquare Crash Reporter, initializing Firebase Performance traces before all SDKs are fully initialized may lead to app crashes. Recommended setup: * Initialize Firebase Crashlytics first * Then initialize Contentsquare Crash Reporter * Trigger Firebase Performance traces only after `FirebaseApp.configure()` Reach out to your Contentsquare contact to learn more about potential alternatives. ### Upload dSYMs *"When Xcode compiles your source code into machine code, it generates a list of symbols in your app — class names, global variables, and method and function names. These symbols correspond to the file and line numbers where they're defined; this association creates a debug symbol"* [See Apple's documentation for more details ↗](https://developer.apple.com/documentation/xcode/building-your-app-to-include-debugging-information/). When an app crashes, the operating system collects diagnostic information about what the app was doing at the time of crash. Some of the most important parts of the crash report are presented as hexadecimal addresses. To translate those addresses into readable function names and line numbers from your source code, a process called symbolication is used. [See Apple's documentation for more details ↗](https://developer.apple.com/documentation/xcode/adding-identifiable-symbol-names-to-a-crash-report/). To symbolicate the crashes reported by a specific version of your app and make them readable, you need to provide the symbol files (dSYMs) that were generated when your app was built. #### Build your app with dSYMs Make sure Xcode is generating dSYMs for your app: 1. Open your project in Xcode. 2. Select the project file in the Xcode Navigator. 3. Select your main target. 4. Select the `Build Settings` tab and click `All` to show all the build settings. 5. Filter by `Debug Information Format`. 6. Set `Debug Information Format` to `DWARF with dSYM File` for all the build types you want to generate dSYMs. 7. Rebuild your main target. #### Locate dSYMs ##### Download dSYMs from the App Store If you build your main target using bitcode (`Bitcode Enabled` turned on in build settings) and you uploaded your app's symbols to the App Store, you need to download the dSYMs from the App Store: 1. Log in to [App Store Connect ↗](https://appstoreconnect.apple.com/login), then select `My Apps`. 2. Select your app from the grid. 3. Select the build you want to download a dSYM for. 4. Click `Build Details` > `Download dSYM`. In case you use bitcode to build your main target but you didn't upload your dSYMs to the App Store, you need to [find your dSYMs on your local machine](#find-dsyms-on-your-local-machine) and [restore hidden symbols using the BCSymbolMaps](#restore-hidden-symbols-using-bcsymbolmaps) Xcode generates. ##### Find dSYMs on your local machine You can find the dSYMs in the `.xcarchive` directory on disk: 1. In Xcode, open the Organizer window (*Window -> Organizer*). 2. Select your app from the list. 3. Control-click an archive and select `Show in Finder`. 4. A Finder window should appear. Control-click the `xcarchive` package and select `Show Package Contents`. 5. There should be a dSYMs directory that contains the dSYMs generated in Xcode's archiving process. If you use the `Download Debug Symbols` option from Xcode's organizer, the recompiled bitcode dSYMs are also downloaded to this directory. #### Restore hidden symbols using BCSymbolMaps Restoring hidden symbols using BCSymbolMaps is only required if you built your main target using bitcode (`Bitcode Enabled` turned on in build settings). If you used bitcode but downloaded the dSYMs from the App Store, the dSYMs will be recompiled and you can skip this step. To restore hidden symbols you can run the following command: ```shell dsymutil -symbol-map /path/to/archive/BCSymbolMaps /path/to/dsym.dSYM ``` #### Get project ID 1. Login to the Contentsquare platform on [https://app.contentsquare.com ↗](https://app.contentsquare.com) 2. Make sure to be on the right project 3. The project ID can be found in the URL query parameter `project`: `https://app.contentsquare.com/#/{MODULE_NAME}?project={PROJECT_ID}&hash={HASH}]` #### Get project credentials Follow the dedicated documentation from the Help Center to get the **client ID** and **client Secret**: [How to create API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/9292880837660). #### Use script to upload dSYMs To upload dSYMs to Error Analysis you need to use the provided `upload-symbols` script. You need to provide the path where the dSYM files are located as a positional argument, and the Project ID, Client ID and Client Secret either as keyword arguments or set them as environment variables. Additionally, you can use a proxy by specifying the proxy URL. Print more detailed logs by using the `--verbose` flag. | Key | Environment Key | | - | - | | --project-id | ERROR\_ANALYSIS\_PROJECT\_ID | | --client-id | ERROR\_ANALYSIS\_CLIENT\_ID | | --client-secret | ERROR\_ANALYSIS\_CLIENT\_SECRET | | --proxy | ERROR\_ANALYSIS\_PROXY\_URL | If both are provided, the keyword arguments will prevail over the environment variables. #### Set up Xcode to automatically upload dSYM files The following steps describe how to configure Xcode to automatically upload your dSYMs whenever you build your app. 1. Open your project's Xcode workspace, then select its project file in the left Project navigator. 2. From the TARGETS list, select your main build target. 3. Click the **Build Phases** tab, then complete the following steps so that Xcode can process your dSYMs and upload the files. 1. Click + > **New Run Script Phase**. Make sure this new Run Script phase is your project's last build phase; otherwise, dSYMs might not be ready. 2. Expand the new **Run Script** section. 3. In the script field (located under the Shell label), add the following run script. The `upload-symbols` script is located in the SPM checkout path for the SDK. Copy the following script. ```shell # Only upload symbols for App Store build. # Replace `Release` with the configuration used when uploading to the App Store. if [ "${CONFIGURATION}" != "Release" ]; then exit 0 fi ${BUILD_DIR%Build/*}SourcePackages/checkouts/CS_iOS_SDK_DYNAMIC/scripts/upload-symbols "${DWARF_DSYM_FOLDER_PATH}" --project-id "PROJECT_ID" --client-id "CLIENT_ID" --client-secret "CLIENT_SECRET" ``` In the **Input Files** section, make sure you have the paths for the locations of the following files: ```plaintext ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME} ``` ```plaintext ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME} ``` ```plaintext ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Info.plist ``` ```plaintext $(TARGET_BUILD_DIR)/$(EXECUTABLE_PATH) ``` Make sure `User Script Sandboxing` is set to NO in Xcode Build Settings. If you do not want to disable it, add the paths of all your dSYM files one by one in **Input Files**. #### Use fastlane to upload dSYMs The instructions require fastlane `1.93.0` or later. 1. Add fastlane plugin to your project: 1. Run `fastlane add_plugin fastlane-plugin-contentsquare`. 2. Select `Git URL` and input [https://github.com/ContentSquare/contentsquare-fastlane-plugin.git ↗](https://github.com/ContentSquare/contentsquare-fastlane-plugin.git). See [fastlane Plugins ↗](https://docs.fastlane.tools/plugins/using-plugins/) for more information. 2. Call fastlane plugin in your build process: `upload_symbols_to_error_analysis(project_id: your_project_id, client_id: "your_client_id", client_secret: "your_client_secret")` Note You need to use `bundle exec fastlane [lane]` to run fastlane. ### Validate crash reporter integration #### Validate crash collection is activated Enabling crash reporting will conflict with any attached debuggers, so make sure a debugger isn't attached when you crash the app. In case a debugger is attached to the device, Crash Reporter won't be initialized and a log will be printed in the console: ```plaintext CSLIB ℹ️ Info: Debugger present, crash reporter is not initialized ``` To test if Crash Reporter is working properly, you first need to disconnect your test device or simulator from Xcode debugger: * Tap on the *Edit scheme...* option of your current scheme * Disable the *Debug executable* option in your scheme configuration. * Build and run your current scheme. If Crash Reporter is successfully initialized when you launch your application, you should see a log printed in the console: ```plaintext CSLIB ℹ️ Info: Crash reporter is initialized ``` Alternatively, you can detach your application from Xcode debugger by stopping it after it is launched. This way Crash Reporter will be initialized and will start reporting crashes, but you won't be able to see the logs printed in the console: * Build and run your current scheme. * Wait until the app is up and running. * Click Stop running the scheme. * Open the app directly from your test device or simulator. #### Validate crash reporting Run your application and force a crash (you can do it by adding a `fatalError()` in your code). Launch the application again using Xcode and you should see a log printed in the console that indicates that a crash has been detected and sent: ```plaintext CSLIB ℹ️ Info: Crash event detected and sent for userID: <user-id>, session: <session-number> on screen: <screen-number> - crashID: <crash-id> ``` ### How Crash Reporter works #### Initialization Crash Reporter is started automatically and begins to report crashes when your application is launched. #### Configuration Once started, our SDK fetches its configuration from our servers. It will start reporting crashes if the Crash Reporter setting is enabled (this is handled by the Contentsquare team). #### Reporting When a crash occurs, a report is created and stored locally in the device. Once the app is launched again, the report is sent to our servers and then removed from the local storage. Warning To make sure crashes occurring at app launch are correctly tracked, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. See [when to send your first screenview](../track-screens/#when-to-send-your-first-screenview) for more details. #### Sending crash data For each crash, a new event will be sent to analytics and Session Replay data when the app is launched again after the crash occurred and the network conditions allow for the server to be reached. Our requests use [`lowPriority` ↗](https://developer.apple.com/documentation/foundation/urlsessiontask/1411509-lowpriority). ### Collected data points Crash Reporter handles multiple types of crashes, including: * Mach kernel exceptions * Fatal signals * C++ exceptions * Objective-C exceptions For each crash we collect information of the application, system, process, threads, stack traces and some other events metadata you can find in [collected data points](../data-collection/#collected-data-points). ### Known limitations and recommendations #### Compatibility with other crash reporters Beyond Firebase Crashlytics (see [Setup Firebase Crashlytics compatibility mode](#setup-firebase-crashlytics-compatibility-mode)), the Contentsquare Crash Reporter is not compatible with other crash reporters. For more details, reach out to your Contentsquare contact. ## WebView errors Errors occurring in web pages loaded in WebViews can be collected if Webview tracking is set up in your app. See 📚 [Webview Tracking implementation](https://docs.contentsquare.com/en/webview-tracking-tag/). Once WebView tracking is implemented, errors collection can be set up. See 📚 [Errors (in WebView)](https://docs.contentsquare.com/en/webview-tracking-tag/error-analysis/) ## Impact on Performance We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. The following performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | iPhone 11 Pro 64GB | | iOS version | 16.5 | | Test App built using Xcode version | 15.3 | | Test App built with Swift version | 5.8 | Note The numbers provided below will vary depending on the user's device, iOS version, SDK version, and if you use Swift or not, which Swift version you use if you do, if you enabled bitcode or not and which options you used when building your IPA for App Store distribution. | Property | Value | | - | - | | Max RAM usage | <2MB | | Max SDK CPU peak on event | <2% | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Error Analysis","description":"How to use Contentsquare Error Analysis in your iOS apps","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/error-analysis/","inLanguage":"en","dateModified":"2026-07-07T11:03:44+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Data Collection - iOS description: Understand how the iOS SDK loads, tracks, and send data lastUpdated: 02 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/data-collection/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/data-collection/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The SDK starts automatically at launch, fetches its configuration, and sends collected analytics events in batches; a session ends after 30 minutes of inactivity. ## Configuration Once started, our SDK fetches it configuration from our servers. Then depending on the segmentation size (defined by our team when you sign a contract) and the user consent status, it will start collecting analytics data from system and user events it detects from the runtime. ## Data collection ### Analytics data collection The SDK monitors the application, lifecycle events, the view hierarchy, and generates data from the behavior of the app, the content of the screen and the user interactions. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. ### Session Replay data collection See [Session Replay Initialization](../session-replay/#data-collection) to learn how Session Replay data collection works. ## Sending data ### Sending analytics data Analytics data are sent in batches of maximum 50 events. Requests are triggered when network conditions allow for the server to be reached and: * The current batch of events has reached 50 * Or the app is put in background ### Sending Session Replay Data See [Session Replay Requests](../session-replay/#requests) to learn more about how Session Replay data is sent. ### Sending crash Data See [Send Crash data](../error-analysis/#sending-crash-data) to learn more about how crash data is sent. ## Session definition A session is one continuous period of user interaction. It starts upon app launch and persists through state changes, including putting the app in the background or terminating and restarting it. As long as users interact at least once every 30 minutes, it remains the same session. ## Collected data points * The events are in JSON format, which lists the properties and their description in comment. * Events are sent to the server in batches. * A batch is a subset of events originating from one session. A session can send events in more than one batch. * The batch size is defined in a run configuration file specific to each app (50 events by default). ### Requests meta data Each batch has a common header, a set of device specific, and repeatable information and an array of events, which is immutable. The header is composed at the moment of sending, so it has to be constant info ONLY. The array in the payload is data stored at the moment of collection. The structure of the batches of events will have the following format: ```javascript { pid:8, // int - ProjectId - represented in the mobile config format uid:"ac1529a7-59f6-49d9-b254-6f0a22f57284", // String - uuid Unique user ID dt:4, // int - device type (loosely enforced enum - [sdk-phone : 4, sdk-tablet :5]) dma:"Samsung", // String - device manufacturer. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. dmo:"SG", // String - device model. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. os:"10.0", // String - os version (Android version name 8.0, 9.0, 10.0) l:"en_US", // String - Language in iso-639 format https://www.ibabbleon.com/iOS-Language-Codes-ISO-639.html tz:"Europe/Paris", // String - timezone https://en.wikipedia.org/wiki/List_of_tz_database_time_zones now:1522159618000, // long - timestamp when the batch was sent to:{ // object - type origin of the event an:"appname" // String - application name st:"sdk-android", // String - type of sdk sf:"release", // string - sdk flavor/variant [release/debug/god] }, r:{ // Device - resolution. w:1080, // int - width h:1920 // int - height d: 1.5 // The device density as float. Its values can vary between (0.75 and 10) }, pl:[] // JSON array payload - list of event objects, see below } ``` ### Events meta data All events have a common first part (don't confuse it with the header explained above). This common section is data which is common for all events by type but is gathered at the moment the event occurred. This common section is a part of the actual event payload. ```javascript { upt:1522, // long - system update in milliseconds euid:"euid", // String - event UUID url:"app-and://identifier/mainPath/secondaryPath?title=screeName", // String - screenName is passed in the title query Parameter scn:4, // int - the number of screens already shown in the session c:3, // int - connectivity type [-1 - offline, 0 - error, 1 - wifi, 2 - 2g, 3 - 3g, 4 - 4g] ci:"verizon", // String - carrier_id when user is on mobile network o:1, // int - orientation [0 = portrait, 1 = landscape] vo:{ // object - version origin of the event sv:"2.1", // string version of the sdk sb:4, // int - sdk build number av:"appVersion", // String - application version af:"appFlavor" // String - application string - [release/debug/god] ab:1 // int - application build number }, sn:1, // int - session id (positive int) t:12894726459435 // long - timestamp of the event (in milliseconds) } ``` All event specific properties are appended to this JSON object. ### App Start This event describes the absolute start of the app. The trigger for this event is the absolute start of the app. This is the first event sent when the SDK is invoked. ```javascript ea: 0; // int - event action - defined above ``` ### App Show This event is sent when the user brings the app in the foreground (switching from another app, exiting lock screen, etc.). This event means the app is focused. ```javascript ea: 1; // int - event action - defined above ``` ### App Hide This event is sent when the user exits (minimizes) the app, or switches to something else. This event means the app is not focused and the session might end, but we have not completely ended the session yet, as the user might return. ```javascript ea: 2; // int - event action - defined above ``` ### Screenview Everything starts with a View event. This is an event which describes the equivalent of a "page view" on the web. This event is sent when the Track Screen API is called. ```javascript ea:4 // int - event action - defined above st:"title", // String - screen title sl:34543 // int - (load time) screen load time (diff between last action and this event) ``` ### Tap Single Finger gesture event, when the user is interacting with a loaded screen. This is an event which describes the equivalent of a "click" in the web. This event is defined by the following sequence of touch events: * Touch Down -> N x Touch Move -> Touch Up ```javascript ea:6 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ur: true, // boolean - was this a "responsive" touch event (the target view had a handler) ``` ### Long press Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Duration: > 500ms * Distance: < 24 dp ```javascript ea:8 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ``` ### Drag (Slow Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity < 100 dp/s ```javascript ea:9 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance dragged tvv:100 // int - target view velocity while dragging dp/s ``` ### Flick (Fast Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity > 100 dp/s ```javascript ea:10 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view graph path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance scrolled tvv:100 // int - target view velocity while scrolling dp/s ``` ### Transaction To track transactions we provide a public API which can send a transaction object (see section [Track Transactions](../track-transactions/)). This object must contain the following parameters: ```javascript ea:16, // int - event action - defined above tr:{ // a json object with different properties defining the transaction made vl: 20.0, // mandatory - float - the value of the transaction cu: 978, // mandatory - int - the ISO 4217 code of the currency of the transaction id: "32akjkljklJ575775" // optional - string - an id for the transaction } ``` ### Dynamic variables To track dynamic variables we provide a public API (see section [Dynamic variables](../track-dynamic-variables/)). **Event with a string value** ```javascript ea:18, // int - event action - defined above k:"key", // String - Custom key assigned by client. v:"value" // String - Custom value assigned by client. ``` **Event with a number value** ```javascript ea:19, // int - event action - defined above k:"key", // String - Custom key assigned by client. v: 2344 // Integer - Custom value assigned by client. ``` ## Reliable targets Limitations * For now, reliable targets are available for UIKit only. * If the view doesn't qualify to be a reliable target then we use our current mechanism for zoning * Reliable identifier must be unique per screen In the Zoning Analysis module, reliable targets are assigned to zones to ensure that a `UIView` remains accessible in the view hierarchy, even if it has been moved within the same page.\ Having a reliable target for a view or a container of views enables the analysis of data across various Screenshots from different dates and versions, including layouts or A/B testing variations. One of the following properties must be assigned for a view to have a reliable target.\ Our SDK will check the properties in this order: 1. [`accessibilityIdentifier` ↗](https://developer.apple.com/documentation/uikit/uiaccessibilityidentification/1623132-accessibilityidentifier) 2. [`restorationIdentifier` ↗](https://developer.apple.com/documentation/uikit/uiviewcontroller/1621499-restorationidentifier) 3. [`tag` ↗](https://developer.apple.com/documentation/uikit/uiview/1622493-tag) ### accessibility Identifier if the view has `accessibilityIdentifier` it uses it as first priority and provides a short reliable target. Example: ```swift /* [SalesViewController] ViewOne | viewTwo / | \ viewThree viewFour viewFive */ let viewOne = UIView() viewOne.accessibilityIdentifier = "rootView" let viewTwo = UIView() viewTwo.restorationIdentifier = "dichotomy" let viewThree = UIButton() viewThree.accessibilityIdentifier = "on_sale" let viewFour = UIButton() viewFour.accessibilityIdentifier = "new_arrivals" let viewFive = UIButton() viewFive.accessibilityIdentifier = "for_kids" viewTwo.addSubview(viewThree) viewTwo.addSubview(viewFour) viewTwo.addSubview(viewFive) viewOne.addSubview(viewTwo) // viewThree target would be: UIButton[ai:SalesViewController.on_sale] // viewFour target would be: UIButton[ai:SalesViewController.new_arrivals] // We change the view hierarchy viewThree.removeFromSuperview() viewFour.addSubview(viewThree) // viewThree target would be: UIButton[ai:SalesViewController.on_sale] // viewFour target would be: UIButton[ai:SalesViewController.new_arrivals] ``` ### restoration Identifier If the view has `restorationIdentifier` and no `accessibilityIdentifier` then it provides a long reliable target. ```swift /* [SalesViewController] ViewOne / viewTwo / \ viewThree viewFour */ let viewOne = UIView() viewOne.restorationIdentifier = "trichotomy" let viewTwo = UIView() viewTwo.restorationIdentifier = "dichotomy" let viewThree = UIView() let viewFour = UIView() viewTwo.addSubview(viewThree) viewTwo.addSubview(viewFour) viewOne.addSubview(viewTwo) // viewThree target would be: [root]>UIView[ri:SalesViewController.trichotomy]>UIView[ri:SalesViewController.dichotomy]>UIView:eq(0) // viewFour target would be: [root]>UIView[ri:SalesViewController.trichotomy]>UIView[ri:SalesViewController.dichotomy]>UIView:eq(1) ``` ### tag If the view has no `accessibilityIdentifier` and no `restorationIdentifier` then our SDK will use the `tag` that has been set, and will provide a long reliable target as well. tag yields the same identifiers as accessibility with a different tag ex: `[root]>UIView[tg:444]>UIView[tg:223]>UIView:eq(1)` ### Workaround for SwiftUI: using `.overlay` to get Reliable Target Identifiers SwiftUI views do not expose stable, introspectable identifiers at runtime. This presents a challenge when attempting to programmatically identify or interact with SwiftUI components - especially for use cases such as analytics tracking, UI testing, or runtime introspection. To work around this limitation, you can inject a transparent overlay that contains a `UIView` with a defined `accessibilityIdentifier`. This allows tooling to detect and reference the view reliably at runtime. Warning Since this approach adds an actual `UIView` on top of your SwiftUI view, it intercepts user interactions. As a result, interactive components below the overlay (like buttons) will no longer receive touches unless they are explicitly layered above it. ```swift struct AccessibleView: UIViewRepresentable { let accessibilityIdentifier: String func makeUIView(context: Context) -> UIView { let view = UIView() view.accessibilityIdentifier = accessibilityIdentifier return view } func updateUIView(_ uiView: UIView, context: Context) { uiView.accessibilityIdentifier = accessibilityIdentifier } } ``` This component embeds a transparent `UIView` with the desired `accessibilityIdentifier`, which becomes visible to accessibility, UI testing, or tracking layers. **Example:** Identifying a *non-interactive* list cell. Here is a typical usage pattern where the overlay is applied to a *non-interactive* cell. Any interactive elements (like a button) are rendered above the overlay to remain functional: ```swift var body: some View { ZStack(alignment: .topTrailing) { VStack { Image(product.imageName) .resizable() .aspectRatio(contentMode: .fit) .frame(width: 100, height: 100) Text(product.title) } // This overlay makes the view identifiable at runtime .overlay(AccessibleView(accessibilityIdentifier: "reliableID")) // This button is placed above the overlay so it remains tappable Button("Tap Me") { // Perform action } .padding([.top, .trailing], 8) } .padding() } ``` This pattern can be used when you want to identify list rows, cards, or containers that do not react to taps, but still need to be tagged for runtime analysis or inspection. Recommendations * Only use `.overlay(AccessibleView(accessibilityIdentifier:...))` on *non-interactive* containers. * Ensure interactive elements are layered above the overlay if interaction is needed. * Generate identifiers in a stable, unique per screen and predictable way, e.g.: ```swift let reliableID = "section-\(sectionIndex)-product-\(product.id)" ``` ## Exposure Metrics In the Zoning Analysis module, Exposure Metrics provide information on the size of the display zone in the application, and data about content exposure in scrolling elements. ### Behavior for scrollable elements Exposure Metrics data for scrolling is only calculated on the first scrollable element on the screen. Other scrolling elements in the view hierarchy are not taken into account. This event is defined by the following content: ```javascript ea:23, // int - event action dx:10, // int - normalized x content offset dy:10, // int - normalized y content offset du: 5, // int - duration of the movement (in milliseconds) ``` #### Exclude `UIScrollView` type object from Exposure Metrics Limitations * Exclusion mechanism is available for UIKit only, for objects inheriting from `UIScrollView`. ```swift let scrollView = UIScrollView() // or UICollectionView, UITableView or any class inheriting from UIScrollView scrollView.excludeFromExposureMetrics() ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Data Collection","description":"Understand how the iOS SDK loads, tracks, and send data","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/data-collection/","inLanguage":"en","dateModified":"2026-06-02T10:48:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Impact on performance - iOS description: Metrics to evaluate the performance impact of Contentsquare iOS SDK on your apps lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/impact-on-performance/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/impact-on-performance/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The CSQ SDK strives to be non-intrusive and transparent to client app developers. The following are the technical specifics we can share on performance. The following performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | iPhone 11 Pro | | iOS version | 16.5 | | Test App built using Xcode version | 15.3 | | Test App built with Swift version | 5.8 | We conducted the tests using a default `Master-Detail` app built using ad hoc distribution with no app thinning and with Swift symbols stripped. In the app, the SDK was making calls to the public APIs, running, and collecting data in its default state. Note The numbers provided below will vary depending on the user's device, iOS version, SDK version, and if you use Swift or not, which Swift version you use if you do, if you enabled bitcode or not and which options you used when building your IPA for App Store distribution. | Property | Value | | - | - | | SDK size (installed size, no Bitcode) | \~15Mb | | Max RAM usage | <2Mb | | Max SDK CPU peak on event | <3% | | Data transmitted over network for a default batch size of 50 events The size of the batch can be customized if needed | \~29kb | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Impact on performance","description":"Metrics to evaluate the performance impact of Contentsquare iOS SDK on your apps","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/impact-on-performance/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - iOS description: Requirements and limitations to develop with the Contentsquare iOS SDK lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/compatibility/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare iOS SDK has specific language, platform, and version requirements for integration. * **Programming languages:** The iOS SDK supports and tracks content on any screen developed in **Objective-C or Swift (version >= 4.2)**. * **SwiftUI:** is officially supported * **iOS version:** starting with SDK 4.50.0 we support **iOS 13.0 and later** * Starting with SDK 4.36.0, **no data will be collected for applications running on iOS < 13.0**, although technically the SDK supports iOS 12.4. * ReactNative requires a minimum of iOS 13.0 * All devices released since 2015 can be updated to iOS 13.0 * `SFSafariViewController` is **not** supported ## Known limitations and recommendations ### Screenshot fidelity: Combining Visual Effects with Filters **Symptom:** Some elements of the screenshots may not be visible, such as `UITabBar` buttons. **Explanation:** Our capturing method prevents to capture views when Visual effects are combined with filters. Our tools captures as much as Xcode's 'Debug View Hierarchy' feature. If you want to preview what is going to be rendered, you can use this feature to visualize your screen. See [Capturing a Snapshot of a UIVisualEffectView ↗](https://developer.apple.com/documentation/uikit/uivisualeffectview#Capture-a-snapshot-of-a-visual-effect-view). ### Screenshot fidelity: Customized layers applied on a container view **Symptom:** Some elements of the screenshots may not be displayed correctly in the **Zoning Analysis**. **Explanation:** Our capture method relies on views to determine zoning elements. A view containing subviews is a container and when a container is assigned a customized [layer ↗](https://developer.apple.com/documentation/uikit/uiview/1622436-layer), it may not appear in the **Zoning Analysis**. **Workaround:** Instead of applying customized layer to the container, prefer applying it on view of type, or subtype, `UIImageView` or `UIControl`. ### Screenshot fidelity: Floating header/footer missing in Zoning **Symptom:** Some elements of the screenshots don't exist in the **Zoning Analysis**. **Explanation:** The **Zoning Analysis** module does not support `UITableViewHeaderFooterView` in `UITableView` and `UICollectionReusableView` in `UICollectionView` due to their highly dynamic memory and rendering behavior. ### Screenshot fidelity: Floating header/footer duplicated in Zoning **Symptom:** Some elements appear multiple times in the **Zoning Analysis**. **Explanation:** The **Screenshot** captures the currently visible content on screen. When a floating header/footer remains visible during scrolling, it may be captured at different positions throughout the **Long screenshot process**, resulting in duplications. ### Screenshot fidelity: Multiple vertical scrollViews **Symptom:** The **Long Screenshot** cinematic may not start on mobile, or the resulting screenshot might be unscrollable in **Zoning Analysis**. **Explanation:** When multiple vertical scrollViews are present on a screen, the **Long Screenshot** cinematic will attempt to run only on the last vertical scrollView the user interacted with. Other scrollable areas will not be automatically scrolled or captured by the cinematic process, even if they contain content. In practice, this means the automatic scrolling (and full content capture) is limited to a single scrollView per screen, based on user interaction. ### Screenshot fidelity: Lottie animations **Symptom:** Lottie Animation elements are not visible in the **Zoning Analysis**. **Explanation:** The **Zoning Analysis** module does not support `LottieAnimationView` because the SDK can't select a specific frame to capture. ### Gestures not attached to `UIImageView` **Symptom:** When analysing the tap rate on an image, we see 0% when we know it is not possible. **Explanation:** By default `UIImageView` have their `isUserInteractionEnabled` property set to false ([See Apple documentation ↗](https://developer.apple.com/documentation/uikit/uiimageview/1621063-isuserinteractionenabled)). This means that the `UIImageView` won't receive any input event. All events will be handled by the first parent to have `isUserInteractionEnabled` set to true (usually the first parent will do). **Workaround:** Create a zone on the parent view to get the taps on the image. ### `UICollectionViewCompositionalLayout` TVP lack of consistency **Explanation:** As explained in the [Apple documentation ↗](https://developer.apple.com/documentation/uikit/uicollectionviewcompositionallayout), `UICollectionViewCompositionalLayout` is a highly dynamic layout creation object. We are not able to ensure TVP value is the same between different usages. ### Long Screenshot: Large Capture Limitation **Symptom:** The Long Screenshot capture completes the creation process, but then fails at the very end without a clear error message. **Explanation:** Long Screenshots can produce a very large amount of data. For reliability and performance reasons, the server enforces a maximum payload size (\~75 MB). Very long or content-heavy screens may exceed this limit, causing the screenshot to be rejected. **Workaround:** Capture a shorter area (reduce the scroll length) and/or reduce the amount of on-screen content (for example fewer or lighter elements), then retry the Long Screenshot. ### Zoning Limitation in SwiftUI with scrolling (Lazy)Stack and (Lazy)Grid * **Screenshot and Gesture Tracking Limitations:** * Using `LazyStack`, or `LazyGrid` nested in a `ScrollView` may present limitations in screenshot and gesture tracking due to differences in memory management compared to UIKit. * Intricate hierarchies of `LazyStacks` or `LazyGrids` can lead to inconsistent identification of elements, impacting the reliability of element identification. **Prefer to use single layered Lazy components**, when possible. * **Rotation Limitation:** * Unique identification of elements within SwiftUI `Stack`, `Grid`, `LazyStack`, or `LazyGrid` is not guaranteed after a rotation, so, **rotation is not supported** for `Stack`, `Grid`, `LazyStack`, or `LazyGrid`. * **Scrolling Element Offset Limitation:** * The consistency of unique identifiers is not guaranteed when the scrolling element is displayed starting at an offset different than zero. Check the following Help Center article for more information about the symptom, root cause and potential mitigation solutions: [I can't create a zone on a list element on iOS (SwiftUI) ↗](https://support.contentsquare.com/hc/en-us/articles/4408117004690) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/compatibility/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: In-app features - iOS description: Enable testing and debugging capabilities within your iOS app using in-app features for enhanced development workflow lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/in-app-features/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/in-app-features/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Alongside its tracking capabilities, the SDK embeds some features aimed at Contentsquare users such as [Screenshot Capture](https://docs.contentsquare.com/en/react-native/in-app-features/#screenshot-capture) and [SDK Logs](#debugging-and-logging). ## Implement in-app features To allow Contentsquare users to enable in-app features, you must perform 2 implementation tasks: 1. [Add the custom URL scheme in your app Info](#1-add-the-custom-url-scheme-in-your-app-info) 2. [Call the SDK when the app is launched via a deeplink](#2-call-the-sdk-when-the-app-is-launched-via-a-deeplink) ### 1. Add the custom URL scheme in your app Info You have to allow your app to be opened via a custom URL scheme which can be done using one of the following methods: #### Xcode 1. Open your project settings 2. Select the app target 3. Select the `Info` settings 4. Scroll to `URL Types` 5. Set the URL scheme to `cs-$(PRODUCT_BUNDLE_IDENTIFIER)` #### Text editor 1. Open the `Info.plist` of your project 2. Add the following snippet: **Info.plist** ```xml <key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>cs-$(PRODUCT_BUNDLE_IDENTIFIER)</string> </array> </dict> </array> ``` ### 2. Call the SDK when the app is launched via a deeplink Depending on the project, there are multiple ways to handle the deeplink opening. Choose the method matching your project structure: * AppDelegate In your `AppDelegate` class, complete or implement the function `application(app, open url:, options:)` with: `CSQ.handle(url: url)` * SceneDelegate In your `WindowSceneDelegate` class, you need to: 1. Update `func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions)` with: ```swift if let url = connectionOptions.urlContexts.first?.url { CSQ.handle(url: url) } ``` 2. Complete or implement `func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>)` with: ```swift if let url = URLContexts.first?.url { CSQ.handle(url: url) } ``` * SwiftUI In the `body` of your main App struct, add the `onOpenURL` modifier and call the `Contentsquare` SDK to handle the URL: ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { MyView() .onOpenURL { url in CSQ.handle(url: url) } } } } ``` ### Enable in-app features Once the implementation is done, in-app features can be enabled in different ways: #### Scan the QR code If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code displayed with your iPhone.  #### Use the custom link for simulator If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and select "Copy link" (to copy the deeplink) and paste it in Safari on your Simulator to trigger the in-app features.  Note If you don't have access to the Contentsquare platform, you can ask the Contentsquare team to share the link with you. #### Using the Terminal In a Terminal console, open an URL in your current simulator with the following command (replacing `CUSTOM_LINK` with yours): ```shell xcrun simctl openurl booted "CUSTOM_LINK" ``` ### Debugging and Logging Contentsquare provides Logging capabilities that allow you to see the raw event data logged by your app in the macOS Console App, Xcode, or in the Contentsquare platform. Use this for validation purposes during the instrumentation phase of development and can help you discover errors and mistakes in your analytics implementation and confirm that all events are being logged correctly. #### Viewing Logs in Xcode or the macOS Console app By default, almost all logs are disabled. There is only one log that is always visible to notify that the SDK has started: ```plaintext CSLIB ℹ️ Info: Contentsquare SDK v1.12.2 starting in app: {{bundleID}} ``` To enable all logs, activate [in-app features](#enable-in-app-features). Logging is directly linked to in-app features state: it starts when in-app features are enabled and stops when you disable in-app features. Note You can also enable logs in the code by changing the log level to Verbose: `CSQ.debug.logLevel = .verbose`. To view logs: 1. Make sure the device you are using is plugged to your Mac or is on the same Wi-Fi network (skip this step if you are using a simulator) 2. Start the macOS Console app *(make sure that info messages are included: [Choose Action > Include Info Messages ↗](https://support.apple.com/guide/console/customize-the-log-window-cnsl35710/mac))* or Xcode. 3. Filter logs on `CSLIB`  #### Viewing logs in the Contentsquare platform To view logs directly on the platform, you can use Log visualizer. Log visualizer is a helper tool to see SDK logs without logging tools. It requires having platform access for your project and enabling in-app features. See the [SDK Log Visualizer Help Center Article ↗](https://support.contentsquare.com/hc/en-us/articles/37271699876625) for more information. ### Screenshot capture To unlock the full data-visualization capabilities of Contentsquare, the SDK provides a way to capture screenshots of your app screens. These screenshots can only be taken by Contentsquare's users on their device. They are not captured from your end-users device. It means your Personal Data is safe, as long as you use a test user account. Warning * For screenshot capture to work, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. * Horizontal scrollable containers are not supported.  Screenshots are used in the **Zoning Analysis** module to look at zone-level metrics (Tap rate, Swipe rate...):  ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"In-app features","description":"Enable testing and debugging capabilities within your iOS app using in-app features for enhanced development workflow","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/in-app-features/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - iOS description: Configure privacy settings and user consent management in your iOS app with the CSQ SDK to ensure regulatory compliance lastUpdated: 28 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/privacy/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Customers ("Customer(s)", "you," or "your"), as app developers and/or publishers, shall ensure compliance with applicable data privacy laws and regulatory guidelines while using Contentsquare SDK for your app. This section explains the data processing involved in the use of Contentsquare SDK and provides information to help you comply with data protection laws, including the GDPR, e-privacy directive, and the [French Data Protection authority (CNIL) guidelines on mobile applications ↗](https://www.cnil.fr/sites/cnil/files/2025-05/recommendation-mobiles-app.pdf). This section is for informational purposes only and is not legal advice. If you are not sure of how to comply with data protection laws that apply to you, refer to legal counsel. To learn about Contentsquare privacy practices, see our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Purpose of processing and categories of personal data collected Here is the list of categories of personal data Contentsquare collects by default that are part of our [privacy manifests](../privacy/#privacy-manifest). All collected personal data listed below is linked to the end-user via the [Contentsquare User ID](#contentsquare-user-id) we generate. Warning The Contentsquare SDK provides features that allow you to send to Contentsquare additional types of personal data (such as username, email address, customer ID, account number): [Dynamic variables](../../experience-analytics/track-dynamic-variables/), [Custom variables](../../experience-analytics/track-custom-variables/), [User identifier](../../experience-analytics/session-replay/#send-user-identifier), [Screen names](../../experience-analytics/track-screens/), [Session Replay (unmasking elements)](../../experience-analytics/session-replay/#personal-data-masking). If you decide to use these features to collect new types of personal data or use already collected data but for a different purpose, it is up to you to describe these privacy practices in your app manifest. | Categories | Data type | Purposes | | - | - | - | | Identifiers | User ID | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Product Interaction such as touch gestures (taps, swipes), user journey (pages visited), time of engagement, or transactions | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Other usage data (any other data about end-user activity in the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Other Data types | Other Data types (technical data, any other data inputted by customers in the dynamic variables, data used as part of the Session Replay feature where applicable) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Diagnostics | Crashes, such as crash logs | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Diagnostics | Performance data, such as launch time, freeze rate, or energy use | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Diagnostics | Other diagnostic data (any other data collected for the purposes of measuring technical diagnostics related to the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Search History | Information about searches performed by an end-user in the app | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Session Replay module](../../experience-analytics/session-replay/)) | | Purchase History | Transaction data about an end-user (such as order reference, amount, bought items) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | See how the data types and purposes are reflected in the [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy). Note Contentsquare is not designed to collect sensitive personal data (such as health, financial, or racial data). It is your responsibility to prevent any sensitive data from being sent to Contentsquare. If you accidentally send sensitive data, contact your customer success manager to immediately delete them from Contentsquare servers. ## User identifiers ### Contentsquare User ID The SDK generates a unique user ID (UUID) (random hash) which is specific to users on their device. Contentsquare cannot identify a user across devices. This user ID and all collected data are stored for 13 months. We don't persist the UUID when the app is deleted and re-installed. The SDK generates a new UUID after install or re-install. Contentsquare does not share this user ID with any third parties. ### IDFA Contentsquare does not collect the **IDFA** (Advertising ID) or any ad related information to identify the user. Check out our page about [10 Things to know about the Contentsquare solution's data processing ↗](https://contentsquare.com/privacy-center/10-things-to-know-cs-data-processing/). ### "User identifier" feature Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier provided by the customer. See [User identifier feature](../../experience-analytics/session-replay/#send-user-identifier) for more information. ## Data retention and storage location ### Data retention By default, end-users personal data are kept for 13 months. The retention of end-users personal data collected via the Session Replay is customizable by customers, from 3 to 24 months. ### Storage location End-users personal data are stored in Europe or in the US, depending on your location. For more details on applicable hosting locations, refer to our [subprocessors list ↗](https://contentsquare.com/privacy-center/subprocessors/). ## Informing your End-User The Contentsquare SDK collects end-user's personal data on your app. As a data controller, app developers, or app publishers, it is your responsibility to provide appropriate information to your end-users on how their personal data is handled when using the CSQ SDK, for example via a privacy policy or cookie banner. Contentsquare provides a sample [description of the services ↗](https://contentsquare.com/privacy-center/sample-cookie-description/) (including Experience Analytics and Product Analytics) to help customers meet their transparency obligations. This description is for information only and is not legal advice. ## Handling User Consent Contentsquare collects usage data on your app. **By default, the SDK will consider every new user to be opted-out.** To start tracking, the SDK [Opt-in API](#opt-in) must be called. You are responsible for handling the UI asking end-users for their consent and allowing them to manage their privacy settings. Use the following APIs to pass the user decision to the Contentsquare SDK. Note If data protection laws that apply to you do not require end-user consent for your app, discuss it during implementation with your Contentsquare contact (as this would go against Apple Privacy guidelines). ### Opt-in Use the Opt-in API to get end-user consent. Calling this API will generate a user ID and initiate tracking. * Experience Analytics ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start() CSQ.optIn() // Continue with post-consent navigation or UI update } ``` * CSQ Experience Platform (Early Access) ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` ### Opt-Out When this API is called, tracking stops immediately, all settings are reset (Session number, Page number, and so on) and all files and directory including personal data collected via the SDK created by Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track and collect any data from the user's phone unless the Opt-in API is called again. ```swift CSQ.optOut() ``` ### Handling your end-user's data subject requests In case Contentsquare receives a request from an individual that identifies as an end-user of your app, Contentsquare will promptly refer such individual directly to you, as the data controller and will support you with any means available to resolve such request. Contentsquare has launched a portal for managing data subject requests to its customers respond to data subjects within the legal deadlines. Therefore, you can forward any data subject request (such as data deletion or data access request) you receive to Contentsquare via this Data Subject Portal at [https://contentsquare.com/privacy-center/data-subject-request-portal/ ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ### Get Contentsquare User ID Since Contentsquare SDK does not collect by default any directly identifiable personal data about your end-user, we cannot help you respond to an end-user's data subject request without their Contentsquare User ID. Use this API to get the Contentsquare User ID of your end-user and forward the end-user's data subject request (such as data deletion or data access request) via Contentsquare's [portal ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ```swift CSQ.metadata.userID ``` Note You are able to get an ID only if the user is not Opted-out. ### Enrichment API [The Enrichment API](https://docs.contentsquare.com/en/api/enrichment/) allows for enriching the behavioural data tracked by Contentsquare client-side, with other session-based data that can be sent server-side. During a visit on an app, you can interact with Contentsquare's SDK to pull those identifiers with the following SDK APIs: ```swift let projectID = CSQ.metadata.projectID let sessionId = CSQ.metadata.sessionID // store these Contentsquare session identifiers in your backend ``` ### Pause / Resume Tracking To completely stop data collection of your end-users of your app, use the pause and resume tracking APIs. When `stop/pause` is called, the Contentsquare SDK pauses all tracking (Analytics, Session Replay, Errors) of your end-users. When `resume` is called, the Contentsquare SDK resumes all tracking (Analytics, Session Replay, Errors) and starts collecting your end-users personal data again with the same Contentsquare user ID. ```swift CSQ.stop() // ... CSQ.resumeTracking() ``` Note As this mechanism pauses the tracking, make sure that you call resume once your user exits the sensitive screen. Best practice would be to link these method calls to lifecycle events on UIView/UIViewControllers. ## Disable user tracking across sessions If you don't want to link the different sessions of a user to the same userID, reset the userID at each app start: ```swift func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) { CSQ.start() CSQ.optOut() CSQ.optIn() // ... } ``` Starting the SDK manually using `start()` will ensure that opt-out is called right after the start of the SDK (no event tracked in between). Calling `optOut()` will delete the previous userID. Calling `optIn()` will set a new one. Note If you are monitoring the network requests, you may see event requests being sent at app start. This is expected as there may be events from the previous session that haven't been sent yet. The [opt-out API](#opt-out) makes sure to send all data stored locally before stopping the tracking and wiping all data. ### Session Replay privacy APIs As part of Session Replay capabilities, Contentsquare provides masking mechanisms to prevent unwanted end-user's personal data from the Session Replay module from being transmitted to Contentsquare. See [Session Replay Personal data masking](../../experience-analytics/session-replay/#personal-data-masking) for more information. ## App Store Privacy Guidelines Compliance As customer app developers, it is your responsibility to comply with the [App Store Privacy guidelines ↗](https://developer.apple.com/app-store/review/guidelines/#privacy). ### Privacy manifest The Contentsquare SDK includes a [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy) describing the types of end-users personal data collected, the purpose of processing and the reasons for using APIs. [See Apple's website for more information ↗](https://developer.apple.com/app-store/app-privacy-details/) ### Tracking and App Tracking Transparency (ATT) App Store (Apple) requests App developers to receive end-users' permission to track them or access Advertising ID using the [AppTrackingTransparency framework ↗](https://developer.apple.com/documentation/apptrackingtransparency) (ATT). **It is not required to ask for end-users' permission through the ATT when using Contentsquare, as it does not fall under the** ["tracking" definition of Apple ↗](https://developer.apple.com/app-store/app-privacy-details/#user-tracking). The data collected by the Contentsquare SDK is not linked with Third-Party Data (as defined by Apple) for targeted advertising or advertising measurement purposes, nor shared with a data broker. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Configure privacy settings and user consent management in your iOS app with the CSQ SDK to ensure regulatory compliance","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/privacy/","inLanguage":"en","dateModified":"2026-04-28T22:02:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Google Tag Manager - iOS description: Leverage our native integration to send Google Tag Manager events to Contentsquare, with the CSQ iOS SDK lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/google-tag-manager/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/google-tag-manager/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. If you are using Firebase to track events such as screenviews or transactions, you can trigger these events for Contentsquare with minimal effort, thanks to Google Tag Manager. ## Prerequisite If you are following this Google Tag Manager integration process, you should already have followed the Google Tag Manager + Firebase setup as described in [Google's Tag Manager + Firebase: Getting Started ↗](https://developers.google.com/tag-manager/ios/) You also need to integrate the CSQ SDK [see section: Add Contentsquare to your app](../#install-the-sdk). ## Screenview events This section covers how to trigger a Contentsquare screenview event for every Firebase screenview event. Firebase allows you to [log screenviews automatically or manually ↗](https://firebase.google.com/docs/analytics/screenviews) for an exhaustive coverage of your app screens. ### Variables Contentsquare screenview events require a `name` parameter. Firebase has 2 ways to track screens: #### 1. Variable for automatically tracked screens Firebase's `screen_view` events have an `_sc` parameter (for screen class) which we can use as parameter for screens that are **automatically tracked**. We will create a variable called **Automatic Screenview Name** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `_sc`  #### 2. Variable for manually tracked screens Firebase's `screen_view` events have a `_sn` parameter (for screen name) which we can use as parameter for screens that are **manually tracked**. We will create a variable called **Manual Screenview Name** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `_sn`  We can also create variables for our own custom parameters, for example, we can send a `screen_view` event like this: ```swift Analytics.logEvent(AnalyticsEventScreenView, parameters: [ AnalyticsParameterScreenName: "MyScreenName", "is_user_logged_in": "true" ]) ``` and create a variable called **Is User Logged In** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `is_user_logged_in` Check out [Configure variables in Tag Manager ↗](https://developers.google.com/tag-platform/tag-manager/ios/v5#configure_variables_in_tag_manager) for more information. ### Screenview trigger We will need to tell Google Tag Manager when to send a Contentsquare screenview, and for that we need to create a **Trigger**. Firebase sends screenviews as events of name `screen_view`, so we need to create a trigger for that event. * Name your trigger `Screenview Trigger` * **Trigger Type** should be set to **Custom** * Trigger should fire on **Some Events** * For the Event, the **Event Name** should be **equal** to `screen_view`  ### Create the custom function Tag In Google Tag Manager, a **Tag** is what configures what happens when some trigger is activated. It will be automatically linked to a custom class which we will create in a later step. The **Tag Type** should be a **Function Call**. You will also need to fill in the **Class Name** field with a class name of your liking, typically related to what the tag is about (here we chose `ContentsquareScreenviewTag`), which you will re-use later.  ### Adding the trigger and the variables to the Tag Edit the `ContentsquareScreenviewTag` Tag: Tip Type `{{` or click `+` to make sure you are referencing existing GTM variables. * Add an argument with the key `auto_screen_name` and the variable **`{{Automatic Screenview Name}}`** as the value * Add an argument with the key `manual_screen_name` and the variables **`{{Manual Screenview Name}} | {{Is User Logged In}}`** or **`{{Manual Screenview Name}}`** as the value * Add **Contentsquare Screenview Trigger** as the Tag's trigger It should look like this now:  ### Create the custom function Tag class In your app code, create a class of the same name as the `Class Name` you configured in the GTM interface, for example `ContentsquareScreenviewTag`. This is how GTM connects the configuration and the actual class to trigger. This class is used to call the Contentsquare screenview tracking function as follows: ```swift @objc(ContentsquareScreenviewTag) final class ContentsquareScreenviewTag: NSObject, TAGCustomFunction { @objc func execute(withParameters parameters: [AnyHashable : Any]!) -> NSObject! { let autoScreenName = parameters[AnyHashable("auto_screen_name")] as? String let manualScreenName = parameters[AnyHashable("manual_screen_name")] as? String let screenName = manualScreenName ?? autoScreenName ?? "No screen name!" CSQ.trackScreenview(screenViewWithName: screenName) return nil } } ``` Now, every time Firebase sends a screenview event, Contentsquare will send one as well. ## Screenview events with Custom Variables Custom Variables Custom variables are additional information on the page, the user or the session, sent with screenviews.\ For more information about custom variables, see [Track Custom Variables](../track-custom-variables/). It is possible to send custom variables along with the screenview events.\ To do so: 1. Follow **Use Google Tag Manager** > [Screenview events](#screenview-events) 2. Add extra arguments to the `ContentsquareScreenviewTag` Tag as follows: * *Key:* the index of the custom variable * *Value:* a string that will contain the custom variable name and value such as `CVAR_NAME : {{Event Name}}` Note The value of the custom variable is composed of a name and a value: `NAME : VALUE` concatenated into a single string and separated by `:`. It should look like this:  For Custom Variables You are free to implement your own logic for filling key and value in GTM, but the application side must be able to receive and extract for each custom variable: 1. An index 1. A name 1. A value In the code of your application, edit the code of your class to handle the added custom variables: ```swift @objc(ContentsquareScreenviewTag) final class ContentsquareScreenviewTag: NSObject, TAGCustomFunction { @objc func execute(withParameters parameters: [AnyHashable : Any]!) -> NSObject! { let autoScreenName = parameters[AnyHashable("auto_screen_name")] as? String let manualScreenName = parameters[AnyHashable("manual_screen_name")] as? String let screenName = manualScreenName ?? autoScreenName ?? "No screen name!" var cvars = [CustomVar]() for (gTagKey, gTagValue) in parameters { guard let gTagKey = gTagKey as? String, let cvarIndex = UInt32(gTagKey), let gTagValue = gTagValue as? String else { continue } let cvarKeyValue = gTagValue.components(separatedBy: ":") if cvarKeyValue.count == 2 { let name = cvarKeyValue[0].trimmingCharacters(in: .whitespaces) let value = cvarKeyValue[1].trimmingCharacters(in: .whitespaces) let cvar = CustomVar(index: cvarIndex, name: name, value: value) cvars.append(cvar) } } CSQ.trackScreenview(screenViewWithName: screenName, cvars: [cvars]) return nil } } ``` With this code, the custom variables will be sent by Contentsquare automatically along with the screenview. ## Transaction events A Contentsquare transaction event can also be triggered for every Firebase `ecommerce_purchase` event (See Firebase [Swift ↗](https://firebase.google.com/docs/reference/swift/firebaseanalytics/api/reference/Constants#analyticseventpurchase) documentation). To do so, you will need to follow the setup described below. ### Variables We have to create at least two variables to be able to build a transaction event: Value and Currency. Optionally, it is also possible to pass a transaction identifier, meaning you would need to create an additional variable to be able to use it. #### Value (mandatory)  #### Currency (mandatory)  #### Transaction ID (optional)  ### Trigger Create the following custom trigger.  ### Tag Create a **Function call** Tag called `ContentsquareTransactionTag`, pass the two to three variables created earlier as arguments (skip the `id` line if you do not want to use it) and set its trigger to the one you just created.  ### Implementing the function call We need to create a `ContentsquareTransactionTag` class, and have it adhere to the `TAGCustomFunction` protocol to link it to the Google Tag Manager custom Tag of the same name. Take good to be able to create and send a Contentsquare Transaction successfully, when you create a Firebase purchase event you will have to at least pass values for `kFIRParameterValue` and `kFIRParameterCurrency`, and can optionally pass a value for `kFIRParameterTransactionID`, when you create a Firebase purchase event. ```swift @objc(ContentsquareTransactionTag) final class ContentsquareTransactionTag: NSObject, TAGCustomFunction { @objc func execute(withParameters parameters: [AnyHashable : Any]!) -> NSObject! { if let currency = parameters[AnyHashable("currency")] as? String, let value = parameters[AnyHashable("value")] as? Float { let identifier = parameters[AnyHashable("id")] as? String CSQ.send(transaction: CustomerTransaction.init(id: identifier, value: value, currency: currency)) } return nil } } ``` Now, every time Firebase sends an `ecommerce_purchase` event, Contentsquare will send one as well. ## Dynamic variable events We can send values from any Firebase event as a Contentsquare dynamic variable: ```swift Analytics.logEvent("addToCart", parameters: [ "product_count": 12, "product_name": "ProductA" ]) ``` ### Variables The `addToCart` event has parameters `product_count`, `product_name`, we will create variables called **Product Count** and **Product Name** with: * The **Variable Type** set to **Event Parameter** * The **Event Type** set to **Custom Parameter** * The **Event Parameter Key** set manually to `product_count`/`product_name` Check out [Configure variables in Tag Manager ↗](https://developers.google.com/tag-platform/tag-manager/ios/v5#configure_variables_in_tag_manager) for more information. ### Triggers We need to create a **Trigger** to tell Google Tag Manager when to send a Contentsquare dynamic variable, so we will create one for the event `addToCart`. * Name your trigger `AddToCartTrigger` * **Trigger Type** should be set to **Custom** * Trigger should fire on **Some Events** * For the Event, the **Event Name** should be **equal** to `addToCart` ### Create the custom function Tag We need to create a function tag **AddToCartDynamicVar** * The **Tag Type** set to **Function Call** * The **Class Name** set to **DynamicVarTag** (we'll create this class later) * Add two arguments, `Key: cs_dynamic_var_key, Value: Product`, `Key: cs_dynamic_var_value, Value: {{Product Name}}: {{Product Count}}` * The **Triggering** set to **AddToCartTrigger** It should look like this now:  ### Create the custom function Tag class In your app code, create a class named `DynamicVarTag`, assuming you used the name we suggested when creating the Tag in the GTM interface. If you named it otherwise, make sure to use the same name here, as it is how GTM connects the configuration and the actual class to trigger. We will use this class to call the Contentsquare dynamic variable function as follows. ```swift import GoogleTagManager import ContentsquareSDK @objc(DynamicVarTag) final class DynamicVarTag: NSObject, TAGCustomFunction { @objc func execute(withParameters parameters: [AnyHashable : Any]!) -> NSObject! { guard let dynamicVarKey = parameters["cs_dynamic_var_key"] as? String else { return nil } let dynamicVarValue = parameters["cs_dynamic_var_value"] if let dynamicVarStringValue = dynamicVarValue as? String { let dynamicVarString = DynamicVar(key: dynamicVarKey, value: dynamicVarStringValue) CSQ.trackScreenview(dynamicVar: dynamicVarString) } else if let dynamicVarIntValue = dynamicVarValue as? UInt32 { let dynamicVarInt = DynamicVar(key: dynamicVarKey, value: dynamicVarIntValue) CSQ.trackScreenview(dynamicVar: dynamicVarInt) } return nil } } ``` Now, every time Firebase sends an `addToCart` event, Contentsquare will send a dynamic variable `DynamicVar(key: "Product", value: "ProductA: 12")`. Note To create another tag for a dynamic variable, you can use the `DynamicVarTag` class again. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Google Tag Manager","description":"Leverage our native integration to send Google Tag Manager events to Contentsquare, with the CSQ iOS SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/google-tag-manager/","inLanguage":"en","dateModified":"2026-05-04T11:50:50+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Third-party libraries license - iOS description: Contentsquare iOS SDK includes several third-party libraries, which are licensed under their own respective licenses lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/third-party-libraries-license/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/third-party-libraries-license/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The CSQ SDK for iOS includes third-party libraries; the tables below list each library, its license, and copyright notice. ## Core SDK | Libraries | License | Copyright | | - | - | - | | SwiftProtobuf | Apache-2.0 license | Copyright (c) 2014 - 2017 Apple Inc. and the project authors | ## Error Analysis SDK | Libraries | License | Copyright | | - | - | - | | PLCrashReporter | MIT | Copyright (c) Microsoft Corporation. and the project authors | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Third-party libraries license","description":"Contentsquare iOS SDK includes several third-party libraries, which are licensed under their own respective licenses","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/third-party-libraries-license/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Session Replay - iOS description: Learn how to integrate and configure Session Replay capabilities in your iOS app with the CSQ SDK lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/session-replay/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/session-replay/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Session Replay enables replaying real sessions to observe how users interact with your product, by capturing screen content - including text and images - as users navigate your mobile app. For more details, see [Introduction to Session Replay for Apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) in the Help Center. ## Starter guide ### Prerequisites #### Update to latest SDK version To enable Session Replay in your app and get the most stable version, it is required to [upgrade the SDK](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/#install-the-sdk) to its latest version. #### Implement screen tracking Ensure screen tracking is implemented, since Session Replay collection starts at the first screenview event. See [Track screens](../track-screens/). #### Handle User consent Ensure user consent is handled for Contentsquare data collection, especially if you're implementing the SDK for the first time. See [Privacy](../privacy/) section. Note Mandatory data collection settings are configured by Contentsquare in your project parameters. [Learn more about Data collection configurations ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) on the Help Center. ### Configure Session Replay masking #### Masking behavior By default, the Contentsquare SDK is configured to mask all content displayed on the user interface (UI) to prevent unnecessary data collection. For more details, see what a fully masked screen looks like in [Masking mechanisms](#masking-mechanisms). **For testing purposes**, use this setup: * Either unmasking all the content by setting the [default masking](#default-masking) status to false. * Or unmasking most content with the [Text and Image unmasking configuration ↗](https://support.contentsquare.com/hc/en-us/articles/37271682878353-Data-masking-in-Session-Replay-Mobile-Apps) in your Console parameters. **For more granular control in deployment mode**, you can use the [Text and Image unmasking configuration ↗](https://support.contentsquare.com/hc/en-us/articles/17800059306396-Data-masking-in-Session-Replay-Mobile-Apps) in your Console parameters in combination with [SDK public masking APIs](#public-masking-apis) to fine-tune exactly which elements remain masked. Warning Always keep sensitive data masked to ensure compliance with privacy regulations and to protect users' personal data. ### Configure Event-Triggered Replays (optional) If Event-Triggered Replays is included in your contract, you can set up ETR events to enable specific screen and session collection in Session Replay. See [Event-Triggered Replays (ETR)](#event-triggered-replays-etr). ### Configure Webviews (optional) If your mobile app includes Webviews, specific implementation steps are required to ensure they are properly reflected in Session Replay: * Implement [Webview tracking](https://docs.contentsquare.com/en/webview-tracking-tag/) * Handle [personal data within WebViews](https://docs.contentsquare.com/en/webview-tracking-tag/session-replay/#personal-data-handling) ### Configure custom fonts (optional) To ensure UIKit text elements are rendered in Session Replay exactly as they appear in your app, you can add fonts in `otf`, `ttf`, `woff`, or `woff2` formats directly from the player. See [Managing iOS Fonts In The Player ↗](https://support.contentsquare.com/hc/en-us/articles/37271807874577) in the Help Center documentation. ### Test your setup #### Enable Session Replay on your device If the Session Replay sampling rate is less than 100%, only a portion of sessions are collected. To ensure data collection on your device for testing and debugging purposes, you can force it from the In-app Features settings by following these steps: 1. [Enable In-app Features](../in-app-features/) 2. Open In-app Features settings with a long press on the screenshot button 3. Under "Session Replay", toggle "Enable Session Replay" on 4. Kill the app 5. Start app, a new session is starting with Session Replay enabled  #### How do I know if Session Replay is enabled? There are 2 places where you can check if Session Replay is enabled: **In the logs:** The log `Session Recording is starting` will confirm that Session Replay is enabled. **In in-app features settings:** Below the "Enable "will start at next app start" *(see below [Access the replay](#access-the-replay))*, you will either see: * `No replay link available` which means Session Replay is not running for the current session * `Get Replay link` which means Session Replay is running for the current session #### Access the Replay The session can be accessed by tapping on `Get replay link` button from the in-app features settings:  The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay your session up to the previous screenview if the session is still running. ## Define when Session Replay starts Session Replay starts automatically by default, but if you need to ensure that Session Replay data is collected only under certain conditions — for example, only after receiving explicit user consent for Session Replay or in specific geolocations — follow instructions described below. ### Disable Automatic Session Replay Initialization Set the option `sessionReplayAutoStart` to `false` when starting the SDK to prevent Session Replay from starting automatically at app launch. ```swift CSQ.start( options: [ .sessionReplayAutoStart: false ] ) ``` ### Start Session Replay Once your app has determined that Session Replay can start — for example, via a reverse geocoding service or after receiving specific user consent for Session Replay — you can call `CSQ.startSessionReplay()` to start Session Replay. Note Calling `startSessionReplay()` does not force Session Replay data collection. It enables the Session Replay module, allowing it to begin checking whether the global Replay sampling rate or Event Triggered Replay conditions are met. Session Replay data collection will only start if these conditions are satisfied. For more information, see [Data collection for Session Replay (Apps) ↗](https://support.contentsquare.com/hc/en-us/articles/37271951720721) on the Help Center. ### Stop Session Replay If you need to stop Session Replay immediately, you can call `CSQ.stopSessionReplay()`. Note A Session Replay stopped with `stopSessionReplay()` cannot be restarted until next app launch. ## Personal Data Masking The Session Replay feature replays every interaction of your users with your app. To respect the user's right to privacy, the Contentsquare SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our [Masking rules](#masking-rules) Warning **Privacy Manifest:** If you decide to use unmasked elements leading to collection of new data or use already collected data but for a different purpose, it is up to you to update the privacy practices described in your app manifest accordingly. Here are some common examples of data collected via unmasked Session Replay: Search history, Purchase history, Advertising data, etc. See [Types of data and purpose](../privacy/) already described in the Contentsquare iOS SDK Privacy Manifest. Contentsquare is not intended nor designed to collect sensitive personal data (such as health, financial, or racial data). It is the customer's responsibility not to send any sensitive personal data to Contentsquare. ### Masking mechanisms Masking depends on the type of element: | Element Type | Masking Behavior | | - | - | | `UIKit.UIImage` and `SwiftUI.Image` | Image isn't collected, a placeholder is sent instead of the content; the "IMG" placeholder will be displayed in the frame of the element. | | `UIKit.UILabel` and `UIKit.UITextView` | Text is replaced by "la" repeated as many times as needed to equal the original character count. White characters are preserved. For instance `the lazy fox` is collected as `lal lala ala`. All other visual properties are collected (text color, background color, alignment, etc.). | | `UIKit.UITextField` | Same as `UIKit.UILabel` or `UIKit.UITextView` unless `isSecureTextEntry` is set to `true`. In this case all characters, including whitespaces are replaced with "•". | | `SwiftUI.Text` | Element is replaced by a black rectangle. | | All other types | No specific data is collected but all visual properties are collected: size, background color, corner radius, etc. | If you think a specific element can reveal personal data from one of these properties mask it using one of the methods presented below. An efficient way to check how a view is rendered in the Session Replay is to navigate to the desired view with the SDK running then use the quick replay link.  #### Original vs Replay fully masked * UIKit  * SwiftUI  ### Masking rules Masking rules can be applied in two ways: 1. **Through remote masking configuration in the CSQ Console (for admin users):** this is managed directly in the Console and takes effect for all sessions as soon as the app is restarted or brought to the foreground. See [How to customize masking rules from the Data Masking tab ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) in the Help Center. 2. **Using public masking APIs in the SDK (for mobile application developers):** these APIs require developer implementation and will be applied only after the mobile app has gone through its release cycle. The SDK determines whether views, images, and texts are masked according to the following rules, ranked from highest to lowest priority. Once a rule is triggered, the state is set, and subsequent rules are not applied. #### General rules | Rules (highest to lowest priority) | Configured via | | - | - | | 1. The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text or Image masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. An [instance](#maskingun-masking-by-instance) is specifically masked or unmasked | API | | 4. A [parent](#masking-and-unmasking-behaviors-on-a-parent-view) is specifically masked or unmasked | API | | 5. A [type](#maskingun-masking-by-type) is masked or unmasked | API | | 6. A parent [type](#maskingun-masking-by-type) is masked or unmasked | API | | 7. Remote Text or Image unmasking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 8. Otherwise the [default masking state](#default-masking) is applied | API | #### Text input fields rules `UIKit.UITextField`, `UIKit.UITextView` and `SwiftUI.TextField` text inputs follow specific rules as the risk of leaking personal data is higher with these elements: | Rules (highest to lowest priority) | Configured via | | - | - | | 1. The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text inputs masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. An [instance](#maskingun-masking-by-instance) is specifically masked or unmasked | API | | 4. A [type](#maskingun-masking-by-type) is masked or unmasked | API | | 5. Otherwise a text input field remains masked | default | Note Default masking and parent masking don't change the masking state of text inputs. ### Public masking APIs #### Default masking All iOS views and subclasses of `UIView` are fully masked by default. Change the default masking state with: ```swift /// Change the masking state of all types of views. /// - Parameter mask: true restores the default masking state. /// false unmasks every type of views. static func setDefaultMasking(_ mask: Bool) ``` Note Setting the default masking state to `false` does not affect `UITextField`, `SwiftUI.TextField` and `WKWebView`. #### Masking/Un-masking by instance * UIKit Use `mask(view:)` and `unmask(view:)` methods to mask or unmask a specific view instance. Masking is applied recursively to all subviews unless specified otherwise (cf. [Masking and Unmasking behaviors on a parent view](#masking-and-unmasking-behaviors-on-a-parent-view)). **Following the previous example on un-masking UIButtons:** you are in default masking, the `UIButton` are unmasked but a screen shows a button, `myButton`, that contains sensitive information. You can mask it with `mask(view: myButton)`. * SwiftUI Mask or unmask a SwiftUI `View` instance by using the following view modifier. Masking is applied recursively to all subviews unless specified otherwise (cf. [Masking and Unmasking behaviors on a parent view](#masking-and-unmasking-behaviors-on-a-parent-view)). ```swift @ViewBuilder func csMasking(_ shouldMask: Bool) -> some View ``` #### Masking/Un-masking by type Although the SDK allows masking elements by type for convenience but it isn't the recommended masking mechanism because it impacts all screens of your application. Use this when you have a specific class for presenting user information or for displaying the user profile picture to make sure it always stays masked, for instance. * UIKit Use `mask(viewsOfType:)` and `unmask(viewsOfType:)` methods if you want to handle a specific type, whether system or custom. **Example: un-masking UIButtons**: If default masking is set to true, and you don't want any button to be masked, call `unmask(viewsOfType: UIButton.self):` to specify that all instances of `UIButton` and its subclasses should not be masked. * SwiftUI Mask or un-mask by type using following methods as needed: ```swift /// Masks or unmasks all text elements. /// /// The text elements are `Text` for SwiftUI and `UILabel` for UIKit static func maskTexts(_ mask: Bool) ``` ```swift /// Masks or unmasks all image elements. /// /// The image elements are `Image` for SwiftUI and `UIImageView` for UIKit. static func maskImages(_ mask: Bool) ``` ```swift /// Masks or unmasks all text input elements. /// /// The text input elements are `TextField`, `SecureField`, `TextEditor` for SwiftUI /// and `UITextField`, `UITextView` for UIKit. /// static func maskTextInputs(_ mask: Bool) ``` Warning These APIs will also affect **UIKit masking**. You can use only these APIs and mask/unmask both UIKit and SwiftUI elements. #### Masking and Unmasking behaviors on a parent view ##### UIKit Masking is applied recursively to all children unless a specific rule has been applied to one of them. In this case, this rule also applies recursively. **Examples** Consider the following structure: ```plaintext (parent view) ------------------------ | "Parent Label" | | | | (child view) | | -------------------- | | | "Child Label" | | | | | | | -------------------- | | | ------------------------ ``` Here's how the masking rules applied affect the parent and child labels: | Rules applied | Parent Label | Child Label | | - | - | - | | No rule applied | Masked | Masked | | Parent view unmasked | Unmasked | Unmasked | | Parent view unmasked and child view masked | Unmasked | Masked | | Default masking = false | Unmasked | Unmasked | | Default masking = false and parent view masked | Masked | Masked | See [Masking rules](#masking-rules). **Unmasking an instance when its type is masked** If you've masked `UILabel` types specifically or are in default masking, call `unmask(view: myLabel)` so that all `UILabel` **instances** are masked except `myLabel`. **Mask an instance when its type is unmasked** If you've unmasked the `UILabel` type specifically or are using default masking, call `mask(view: myLabel)` so that no `UILabel` is masked except `myLabel`. ### Implementation recommendations * UIKit Masking operations should **always be performed before the target view is added to the window** to avoid any Personal Data leak. For instance, you can set up masking in the `didFinishLaunching` callback of your app or if you need to change masking behavior while your app is launched: this can be done in `loadView`, `viewDidLoad` or `viewWillAppear` if you use a `ViewController`. * SwiftUI Masking operations should be done as early as possible. For masking [by type](#maskingun-masking-by-type), in the setup of your app for instance. For masking [by instance](#maskingun-masking-by-instance), in the body of your `View` by calling the `csMasking` modifier. ### Keeping track of what is masked The SDK doesn't provide a list of what is currently masked, if you need to keep track, you probably will have to write your specific wrapper. ### Masking operations performance impact Repeating the same operation has little to no impact. For example, you can call `unmask(viewsOfType: UIButton.self)` multiple times without impacting the SDK or your app performance. ## Event-Triggered Replays (ETR) Event-Triggered Replays (ETR) is an add-on feature that allows you to selectively collect specific screens or sessions for Session Replay, based on predefined custom events. Once configured, ETR events can be used to filter specific replays, or view these events as they happen in the player event stream. To enable ETR, contact your CSM or Implementation Manager. For more information, see [Event-Triggered Replays ↗](https://support.contentsquare.com/hc/en-us/articles/4412027865874) in the Help Center. Note When ETR is enabled, the SDK collects data for the entire session even if none of the ETR methods described below are called. After collection, only the sessions or screens that match the global replay sampling rate or are associated with ETR events are retained. As a result, you may notice a network activity during all sessions, regardless of whether ETR has been triggered or not. Warning To protect end-user personal data, ensure that appropriate masking configurations are applied to all screens even the ones that are not associated with ETR events. ### Trigger Replay for the Session Use the following function to trigger Session Replay for the entire current session, with the parameter `name` as "ETR event". ```swift CSQ.triggerReplayForCurrentSession(name: name) ``` ### Trigger Replay for the Screen Use the following function to trigger Session Replay for the entire current screen, with the parameter `name` as "ETR event". ```swift CSQ.triggerReplayForCurrentScreen(name: name) ``` ## Advanced features for Experience Monitoring Note These features are only available for Experience Monitoring Mobile customers. Reach out to your Contentsquare contact for more details. ### Send user identifier Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier: email, phone number, customer ID… As these values are typically personal data, from the moment the SDK is collecting the User Identifier, we immediately encode the value using a hashing algorithm so that the information is hidden and can never be accessed. Warning **Note about Privacy Manifest:** If you decide to use User Identifier to collect new data or use already collected data but for a different purpose, it is up to you to update the privacy practices described in your app manifest accordingly. Here are some common examples of data collected via User Identifier: Email, Other user contact info, etc. See [Purpose of processing and categories of personal data collected](../privacy/#purpose-of-processing-and-categories-of-personal-data-collected) already described in the Contentsquare iOS SDK Privacy Manifest. Use the following code to send a user identifier: ```swift CSQ.sendUserIdentifier("any_identifier") ``` When called, the SDK will log: ```plaintext CSLIB ℹ️ Info: User identifier hashed sent {value} ``` ### Sending a user identifier for each session You may want to send the user identifier for each session. While triggering the user identifier at app launch will cover most cases, it will not be enough. A session ends start 30 minutes after the last event. See [Session definition](../data-collection/#session-definition) for more information. That is why we also recommend sending the user identifier every time the app enters foreground. You can use [`didBecomeActiveNotification` notification ↗](https://developer.apple.com/documentation/uikit/uiapplication/1622953-didbecomeactivenotification) and [`sceneDidBecomeActive(_:)` callback ↗](https://developer.apple.com/documentation/uikit/uiscenedelegate/3197915-scenedidbecomeactive) to detect foreground and trigger a `sendUserIdentifier()`. ### Limitations * User identifier max length is 100 characters (if the limit is exceeded, the user identifier will not be handled and you will see an error message in the Console/Logcat) * Only the first 15 user identifiers per view will be processed on server side * The SDK will trim and lowercase user identifier * User identifier event are not visible in Log visualizer ## Integrations Contentsquare provides the ability to retrieve the link of the replay to be attached to other vendors such as Voice of Customer or Crash reporting tools. ### Get current replay Link Generate a link to the replay of the current session. This link can be pushed to any internal or 3rd-party tool as a custom property/variable. For instance, you can add the replay link to: * Each user request sent to your customer service tool * Each user voting in your Voice of Customer tool * Each user session in your App Performance, Observability tool * ... Note The replay link can also be accessed from the in-app features settings. See [Access the Replay](#access-the-replay). You can register to replay link creation and updates using the following API: ```swift CSQ.metadata.onChange { print("CSQ current replay link is \($0.sessionReplayURL ?? "not set")") } ``` Warning You can only have one callback at a time. Calling this API twice will override the previous callback. When a new link is available, the SDK logs: ```plaintext CSLIB ℹ️ Info: SessionReplay link updated: https://app.contentsquare.com/quick-playback/index.html?pid={projectId}&uu={userId}&sn={sessionNumber}&recordingType=cs ``` Warning For the callback to be called, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event must have been sent, since Session Replay only starts after the first screenview event. If you have a Contentsquare account, you can use this link to directly watch your current Session Replay on the Contentsquare Platform. The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay the session up to the previous screenview if the session is still running. ## How Session Replay works ### Initialization Sessions can be collected for Session Replay if the Session Replay feature has been enabled for your project and the session matches the collection criteria. The following conditions will have an impact on which sessions will be collected: * **User consent**: The users have given their **consent** (if required) * **Collection rate**: The session is being **drawn for collection** (see Collection Rate below) * **Compatibility**: The **OS version** is supported. * **App version**: The **app version** is not part of the block list (see App version block list below) When Session Replay is turned off, no content specific to Session Replay is collected whatsoever. The standard Contentsquare analytics tracking remains unaffected by this. #### Collection rate Session Replay collection is based on a percentage of the total sessions. By default Session Replay collection is disabled. During the early access phase, the percentage or collected sessions will be set to 1% at the beginning. It will then be adjusted according to: * The traffic on your app * The volume of collected sessions set in the contract #### Compatibility See [Compatibility](../compatibility/). #### App version block list Contentsquare team can add versions of your app in the block list to make sure Session Replay does not start on these versions. This is done when a problem is discovered on a specific version of your app, such as a Personal Data for which the masking was forgotten. This allows to keep Session Replay to work on the other app versions (especially the new ones with the fix). ### Data Collection The SDK monitors the application lifecycle events and the view hierarchy, and generates Session Replay data from the behavior of the app, the content of the screen and the interaction of the user. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. Tip Session collection will start at the 1st screenview event. ### Quality levels Session Replay has three quality levels available: High, Medium, Low. Quality level is defined by the frame rate and the image quality. The quality level is defined independently for **Wi-Fi** and **Cellular Network**. The default level for both is **Medium**. For more information on network data consumption see: [Performance Impact section](#performance-impact). Note If you require a particular setting, reach out to your Contentsquare contact that will make the adjustment in the project configuration. #### Quality-level examples Select the image to open it in full size and GIF format. [](https://docs.contentsquare.com/_astro/ios-quality-level.CjUY6Jo0.gif) ### Network and Storage By default, Session Replay data can be sent over **cellular network**. If the particular context of your app or users requires a very limited impact on cellular data consumption, **sending data over cellular network can be completely disabled**. Once disabled, data will be sent when the device is using Wi-Fi. Reach out to your Contentsquare contact that will make the adjustment in the project configuration. #### Storage Before being sent, data is stored in local files on disk up to 30MB on iOS and 20MB on Android. If the limit is reached, Session Replay is stopped. It will restart at the next app launch once the SDK is able to send the data. ### Requests The maximum request size is 1Mbyte. Requests are sent: * Every 10 seconds * At app hide * When [Replay Link API](#get-current-replay-link) is called ## Performance impact We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. ### Performance impact mitigation Most operations related to Session Collection are performed on background threads, for the impact on the main thread to be minimal. To make sure of this, we run performance tests on testing applications, using XCTMetric and Hitch Time Ratio measures. We also set up mechanisms that stop the Session Collection if we detect the feature is using too much memory. We defined our network strategy to have the lesser impact on CPU and battery of the users devices. We measure these impacts, using Apple Dev Tools, for each release of our SDK. Session Collection will also stop if we use up to 30Mbytes of local storage. You can reduce the quality level if you want to favor performance impact over quality. ### Performance test results The following performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | iPhone 7 | | iOS version | 15.7.8 | | Test App built using Xcode version | 14.3.1 | | Test App built with Swift version | 5.8 | | Quality level | High | | Default Masking State | Disabled | We conducted the tests using a default `Master-Detail` app built using ad hoc distribution with no app thinning and with Swift symbols stripped. In the app, the SDK was making calls to the public APIs, running, and collecting data in its default state. Note The numbers provided below will vary depending on the user's device, iOS version, SDK version, and if you use Swift or not, which Swift version you use if you do, if you enabled bitcode or not and which options you used when building your IPA for App Store distribution. Note Screens built with SwiftUI produce, on average, 120% of the SR data produced by similar screens built with UIKit. | Property | Value | | - | - | | Max CPU overhead | <10% | | Max RAM usage | <5MB | | Session Replay data transmitted over network during 1 minute of use | | | - with "High quality" level | <2Mbytes | | - with "Medium quality" level | <1Mbytes | | - with "Low quality" level | <900Kbytes | ## Known limitations ### Color [Init `UIColor` with Color ↗](https://developer.apple.com/documentation/uikit/uicolor/3550899-init) doesn't work in dark mode. **Workaround:** Use [`UIColor.init(named:)` ↗](https://developer.apple.com/documentation/uikit/uicolor/2877380-init). ### Maps Maps can potentially contain Personal Data and are therefore replaced by a placeholder with no ability to un-mask them. ### NSAttributedString handling The extracted text doesn't support the `expansion`, `obliqueness`, `paragraphStyle` and `textEffect` attributes. ### Multiline labels UIKit labels configured for multiple lines may overflow their bounding box, depending on the font and text length. A longer text increases the risks of causing an overlap with elements below (e.g.: other text, or image). ### Multiple windows Multi-window is not supported. ### System elements capture System elements are not collected. For instance, we do not collect: * `UIImagePickerController` * `SKStoreReviewController` * All `AVFoundation` components such as: * `AVPlayerViewController` for videos * `AVCaptureVideoPreviewLayer` for camera ### System elements masking Bottom line is that masking/unmasking any element is possible only if you have a reference or you know the type of the element that you want to mask. Since the access to the instance/type of Alert and Menu components is not documented in [Apple documentation ↗](https://developer.apple.com/documentation/uikit/uialertcontroller#overview), developers cannot directly mask/unmask these components or parts of them with CS public masking APIs. However, there are workarounds to mask/unmask them, as described below. #### Alerts ##### UIKit A possible workaround to fully mask a UIKit Alert is to pass the `UIAlertController` `view` property to the `mask(view:)` and `unmask(view:)` APIs. ##### SwiftUI SwiftUI Alerts cannot be specifically masked or unmasked. If the [default masking](#default-masking) is `false` and you want to mask an alert, a possible workaround is to mask all the app by changing the default masking to `true` when the alert appears and back to `false` when it disappears. Warning There is no workaround to unmask only an alert if the default masking is `true`. #### Menus Menus cannot be specifically masked or unmasked. If the [default masking](#default-masking) is `false` and you want to mask a menu, a possible workaround is to mask all the app by changing the default masking to `true` when the menu appears and back to `false` when it disappears. Warning There is no workaround to unmask only a menu if the default masking is `true`. ### System images ```swift Image(systemName: "pencil") ``` On iOS 17.0 and later, system images are considered as text within the masking rules. Any system-provided images used in your app's UI is subject to the same privacy and masking regulations as text content. ### Animations Animations lasting longer than 35 ms may be partially rendered in the replay, potentially resulting in a broken or incomplete layout for the rest of the animation. This does not affect the rest of the session, and the app will render correctly again on the next user interaction or detected animation. ### iOS 26 rendering Rendering limitation of apps compiled with Xcode 26 and running on iOS 26 include: * Some SwiftUI button backgrounds are not displayed correctly * Liquid Glass design and transparency effects are not faithfully rendered ### Apple Pay button The Apple Pay button is not rendered in the replay and appears as blank space. ## Troubleshooting ### Requests are not sent from an iOS simulator If you struggle to watch a replay collected on an emulator/simulator, it may be due to some network constraints applied on your computer (VPN, company network restrictions, etc.). Check your configuration or use a real device. See [Requests are failing](../troubleshooting/#requests-are-failing) for more information about our endpoints and requests. ### Very long session on an iOS simulator If you leave the simulator/emulator running with the app in foreground, the session will not end, even if you are inactive. This can lead to artificially long sessions (several hours). To better emulate actual user behavior, put the app in background or kill it. Note An app kill **does not end a session**.\ See [Session definition](../data-collection/#session-definition). ### Uncaught exception due to NSAttributedString If the following exception is encountered: `NSInvalidArgumentException: -[__NSCFType CGColor]: unrecognized selector sent to instance`, It is probably due to an Objective-C bridging issue in `Foundation`, which makes it possible to pass `CGColor` instances as values for the `foregroundColor` and `strikeThroughColor` attributes of a `NSAttributedString`. While a `UILabel` with such an attributed string will be displayed correctly, its `textColor` attribute will have the wrong type, and the SDK won't be able to handle it, causing a crash in Session Replay. Because of this, it is important to ensure that actual `UIColor` instances are passed as values, as per the [official documentation ↗](https://developer.apple.com/documentation/foundation/nsattributedstring/key/1533563-foregroundcolor). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Session Replay","description":"Learn how to integrate and configure Session Replay capabilities in your iOS app with the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/session-replay/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Product Analytics data capture - iOS description: Access to acquisition analysis and lifetime metrics by implementing the Product Analytics data capture using the CSQ SDK lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/set-up-product-analytics-data-capture/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/set-up-product-analytics-data-capture/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This page instructs how to set up Product Analytics data capture in combination with Experience Analytics. 1. Configure and start the SDK with `CSQ.start()`. * Product Analytics **AppDelegate.swift** ```swift import UIKit import ContentsquareSDK @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // ... CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID" ) } } ``` Find your environment ID `YOUR_ENVIRONMENT_ID` is either provided to you by Contentsquare or you can find it in **Account** > **Manage** > **Projects** > \[Select your project] > **Environments** within the [Product Analytics web app ↗](https://heapanalytics.com/app/). * CSQ Experience Platform (Early Access) **AppDelegate.swift** ```swift import UIKit import ContentsquareSDK @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // ... CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID" ) } } ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 2. Enable autocapture with `.enableNativeAutocapture = true`. * Product Analytics **AppDelegate.swift** ```swift import UIKit import ContentsquareSDK @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // ... CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .enableNativeAutocapture: true ] ) } } ``` * CSQ Experience Platform (Early Access) **AppDelegate.swift** ```swift import UIKit import ContentsquareSDK @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // ... CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ .enableNativeAutocapture: true ] ) } } ``` 3. (Optional) If your Product Analytics environment is hosted in the EU, set the `baseURL` option to `"https://mh.ba.contentsquare.net"`. * Product Analytics ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .baseURL: "https://mh.ba.contentsquare.net" ] ) ``` * CSQ Experience Platform (Early Access) ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ .baseURL: "https://mh.ba.contentsquare.net" ] ) ``` 4. Add `.disablePageviewAutocapture = true`. * Product Analytics **AppDelegate.swift** ```swift import UIKit import ContentsquareSDK @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // ... CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .enableNativeAutocapture: true, .disablePageviewAutocapture: true ] ) } } ``` * CSQ Experience Platform (Early Access) **AppDelegate.swift** ```swift import UIKit import ContentsquareSDK @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // ... CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ .enableNativeAutocapture: true, .disablePageviewAutocapture: true ] ) } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Product Analytics data capture","description":"Access to acquisition analysis and lifetime metrics by implementing the Product Analytics data capture using the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/set-up-product-analytics-data-capture/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track custom variables - iOS description: Enhance analytics by capturing custom variables for detailed user behavior analysis in your iOS app with the CSQ SDK lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-custom-variables/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-custom-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Custom variables attach additional information about the screen, user, or session to screenview events. For example, they can include information on the current layout of a screen, like day/night mode. Warning **Note about Privacy Manifest:** If you decide to use Custom Variables to collect new data or use already collected data but for a different purpose, it is up to you to update the privacy practices described in your app manifest accordingly. See [Purpose of processing and categories of personal data collected](../privacy/#purpose-of-processing-and-categories-of-personal-data-collected) already described in the Contentsquare iOS SDK Privacy Manifest. ## Defining custom variables To define and send custom variables, follow this: ```swift CSQ.trackScreenview("screen_name", cvars: [ CustomVar(key: "key1", value: "value1"), CustomVar(key: "key2", value: "value2"), ]) ``` ## Limits ### On the server side * It is possible to save up to 20 distinct custom variables per screenview. If more are received, only the first 20 custom variables, based on their `index` value, will be kept. * The `index` value of the custom variable is used to determine which custom variables to be kept. Only `index` value between 1 and 20 will be taken into account. ### On the SDK side * Every custom variable is composed of `index`, `name` and `value`. * If you are using the same `index` twice in the same screen, only the first (`name`, `value`) pair associated with the `index` will be kept. * In case `name`(max. 512 characters) or `value`(max. 255 characters) maximum character length is reached, the SDK will automatically trim the exceeding characters. * If `name` or `value` are empty, the SDK will instead send the literal string `"cs-empty"`. * Use a consistent index for a given custom var within an application — for instance, if the "screen layout" is collected with an `index` of 3, use the slot 3 for this information on every screen of the application. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track custom variables","description":"Enhance analytics by capturing custom variables for detailed user behavior analysis in your iOS app with the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-custom-variables/","inLanguage":"en","dateModified":"2026-05-04T11:50:50+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track dynamic variables - iOS description: Learn how to track and analyze variable metrics over time in your iOS app using the CSQ SDK lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-dynamic-variables/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-dynamic-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. *Dynamic variables* are additional information on the session that can be used to *segment sessions*. For example, they can include information on the A/B Test variations displayed to the current user. ## Defining dynamic variables To define and send a dynamic variable, directly use the key and String/Long value: ```swift CSQ.addDynamicVar("cart_value", 123); CSQ.addDynamicVar("user_account_status", "premium"); ``` **Type of the value** — The value can be either a **whole number** or a **string**. For each case, available features won't be the same in the Contentsquare app: * For **whole numbers**, you will be able to do some algebra. Example: *sessions with dynamic variable key = "numberOfFriends" and value >= 10* * For **strings**, auto-completion and Regular Expression will be available. Example: *sessions with dynamic variable key = "accountType" and value = "Premium"* ## Sending a dynamic variable for each session You may want to send a dynamic variable for each session (like the user's country or store). While **triggering the dynamic variable at app launch will cover most cases, it will not be enough**. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See [Session definition](../data-collection/#session-definition) section for more information. That is why we also recommend **sending such dynamic variable every time the app enters foreground**. You can use [`didBecomeActiveNotification` notification ↗](https://developer.apple.com/documentation/uikit/uiapplication/1622953-didbecomeactivenotification) and [`sceneDidBecomeActive(_:)` callback ↗](https://developer.apple.com/documentation/uikit/uiscenedelegate/3197915-scenedidbecomeactive) to detect foreground and trigger a dynamic variable. ## Limits ### On the server side * It is possible to save up to 40 distinct *dynamic variable keys* per screenview. If more are received, only the first 40 keys will be kept. * If you are using the same key twice on the same screenview, the last value associated with the key will be collected. ### On the SDK side * Every dynamic variable is composed of a pair of key (max. 512 characters) and value (max. 255 characters string or number of type `Long` between 0 and 232 - 1). In case these maximums length are reached, the SDK will automatically trim the exceeding characters. * If key or value are empty, the SDK will instead send the literal string "cs-empty". ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track dynamic variables","description":"Learn how to track and analyze variable metrics over time in your iOS app using the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-dynamic-variables/","inLanguage":"en","dateModified":"2026-05-04T11:50:50+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track transactions - iOS description: Track transactions with the Contentsquare iOS SDK lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-transactions/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-transactions/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To associate a user's session with their potential purchases (and corresponding revenue), you must send the transaction via a dedicated API. For each transaction, we send: * Price (mandatory) * Currency (mandatory) * Transaction ID (optional) ```swift import ContentsquareSDK let transaction = Transaction(id: "transactionId", value: 100.0, currency: "USD") CSQ.trackTransaction(transaction) ``` Warning **Each transaction must only be sent once**. A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ## Currency The currency is conforming to the [ISO 4217 ↗](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) standard. The currency can be passed either as "alphanumeric code" or "numeric code". If the currency passed doesn't match the supported currencies, the SDK will send a currency value of `-1`. It will be processed as the default currency of the project. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track transactions","description":"Track transactions with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-transactions/","inLanguage":"en","dateModified":"2026-05-04T11:50:50+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track Webviews - iOS description: Track webviews with the Contentsquare iOS SDK lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-webviews/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-webviews/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. WebView tracking links the Contentsquare SDK to the JavaScript tag running inside your WebViews to support analytics and Session Replay for web content displayed within your app. iOS compatibility Contentsquare **only** allows to track instances of `WKWebView`.\ `SFSafariViewController` is **not** supported: The Contentsquare SDK **cannot** track what is happening within its context, and its content will **not** be visible in Session Replay. ## Enable tracking in WebViews ### Where to inject your WebViews? It is **essential** that you register your WebViews in `viewWillAppear()` and unregister them in `viewWillDisappear()`. Additionally, when setting a delegate on your WebView, ensure that it is implemented and set **before** calling `CSQ.registerWebView(webView: WKWebView)`. If this order is not respected, your delegate will **not** receive any callbacks. ### WebView tracking lifecycle Use the following APIs: ```swift import ContentsquareSDK import WebKit // Register a WKWebView with ContentsquareSDK CSQ.registerWebView(webView) // Unregister a WKWebView with ContentsquareSDK CSQ.unregisterWebView(webView) ``` ### Tag setup To complete the implementation, inject the **CS Tag in WebView mode** on your pages. See 📚 [Mobile Apps WebView Tracking Documentation](https://docs.contentsquare.com/en/webview-tracking-tag/#manual-injection). ## Full example Here is a `UIViewController` implementation. Register the WebView in `viewWillAppear()` and unregister it in `viewWillDisappear()`: ```swift override func viewWillAppear(_ animated: Bool) { super.viewWillAppear(animated) // Inject the Bridge between the CS Tag in WebView mode and the SDK CSQ.registerWebView(webView) } override func viewWillDisappear(_ animated: Bool) { super.viewWillDisappear(animated) CSQ.unregisterWebView(webView) } ``` ## Validate WebView tracking ### On the native side Once you open the screen with the tracked WebView in your app, you should see the following logs in sequence: 1. **WebView registered:** ```plaintext CSLIB ℹ️ Info: [WebView] Registering WebView on native side for page: [URL]. Waiting for Web Tracking Tag messages… ``` 2. **Web page loaded:** ```plaintext CSLIB ℹ️ Info: [WebView] Navigated to new page: [URL]. Waiting for Web Tracking Tag messages… ``` ### On the Web side Once the Web Tracking tag runs in the web page, you should see the following logs in sequence: 1. **JavaScript bridge detected:** ```plaintext CSLIB ℹ️ Info: [WebView] CSJavascriptBridge is detected on page: [URL] ``` 2. **Tag configuration received — confirms successful tag to SDK communication:** ```plaintext CSLIB ℹ️ Info: [WebView JS log] (TAG_CONFIGURATION) [Config] ``` #### Validating Pageview and Gestures tracking * Page views sent through the Web Tracking Tag are displayed the same way as native screen views: ```plaintext CSLIB ℹ️ Info: Screenview - Screen name: "{{page name given}}" - Screen number: 11 ``` * Taps and swipes detected by the Web Tracking Tag are also displayed the same way as taps and swipe on native elements, but the end of the target contains HTML DOM elements: ```plaintext CSLIB ℹ️ Info: Tap - Target: ...>UIViewControllerWrapperView:eq(0)>UIView:eq(0)>WKWebView:eq(0)|webview|img#picture-holder ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track Webviews","description":"Track webviews with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-webviews/","inLanguage":"en","dateModified":"2026-05-04T11:50:50+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track Screens - iOS description: Learn how to implement screen tracking in your iOS app with CSQ SDK to capture user navigation patterns and screen interactions lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-screens/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-screens/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare aggregates user behavior and engagement at the screen level. To do so, it is required to track screen transitions by calling a dedicated API. When the API is called, the SDK logs a `screen_view` event that identifies the new screen with the screen name provided. Warning Sessions without at least one screenview will be discarded. ```swift let customVar = CustomVar(index: 123, name: "my_custom_var", value: "some_value") CSQ.trackScreenview("MyViewController", cvars: [customVar]) ``` ## Screen name handling The screen name is limited to 2083 characters. However, this limit is not enforced by the SDK, but rather by the Contentsquare servers. Note If the Track screen API is called without passing a screen name, the event will still be processed with default value: `missing screenName ([ViewController className])` Warning **Note about Privacy Manifest:** If you decide to use Screen names to collect new data or use already collected data but for a different purpose, it is up to you to update the privacy practices described in your app manifest accordingly. See [Purpose of processing and categories of personal data collected](../privacy/#purpose-of-processing-and-categories-of-personal-data-collected) already described in the Contentsquare iOS SDK Privacy Manifest. ## Screenview after app in background The SDK triggers a screenview automatically after the app is put in background and foreground, as long as a screenview with a screen name has been triggered previously. It will use the last screen name set. ## Implementation recommendations From a functional standpoint, we expect a screenview to be sent: * Right after the SDK has started * When the screen appears * When a modal/pop-up is closed and the user is back on the screen * When the app is put in the foreground (after an app hide) We advise you to take a look at our reference implementations of screenviews in [our sample app ↗](https://github.com/ContentSquare/apple-sample-app). Learning from them is the best way to make sure your implementations are correct. Regardless, here is some general advice. ### When to send your first screenview Most events collected by the SDK require a screenview event to be sent first so they can be associated with that screen; otherwise, they will be discarded. If you need to collect events from the moment the app launches, you should trigger a screenview event immediately after the SDK has started: ```swift CSQ.start() CSQ.trackScreenview("Launch screen") ``` #### UIKit As a general rule of thumb, you should send your screenviews in `viewWillAppear(_ animate: Bool)`. Be aware that only doing this might not cover all your cases though, and you might need to send screenview events in other parts of your code. #### SwiftUI If you are using SwiftUI to build your application, you should send your screenview in `.onAppear()`. Be aware that only doing this might not cover all your cases though, and you might need to send screenview events in other parts of your code. ```swift import ContentsquareSQK var body: some View { Text("My first screen") .foregroundColor(Color.blue) .onAppear() { CSQ.trackScreenview("First screenView") } } ``` Known limitation Apps using the SwiftUI [`.drawingGroup(opaque:colorMode:)` ↗](https://developer.apple.com/documentation/swiftui/view/drawinggroup\(opaque:colormode:\)) modifier may experience issues with Zoning Analysis. This modifier flattens a subtree of views into a single offscreen image (bitmap) before rendering it. As a result, individual components within the group are not accessible to the SDK, making it impossible to apply zoning to them. ### ScrollViews with paging Be careful when tagging screens with paged ScrollViews: if you want to create a screenview event whenever the user changes the page, do so in UIScrollViewDelegate's `scrollViewDidEndDecelerating(_ scrollView: UIScrollView)` function. Make sure that you do not trigger a double tag when the screen appears, or when you come back to the screen after the app being hidden. Also make sure not to send a screenview when the user slightly interacts with a page, but without really changing pages. ### Popups and modals When dealing with popups and modals, if you are having issues triggering a screenview event for the underlying view when the modal closes we have the following advice. You could overcome this issue by using a delegate pattern, and setting the underlying screen as the modal's delegate. The modal would call some delegate method when it is dismissed. The underlying screen would implement that method, where it would make the screenview. iOS 13 and later On iOS 13 and more, modals can be dismissed by swiping down.\ In that case, `unwindFromSegue` won't be triggered. The new `presentationControllerDidDismiss(_ presentationController:)` function of `UIAdaptivePresentationControllerDelegate` will be triggered instead. Implement this function and call `CSQ.trackScreenview(screenViewWithName:)` there for the tracking to be correct on all iOS versions. [Check out our sample app ↗](https://github.com/ContentSquare/apple-sample-app/blob/master/Shared/Showcases/Screen%20Views/Modals/ModalPresentingViewController.swift) for more details about the implementation. ### Back navigation and navigation between screens Make sure that screenview events will be triggered when a user will go to the previous screen (example: Home → Profile → Home), it is expected to have a screenview event for the Home screen that might be reached with the back navigation button. Normally, if you send your screenviews in `viewWillAppear`, this should work fine. ### Redirecting the user to another screen (authentication, home) when closing the app/re-opening the app For some apps, you might want to redirect users whenever they hide your app, for example for security purposes (bank apps, password managers, etc...). If that is the case, pay specific attention to the way screenview events are sent, in order not to track a screen which is not actually shown users. ### Application life cycle When your application returns from the background to the foreground, the SDK automatically logs a screenview with the title of the last logged screenview, so you don't have to handle this transition yourself. ## How to name screens As a general rule, keep the number of distinct screen names under 100. Since these names are used to map your app in Contentsquare, choose names that are clear and comprehensive. ### Separate words with spaces, dashes, or underscores When generating screen names with multiple words, separate them using spaces, dashes, or underscores. For instance, use `Home & Living - Home Furnishings` instead of ~~`homeLivingHomeFurnishings`~~ for a sub-category in a retail app. Casing sensitivity Screen names are not case sensitive and will appear in lowercase on the Contentsquare platform. ```swift CSQ.trackScreenview("ScreenName") // screenname CSQ.trackScreenview("Screen Name") // screen name CSQ.trackScreenview("screen_name") // screen_name CSQ.trackScreenview("screenname") // screenname ``` ### Use screen template/layout names As a general recommendation, use names referring to the screen template/layout rather than referring to the specific content (data). This will help: * To keep the number of distinct screen names low and therefore make Contentsquare easier to use * Remove the risk of sending Personal Data to Contentsquare List of screen types falling into that category: *Product detail, Event detail, Conversation/Chat, User profile...* ### Screens with multiple states/layouts Screens can have different layouts or states depending on the user context. In this case, append its value to the screen name. **Home screen** | State | Screen name | | - | - | | App landing layout | `Home` | | Women products layout | `Home - Women` | | Men products layout | `Home - Men` | | Sales layout | `Home - Sales` | **Product Detail screen (PDP)** | State | Screen name | | - | - | | Users on a Top for Women PDP | `PDP - Clothing - Women - Tops` | | Users on a Microwave PDP | `PDP - Kitchenware - Electrics - Microwave` | | Users on a Hotel details screen | `PDP - Holiday type - Season - Board` | **User account screen** | State | Screen name | | - | - | | Overview | `My Account - Dashboard` | | Order history | `My Account - Order history` | | Returns | `My Account - Returns` | **Search screen** | State | Screen name | | - | - | | Search | `Search` | | Search results for "Skincare" products | `Search - Skincare` | | Search results error screen | `Search - Error` | **Cart screen** | State | Screen name | | - | - | | Empty cart | `Cart - Empty` | | Items have been added to the cart | `Cart - Populated` | | Issues with availability or pricing | `Cart - Error` | **Checkout screen** | State | Screen name | | - | - | | User provides name, surname, and date of birth | `Checkout - User Details` | | User provides shipping address | `Checkout - Shipping Details` | | User inputs their credit card information | `Checkout - Payment` | ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track Screens","description":"Learn how to implement screen tracking in your iOS app with CSQ SDK to capture user navigation patterns and screen interactions","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-screens/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Troubleshooting - iOS description: Need help? We share probable causes and recommended fixes lastUpdated: 29 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/troubleshooting/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/troubleshooting/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. When the SDK is not sending data as expected, use this page to identify probable causes and apply recommended fixes. ## Requests are failing In order for Contentsquare to work, you need to make sure the following endpoints are not blocked by your network (VPN): | Request | Endpoint | Detail | | - | - | - | | Config file | `https://mobile-production.content-square.net` | See [Configuration](../data-collection/#configuration) | | Experience Analytics data (EU) | `https://m.csqtrk.net` `https://m.ba.contentsquare.net` `https://m.aa.contentsquare.net` | See [Sending data](../data-collection/#sending-data) | | Experience Analytics data (US) | `https://m-aus1.contentsquare.net` `https://m.bf.contentsquare.net` `https://m.af.contentsquare.net` | See [Sending data](../data-collection/#sending-data) | | Product Analytics data | `https://mh.bf.contentsquare.net` | See [Product Analytics](../../product-analytics/) | | Monitoring | `https://l.contentsquare.net` | Used by the SDK to send SDK monitoring analysis in JSON format over HTTPS. | | Session Replay data (EU) | `https://ka-aeu1.contentsquare.net` `https://ka.ba.contentsquare.net` `https://ka.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Session Replay data (US) | `https://ka-aus1.contentsquare.net` `https://ka.bf.contentsquare.net` `https://ka.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Screenshot (EU) | `https://s.contentsquare.net` `https://b.ba.contentsquare.net` `https://b.aa.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Screenshot (US) | `https://s-aus1.contentsquare.net` `https://b.bf.contentsquare.net` `https://b.af.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Resources manager (EU) | `https://srm.ba.contentsquare.net` `https://srm.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Resources manager (US) | `https://srm.bf.contentsquare.net` `https://srm.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | ## Error message "Contentsquare SDK cannot run operation" If the following message appears in the logs: ```plaintext CSLIB ℹ️ Info:⚠️ Contentsquare SDK cannot execute operation because it hasn't been started. ``` It means SDK API calls were done incorrectly. In this case: **gestures and lifecycle events won't be tracked by the SDK.** Two possible explanations exist for this issue: * The SDK is manually started and API calls were made before call to `start`. * The SDK is automatically started and API calls were made before the `AppDelegate.willFinishLaunchingWithOptions`. Ensure that it doesn't happen or contact our support team if you have a specific need. ## Providing a debug build for investigation 1. Build your app for iOS device (not simulator) 2. Open the product folder for your app  3. Copy the .app from Debug-iphoneos and send it to the Contentsquare team  ## Wrong tag loaded in WebView When using Manual tag injection for dual context (WebView and Browser tracking on the same webpage), the SDK injects a script that may load after the page, causing the wrong tag to load in the WebView. Use one of the following solutions: * Add your own user script before the webview loads the page: ```swift let userScript = WKUserScript( source: "window.isWebView = true;", injectionTime: .atDocumentStart, forMainFrameOnly: false ) webView.configuration.userContentController.addUserScript(userScript) ``` Then make sure to include the added script variable in the webview check on the page itself: ```javascript function isWebView() { return navigator.userAgent.indexOf('CS_WebView') !== -1 || typeof CSJavascriptBridge != 'undefined' || !!window.CS_isWebView || window.isWebView; // Your added variable } /// ... ``` * Add a query parameter to the URL of the page you are loading in the WebView: ```swift URL(string: "https://www.apple.com/?isWebView=1") ``` Then add it to the conditions in the page script itself: ```javascript function isWebView() { return navigator.userAgent.indexOf('CS_WebView') !== -1 || typeof CSJavascriptBridge != 'undefined' || !!window.CS_isWebView || new URLSearchParams(window.location.search).get('isWebView') === '1'; } /// ... ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Troubleshooting","description":"Need help? We share probable causes and recommended fixes","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/troubleshooting/","inLanguage":"en","dateModified":"2026-07-29T20:54:18+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Contentsquare SDK to CSQ SDK - iOS description: Migrate to the CSQ SDK lastUpdated: 30 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-ios/experience-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide provides a step-by-step upgrade process from your current installation of Contentsquare Mobile SDK to the latest version of the CSQ SDK.  **Contentsquare SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. ## Dependency upgrades Replace the Contentsquare SDK by the CSQ SDK. CocoaPods support is ending CocoaPods trunk becomes read-only on December 2, 2026. After this date, Contentsquare will no longer publish new SDK versions via CocoaPods. [Migrate to Swift Package Manager (SPM)](https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/) to continue receiving updates. 1. In your Xcode project > `Package Dependencies`, update the repository location: ```diff https://github.com/ContentSquare/CS_iOS_SDK.git https://github.com/ContentSquare/apple-sdk.git ``` 2. Set the Dependency Rule to `Exact Version` `1.12.2`. 3. To ensure the library can start properly, add `-ObjC` as a linker flag under `Build Settings` > `Linking - General` > `Other Linker Flags`. ## Library imports Replace the Contentsquare SDK import with the CSQ SDK import. ```diff import ContentsquareModule import ContentsquareSDK ``` ## SDK start 1. Start the CSQ SDK manually using `CSQ.start()`. Unlike earlier versions, it no longer starts automatically. * UIKit ```swift @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { CSQ.start() return true } } ``` * SceneDelegate ```swift class SceneDelegate: UIResponder, UIWindowSceneDelegate { var window: UIWindow? func scene( _ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions ) { CSQ.start() } } ``` * SwiftUI ```swift @main struct MyApp: App { init() { CSQ.start() } var body: some Scene { WindowGroup { ContentView() } } } ``` * SwiftUI (AppDelegate) ```swift class AppDelegate: NSObject, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { CSQ.start() return true } } @main struct MyApp: App { @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate var body: some Scene { WindowGroup { ContentView() } } } ``` 2. (Optional) If you were relying on the Contentsquare SDK autostart, remove the `CSDisableAutostart` property and calls to `Contentsquare.start()`. **Info.plist** ```xml <key>CSDisableAutostart</key> <true/> ``` **AppDelegate.swift** ```swift Contentsquare.start() ``` ## Get user consent Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. * Experience Analytics ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start() CSQ.optIn() // Continue with post-consent navigation or UI update } ``` * CSQ Experience Platform (Early Access) ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. ```diff Contentsquare.start() CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID") ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### GDPR / Identification | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.optIn()` | `CSQ.optIn()` | | `Contentsquare.optOut()` | `CSQ.optOut()` | | `Contentsquare.sendUserIdentifier()` | `CSQ.sendUserIdentifier()` | | `Contentsquare.userID` | `CSQ.metadata.userID` | | `Contentsquare.projectID` | `CSQ.metadata.projectID` | | `Contentsquare.sessionNumber` | `CSQ.metadata.sessionID` | Deprecated **Contentsquare.forgetMe()** You can use `CSQ.optOut()` instead to forget user id and stop tracking. If needed call `CSQ.optIn()` when you want to resume tracking. ### Logging | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.logLevel { get set }` | `CSQ.debug.logLevel { get set }` | ### Property tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.send(dynamicVar: DynamicVar(key: String, value: UInt32))` `Contentsquare.send(dynamicVar: DynamicVar(key: String, value: String))` | `CSQ.addDynamicVar(DynamicVar)` | ### View tracking | Contentsquare SDK | CSQ SDK | | - | - | | `UIScrollView.excludeFromExposureMetric()` | `UIScrollView.excludeFromExposureMetrics()` | ### CSInApp | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.handle(url: URL)` | `CSQ.handle(url: URL)` | | `Contentsquare.csInApp` | `CSQ.csInApp` | ### Interoperability | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.onSessionReplayLinkChange(callback)` | `CSQ.metadata.onChange { metadata in }` | | `Contentsquare.register(webView: WKWebView)` | `CSQ.registerWebView(WKWebView)` | | `Contentsquare.unregister(webView: WKWebView)` | `CSQ.unregisterWebView(WKWebView)` | ### Event tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.send(transaction: CustomerTransaction)` | `CSQ.trackTransaction(Transaction)` | | `Contentsquare.send(screenViewWithName name: String)` / `Contentsquare.send(screenViewWithName name: String, cvars: [CustomVar] = [])` | `CSQ.trackScreenview(String)/CSQ.trackScreenview(String, cvars: [CustomVar])` | ### Error tracking | Contentsquare SDK | CSQ SDK | | - | - | | `ErrorAnalysis.setUrlMaskingPatterns([String])` | `CSQ.setURLMaskingPatterns([String])` | | `ErrorAnalysis.onCrashReporterStart()` | `CSQ.onCrashReporterStart()` | | `HTTPMetric` | `NetworkMetric` | | `HTTPMetric.stop()` | `CSQ.trackNetworkMetric(NetworkMetric)` | | `ErrorAnalysis.getInstance().newNetworkMetric(url, ErrorAnalysis.HttpMethod.GET)` | `CSQ.trackNetworkMetric(NetworkMetric(id, httpMethod, optionalId))` | ### Personal Data Handling and Masking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.setDefaultMasking(boolean masked)` | `CSQ.setDefaultMasking(boolean masked)` | | `Contentsquare.mask(viewsOfType: UIView.Type)` | `CSQ.mask(viewsOfType: UIView.Type)` | | `Contentsquare.mask(view: UIView)` | `CSQ.mask(UIView)`/ `UIView.csqMaskContents (UIKit)` | | `View.csMasking(Bool)` | `View.csqMaskContents(enable: Boolean) (SwiftUI)` | | `Contentsquare.unmask(UIView)` | `CSQ.unmask(UIView)` | | `Contentsquare.unmask(viewsOfType: UIView.Type)` | `CSQ.unmask(viewsOfType: UIView.Type)` | | `Contentsquare.maskTexts(mask: Boolean)` | `CSQ.maskTexts(mask: Boolean)` | | `Contentsquare.maskImages(mask: Boolean)` | `CSQ.maskImages(mask: Boolean)` | | `Contentsquare.maskTextInputs(mask: Boolean)` | `CSQ.maskTextInputs(mask: Boolean)` | ### SDK initialization and manipulation | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.start()` | `CSQ.start()` | | `Contentsquare.stopTracking()` | `CSQ.pauseTracking()` | | `Contentsquare.resumeTracking()` | `CSQ.resumeTracking()` | ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that your build files no longer reference `https://github.com/ContentSquare/CS_iOS_SDK.git`. Your `import ContentsquareModule` declarations have been updated to `import ContentsquareSDK`. You no longer have references to `Contentsquare.` methods in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Contentsquare SDK to CSQ SDK","description":"Migrate to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/","inLanguage":"en","dateModified":"2026-06-30T16:49:52+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Core SDK + Contentsquare SDK to CSQ SDK - iOS description: Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK lastUpdated: 30 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-heap-and-cs-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-heap-and-cs-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-ios/experience-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide provides a step-by-step upgrade process from your current installation of Contentsquare and Heap Mobile to the latest version of the CSQ SDK.  **Heap Core SDK** \+  **Contentsquare SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. ## Dependency upgrades If you are loading both Heap and Contentsquare SDK, replace these dependencies by the CSQ SDK. CocoaPods support is ending CocoaPods trunk becomes read-only on December 2, 2026. After this date, Contentsquare will no longer publish new SDK versions via CocoaPods. [Migrate to Swift Package Manager (SPM)](https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/) to continue receiving updates. 1. In your Xcode project > `Package Dependencies`, update your packages: ```diff https://github.com/heap/heap-swift-core-sdk.git https://github.com/ContentSquare/CS_iOS_SDK.git https://github.com/heap/heap-ios-cs-integration-sdk.git https://github.com/heap/heap-ios-autocapture-sdk.git https://github.com/heap/heap-notification-autocapture-sdk.git https://github.com/ContentSquare/apple-sdk.git ``` 2. Set the Dependency Rule to `Exact Version` `1.12.2`. 3. To ensure the library can start properly, add `-ObjC` as a linker flag under `Build Settings` > `Linking - General` > `Other Linker Flags`. Migrating from CSQ SDK 0.x? Update the version for the `apple-sdk` package. Skip the Heap dependency lines. All other steps in this guide still apply. In your Xcode project > `Package Dependencies`, update the `apple-sdk` version: * Remove the existing `https://github.com/ContentSquare/apple-sdk.git` package. * Re-add `https://github.com/ContentSquare/apple-sdk.git` and set the Dependency Rule to `Exact Version` `1.12.2`. Previously no version was pinned. An exact version is now required. ## Library imports Replace the Heap and Contentsquare imports with the CSQ SDK import. ```diff import HeapSwiftCore import HeapContentsquareIntegrationSDK import HeapIOSAutocapture import HeapNotificationAutocapture import ContentsquareModule import ContentsquareSDK ``` ## SDK start Follow these steps to start the CSQ SDK with your current configuration. 1. Delete `Heap.shared.startRecording()` and migrate configuration to the unified `CSQ.start()` method. * Product Analytics ```swift Heap.shared.startRecording("YOUR_ENVIRONMENT_ID", with: [ // ...options ]) CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ...options ] ) ``` * CSQ Experience Platform (Early Access) ```swift Heap.shared.startRecording("YOUR_ENVIRONMENT_ID", with: [ // ...options ]) CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ // ...options ] ) ``` Deprecated configuration options The following Heap SDK configuration options are not ported to the CSQ SDK: * `startSessionImmediately` * `disableInteractionTextCapture` * `disableInteractionAccessibilityLabelCapture` * `enableInteractionReferencingPropertyCapture` * `interactionHierarchyCaptureLimit` * `captureVendorID` * `captureAdvertiserID` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `messageBatchByteLimit` * `resumePreviousSession` See [supported options](../command-reference/#sdk-configuration-options) for more information. 2. Recommended for UIKit Enable Autocapture with `.enableNativeAutocapture: true` and remove the call to `Heap.iOSAutocaptureSource.register()` * Product Analytics ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ...options .enableNativeAutocapture: true ] ) Heap.iOSAutocaptureSource.register(isDefault: true) ``` * CSQ Experience Platform (Early Access) ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ // ...options .enableNativeAutocapture: true ] ) Heap.iOSAutocaptureSource.register(isDefault: true) ``` 3. Remove `HeapContentsquareIntegration.bind()`. Sending Heap pageviews to Contentsquare **AppDelegate.swift** ```swift HeapContentsquareIntegration.bind( sendHeapPageviewsToContentsquare: false, sendContentsquareScreenviewsToHeap: true ) ``` Note Make sure you don't have calls to `CSQ.trackScreenview()` if you have autocapture enabled. Sending Contentsquare screenviews to Heap * Product Analytics **AppDelegate.swift** ```swift HeapContentsquareIntegration.bind( sendHeapPageviewsToContentsquare: true, sendContentsquareScreenviewsToHeap: false ) CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ...options .disablePageviewAutocapture: true ] ) ``` * CSQ Experience Platform (Early Access) **AppDelegate.swift** ```swift HeapContentsquareIntegration.bind( sendHeapPageviewsToContentsquare: true, sendContentsquareScreenviewsToHeap: false ) CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ // ...options .disablePageviewAutocapture: true ] ) ``` 4. (Optional) If you were relying on the Contentsquare SDK autostart, remove the `CSDisableAutostart` property and calls to `Contentsquare.start()`. **Info.plist** ```xml <key>CSDisableAutostart</key> <true/> ``` **AppDelegate.swift** ```swift Contentsquare.start() ``` ## Get user consent Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. * Experience Analytics ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start() CSQ.optIn() // Continue with post-consent navigation or UI update } ``` * CSQ Experience Platform (Early Access) ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. ```diff Contentsquare.start() Heap.shared.startRecording("YOUR_ENVIRONMENT_ID") CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID") ``` The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. For more information on SDK methods, see the [SDK API reference](../command-reference/). ### Product Analytics (Heap Core SDK) ### GDPR / Identification | Heap Core SDK | CSQ SDK | | - | - | | `Heap.shared.identify(string)` | `CSQ.identify(String)` | | `Heap.shared.resetIdentity()` | `CSQ.resetIdentity()` | | `Heap.shared.userId` | `CSQ.metadata.userID` | | `Heap.shared.sessionId` | `CSQ.metadata.sessionID` | | `Heap.shared.getEnvironmentId` | `CSQ.metadata.environmentID` | | `Heap.shared.identity` | `CSQ.metadata.identity` | ### Logging | Heap Core SDK | CSQ SDK | | - | - | | `Heap.shared.logLevel { get set }` | `CSQ.debug.logLevel { get set }` | | `Heap.shared.logChannel { get set }` | `CSQ.debug.logChannel(LogChannel)` | | `Heap.shared.printLog()` | `LogChannel.printLog()` | ### Property tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.shared.addUserProperties(properties: [String: HeapPropertyValue])` | `CSQ.addUserProperties([Property])` | | `Heap.shared.addEventProperties(properties: [String: HeapPropertyValue])` | `CSQ.addEventProperties([Property])` | | `Heap.shared.removeEventProperty(name: String)` | `CSQ.removeEventProperty(name: String)` | | `Heap.shared.clearEventProperties()` | `CSQ.clearEventProperties()` | ### Event tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.shared.track()` | `CSQ.trackEvent(name: String, properties: [String, PropertyValue]?)` | ### Personal Data Handling and Masking | Heap Core SDK | CSQ SDK | | - | - | | `View.heapIgnoreInteractions` | `CSQ.ignoreInteractions(View)` / `CSQ.ignoreInteractions(UIView)` / `UIView.csqIgnoreInteractions (UIKit)` / `View.csqIgnoreInteractions(shouldIgnore:Boolean)(SwiftUI)` | | `View.heapRedactText` / `View.heapRedactAccessibilityLabel` | `CSQ.mask(UIView)` / `UIView.csqMaskContents (UIKit)`/ `View.csqMaskContents(enable: boolean) (SwiftUI)` | | `view.setTag(R.id.heapRedactText, false)` | `CSQ.unmask(UIView)` / `UIView.csqMaskContents (UIKit)` / `View.csqMaskContents(enable: Boolean) (SwiftUI)` | | Initialization options `disableInteractionTextCapture` and `disableInteractionAccessibilityLabelCapture` | `CSQ.maskTexts(mask: Boolean)` | | `UIView.heapIgnoreInteractionsDefault` | `csqIgnoreInteractionsDefault` | | `UIView.heapIgnoreInnerHierarchy` | `csqIgnoreInnerHierarchy` | | `UIView.heapIgnoreInnerHierarchyDefault` | `csqIgnoreInnerHierarchyDefault` | ### SDK initialization and manipulation | Heap Core SDK | CSQ SDK | | - | - | | Heap SDK initialization options | `CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID", options: AnalyticsOptions(...))` See [supported options](../command-reference/#sdk-configuration-options) for more information. | | `Heap.shared.startRecording(context, id)` | `CSQ.start()` | | `Heap.shared.stopRecording(deleteUser = true)` | `CSQ.stop()` | | `Heap.shared.stopRecording(deleteUser = false)` | `CSQ.pauseTracking()` | ### Experience Analytics (Contentsquare SDK) ### GDPR / Identification | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.optIn()` | `CSQ.optIn()` | | `Contentsquare.optOut()` | `CSQ.optOut()` | | `Contentsquare.sendUserIdentifier()` | `CSQ.sendUserIdentifier()` | | `Contentsquare.userID` | `CSQ.metadata.userID` | | `Contentsquare.projectID` | `CSQ.metadata.projectID` | | `Contentsquare.sessionNumber` | `CSQ.metadata.sessionID` | Deprecated **Contentsquare.forgetMe()** You can use `CSQ.optOut()` instead to forget user id and stop tracking. If needed call `CSQ.optIn()` when you want to resume tracking. ### Logging | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.logLevel { get set }` | `CSQ.debug.logLevel { get set }` | ### Property tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.send(dynamicVar: DynamicVar(key: String, value: UInt32))` `Contentsquare.send(dynamicVar: DynamicVar(key: String, value: String))` | `CSQ.addDynamicVar(DynamicVar)` | ### View tracking | Contentsquare SDK | CSQ SDK | | - | - | | `UIScrollView.excludeFromExposureMetric()` | `UIScrollView.excludeFromExposureMetrics()` | ### CSInApp | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.handle(url: URL)` | `CSQ.handle(url: URL)` | | `Contentsquare.csInApp` | `CSQ.csInApp` | ### Interoperability | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.onSessionReplayLinkChange(callback)` | `CSQ.metadata.onChange { metadata in }` | | `Contentsquare.register(webView: WKWebView)` | `CSQ.registerWebView(WKWebView)` | | `Contentsquare.unregister(webView: WKWebView)` | `CSQ.unregisterWebView(WKWebView)` | ### Event tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.send(transaction: CustomerTransaction)` | `CSQ.trackTransaction(Transaction)` | | `Contentsquare.send(screenViewWithName name: String)` / `Contentsquare.send(screenViewWithName name: String, cvars: [CustomVar] = [])` | `CSQ.trackScreenview(String)/CSQ.trackScreenview(String, cvars: [CustomVar])` | ### Error tracking | Contentsquare SDK | CSQ SDK | | - | - | | `ErrorAnalysis.setUrlMaskingPatterns([String])` | `CSQ.setURLMaskingPatterns([String])` | | `ErrorAnalysis.onCrashReporterStart()` | `CSQ.onCrashReporterStart()` | | `HTTPMetric` | `NetworkMetric` | | `HTTPMetric.stop()` | `CSQ.trackNetworkMetric(NetworkMetric)` | | `ErrorAnalysis.getInstance().newNetworkMetric(url, ErrorAnalysis.HttpMethod.GET)` | `CSQ.trackNetworkMetric(NetworkMetric(id, httpMethod, optionalId))` | ### Personal Data Handling and Masking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.setDefaultMasking(boolean masked)` | `CSQ.setDefaultMasking(boolean masked)` | | `Contentsquare.mask(viewsOfType: UIView.Type)` | `CSQ.mask(viewsOfType: UIView.Type)` | | `Contentsquare.mask(view: UIView)` | `CSQ.mask(UIView)`/ `UIView.csqMaskContents (UIKit)` | | `View.csMasking(Bool)` | `View.csqMaskContents(enable: Boolean) (SwiftUI)` | | `Contentsquare.unmask(UIView)` | `CSQ.unmask(UIView)` | | `Contentsquare.unmask(viewsOfType: UIView.Type)` | `CSQ.unmask(viewsOfType: UIView.Type)` | | `Contentsquare.maskTexts(mask: Boolean)` | `CSQ.maskTexts(mask: Boolean)` | | `Contentsquare.maskImages(mask: Boolean)` | `CSQ.maskImages(mask: Boolean)` | | `Contentsquare.maskTextInputs(mask: Boolean)` | `CSQ.maskTextInputs(mask: Boolean)` | ### SDK initialization and manipulation | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.start()` | `CSQ.start()` | | `Contentsquare.stopTracking()` | `CSQ.pauseTracking()` | | `Contentsquare.resumeTracking()` | `CSQ.resumeTracking()` | ## Number of sessions Session timeout definition changed: * **Before**: 30 minutes after app goes to background * **Now**: 30 minutes after last event This may affect session counts and aligns with web and market standards. ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that your build files no longer reference `https://github.com/heap/heap-swift-core-sdk.git`, `https://github.com/ContentSquare/CS_iOS_SDK.git`. Your `import Heap` and `import Contentsquare` declarations have been updated to `import ContentsquareSDK`. You no longer have references to `Heap.` (except if you are using webviews), `HeapContentsquareIntegration.`, or `Contentsquare.` methods in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK + Contentsquare SDK to CSQ SDK","description":"Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-heap-and-cs-sdk/","inLanguage":"en","dateModified":"2026-06-30T16:49:52+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Upgrade your SDK - iOS description: Understand the benefits of upgrading to the CSQ SDK lastUpdated: 12 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-your-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-your-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-ios/experience-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This section guides you through the upgrade from your current SDK implementation to our latest CSQ SDK. Upgrading has no impact on your current data collection and does not alter the data observed on the platform. It mainly consists of searching and replacing APIs according to the mappings provided in the upgrade guides. Get started by selecting the upgrade guide that corresponds to your current implementation: * **[Contentsquare SDK](../upgrade-from-cs-sdk/)** - Upgrade from the legacy Contentsquare SDK * **[Heap SDK + Contentsquare SDK](../upgrade-from-heap-and-cs-sdk/)** - Upgrade from combined Heap and Contentsquare SDKs ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Upgrade your SDK","description":"Understand the benefits of upgrading to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-your-sdk/","inLanguage":"en","dateModified":"2026-05-12T12:05:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Agent skills for iOS - iOS description: Use AI coding assistants to integrate, upgrade, and configure the Contentsquare iOS SDK with downloadable Agent skills lastUpdated: 16 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/using-agent-skills/ md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/using-agent-skills/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use the Contentsquare wizard or skills to set up, update, and configure iOS with your AI coding assistant. Disclaimer This skill guides your AI coding agent through the SDK installation and implementation. The agent you use (Cursor, Claude Code, Copilot) is your own tool and operates under your settings and permissions. Contentsquare is not responsible for how your agent interprets or applies the instructions contained in these files. ## Contentsquare wizard Run the wizard in your project directory. It configures your AI coding assistant, installs the matching Contentsquare integration, and verifies the installation. ```shell npx @contentsquare/wizard install ``` Supports GitHub Copilot, Cursor, and Claude Code. Requires Node.js ≥ 18 and an AI coding agent with MCP support. ## Manual setup Use this path when you prefer to configure your AI coding assistant yourself. ### 1. Add the Contentsquare skill Choose how to install the Contentsquare skill. * Copilot CLI Add the Contentsquare marketplace, then install the plugin for iOS: ```shell copilot plugin marketplace add ContentSquare/agents copilot plugin install contentsquare-ios@contentsquare ``` * Claude Code Add the Contentsquare marketplace, then install the plugin for iOS: ```shell /plugin marketplace add ContentSquare/agents /plugin install contentsquare-ios@contentsquare ``` * Cursor Install **contentsquare** from the [Cursor marketplace ↗](https://cursor.com/marketplace), or add the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents) directly. Cursor reads the `.cursor-plugin` catalog in the repository. * Other agents Install the Contentsquare skill pack with the open `skills.sh` ecosystem: ```shell npx skills add contentsquare/agents ``` * From source Download or clone the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents), then copy `skills/contentsquare-ios-sdk` into the location your AI coding assistant scans for skills: | AI coding assistant | Skill location | | - | - | | GitHub Copilot | `.github/skills/` or `.agents/skills/` | | Cursor | `.cursor/rules/` or the project root | | Claude Code | `.claude/skills/` or the project root | | Other compatible agents | `.agents/skills/` | ### 2. Ask your AI coding assistant After installing the skill, paste this prompt into your AI coding assistant: ```text Install Contentsquare for iOS. ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Agent skills for iOS","description":"Use AI coding assistants to integrate, upgrade, and configure the Contentsquare iOS SDK with downloadable Agent skills","url":"https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/using-agent-skills/","inLanguage":"en","dateModified":"2026-07-16T17:50:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - iOS description: The Contentsquare iOS changelog lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/changelog/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. 📬 Stay updated! ## Opt-in to CSQ Experience Platform Already using the CSQ SDK in standalone mode? Follow these steps to switch to CSQ Experience Platform and combine Experience Analytics and Product Analytics under a single data source. CSQ Experience Platform is currently an Early Access program. To gain access, contact your Customer Success Manager. CSQ Experience Platform guidance Throughout the documentation, code samples highlight differences between standalone and CSQ Experience Platform integrations.  1. [Update the SDK package to 1.10.0 or later](../#install-the-sdk). 2. Replace your current `CSQ.start()` or `CSQ.start(environmentID:)` call with the `dataSourceID` provided by your Customer Success Manager. This links your app to the CSQ Experience Platform data source. **AppDelegate.swift** ```swift CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 3. Review changes [introduced in 1.10.0](#1100---20260504) which notably removes support for several Product Analytics options. ## 1.12.2 - 2026.08.06 Experience Analytics * Update Experience Analytics SDK version to `4.52.1`: * **Analytics** * Improved reliability of exposure rate and scroll rate. * **Session Replay** * **Bug fix:** fixed SwiftUI image foreground color issues. * **Bug fix:** fixed an issue where the keyboard was sometimes not displayed. * **Bug fix:** fixed a rare crash related to SwiftUI. ## 1.12.0 - 2026.07.31 Experience Analytics * Update Experience Analytics SDK version to `4.52.0`: * Bug fixes and performance improvements. Product Analytics * Update Product Analytics Core SDK version to `0.9.2` * Update Product Analytics Autocapture SDK version to `0.10.2` ## 1.11.2 - 2026.07.27 Experience Analytics Deprecated version This version is deprecated. Upgrade to the [latest version](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/). * Update Experience Analytics SDK version to `4.51.2`: * **Webviews** * **Bug fix:** fixed a synchronisation issue that could result in a "Webview Not Tracked" in the Session Replay Player * **Bug fix:** fixed an issue where coming back from background into a webview would result in a "Webview Not Tracked" in the Session Replay Player ## 1.11.1 - 2026.07.20 Experience Analytics Deprecated version This version is deprecated. Upgrade to the [latest version](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/). * Update Experience Analytics SDK version to `4.51.1`: * Re-signed the release artefacts with a new valid certificate to resolve a code-signing validation failure (`CSSMERR_TP_CERT_REVOKED`). No functional changes. ## 1.11.0 - 2026.06.05 Experience Analytics * Update Experience Analytics SDK version to `4.51.0`: * **Session Replay** * Improve stability when calling APIs from background threads. * Fix harmonized masking behavior for fully SwiftUI-based apps. * Use the unified SDK version for full masking rules. * **Analytics** * A more explicit message is displayed when the screenshot size exceeds server-side limit Product Analytics * Update Product Analytics Core SDK version to `0.9.1` ## 1.10.0 - 2026.05.04 Experience Analytics * Update Experience Analytics SDK version to `4.50.0`: * The Session timeout definition changes from "30 minutes after being in background" to **30 minutes after last event**. See [Session definition](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/data-collection/#session-definition). Product Analytics * Update Product Analytics Autocapture SDK version to `0.11.0` * Update Product Analytics Core SDK version to `0.9.0` * Update Product Analytics Notification SDK version to `0.9.0` ### Configuration **API update:** `CSQ.configureProductAnalytics()` is now deprecated in favor of use `CSQ.start()` which combines SDK configuration and initialization in a single call: **AppDelegate.swift** ```swift CSQ.configureProductAnalytics( environmentID: "YOUR_ENVIRONMENT_ID", additionalOptions: [ // ... ] ) CSQ.start() CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ... ] ) ``` ### Options **Added:** `.sessionReplayAutoStart` — set to `false` to disable automatic Session Replay start and control it manually. Defaults to `true`. ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .sessionReplayAutoStart: false ] ) ``` **Renamed:** `.enableUIKitAutocapture` is now `.enableNativeAutocapture`: ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .enableUIKitAutocapture: true, .enableNativeAutocapture: true, ] ) ``` **Removed:** `.captureVendorID`, `.captureAdvertiserID`, `.clearEventPropertiesOnNewUser`, `.messageBatchByteLimit`, `.messageBatchMessageLimit`, `.resumePreviousSession`, `.pruningLookBackWindow`, `.disableScreenviewForwardToDXA`, `.disableScreenviewForwardToPA`, `.interactionHierarchyCaptureLimit`, `.disableInteractionTextCapture`, and `.disableInteractionAccessibilityLabelCapture` are no longer available. Remove them from your `CSQ.start()` call if present: ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .captureVendorID: true, .captureAdvertiserID: true, .clearEventPropertiesOnNewUser: true, .messageBatchByteLimit: 200_000, .messageBatchMessageLimit: 100, .resumePreviousSession: true, .pruningLookBackWindow: 6, .disableScreenviewForwardToDXA: true, .disableScreenviewForwardToPA: true, .interactionHierarchyCaptureLimit: 5, .disableInteractionTextCapture: true, .disableInteractionAccessibilityLabelCapture: true, ] ) ``` ## 1.6.4 - 2026.07.20 Experience Analytics * Update Experience Analytics SDK version to `4.46.4`: * Re-signed the release artefacts with a new valid certificate to resolve a code-signing validation failure (`CSSMERR_TP_CERT_REVOKED`). No functional changes. ## 1.6.3 - 2026.04.10 Experience Analytics * Update Experience Analytics SDK version to `4.46.3`: **Session Replay** * Improved performance of view hierarchy processing, reducing CPU usage. * Fixed a threading issue that could cause occasional crashes. * Fixed an issue where some images could be missing in replays. **Analytics** * Improved runtime stability **Errors** * Enhanced tracking of initial crashes after application installation. ## 1.6.2 - 2026.03.23 Experience Analytics * Update Experience Analytics SDK version to `4.46.2`: **Session Replay** * Fixed a crash related to SVG images when harmonized masking is enabled **Analytics** * Fixed an issue where a screenshot capture would cause the app to become unresponsive ## 1.6.1 - 2026.03.05 Experience Analytics * Update Experience Analytics SDK version to `4.46.1`: **Analytics** * Zoning / Heatmap: Add support for SwiftUI `drawingGroup` **Session Replay** * Fix a protobuf serialization crash * Fix a crash related to `NSAttributedString` encoding ## 1.6.0 - 2026.02.19 Experience Analytics * Update Experience Analytics SDK version to `4.46.0`: **Session Replay** * Improved session synchronization between Session Replay and Product Analytics * Enhance playback reliability when using `stopTracking()` followed by `resumeTracking()` * Strengthen playback stability when `optOut()` is triggered * Fix nil replay link when callback is subscribed before `start()` * Enhance stability when using `csMasking` SwiftUI modifier * Improve robustness against race conditions involving weak SwiftUI component references * Optimize handling of collections with unusually long durations **Errors** * Improve API error handling by ensuring URLs remain visible when invalid masking patterns are provided via `ErrorAnalysis.setURLMaskingPatterns()` **Analytics** * Improved Zoning metrics accuracy for some custom SwiftUI components * Fixed an issue where a screenshot captures would fail for React Native applications Product Analytics * Update Product Analytics Notification SDK version to `0.8.3` ## 1.5.5 - 2025.12.29 Experience Analytics * Update Experience Analytics SDK version to `4.45.6`: **Session Replay** * Fix a crash due to infinite recursion when a sublayer references the parent view as delegate (issue observed in CorePlot) ## 1.5.4 - 2025.12.22 Experience Analytics * Update Experience Analytics SDK version to `4.45.5`: ## 1.5.3 - 2025.12.12 Experience Analytics * Update Experience Analytics SDK version to `4.45.4`: ## 1.5.2 - 2025.12.08 Experience Analytics * Update Experience Analytics SDK version to `4.45.3` Product Analytics * Update Product Analytics Autocapture SDK version to `0.10.1` * Update Product Analytics Core SDK version to `0.8.8`: * Update Product Analytics Notification SDK version to `0.8.1`: ## 1.5.1 - 2025.11.27 Experience Analytics * Update Experience Analytics SDK version to `4.45.1`: ## 1.5.0 - 2025.11.14 Experience Analytics * Update Experience Analytics SDK version to `4.45.0`: **Analytics** * Fixed a crash related to Zoning and Heatmap data collection on iOS 26 devices **Session Replay** * Fixed a crash related to gesture capture on iOS 26 devices * Fixed an issue where the background color of an Image wouldn’t be correctly rendered * Fixed a protobuf serialization crash on iOS 26 devices * Performance improvement on iOS 26 devices ## 1.4.2 - 2025.10.29 Experience Analytics * Update Experience Analytics SDK version to `4.44.3`: **Session Replay** * Fixed a rare crash related to gesture. ## 1.4.1 - 2025.10.28 Experience Analytics * Update Experience Analytics SDK version to `4.44.2`: **Session Replay** * Fixed a crash related to `AVPlayerViewController`. Product Analytics * Update Product Analytics Autocapture SDK version to `0.9.1`: * Fixed a crash when calling `AttributedString(localized:)` with an interpolated string. * Taps inside `WKWebView` are now ignored by default because they don't contain meaningful data and produce noise when integrating with tag capture. To restore capture on a specific view, use `webView.heapIgnoreInteractions = false`. ## 1.4.0 - 2025.10.22 **Webviews** The One WebView Tag feature is now available in controlled general availability. It brings key Product Analytics features — Identity, User Properties, Hierarchy, and Target Text — to WebViews, enabling unified Product Analytics and Experience Analytics. To gain access, contact your Customer Success Manager to be added to the eligibility list. ## 1.3.1 - 2025.10.17 Experience Analytics * Update Experience Analytics SDK version to `4.44.1`: **Core SDK** * Fix an issue with the SDK internal Codable conformance extension for NSTextAlignment. **Analytics** * Heatmaps: Fix an issue where some taps would be inaccurate on iOS 26 devices ## 1.3.0 - 2025.10.14 Experience Analytics * Update Experience Analytics SDK version to `4.44.0`: **Analytics** * Improved iOS 26 support for Zoning and Heatmap analysis * ⚠️ Starting with iOS 26: Reliable targets are compatible with UIKit `accessibilityIdentifier` only. Read more at [Reliable targets](https://docs.contentsquare.com/en/ios/collected-data-points/#reliable-targets) * Improved data collection on segmented controls **Session Replay** * Improved iOS 26 support to display correctly text and images on SwiftUI views for apps built with Xcode 26 * Fix a crash related to bitmap rendering Product Analytics * Update Product Analytics Core SDK version to `0.8.7`: * SDK is now built with Xcode 16.0. * Internal improvements for autocapture. ## 1.2.1 - 2025.09.24 Experience Analytics * Update Experience Analytics SDK version to `4.43.3`: **Session Replay** * Fixed a bug where gradient backgrounds were not properly collected for React Native **Analytics** * Heatmaps: Fixed a crash related to frame computations ## 1.2.0 - 2025.09.12 Product Analytics * Update Product Analytics Autocapture SDK version to `0.9.0`: * **SwiftUI Autocapture** * Our Autocapture SDK now includes support for SwiftUI Experience Analytics * Update Experience Analytics SDK version to `4.43.2`: * **Core SDK** * Improved internal feature flag stability * **Session Replay** * Fixed an issue where SwiftUI images were missing from the replay on iOS 26 devices. ## 1.1.0 - 2025.08.06 Experience Analytics * Update Experience Analytics SDK version to `4.43.0`: * **Session Replay** * Image/Text masking configuration in the CSQ Console * Support Event Triggered Replay ## 1.0.1 - 2025.07.22 Experience Analytics * Update Experience Analytics SDK version to `4.42.4`: * **Session Replay** * Fix an issue related to CSInApp on iPad * Support for React Native New Architecture Text * Improved Session Replay screen change consistency on Capacitor apps * **WebView** * Fix an issue related to config ## 1.0.0 - 2025.06.26 Initial release of the CSQ SDK. * Introduces the unified CSQ API, which combines Product Analytics, Experience Analytics, and Monitoring features into a single, cohesive library. * This initial release includes: * Experience Analytics SDK version `4.42.1`. * Product Analytics Core SDK version `0.8.6`. * Product Analytics Autocapture SDK version `0.8.0`. * Product Analytics Notification Autocapture SDK version `0.8.0`. Upgrade to CSQ SDK 1.+ Looking to upgrade from CSQ SDK 0.x to the latest? See the [upgrade guide](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-heap-and-cs-sdk/). ## 0.11.4 - 2026.07.20 * Update Experience Analytics SDK to [`4.46.4`](https://docs.contentsquare.com/en/ios/changelog/#4464---20260720). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.3` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.11.3 - 2026.04.10 * Update Experience Analytics SDK to [`4.46.3`](https://docs.contentsquare.com/en/ios/changelog/#4463---20260410). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.3` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.11.2 - 2026.03.23 * Update Experience Analytics SDK to [`4.46.2`](https://docs.contentsquare.com/en/ios/changelog/#4462---20260320). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.3` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.11.1 - 2026.03.05 * Update Experience Analytics SDK to [`4.46.1`](https://docs.contentsquare.com/en/ios/changelog/#4461---20260305). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.3` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.11.0 - 2026.02.16 * Update Experience Analytics SDK to [`4.46.0`](https://docs.contentsquare.com/en/ios/changelog/#4460---20260213). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.10.4 - 2025.12.29 * Update Experience Analytics SDK to [`4.45.6`](https://docs.contentsquare.com/en/ios/changelog/#4456---20251230). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.10.3 - 2025.12.22 * Update Experience Analytics SDK to [`4.45.5`](https://docs.contentsquare.com/en/ios/changelog/#4455---20251219). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.10.2 - 2025.12.12 * Update Experience Analytics SDK to [`4.45.4`](https://docs.contentsquare.com/en/ios/changelog/#4454---20251212). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.10.1 - 2025.12.10 * Update Experience Analytics SDK to [`4.45.3`](https://docs.contentsquare.com/en/ios/changelog/#4453---20251205). * Update Product Analytics [Core `0.8.8` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.10.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.10.0 - 2025.11.14 * Update Experience Analytics SDK to [`4.45.0`](https://docs.contentsquare.com/en/ios/changelog/#4450---20251114). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.9.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.9.2 - 2025.10.28 * Update Experience Analytics SDK to [`4.44.2`](https://docs.contentsquare.com/en/ios/changelog/#4442---20251024). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.9.1` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.9.1 - 2025.10.17 * Update Experience Analytics SDK to [`4.44.1`](https://docs.contentsquare.com/en/ios/changelog/#4441---20251017). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.9.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.9.0 - 2025.10.07 * Update Experience Analytics SDK to [`4.44.0`](https://docs.contentsquare.com/en/ios/changelog/#4440---20251006). * Update Product Analytics [Core `0.8.7` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.9.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.8.1 - 2025.09.25 * Update Experience Analytics SDK to [`4.43.3`](https://docs.contentsquare.com/en/ios/changelog/#4433---20250924). * Update Product Analytics [Core `0.8.6` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.9.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.8.0 - 2025.09.11 * Update Experience Analytics SDK to [`4.43.2`](https://docs.contentsquare.com/en/ios/changelog/#4432---20250819). * Update Product Analytics [Core `0.8.6` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.9.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) (includes SwiftUI Autocapture) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.7.0 - 2025.08.01 * Update Experience Analytics SDK to [`4.43.0`](https://docs.contentsquare.com/en/ios/changelog/#4430---20250731). * Update Product Analytics [Core `0.8.6` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.6.3 - 2025.06.20 * Update Experience Analytics SDK to [`4.42.1`](https://docs.contentsquare.com/en/ios/changelog/#4421---20250617). * Update Product Analytics [Core `0.8.5` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.6.2 - 2025.05.22 * Update Product Analytics [Core `0.8.5` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.6.1 - 2025.05.19 * Update Experience Analytics SDK to [`4.41.3`](https://docs.contentsquare.com/en/ios/changelog/#4413---20250516). * Update Product Analytics [Core `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.6.0 - 2025.04.02 * Update Experience Analytics SDK to [`4.41.0`](https://docs.contentsquare.com/en/ios/changelog/#4410---20250402). * Update Product Analytics [Core `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.5.2 - 2025.03.12 * Update Experience Analytics SDK to [`4.40.2`](https://docs.contentsquare.com/en/ios/changelog/#4402---20250220). * Update Product Analytics [Core `0.8.1` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.5.1 - 2025.02.21 * Update Experience Analytics SDK to [`4.40.1`](https://docs.contentsquare.com/en/ios/changelog/#4401---20250218). * Update Product Analytics [Core `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.5.0 - 2025.02.14 * Update Experience Analytics SDK to [`4.40.0`](https://docs.contentsquare.com/en/ios/changelog/#4400---20250212). * Update Product Analytics [Core `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.8.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.4.0 - 2025.01.15 * Update Experience Analytics SDK to [`4.39.0`](https://docs.contentsquare.com/en/ios/changelog/#4390---20250109). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.3.1 - 2024.12.06 * Update Experience Analytics SDK to [`4.38.2`](https://docs.contentsquare.com/en/ios/changelog/#4382---20241128). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.3.0 - 2024.10.25 * Update Experience Analytics SDK to [`4.38.0`](https://docs.contentsquare.com/en/ios/changelog/#4380---20241025). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.2.3 - 2024.10.25 * Update Experience Analytics SDK to [`4.37.3`](https://docs.contentsquare.com/en/ios/changelog/#4373---20241022). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.2.2 - 2024.10.18 * Update Experience Analytics SDK to [`4.37.2`](https://docs.contentsquare.com/en/ios/changelog/#4372---20241015). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.2.1 - 2024.10.14 * Update Experience Analytics SDK to [`4.37.1`](https://docs.contentsquare.com/en/ios/changelog/#4371---20241001). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.2.0 - 2024.10.11 * Update Experience Analytics SDK to [`4.37.0`](https://docs.contentsquare.com/en/ios/changelog/#4370---20240927). * Update Product Analytics [Core `0.7.2` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.1.1 - 2024.09.27 * Update Experience Analytics SDK to [`4.36.1`](https://docs.contentsquare.com/en/ios/changelog/#4361---20240920). * Update Product Analytics [Core `0.7.1` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ## 0.1.0 - 2024.09.06 This release marks the introduction of the CSQ SDK which brings together Product Analytics, Experience Analytics, and Monitoring features. From this version onwards, the SDK releases follow a new versioning scheme. * Update Experience Analytics SDK to [`4.36.0`](https://docs.contentsquare.com/en/ios/changelog/#4360---20240906). * Update Product Analytics [Core `0.7.1` ↗](https://developers.heap.io/docs/ios-changelog#swift-core-changelog) - [Autocapture `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog) - [Autocapture Notification `0.7.0` ↗](https://developers.heap.io/docs/ios-changelog#ios-autocapture-changelog). ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare iOS changelog","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/changelog/","inLanguage":"en","dateModified":"2026-07-08T17:11:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - iOS description: Requirements and limitations to develop with the Contentsquare iOS SDK lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/compatibility/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The Contentsquare iOS SDK has specific language, platform, and version requirements for integration. * **Programming languages:** The iOS SDK supports and tracks content on any screen developed in **Objective-C or Swift (version >= 4.2)**. * **SwiftUI:** is officially supported * **iOS version:** starting with SDK 4.50.0 we support **iOS 13.0 and later** * Starting with SDK 4.36.0, **no data will be collected for applications running on iOS < 13.0**, although technically the SDK supports iOS 12.4. * ReactNative requires a minimum of iOS 13.0 * All devices released since 2015 can be updated to iOS 13.0 * `SFSafariViewController` is **not** supported ## Known limitations and recommendations ### Screenshot fidelity: Combining Visual Effects with Filters **Symptom:** Some elements of the screenshots may not be visible, such as `UITabBar` buttons. **Explanation:** Our capturing method prevents to capture views when Visual effects are combined with filters. Our tools captures as much as Xcode's 'Debug View Hierarchy' feature. If you want to preview what is going to be rendered, you can use this feature to visualize your screen. See [Capturing a Snapshot of a UIVisualEffectView ↗](https://developer.apple.com/documentation/uikit/uivisualeffectview#Capture-a-snapshot-of-a-visual-effect-view). ### Screenshot fidelity: Customized layers applied on a container view **Symptom:** Some elements of the screenshots may not be displayed correctly in the **Zoning Analysis**. **Explanation:** Our capture method relies on views to determine zoning elements. A view containing subviews is a container and when a container is assigned a customized [layer ↗](https://developer.apple.com/documentation/uikit/uiview/1622436-layer), it may not appear in the **Zoning Analysis**. **Workaround:** Instead of applying customized layer to the container, prefer applying it on view of type, or subtype, `UIImageView` or `UIControl`. ### Screenshot fidelity: Floating header/footer missing in Zoning **Symptom:** Some elements of the screenshots don't exist in the **Zoning Analysis**. **Explanation:** The **Zoning Analysis** module does not support `UITableViewHeaderFooterView` in `UITableView` and `UICollectionReusableView` in `UICollectionView` due to their highly dynamic memory and rendering behavior. ### Screenshot fidelity: Floating header/footer duplicated in Zoning **Symptom:** Some elements appear multiple times in the **Zoning Analysis**. **Explanation:** The **Screenshot** captures the currently visible content on screen. When a floating header/footer remains visible during scrolling, it may be captured at different positions throughout the **Long screenshot process**, resulting in duplications. ### Screenshot fidelity: Multiple vertical scrollViews **Symptom:** The **Long Screenshot** cinematic may not start on mobile, or the resulting screenshot might be unscrollable in **Zoning Analysis**. **Explanation:** When multiple vertical scrollViews are present on a screen, the **Long Screenshot** cinematic will attempt to run only on the last vertical scrollView the user interacted with. Other scrollable areas will not be automatically scrolled or captured by the cinematic process, even if they contain content. In practice, this means the automatic scrolling (and full content capture) is limited to a single scrollView per screen, based on user interaction. ### Screenshot fidelity: Lottie animations **Symptom:** Lottie Animation elements are not visible in the **Zoning Analysis**. **Explanation:** The **Zoning Analysis** module does not support `LottieAnimationView` because the SDK can't select a specific frame to capture. ### Gestures not attached to `UIImageView` **Symptom:** When analysing the tap rate on an image, we see 0% when we know it is not possible. **Explanation:** By default `UIImageView` have their `isUserInteractionEnabled` property set to false ([See Apple documentation ↗](https://developer.apple.com/documentation/uikit/uiimageview/1621063-isuserinteractionenabled)). This means that the `UIImageView` won't receive any input event. All events will be handled by the first parent to have `isUserInteractionEnabled` set to true (usually the first parent will do). **Workaround:** Create a zone on the parent view to get the taps on the image. ### `UICollectionViewCompositionalLayout` TVP lack of consistency **Explanation:** As explained in the [Apple documentation ↗](https://developer.apple.com/documentation/uikit/uicollectionviewcompositionallayout), `UICollectionViewCompositionalLayout` is a highly dynamic layout creation object. We are not able to ensure TVP value is the same between different usages. ### Long Screenshot: Large Capture Limitation **Symptom:** The Long Screenshot capture completes the creation process, but then fails at the very end without a clear error message. **Explanation:** Long Screenshots can produce a very large amount of data. For reliability and performance reasons, the server enforces a maximum payload size (\~75 MB). Very long or content-heavy screens may exceed this limit, causing the screenshot to be rejected. **Workaround:** Capture a shorter area (reduce the scroll length) and/or reduce the amount of on-screen content (for example fewer or lighter elements), then retry the Long Screenshot. ### Zoning Limitation in SwiftUI with scrolling (Lazy)Stack and (Lazy)Grid * **Screenshot and Gesture Tracking Limitations:** * Using `LazyStack`, or `LazyGrid` nested in a `ScrollView` may present limitations in screenshot and gesture tracking due to differences in memory management compared to UIKit. * Intricate hierarchies of `LazyStacks` or `LazyGrids` can lead to inconsistent identification of elements, impacting the reliability of element identification. **Prefer to use single layered Lazy components**, when possible. * **Rotation Limitation:** * Unique identification of elements within SwiftUI `Stack`, `Grid`, `LazyStack`, or `LazyGrid` is not guaranteed after a rotation, so, **rotation is not supported** for `Stack`, `Grid`, `LazyStack`, or `LazyGrid`. * **Scrolling Element Offset Limitation:** * The consistency of unique identifiers is not guaranteed when the scrolling element is displayed starting at an offset different than zero. Check the following Help Center article for more information about the symptom, root cause and potential mitigation solutions: [I can't create a zone on a list element on iOS (SwiftUI) ↗](https://support.contentsquare.com/hc/en-us/articles/4408117004690) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Contentsquare iOS SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/compatibility/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: SDK API reference - iOS description: SDK commands reference including signature, parameter descriptions, and examples lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/command-reference/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-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). ```swift 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. ```swift 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`. ```swift CSQ.identify("userIdentity") ``` #### Parameters * #### identity  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. ```swift 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. This is an identifier from Product Analytics by default or Experience Analytics if PA is not active. ```swift let 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. ```swift let sessionID = CSQ.metadata.sessionID ``` #### CSQ.metadata.projectID Project identifier for Experience Analytics. ```swift let projectID = CSQ.metadata.projectID ``` #### CSQ.metadata.environmentID Environment identifier for Product Analytics. ```swift let environmentID = CSQ.metadata.environmentID ``` #### CSQ.metadata.sessionReplayURL URL of current Session Replay. ```swift let sessionReplayURL = CSQ.metadata.sessionReplayURL ``` #### CSQ.metadata.identity Identity associated with the user by calling [`identify()`](#csqidentify). ```swift let identity = CSQ.metadata.identity ``` ### CSQ.metadata.onChange { metadata in } **Added in:** `1.0.0` A block triggered each time user information is updated. For example when `sessionReplayURL` becomes available or `userID` updates. Set this block to subscribe to the updates. Contentsquare will call this block with updated metadata. Note This may not trigger on changes to Product Analytics data. ```swift CSQ.metadata.onChange { metadata in // Handle information change } ``` #### Parameters * #### metadata  Metadata   Metadata associated with the current user and project. ## Logging ### CSQ.debug.logLevel **Added in:** `1.0.0` Gets or sets the current log level. ```swift CSQ.debug.logLevel = .debug ``` #### Parameters * #### level  Enum (CSQ.Log.Level)   Possible values: `none`, `trace`, `debug`, `info`, `warn`, `error`, or `important`. ### CSQ.debug.logChannel Product Analytics | **Added in:** `1.0.0` Gets or sets the `LogChannel` to which send log messages. ```swift CSQ.debug.logChannel = customLogChannel ``` #### Parameters * #### LogChannel  interface   The interface where log messages will be routed. ### LogChannel.printLog() Product Analytics | **Added in:** `1.0.0` Implement this function to route SDK logs to another location such as CocoaLumberjack, SwiftyBeaver, or similar logging libraries.\ The default implementation routes all logs through `os_log`. ```swift class CustomLogChannel: LogChannel { func printLog(logLevel: Log.Level, message: () -> String, source: String?, file: String, line: UInt) { // your implementation } } ``` #### Parameters * No parameters. ## 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` object, representing a key-value pair that is scoped to the session. ```swift let var1 = DynamicVar(key: "key1", value: "value1") let var2 = DynamicVar(key: "key2", value: 2) CSQ.addDynamicVar(var1) CSQ.addDynamicVar(var2) ``` #### Parameters * #### dVar  DynamicVar   The dynamic variable * #### key  String (<= 512 chars)   Dynamic variable key * #### intValue  UInt32   Dynamic variable integer value * #### stringValue  String   Dynamic variable string value ### CSQ.addUserProperties() Product Analytics | **Added in:** `1.0.0` Add a collection of properties to be associated with the current user. ```swift CSQ.addUserProperties(["propertyKey"": "propertyValue"]) ``` #### Parameters * #### properties  \[String: PropertyValue]   A dictionary of user properties. `PropertyValue` can be `String`, `Substring`, `Bool`, `Double`, `Float`, `Int`, `Int64`, `Int32`, `Int16` or `Int8`. ### CSQ.addEventProperties() Product Analytics | **Added in:** `1.0.0` Add a collection of properties to be associated with all future events. ```swift CSQ.addEventProperties(["propertyKey": "propertyValue"]) ``` #### Parameters * #### properties  \[String: PropertyValue]   A dictionary of event properties. `PropertyValue` can be `String`, `Substring`, `Bool`, `Double`, `Float`, `Int`, `Int64`, `Int32`, `Int16` or `Int8`. ### CSQ.removeEventProperty() Product Analytics | **Added in:** `1.0.0` Removes a single property from the collection of event-wide properties. ```swift CSQ.removeEventProperty("propertyKey") ``` #### Parameters * #### key  String   The key of the property to remove. ### CSQ.clearEventProperties() Product Analytics | **Added in:** `1.0.0` Removes all event-wide properties. ```swift CSQ.clearEventProperties() ``` ## View Tracking ### UIScrollView\.excludeFromExposureMetrics() Experience Analytics | **Added in:** `1.0.0` Exclude a scrollable view or subclass from Exposure Metric computations. ```swift let scrollView = UIScrollView() scrollView.excludeFromExposureMetrics() ``` ## CSInApp ### CSQ.handle() Experience Analytics | **Added in:** `1.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](../../experience-analytics/in-app-features/). ```swift CSQ.handle(url: <CSInAppURL>)) ``` #### Parameters * #### url  URL   See [https://developer.apple.com/documentation/foundation/url ↗](https://developer.apple.com/documentation/foundation/url) ### CSQ.csInApp Experience Analytics | **Added in:** `1.0.0` Boolean to manually activate or deactivate in-app features. When `CSQ.csInApp = true`, the in-app function is activated automatically at app start. ```swift CSQ.csInApp = true ``` ## Interoperability ### CSQ.registerWebView() Experience Analytics | **Added in:** `1.0.0` Register a webview for tracking. ```swift let webView = WKWebView() CSQ.registerWebView(webView) ``` #### Parameters * #### webView  WKWebView   The webview to register for tracking. ### CSQ.unregisterWebView() **Added in:** `1.0.0` Unregister a webview for tracking. ```swift CSQ.unregisterWebView(webView) ``` #### Parameters * #### webView  WKWebView   The webview to unregister from tracking. ## Event Tracking ### CSQ.trackTransaction() Experience Analytics | **Added in:** `1.0.0` Send a transaction. ```swift let transaction = Transaction(id: "transactionId", total: 100.0, currency: .usd) CSQ.trackTransaction(transaction) ``` #### Parameters * #### Transaction  Transaction   The transaction object to be sent. Initialized with id, total, and ISO 4217 currency enum. ### CSQ.trackScreenview() **Added in:** `1.0.0` Send a screen view with or without custom variables. Requires Experience Analytics to be started. ```swift CSQ.trackScreenview(name: "ScreenName", cvars: [CustomVar(index: 1, name: "name", value: "value")]) ``` #### Parameters * #### name  String   The name of the screen. * #### cvars  CustomVar\[] (optional)   An array of custom variables to attach to the screen view. * #### index  UInt32   Custom variable index * #### key  String (<= 512 chars)   Custom variable key * #### 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. ```swift CSQ.trackEvent(name: String, properties: ["propertyKey": "propertyValue"]?) ``` #### Parameters * #### name  String   The name of the event to be tracked. * #### properties  \[String: PropertyValue>] (optional)   Optional properties to associate with the event. `PropertyValue` can be `String`, `Substring`, `Bool`, `Double`, `Float`, `Int`, `Int64`, `Int32`, `Int16` or `Int8`. ## Surveys ### CSQ.triggerSurvey() Experience Analytics Voice of Customer | **Added in:** `1.0.0` Triggers a survey by referencing a predefined trigger name. This method allows your mobile app to trigger surveys at specific moments in the user journey. Triggers act as flexible placeholders that are not bound to individual surveys, enabling your business team to assign or update surveys later without requiring code changes. ```swift CSQ.triggerSurvey(triggerName) ``` #### Parameters * #### triggerName  String   The name of the trigger associated with the survey. This should match the trigger name configured in the Contentsquare platform. #### Example ```swift // Trigger a survey after a purchase is completed CSQ.triggerSurvey("purchase-complete") ``` ## Error tracking ### CSQ.setUrlMaskingPatterns() Experience Analytics | **Added in:** `1.0.0` Sets URL masking patterns. ```swift CSQ.setUrlMaskingPatterns(["pattern1", "pattern2"]) ``` #### Parameters * #### patterns  \[String]   A list of URL patterns to mask. ### CSQ.onCrashReporterStart() Experience Analytics | **Added in:** `1.0.0` Trigger a callback when the Contentsquare Crash Reporter is initialized. ```swift CSQ.onCrashReporterStart { enabled in // do your work here, e.g. start Firebase Crashlytics } ``` #### Parameters * #### onCrashReporterStart  (enabled: Bool -> Void)   Closure triggered when crash reporter is started. Passes a boolean indicating if crash reporter is actually enabled. ### CSQ.sendUserIdentifier() Experience Analytics | **Added in:** `1.0.0` Associate the user identifier to the session. ```swift CSQ.sendUserIdentifier("any_identifier") ``` #### Parameters * #### userIdentifier  String   The user identifier to track. Should be max 100 characters long. ### CSQ.trackNetworkMetric() Experience Analytics | **Added in:** `1.0.0` Track network metrics. ```swift let networkMetric = NetworkMetric(url: "https://example.com", httpMethod: "GET") CSQ.trackNetworkMetric(networkMetric) ``` #### Parameters * #### networkMetric  NetworkMetric   NetworkMetric object for a network request to collect HTTP network errors. ## Personal Data/Masking ### CSQ.ignoreInteractions() **Added in:** `1.0.0` Ignore interactions for a specific view. ```swift CSQ.ignoreInteractions(view) ``` #### Parameters * #### view  UIView   [https://developer.apple.com/documentation/uikit/uiview ↗](https://developer.apple.com/documentation/uikit/uiview) ### UIView\.csqIgnoreInteractions UIKit IBInspectable | **Added in:** `1.0.0` Ignore interactions for a specific view. ```swift view.csqIgnoreInteractions = true ``` #### Parameters * No parameters. ### View\.csqIgnoreInteractions() Product Analytics SwiftUI | **Added in:** `1.2.0` Ignore interactions for a specific view. ```swift Text("Hello World!").csqIgnoreInteractions(shouldIgnore: true) ``` #### Parameters * #### shouldIgnore  Bool   Whether to ignore interactions. ### CSQ.setDefaultMasking() Experience Analytics | **Added in:** `1.0.0` Set the default masking state.\ All UIView elements, their subclasses and SwiftUI components are fully masked by default. ```swift CSQ.setDefaultMasking(true) ``` #### Parameters * #### masked  Bool   The default masking state to be set. ### CSQ.mask(UIView) **Added in:** `1.0.0` Mask a view's content. ```swift CSQ.mask(view) ``` #### Parameters * #### view  UIView   The view which content will be masked. ### CSQ.unmask(UIView) **Added in:** `1.0.0` Unmask a view's content. ```swift CSQ.unmask(view) ``` #### Parameters * #### view  UIView   The view which content will be unmasked. ### UIView\.csqMaskContents UIKit IBInspectable | **Added in:** `1.0.0` Mask the content of a view. ```swift view.csqMaskContents = true ``` #### Parameters * No parameters. ### View\.csqMaskContents SwiftUI | **Added in:** `1.0.0` Mask the content of a view. ```swift Text("Hello World!").csqMaskContents(true) ``` #### Parameters * #### enable  Bool   Whether to mask the content of the view. ### CSQ.mask(`viewsOfType: UIView.Type`) Experience Analytics | **Added in:** `1.0.0` Mask content for views of a specific type. ```swift CSQ.mask(viewsOfType: UIView.Type) ``` #### Parameters * #### viewsOfType  UIView\.Type   The class type of the view whose content will be masked. ### CSQ.unmask(`viewsOfType: UIView.Type`) **Added in:** `1.0.0` Unmask content for views of a specific type. ```swift CSQ.unmask(viewsOfType: UIView.self) ``` #### Parameters * #### viewsOfType  UIView\.Type   The class type of the view whose content will be unmasked. ### CSQ.maskTexts() **Added in:** `1.0.0` Mask all texts. ```swift CSQ.maskTexts(true) ``` #### Parameters * #### mask  Bool   Whether to mask text. ### CSQ.maskImages() Experience Analytics | **Added in:** `1.0.0` Mask images. ```swift CSQ.maskImages(true) ``` #### Parameters * #### mask  Bool   Whether to mask images. ### CSQ.maskTextInputs() Experience Analytics | **Added in:** `1.0.0` Mask text input fields. ```swift CSQ.maskTextInputs(true) ``` #### Parameters * #### mask  Bool   Whether to mask text inputs. ### UIView\.csqIgnoreInnerHierarchy Product Analytics UIKit IBInspectable | **Added in:** `1.0.0` If set on a view or view controller, all touches inside that control will be attributed to it rather than child views. This can be helpful in blocking sensitive parts of an interaction and keeping implementation details out of a view hierarchy. For example, Contentsquare uses this property internally to suppress inner touches on `UIDatePicker`. ```swift let view = UIView() view.csqIgnoreInnerHierarchy = true ``` ## SDK Initialization and Management ### CSQ.configureProductAnalytics() Deprecated Product Analytics | **Added in:** `1.0.0` SDK configuration method for Product Analytics. Use [`CSQ.start()`](#csqstart) instead, which combines configuration and initialization in a single call. ### CSQ.start() **Added in:** `1.0.0` Start the SDK. This method combines configuration and initialization in a single call. There are three overloads depending on whether you want Experience Analytics, Product Analytics, or CSQ Experience Platform. **Experience Analytics only:** ```swift CSQ.start() ``` **Product Analytics (optionally with Experience Analytics extension) with `environmentID`:** ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .enableNativeAutocapture: true ] ) ``` **CSQ Experience Platform with `dataSourceID`:** ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ .enableNativeAutocapture: true ] ) ``` #### Parameters * #### environmentID  String (optional)   Your Product Analytics environment ID. * #### dataSourceID  String (optional)   Your CSQ Experience Platform data source ID. Enables both Product Analytics and Experience Analytics with a single identifier. * #### options  \[AnalyticsOption: Any] (optional)   SDK [configuration options](#sdk-configuration-options). ### CSQ.stop() **Added in:** `1.0.0` Stop all activity from the SDK.\ Once run no requests, telemetry collection, or logs will be generated. ```swift CSQ.stop() ``` ### CSQ.pauseTracking() **Added in:** `1.0.0` Pause all tracking features. ```swift CSQ.pauseTracking() ``` ### CSQ.resumeTracking() **Added in:** `1.0.0` Resume all tracking features. ```swift CSQ.resumeTracking() ``` #### Parameters * No parameters. ### CSQ.startSessionReplay() **Added in:** `1.10.0` Enable and eventually start Session Replay independently of other CSQ SDK features, allowing for on-demand collection. To use this functionality, disable the automatic start of Session Replay at SDK initialization using the [`.sessionReplayAutoStart`](#sessionreplayautostart) option. ```swift CSQ.startSessionReplay() ``` ### CSQ.stopSessionReplay() **Added in:** `1.10.0` Stop Session Replay immediately. ```swift CSQ.stopSessionReplay() ``` ## SDK configuration options CSQ SDK options passed to [`CSQ.start()`](#csqstart). ```swift CSQ.start( // optional: environmentID: String | dataSourceID: String options: [ .uploadInterval: TimeInterval, .baseURL: URL, // EU: "https://mh.ba.contentsquare.net"; https://mh.bf.contentsquare.net (default) .disablePageviewAutocapture: Bool, .disablePageviewTitleAutocapture: Bool, .disableInteractionAutocapture: Bool, .enableNativeAutocapture: Bool, .enablePushNotificationAutocapture: Bool, .enablePushNotificationTitleAutocapture: Bool, .enablePushNotificationBodyAutocapture: Bool, .sessionReplayAutoStart: Bool ] ) ``` ### `uploadInterval` The interval in seconds between event batch uploads. Accepts a `TimeInterval` (Double) value. ### `baseURL` The CSQ API endpoint to use: * `https://mh.ba.contentsquare.net` — EU-hosted environments * `https://mh.bf.contentsquare.net` — all other environments (default) ### `disablePageviewAutocapture` Whether source pageview events will be auto-captured. Defaults to `false`. ### `disablePageviewTitleAutocapture` Whether autocapture of pageview titles is disabled. Defaults to `false`. ### `disableInteractionAutocapture` Disables autocapture of touch events on UIKit views. Defaults to `false`. ### `enableNativeAutocapture` Whether to enable autocapture of native UIKit view interaction events. Defaults to `false`. ### `enablePushNotificationAutocapture` Whether the SDK will auto capture interaction events on notifications. Defaults to `false`. ### `enablePushNotificationTitleAutocapture` Whether to capture the title of the notification where an interaction was performed. `enablePushNotificationAutocapture` must be set to `true`. Defaults to `false`. ### `enablePushNotificationBodyAutocapture` Whether to capture the body text of the notification where an interaction was performed. `enablePushNotificationAutocapture` must be set to `true`. 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. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"SDK API reference","description":"SDK commands reference including signature, parameter descriptions, and examples","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/command-reference/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Customize autocaptured screen names - iOS description: Customize screen names collected via autocapture in UIKit and SwiftUI apps lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/customize-autocaptured-screen-names/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/customize-autocaptured-screen-names/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. SwiftUI screenview autocapture depends on our UIKit autocapture behavior. When a view controller appears, by way of a `NavigationLink`, `TabView`, or `UIHostingController`, we detect its appearance and use the class name of the view controller along with the title text as the default data for labeling events. For hybrid SwiftUI/UIKit apps and apps with distinct screen titles, this may provide enough information without code changes. For pure SwiftUI apps, this may not be enough information, as SwiftUI may erase helpful type information. Adding the `csqScreenName` view modifier alongside modifiers like `navigationTitle` or inside the view body will provide a stable name for the autocaptured screenview. ```swift struct TransactionView: View { let transaction: Transaction var body: some View { ScrollView { ... } .navigationTitle("title-transaction") .csqScreenName("TransactionScreen") } } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Customize autocaptured screen names","description":"Customize screen names collected via autocapture in UIKit and SwiftUI apps","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/customize-autocaptured-screen-names/","inLanguage":"en","dateModified":"2026-04-07T14:16:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - iOS description: Configure privacy settings and user consent management in your iOS app with the CSQ SDK to ensure regulatory compliance lastUpdated: 28 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/privacy/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Customers ("Customer(s)", "you," or "your"), as app developers and/or publishers, shall ensure compliance with applicable data privacy laws and regulatory guidelines while using Contentsquare SDK for your app. This section explains the data processing involved in the use of Contentsquare SDK and provides information to help you comply with data protection laws, including the GDPR, e-privacy directive, and the [French Data Protection authority (CNIL) guidelines on mobile applications ↗](https://www.cnil.fr/sites/cnil/files/2025-05/recommendation-mobiles-app.pdf). This section is for informational purposes only and is not legal advice. If you are not sure of how to comply with data protection laws that apply to you, refer to legal counsel. To learn about Contentsquare privacy practices, see our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Purpose of processing and categories of personal data collected Here is the list of categories of personal data Contentsquare collects by default that are part of our [privacy manifests](../privacy/#privacy-manifest). All collected personal data listed below is linked to the end-user via the [Contentsquare User ID](#contentsquare-user-id) we generate. Warning The Contentsquare SDK provides features that allow you to send to Contentsquare additional types of personal data (such as username, email address, customer ID, account number): [Dynamic variables](../../experience-analytics/track-dynamic-variables/), [Custom variables](../../experience-analytics/track-custom-variables/), [User identifier](../../experience-analytics/session-replay/#send-user-identifier), [Screen names](../../experience-analytics/track-screens/), [Session Replay (unmasking elements)](../../experience-analytics/session-replay/#personal-data-masking). If you decide to use these features to collect new types of personal data or use already collected data but for a different purpose, it is up to you to describe these privacy practices in your app manifest. | Categories | Data type | Purposes | | - | - | - | | Identifiers | User ID | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Product Interaction such as touch gestures (taps, swipes), user journey (pages visited), time of engagement, or transactions | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Other usage data (any other data about end-user activity in the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Other Data types | Other Data types (technical data, any other data inputted by customers in the dynamic variables, data used as part of the Session Replay feature where applicable) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Diagnostics | Crashes, such as crash logs | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Diagnostics | Performance data, such as launch time, freeze rate, or energy use | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Diagnostics | Other diagnostic data (any other data collected for the purposes of measuring technical diagnostics related to the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Search History | Information about searches performed by an end-user in the app | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Session Replay module](../../experience-analytics/session-replay/)) | | Purchase History | Transaction data about an end-user (such as order reference, amount, bought items) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | See how the data types and purposes are reflected in the [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy). Note Contentsquare is not designed to collect sensitive personal data (such as health, financial, or racial data). It is your responsibility to prevent any sensitive data from being sent to Contentsquare. If you accidentally send sensitive data, contact your customer success manager to immediately delete them from Contentsquare servers. ## User identifiers ### Contentsquare User ID The SDK generates a unique user ID (UUID) (random hash) which is specific to users on their device. Contentsquare cannot identify a user across devices. This user ID and all collected data are stored for 13 months. We don't persist the UUID when the app is deleted and re-installed. The SDK generates a new UUID after install or re-install. Contentsquare does not share this user ID with any third parties. ### IDFA Contentsquare does not collect the **IDFA** (Advertising ID) or any ad related information to identify the user. Check out our page about [10 Things to know about the Contentsquare solution's data processing ↗](https://contentsquare.com/privacy-center/10-things-to-know-cs-data-processing/). ### "User identifier" feature Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier provided by the customer. See [User identifier feature](../../experience-analytics/session-replay/#send-user-identifier) for more information. ## Data retention and storage location ### Data retention By default, end-users personal data are kept for 13 months. The retention of end-users personal data collected via the Session Replay is customizable by customers, from 3 to 24 months. ### Storage location End-users personal data are stored in Europe or in the US, depending on your location. For more details on applicable hosting locations, refer to our [subprocessors list ↗](https://contentsquare.com/privacy-center/subprocessors/). ## Informing your End-User The Contentsquare SDK collects end-user's personal data on your app. As a data controller, app developers, or app publishers, it is your responsibility to provide appropriate information to your end-users on how their personal data is handled when using the CSQ SDK, for example via a privacy policy or cookie banner. Contentsquare provides a sample [description of the services ↗](https://contentsquare.com/privacy-center/sample-cookie-description/) (including Experience Analytics and Product Analytics) to help customers meet their transparency obligations. This description is for information only and is not legal advice. ## Handling User Consent Contentsquare collects usage data on your app. **By default, the SDK will consider every new user to be opted-out.** To start tracking, the SDK [Opt-in API](#opt-in) must be called. You are responsible for handling the UI asking end-users for their consent and allowing them to manage their privacy settings. Use the following APIs to pass the user decision to the Contentsquare SDK. Note If data protection laws that apply to you do not require end-user consent for your app, discuss it during implementation with your Contentsquare contact (as this would go against Apple Privacy guidelines). ### Opt-in Use the Opt-in API to get end-user consent. Calling this API will generate a user ID and initiate tracking. * Product Analytics ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` * CSQ Experience Platform (Early Access) ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` ### Opt-Out When this API is called, tracking stops immediately, all settings are reset (Session number, Page number, and so on) and all files and directory including personal data collected via the SDK created by Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track and collect any data from the user's phone unless the Opt-in API is called again. ```swift CSQ.optOut() ``` ### Handling your end-user's data subject requests In case Contentsquare receives a request from an individual that identifies as an end-user of your app, Contentsquare will promptly refer such individual directly to you, as the data controller and will support you with any means available to resolve such request. Contentsquare has launched a portal for managing data subject requests to its customers respond to data subjects within the legal deadlines. Therefore, you can forward any data subject request (such as data deletion or data access request) you receive to Contentsquare via this Data Subject Portal at [https://contentsquare.com/privacy-center/data-subject-request-portal/ ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ### Get Contentsquare User ID Since Contentsquare SDK does not collect by default any directly identifiable personal data about your end-user, we cannot help you respond to an end-user's data subject request without their Contentsquare User ID. Use this API to get the Contentsquare User ID of your end-user and forward the end-user's data subject request (such as data deletion or data access request) via Contentsquare's [portal ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ```swift CSQ.metadata.userID ``` Note You are able to get an ID only if the user is not Opted-out. ### Enrichment API [The Enrichment API](https://docs.contentsquare.com/en/api/enrichment/) allows for enriching the behavioural data tracked by Contentsquare client-side, with other session-based data that can be sent server-side. During a visit on an app, you can interact with Contentsquare's SDK to pull those identifiers with the following SDK APIs: ```swift let projectID = CSQ.metadata.projectID let sessionId = CSQ.metadata.sessionID // store these Contentsquare session identifiers in your backend ``` ### Pause / Resume Tracking To completely stop data collection of your end-users of your app, use the pause and resume tracking APIs. When `stop/pause` is called, the Contentsquare SDK pauses all tracking (Analytics, Session Replay, Errors) of your end-users. When `resume` is called, the Contentsquare SDK resumes all tracking (Analytics, Session Replay, Errors) and starts collecting your end-users personal data again with the same Contentsquare user ID. ```swift CSQ.stop() // ... CSQ.resumeTracking() ``` Note As this mechanism pauses the tracking, make sure that you call resume once your user exits the sensitive screen. Best practice would be to link these method calls to lifecycle events on UIView/UIViewControllers. ## Disable user tracking across sessions If you don't want to link the different sessions of a user to the same userID, reset the userID at each app start: ```swift func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) { CSQ.start() CSQ.optOut() CSQ.optIn() // ... } ``` Starting the SDK manually using `start()` will ensure that opt-out is called right after the start of the SDK (no event tracked in between). Calling `optOut()` will delete the previous userID. Calling `optIn()` will set a new one. Note If you are monitoring the network requests, you may see event requests being sent at app start. This is expected as there may be events from the previous session that haven't been sent yet. The [opt-out API](#opt-out) makes sure to send all data stored locally before stopping the tracking and wiping all data. ### Session Replay privacy APIs As part of Session Replay capabilities, Contentsquare provides masking mechanisms to prevent unwanted end-user's personal data from the Session Replay module from being transmitted to Contentsquare. See [Session Replay Personal data masking](../../experience-analytics/session-replay/#personal-data-masking) for more information. ## App Store Privacy Guidelines Compliance As customer app developers, it is your responsibility to comply with the [App Store Privacy guidelines ↗](https://developer.apple.com/app-store/review/guidelines/#privacy). ### Privacy manifest The Contentsquare SDK includes a [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy) describing the types of end-users personal data collected, the purpose of processing and the reasons for using APIs. [See Apple's website for more information ↗](https://developer.apple.com/app-store/app-privacy-details/) ### Tracking and App Tracking Transparency (ATT) App Store (Apple) requests App developers to receive end-users' permission to track them or access Advertising ID using the [AppTrackingTransparency framework ↗](https://developer.apple.com/documentation/apptrackingtransparency) (ATT). **It is not required to ask for end-users' permission through the ATT when using Contentsquare, as it does not fall under the** ["tracking" definition of Apple ↗](https://developer.apple.com/app-store/app-privacy-details/#user-tracking). The data collected by the Contentsquare SDK is not linked with Third-Party Data (as defined by Apple) for targeted advertising or advertising measurement purposes, nor shared with a data broker. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Configure privacy settings and user consent management in your iOS app with the CSQ SDK to ensure regulatory compliance","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/privacy/","inLanguage":"en","dateModified":"2026-04-28T22:02:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Experience Analytics extension - iOS description: Understand the benefits of upgrading to the CSQ SDK lastUpdated: 12 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/dxae-setup/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/dxae-setup/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use this page to set up the Mobile Experience Analytics extension for Contentsquare Product Analytics. This will supercharge the Product Analytics platform with: * Powerful Session Replay * Heatmaps * Analysis capabilities of Mobile API Errors and Crashes This guide assumes that you have already implemented the [CSQ SDK for Product Analytics](../). ## Enable the extension in the Product Analytics UI 1. In Product Analytics, navigate to **Account** > **Manage** > **Replays & Heatmaps**. 2. If this is your first time setting up Session Replay, select the checkbox to accept the terms and conditions. 3. Click **Add web or mobile app** to launch the setup wizard. There is one configuration per app. 4. Select **Mobile** as platform. 5. Give your app a name and choose a storage location (**US** or **EU**). 6. Set a sampling rate for how many sessions to record. 7. Configure replay settings: * **App ID**: enter the bundle ID of your app (for example, `com.companyname.appname`). * **Quality Settings**: choose the recording fidelity for Wi-Fi and Cellular connections. The default for both is Medium; keep Cellular equal to or lower than Wi-Fi. * **User Consent**: enable this if your app requires explicit opt-in before recording. See [Privacy docs](../privacy/#opt-in) for the opt-in API. 8. Click **Save and Continue** to finish the wizard. ## Enable error and crash collection Error and crash collection is managed separately from the setup wizard. Navigate to **Account** > **Manage** > **Replays & Heatmaps**, click **Edit** next to your app configuration, then scroll to the relevant section under **General Settings**: * **Error Capture**: toggles for **API Errors** and **Custom Errors**. * **Crashes Capture**: toggle for **Crashes**. Click **Save** when finished. ## Session Replay masking The Session Replay feature replays every interaction of your users with your app. To respect the user's right to privacy, the Contentsquare SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our [Masking rules](#masking-rules) Warning **Privacy Manifest:** If you decide to use unmasked elements leading to collection of new data or use already collected data but for a different purpose, it is up to you to update the privacy practices described in your app manifest accordingly. Here are some common examples of data collected via unmasked Session Replay: Search history, Purchase history, Advertising data, etc. See [Types of data and purpose](../privacy/) already described in the Contentsquare iOS SDK Privacy Manifest. Contentsquare is not intended nor designed to collect sensitive personal data (such as health, financial, or racial data). It is the customer's responsibility not to send any sensitive personal data to Contentsquare. ### Masking mechanisms Masking depends on the type of element: | Element Type | Masking Behavior | | - | - | | `UIKit.UIImage` and `SwiftUI.Image` | Image isn't collected, a placeholder is sent instead of the content; the "IMG" placeholder will be displayed in the frame of the element. | | `UIKit.UILabel` and `UIKit.UITextView` | Text is replaced by "la" repeated as many times as needed to equal the original character count. White characters are preserved. For instance `the lazy fox` is collected as `lal lala ala`. All other visual properties are collected (text color, background color, alignment, etc.). | | `UIKit.UITextField` | Same as `UIKit.UILabel` or `UIKit.UITextView` unless `isSecureTextEntry` is set to `true`. In this case all characters, including whitespaces are replaced with "•". | | `SwiftUI.Text` | Element is replaced by a black rectangle. | | All other types | No specific data is collected but all visual properties are collected: size, background color, corner radius, etc. | If you think a specific element can reveal personal data from one of these properties mask it using one of the methods presented below. An efficient way to check how a view is rendered in the Session Replay is to navigate to the desired view with the SDK running then use the quick replay link.  #### Original vs Replay fully masked * UIKit  * SwiftUI  ### Masking rules Masking rules can be applied in two ways: 1. **Through remote masking configuration in the CSQ Console (for admin users):** this is managed directly in the Console and takes effect for all sessions as soon as the app is restarted or brought to the foreground. See [How to customize masking rules from the Data Masking tab ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) in the Help Center. 2. **Using public masking APIs in the SDK (for mobile application developers):** these APIs require developer implementation and will be applied only after the mobile app has gone through its release cycle. The SDK determines whether views, images, and texts are masked according to the following rules, ranked from highest to lowest priority. Once a rule is triggered, the state is set, and subsequent rules are not applied. #### General rules | Rules (highest to lowest priority) | Configured via | | - | - | | 1. The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text or Image masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. An [instance](#maskingun-masking-by-instance) is specifically masked or unmasked | API | | 4. A [parent](#masking-and-unmasking-behaviors-on-a-parent-view) is specifically masked or unmasked | API | | 5. A [type](#maskingun-masking-by-type) is masked or unmasked | API | | 6. A parent [type](#maskingun-masking-by-type) is masked or unmasked | API | | 7. Remote Text or Image unmasking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 8. Otherwise the [default masking state](#default-masking) is applied | API | #### Text input fields rules `UIKit.UITextField`, `UIKit.UITextView` and `SwiftUI.TextField` text inputs follow specific rules as the risk of leaking personal data is higher with these elements: | Rules (highest to lowest priority) | Configured via | | - | - | | 1. The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2. Remote Text inputs masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3. An [instance](#maskingun-masking-by-instance) is specifically masked or unmasked | API | | 4. A [type](#maskingun-masking-by-type) is masked or unmasked | API | | 5. Otherwise a text input field remains masked | default | Note Default masking and parent masking don't change the masking state of text inputs. ### Public masking APIs #### Default masking All iOS views and subclasses of `UIView` are fully masked by default. Change the default masking state with: ```swift /// Change the masking state of all types of views. /// - Parameter mask: true restores the default masking state. /// false unmasks every type of views. static func setDefaultMasking(_ mask: Bool) ``` Note Setting the default masking state to `false` does not affect `UITextField`, `SwiftUI.TextField` and `WKWebView`. #### Masking/Un-masking by instance * UIKit Use `mask(view:)` and `unmask(view:)` methods to mask or unmask a specific view instance. Masking is applied recursively to all subviews unless specified otherwise (cf. [Masking and Unmasking behaviors on a parent view](#masking-and-unmasking-behaviors-on-a-parent-view)). **Following the previous example on un-masking UIButtons:** you are in default masking, the `UIButton` are unmasked but a screen shows a button, `myButton`, that contains sensitive information. You can mask it with `mask(view: myButton)`. * SwiftUI Mask or unmask a SwiftUI `View` instance by using the following view modifier. Masking is applied recursively to all subviews unless specified otherwise (cf. [Masking and Unmasking behaviors on a parent view](#masking-and-unmasking-behaviors-on-a-parent-view)). ```swift @ViewBuilder func csMasking(_ shouldMask: Bool) -> some View ``` #### Masking/Un-masking by type Although the SDK allows masking elements by type for convenience but it isn't the recommended masking mechanism because it impacts all screens of your application. Use this when you have a specific class for presenting user information or for displaying the user profile picture to make sure it always stays masked, for instance. * UIKit Use `mask(viewsOfType:)` and `unmask(viewsOfType:)` methods if you want to handle a specific type, whether system or custom. **Example: un-masking UIButtons**: If default masking is set to true, and you don't want any button to be masked, call `unmask(viewsOfType: UIButton.self):` to specify that all instances of `UIButton` and its subclasses should not be masked. * SwiftUI Mask or un-mask by type using following methods as needed: ```swift /// Masks or unmasks all text elements. /// /// The text elements are `Text` for SwiftUI and `UILabel` for UIKit static func maskTexts(_ mask: Bool) ``` ```swift /// Masks or unmasks all image elements. /// /// The image elements are `Image` for SwiftUI and `UIImageView` for UIKit. static func maskImages(_ mask: Bool) ``` ```swift /// Masks or unmasks all text input elements. /// /// The text input elements are `TextField`, `SecureField`, `TextEditor` for SwiftUI /// and `UITextField`, `UITextView` for UIKit. /// static func maskTextInputs(_ mask: Bool) ``` Warning These APIs will also affect **UIKit masking**. You can use only these APIs and mask/unmask both UIKit and SwiftUI elements. #### Masking and Unmasking behaviors on a parent view ##### UIKit Masking is applied recursively to all children unless a specific rule has been applied to one of them. In this case, this rule also applies recursively. **Examples** Consider the following structure: ```plaintext (parent view) ------------------------ | "Parent Label" | | | | (child view) | | -------------------- | | | "Child Label" | | | | | | | -------------------- | | | ------------------------ ``` Here's how the masking rules applied affect the parent and child labels: | Rules applied | Parent Label | Child Label | | - | - | - | | No rule applied | Masked | Masked | | Parent view unmasked | Unmasked | Unmasked | | Parent view unmasked and child view masked | Unmasked | Masked | | Default masking = false | Unmasked | Unmasked | | Default masking = false and parent view masked | Masked | Masked | See [Masking rules](#masking-rules). **Unmasking an instance when its type is masked** If you've masked `UILabel` types specifically or are in default masking, call `unmask(view: myLabel)` so that all `UILabel` **instances** are masked except `myLabel`. **Mask an instance when its type is unmasked** If you've unmasked the `UILabel` type specifically or are using default masking, call `mask(view: myLabel)` so that no `UILabel` is masked except `myLabel`. ### Implementation recommendations * UIKit Masking operations should **always be performed before the target view is added to the window** to avoid any Personal Data leak. For instance, you can set up masking in the `didFinishLaunching` callback of your app or if you need to change masking behavior while your app is launched: this can be done in `loadView`, `viewDidLoad` or `viewWillAppear` if you use a `ViewController`. * SwiftUI Masking operations should be done as early as possible. For masking [by type](#maskingun-masking-by-type), in the setup of your app for instance. For masking [by instance](#maskingun-masking-by-instance), in the body of your `View` by calling the `csMasking` modifier. ### Keeping track of what is masked The SDK doesn't provide a list of what is currently masked, if you need to keep track, you probably will have to write your specific wrapper. ### Masking operations performance impact Repeating the same operation has little to no impact. For example, you can call `unmask(viewsOfType: UIButton.self)` multiple times without impacting the SDK or your app performance. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Experience Analytics extension","description":"Understand the benefits of upgrading to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/dxae-setup/","inLanguage":"en","dateModified":"2026-06-12T11:40:35+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Hide sensitive data - iOS description: Protect sensitive data in Contentsquare by disabling text capture, masking specific views, or ignoring interactions lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/hide-sensitive-data/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/hide-sensitive-data/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. When using autocapture, Product Analytics collects target text information about the element that was interacted with, and text data from UI elements further up in an element's ancestry. However, some of these elements might contain sensitive user information, or Personal Data, that needs to be excluded from data capture. There are three options for hiding sensitive data: * Disabling text capture * Per-view text masking * Ignoring interactions for specific views ## Disabling all text capture You have the option to disable text capture for all events that are automatically captured. To do this, use the `CSQ.maskTexts()` API. ```swift CSQ.maskTexts(true) CSQ.start() ``` ## Masking text for specific views If you don't want to disable all text capture for your app, you can take a more targeted approach of only masking text for specific views in your app that you know might contain sensitive data. When text is masked for a view, it will still have target text, but the actual text will be replaced with `****`. ```swift let view = UIView() CSQ.mask(view) // view.csqMaskContents = true // UIKit View().csqMaskContents(true) // SwiftUI, use ViewModifier CSQ.start() ``` Note Masking the visible text also masks the text in the accessibility label to ensure Personal Data isn't leaked when the visible text and the accessibility text are the same value. ### Ignoring all interactions for specific views If you find that certain interactions are prone to capturing sensitive data, or that a certain interaction might indicate sensitive information about a user during analysis, you have the option of ignoring all interactions on a per-view basis. ```swift let view = UIView() CSQ.ignoreInteractions(view) // UIKit, by method view.csqIgnoreInteractions = true // UIKit, by property accessor View().csqIgnoreInteractions(true) // SwiftUI, use ViewModifier CSQ.start() ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Hide sensitive data","description":"Protect sensitive data in Contentsquare by disabling text capture, masking specific views, or ignoring interactions","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/hide-sensitive-data/","inLanguage":"en","dateModified":"2026-05-04T11:50:50+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track events manually - iOS description: Learn how to track custom events in your iOS app using the CSQ SDK lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/track-events-manually/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/track-events-manually/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. In addition to autocaptured events, use the `CSQ.trackEvent()` API to send custom events and attach properties to them for use in Product Analytics. ```swift CSQ.trackEvent("custom_event_name") ``` It doesn't matter what you call your event, there are ways in Product Analytics to cross-track events regardless of name. See our [guide on combo events ↗](https://help.heap.io/hc/en-us/articles/37271999013009-How-to-combine-events-using-a-combo-event) to learn more. ## Adding properties to custom events Custom events can be enhanced with a set of properties that will correspond to the tracked event when passed into the `CSQ.trackEvent()` API call. ```swift CSQ.trackEvent("custom_event_with_properties", properties: [ "property1": "sample value", "property2": 10, "property3": false, ]) ``` ## Adding properties to all events In some cases, you might want to add a property, or a collection of properties, to all events tracked by Product Analytics. Adding a global event property can be accomplished using `CSQ.addEventProperties()`. ```swift CSQ.addEventProperties([ "property1": "sample value", "property2": 10, "property3": false, ]) ``` Properties that are added using the `CSQ.addEventProperties()` API will be attached to all events tracked by Product Analytics, including any events that are automatically tracked by a CSQ autocapture SDK. ## Removing a Property Once a property is no longer needed in the global collection, use `CSQ.removeEventProperty()` to remove properties one at a time. ```swift CSQ.removeEventProperty("property1") ``` ## Removing All Properties On the other hand, if you want to remove all properties added with `CSQ.addEventProperties()` at once, you can achieve this by using `CSQ.clearEventProperties()`. ```swift CSQ.clearEventProperties() ``` However, neither of these methods will affect events that have already been processed. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track events manually","description":"Learn how to track custom events in your iOS app using the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/track-events-manually/","inLanguage":"en","dateModified":"2026-05-04T11:50:50+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track identity - iOS description: Enhance user tracking with identify and addUserProperties APIs. Link anonymous and identified user data across sessions and devices for comprehensive analytics lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/track-identity/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/track-identity/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Product Analytics assigns every visitor a random user ID; call `identify` to merge anonymous and identified profiles, and `addUserProperties` to attach custom attributes. ## User Identities and Properties Contentsquare Product Analytics empowers you to use the rich information about your users to better understand how users interact with your site or app, and build charts to continually track engagement. There are two primary APIs for enriching user data in Product Analytics: * The [`CSQ.identify()`](../command-reference/#csqidentify) API allows you to attach a unique identity and maintain user histories across sessions and devices under a single profile, * The [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) API allows you to attach custom properties to your users, whether they are identified or still anonymous. ## Read This First: Key Considerations Before implementing our APIs, check the following explanations on how these APIs work and common implementation mistakes to avoid. ### Anonymous Users When a person interacts with your site or app, Product Analytics generates a random unique user ID and stores it in a cookie. In Product Analytics, these users will appear in the [Users ↗](https://developers.heap.io/docs/users) view as "User 123456" where the 123456 is their user ID. We refer to these users as anonymous users throughout this document. Tip Though this guide focuses on web use cases, the same principles apply to mobile. The user ID may be stored differently depending on the platform. If a user visits your website on their mobile device and their laptop, Product Analytics will recognize 2 different anonymous users because both devices will have different cookies. We can identify these users on both platforms and link the two anonymous users into a single identified user. Note While Product Analytics can track identified users across different domains, it will not track anonymous users across domains. For cross-domain tracking support, you should using our APIs to identify users. ### Identified Users You can use the `identify` API to attach your own unique identifier to a user. The `identify` API takes a single string value as an argument. Examples are provided further down in this guide in the [Examples section ↗](https://developers.heap.io/docs/using-identify#examples). Warning When a user is identified, their past sessions and event activity from when they were anonymous are now tied to that identity. This allows the user to use multiple devices/browsers to access your website with a single identity. ### User Properties The [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) API can be used to attach properties to users' profiles. Product Analytics sets some of these properties automatically, such as Initial Location, Initial Referrer, Initial Marketing Channel, and more. A full list of all user properties captured by default is available in [Autocaptured Data ↗](https://help.heap.io/getting-started/how-heap-works/autocaptured-data/). The [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) API allows you to attach any string or number as a user property that's not automatically captured. Some practical properties to use include: payment plan, marketing segment, or A/B experiment. Once set, these properties can be used in charts to [group by ↗](https://developers.heap.io/docs/group-bys) and [filter ↗](https://developers.heap.io/docs/filters) against. Check out some specific examples further down this page. ### Common Identify Implementation Errors Below we've listed the most common mistakes developers may make when implementing the `identify` API. #### Using a Non-Unique Identifier A common assumption is that a unique identifier attached via [`CSQ.identify()`](../command-reference/#csqidentify) is required in order for the [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) API to attach properties to a user. In cases where a unique identifier isn't available, we've seen people include a specific name, like 'guest', or 'Anonymous User'. This can cause irreversible behavior with how Product Analytics merges user profiles. You can call [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) at any time, whether the user has been given a unique identity. For this reason, the following identify calls are blocklisted: * `anonymous` * `guest` * `null` * `true` * `false` * `not_authenticated` * `NaN` * `' '` (empty string) * `0` * `None` * `none` * `Email` * `email` As an example of how this would impact your setup: let's say that you have a marketing campaign, and you want to associate it with a visitor when they visit your landing page. They aren't logged in, so you don't have a unique identifier. **Don't do this:** ```swift CSQ.identify("guest") CSQ.addUserProperties(["campaign": "Campaign Name"]) ``` This will merge all visitors into a single user profile called 'guest', which will break any metrics that rely on user flow, or the unique user count. **Instead, do this:** ```swift CSQ.addUserProperties(["campaign": "Campaign Name"]) ``` Now the campaign property will be associated with the anonymous user, using the value of the JavaScript variable 'campaign'. ### Adding an Anonymous Unique Identifier of Your Own Some tools require a unique identifier to be provided to add user-level properties. This leads people to add their own unique identifier to all visitors. in Product Analytics automatically assigns each unidentified user a unique user ID so that you aren't required to call `identify` to add user-level properties. Assigning an identity to a user when it isn't required can lead to undesirable, or unexpected behavior. Product Analytics does not allow you to change an already applied identity or assign multiple identities to the same user. If you call `identify` with an anonymized identity, such as a `uuid` or random hash, this will be their permanent identity in Product Analytics. If you call the identify API at another time for the same user with a different identity, such as an internal user ID or username, this will create a new user in Product Analytics, splitting this users into two identified users, one with the random `uuid` containing all of the historical events, and another with the user ID or username which has events going forward. Since Product Analytics automatically creates a randomized unique identifier, it's not necessary for you to send your own identifier unless you are certain it is a unique, permanent identifier for the user. If you want to add properties to a user using [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties), you can do so without providing a unique identifier. Calling `CSQ.addUserProperties({property: 'value'})` will add this property to the anonymous user's Product Analytics profile automatically. ## When and Where to Call `identify` and `addUserProperties` The [`CSQ.identify()`](../command-reference/#csqidentify) and [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) APIs can be called anytime and anywhere the data is available about that user. The typical place for an identify call that includes a unique identifier is on any post-login or post-signup page. You should making an identify call on each page load as opposed to only the first page load. When setting properties, it's OK to call the [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) API on any page, though you should that you add user properties on identified users. This will greatly improve your experience when analyzing your user base. You can place a [`CSQ.identify()`](../command-reference/#csqidentify) call within the Product Analytics installation snippet or outside of it. If you're adding a `CSQ.identify()` call within the snippet, it should be placed after `CSQ.start()` within that snippet. ### Identity Examples #### Anonymous to New Identity Let's say we have an internal user ID from our own database, and we want to identify a user based on that ID. We can do that like this: ```swift // userID = "12345" CSQ.identify(userID) ``` Now, their profile in the **Users** view will look like this:  #### Anonymous to Existing Identity In the last example, we identified a user with the unique user ID of 12345. Let's say that this person visits your site from their mobile device for the first time. Product Analytics will generate a new, random, unique userID, in this case it's 5404281197559477. In Product Analytics' users view, this visitor looks like this:  When this person logs in, and you recognize that their internal user ID is 12345, you can call identify like this: ```swift //userID = "12345" CSQ.identify(userID) ``` The previous user's profile with the random user ID of 1565941335949135 is merged, along with its previous sessions and events into the Product Analytics profile of the identified user with the identity of 12345. ### addUserProperties Examples #### Common User Properties User properties can be used to capture additional data about a user, such as first and last name, email address, time zone, and account plan. The following example covers how to add an account plan user property using the [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) API, and this can be modified to capture any of the previously mentioned user properties. #### Account Plan Many products include some sort of tiered pricing plan. Using the [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) API to attach this information to your visitors' profiles can help you compare and contrast usage between different segments. When someone visits Product Analytics, we pull their account tier from our database and inject that into an identify call like this: ```swift CSQ.addUserProperties(["plan": "Startup"]) ``` This lets us build powerful charts, like this bar chart showing sign-ups split by plan type. ### Industry Recommendations Call `CSQ.addUserProperties()` in the part of your website flow where the data you want to capture is being presented. Below are some examples of places to call the API, based on industry. | Industry | API Use Case | API Call Placement | | - | - | - | | e-Commerce | Improve personalization and recommendation algorithms. | On user login or significant actions (such as a purchase). Attach properties like login info, purchase amount, and spender type. | | Social media platform | Enhance user engagement and content personalization. | When a user updates their profile, adds interests, or engages in specific types of content. Attach custom properties like user interests or content preferences. | | Subscription-based service | Understand user demographics and preferences to optimize its offerings. | When a user signs up, completes a survey, or changes subscription preferences. Attach custom properties such as geographical location, email, or subscription plan details. | ## What about the identity API? Once you have the identify API set up, you can use [CSQ.metadata.identity](../command-reference/#csqmetadataidentity) to find a specific user's identity. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track identity","description":"Enhance user tracking with identify and addUserProperties APIs. Link anonymous and identified user data across sessions and devices for comprehensive analytics","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/track-identity/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track push notifications - iOS description: Learn how to track mobile notification interactions automatically with Contentsquare lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/track-push-notifications/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/track-push-notifications/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. After completing the setup process you will be able to: * Automatically track interactions on your mobile notifications * Define and analyze notification interaction events in Contentsquare ## Initializing Notification Autocapture Notification autocapture can be initialized with `enablePushNotificationAutocapture: true` in `CSQ.start()`. * Product Analytics ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .enablePushNotificationAutocapture: true ] ) ``` * CSQ Experience Platform (Early Access) ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ .enablePushNotificationAutocapture: true ] ) ``` Capture the title or body text of the notification where an interaction was performed using `enablePushNotificationTitleAutocapture` and `enablePushNotificationBodyAutocapture`. * Product Analytics ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ .enablePushNotificationAutocapture: true, .enablePushNotificationTitleAutocapture: true, .enablePushNotificationBodyAutocapture: true ] ) ``` * CSQ Experience Platform (Early Access) ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ .enablePushNotificationAutocapture: true, .enablePushNotificationTitleAutocapture: true, .enablePushNotificationBodyAutocapture: true ] ) ``` Once registered, Contentsquare will begin collecting interaction events on notifications. ## What's Next? With notification data flowing, you'll want to jump into the Product Analytics app and start defining notification interaction events. These events will show up as a special "Notification Interaction" event type in Product Analytics and have several properties available to create definitions: * **Notification Title**: The title text of the notification. Capture can be enabled/disabled via a config option as described above. * **Notification Body**: The body text of the notification. Capture can be enabled/disabled via a config option as described above. * **Notification Action**: The text of the notification action that was interacted with, if any. * **Notification Source**: What caused the notification to fire. This could be a push service, a geofence, or unknown. * **Notification Handling Component**: The name of the component in code that handled the notification interaction. * **Notification Category**: This is the notification channel that the notification was delivered to. This typically denotes the type of notification that with which the interaction occurred. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track push notifications","description":"Learn how to track mobile notification interactions automatically with Contentsquare","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/track-push-notifications/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Core SDK + Contentsquare SDK to CSQ SDK - iOS description: Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK lastUpdated: 30 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-from-heap-and-cs-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-from-heap-and-cs-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-ios/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide provides a step-by-step upgrade process from your current installation of Contentsquare and Heap Mobile to the latest version of the CSQ SDK.  **Heap Core SDK** \+  **Contentsquare SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. ## Dependency upgrades If you are loading both Heap and Contentsquare SDK, replace these dependencies by the CSQ SDK. CocoaPods support is ending CocoaPods trunk becomes read-only on December 2, 2026. After this date, Contentsquare will no longer publish new SDK versions via CocoaPods. [Migrate to Swift Package Manager (SPM)](https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/) to continue receiving updates. 1. In your Xcode project > `Package Dependencies`, update your packages: ```diff https://github.com/heap/heap-swift-core-sdk.git https://github.com/ContentSquare/CS_iOS_SDK.git https://github.com/heap/heap-ios-cs-integration-sdk.git https://github.com/heap/heap-ios-autocapture-sdk.git https://github.com/heap/heap-notification-autocapture-sdk.git https://github.com/ContentSquare/apple-sdk.git ``` 2. Set the Dependency Rule to `Exact Version` `1.12.2`. 3. To ensure the library can start properly, add `-ObjC` as a linker flag under `Build Settings` > `Linking - General` > `Other Linker Flags`. ## Library imports Replace the Heap and Contentsquare dependency imports with the CSQ SDK import. ```diff import HeapSwiftCore import HeapContentsquareIntegrationSDK import HeapIOSAutocapture import HeapNotificationAutocapture import ContentsquareModule import ContentsquareSDK ``` ## SDK start Follow these steps to start the CSQ SDK with your current configuration. 1. Delete `Heap.shared.startRecording()` and migrate configuration to the unified `CSQ.start()` method. * Product Analytics ```swift Heap.shared.startRecording("YOUR_ENVIRONMENT_ID", with: [ // ...options ]) CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ...options ] ) ``` * CSQ Experience Platform (Early Access) ```swift Heap.shared.startRecording("YOUR_ENVIRONMENT_ID", with: [ // ...options ]) CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ // ...options ] ) ``` Deprecated configuration options The following Heap SDK configuration options are not ported to the CSQ SDK: * `startSessionImmediately` * `disableInteractionTextCapture` * `disableInteractionAccessibilityLabelCapture` * `enableInteractionReferencingPropertyCapture` * `interactionHierarchyCaptureLimit` * `captureVendorID` * `captureAdvertiserID` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `messageBatchByteLimit` * `resumePreviousSession` See [supported options](../command-reference/#sdk-configuration-options) for more information. 2. Recommended for UIKit Enable Autocapture with `.enableNativeAutocapture: true` and remove the call to `Heap.iOSAutocaptureSource.register()` * Product Analytics ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ...options .enableNativeAutocapture: true ] ) Heap.iOSAutocaptureSource.register(isDefault: true) ``` * CSQ Experience Platform (Early Access) ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ // ...options .enableNativeAutocapture: true ] ) Heap.iOSAutocaptureSource.register(isDefault: true) ``` 3. Remove `HeapContentsquareIntegration.bind()`. Sending Heap pageviews to Contentsquare **AppDelegate.swift** ```swift HeapContentsquareIntegration.bind( sendHeapPageviewsToContentsquare: false, sendContentsquareScreenviewsToHeap: true ) ``` Note Make sure you don't have calls to `CSQ.trackScreenview()` if you have autocapture enabled. Sending Contentsquare screenviews to Heap * Product Analytics **AppDelegate.swift** ```swift HeapContentsquareIntegration.bind( sendHeapPageviewsToContentsquare: true, sendContentsquareScreenviewsToHeap: false ) CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ...options .disablePageviewAutocapture: true ] ) ``` * CSQ Experience Platform (Early Access) **AppDelegate.swift** ```swift HeapContentsquareIntegration.bind( sendHeapPageviewsToContentsquare: true, sendContentsquareScreenviewsToHeap: false ) CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ // ...options .disablePageviewAutocapture: true ] ) ``` 4. (Optional) If you were relying on the Contentsquare SDK autostart, remove the `CSDisableAutostart` property and calls to `Contentsquare.start()`. **Info.plist** ```xml <key>CSDisableAutostart</key> <true/> ``` **AppDelegate.swift** ```swift Contentsquare.start() ``` ## Get user consent Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. * Product Analytics ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` * CSQ Experience Platform (Early Access) ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more. Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code. ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. ```diff Contentsquare.start() Heap.shared.startRecording("YOUR_ENVIRONMENT_ID") CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID") ``` The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. For more information on SDK methods, see the [SDK API reference](../command-reference/). ### Product Analytics (Heap Core SDK) ### GDPR / Identification | Heap Core SDK | CSQ SDK | | - | - | | `Heap.shared.identify(string)` | `CSQ.identify(String)` | | `Heap.shared.resetIdentity()` | `CSQ.resetIdentity()` | | `Heap.shared.userId` | `CSQ.metadata.userID` | | `Heap.shared.sessionId` | `CSQ.metadata.sessionID` | | `Heap.shared.getEnvironmentId` | `CSQ.metadata.environmentID` | | `Heap.shared.identity` | `CSQ.metadata.identity` | ### Logging | Heap Core SDK | CSQ SDK | | - | - | | `Heap.shared.logLevel { get set }` | `CSQ.debug.logLevel { get set }` | | `Heap.shared.logChannel { get set }` | `CSQ.debug.logChannel(LogChannel)` | | `Heap.shared.printLog()` | `LogChannel.printLog()` | ### Property tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.shared.addUserProperties(properties: [String: HeapPropertyValue])` | `CSQ.addUserProperties([Property])` | | `Heap.shared.addEventProperties(properties: [String: HeapPropertyValue])` | `CSQ.addEventProperties([Property])` | | `Heap.shared.removeEventProperty(name: String)` | `CSQ.removeEventProperty(name: String)` | | `Heap.shared.clearEventProperties()` | `CSQ.clearEventProperties()` | ### Event tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.shared.track()` | `CSQ.trackEvent(name: String, properties: [String, PropertyValue]?)` | ### Personal Data Handling and Masking | Heap Core SDK | CSQ SDK | | - | - | | `View.heapIgnoreInteractions` | `CSQ.ignoreInteractions(View)` / `CSQ.ignoreInteractions(UIView)` / `UIView.csqIgnoreInteractions (UIKit)` / `View.csqIgnoreInteractions(shouldIgnore:Boolean)(SwiftUI)` | | `View.heapRedactText` / `View.heapRedactAccessibilityLabel` | `CSQ.mask(UIView)` / `UIView.csqMaskContents (UIKit)`/ `View.csqMaskContents(enable: boolean) (SwiftUI)` | | `view.setTag(R.id.heapRedactText, false)` | `CSQ.unmask(UIView)` / `UIView.csqMaskContents (UIKit)` / `View.csqMaskContents(enable: Boolean) (SwiftUI)` | | Initialization options `disableInteractionTextCapture` and `disableInteractionAccessibilityLabelCapture` | `CSQ.maskTexts(mask: Boolean)` | | `UIView.heapIgnoreInteractionsDefault` | `csqIgnoreInteractionsDefault` | | `UIView.heapIgnoreInnerHierarchy` | `csqIgnoreInnerHierarchy` | | `UIView.heapIgnoreInnerHierarchyDefault` | `csqIgnoreInnerHierarchyDefault` | ### SDK initialization and manipulation | Heap Core SDK | CSQ SDK | | - | - | | Heap SDK initialization options | `CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID", options: AnalyticsOptions(...))` See [supported options](../command-reference/#sdk-configuration-options) for more information. | | `Heap.shared.startRecording(context, id)` | `CSQ.start()` | | `Heap.shared.stopRecording(deleteUser = true)` | `CSQ.stop()` | | `Heap.shared.stopRecording(deleteUser = false)` | `CSQ.pauseTracking()` | ### Experience Analytics (Contentsquare SDK) ### GDPR / Identification | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.optIn()` | `CSQ.optIn()` | | `Contentsquare.optOut()` | `CSQ.optOut()` | | `Contentsquare.sendUserIdentifier()` | `CSQ.sendUserIdentifier()` | | `Contentsquare.userID` | `CSQ.metadata.userID` | | `Contentsquare.projectID` | `CSQ.metadata.projectID` | | `Contentsquare.sessionNumber` | `CSQ.metadata.sessionID` | Deprecated **Contentsquare.forgetMe()** You can use `CSQ.optOut()` instead to forget user id and stop tracking. If needed call `CSQ.optIn()` when you want to resume tracking. ### Logging | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.logLevel { get set }` | `CSQ.debug.logLevel { get set }` | ### Property tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.send(dynamicVar: DynamicVar(key: String, value: UInt32))` `Contentsquare.send(dynamicVar: DynamicVar(key: String, value: String))` | `CSQ.addDynamicVar(DynamicVar)` | ### View tracking | Contentsquare SDK | CSQ SDK | | - | - | | `UIScrollView.excludeFromExposureMetric()` | `UIScrollView.excludeFromExposureMetrics()` | ### CSInApp | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.handle(url: URL)` | `CSQ.handle(url: URL)` | | `Contentsquare.csInApp` | `CSQ.csInApp` | ### Interoperability | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.onSessionReplayLinkChange(callback)` | `CSQ.metadata.onChange { metadata in }` | | `Contentsquare.register(webView: WKWebView)` | `CSQ.registerWebView(WKWebView)` | | `Contentsquare.unregister(webView: WKWebView)` | `CSQ.unregisterWebView(WKWebView)` | ### Event tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.send(transaction: CustomerTransaction)` | `CSQ.trackTransaction(Transaction)` | | `Contentsquare.send(screenViewWithName name: String)` / `Contentsquare.send(screenViewWithName name: String, cvars: [CustomVar] = [])` | `CSQ.trackScreenview(String)/CSQ.trackScreenview(String, cvars: [CustomVar])` | ### Error tracking | Contentsquare SDK | CSQ SDK | | - | - | | `ErrorAnalysis.setUrlMaskingPatterns([String])` | `CSQ.setURLMaskingPatterns([String])` | | `ErrorAnalysis.onCrashReporterStart()` | `CSQ.onCrashReporterStart()` | | `HTTPMetric` | `NetworkMetric` | | `HTTPMetric.stop()` | `CSQ.trackNetworkMetric(NetworkMetric)` | | `ErrorAnalysis.getInstance().newNetworkMetric(url, ErrorAnalysis.HttpMethod.GET)` | `CSQ.trackNetworkMetric(NetworkMetric(id, httpMethod, optionalId))` | ### Personal Data Handling and Masking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.setDefaultMasking(boolean masked)` | `CSQ.setDefaultMasking(boolean masked)` | | `Contentsquare.mask(viewsOfType: UIView.Type)` | `CSQ.mask(viewsOfType: UIView.Type)` | | `Contentsquare.mask(view: UIView)` | `CSQ.mask(UIView)`/ `UIView.csqMaskContents (UIKit)` | | `View.csMasking(Bool)` | `View.csqMaskContents(enable: Boolean) (SwiftUI)` | | `Contentsquare.unmask(UIView)` | `CSQ.unmask(UIView)` | | `Contentsquare.unmask(viewsOfType: UIView.Type)` | `CSQ.unmask(viewsOfType: UIView.Type)` | | `Contentsquare.maskTexts(mask: Boolean)` | `CSQ.maskTexts(mask: Boolean)` | | `Contentsquare.maskImages(mask: Boolean)` | `CSQ.maskImages(mask: Boolean)` | | `Contentsquare.maskTextInputs(mask: Boolean)` | `CSQ.maskTextInputs(mask: Boolean)` | ### SDK initialization and manipulation | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.start()` | `CSQ.start()` | | `Contentsquare.stopTracking()` | `CSQ.pauseTracking()` | | `Contentsquare.resumeTracking()` | `CSQ.resumeTracking()` | ## Number of sessions Session timeout definition changed: * **Before**: 30 minutes after app goes to background * **Now**: 30 minutes after last event This may affect session counts and aligns with web and market standards. ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that your build files no longer reference `https://github.com/heap/heap-swift-core-sdk.git`, `https://github.com/ContentSquare/CS_iOS_SDK.git`. Your `import Heap` and `import Contentsquare` declarations have been updated to `import ContentsquareSDK`. You no longer have references to `Heap.` (except if you are using webviews), `HeapContentsquareIntegration.`, or `Contentsquare.` methods in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK + Contentsquare SDK to CSQ SDK","description":"Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-from-heap-and-cs-sdk/","inLanguage":"en","dateModified":"2026-06-30T16:49:52+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Classic SDK to CSQ SDK - iOS description: Steps to migrate from a Heap Classic install to the CSQ SDK lastUpdated: 30 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-from-heap-classic-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-from-heap-classic-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-ios/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide provides a step-by-step upgrade process from your current installation of Heap Mobile to the latest version of the CSQ SDK.  **Heap Classic SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. Key differences from Heap Classic SDK * **Custom tracking first**: CSQ SDK starts with custom tracking APIs; you should use autocapture (vs Classic's autocapture-by-default approach) * **Improved event accuracy**: No touch events during scrolls; refined pageview logic for `UINavigationController` and multi-window iPad apps; no gesture events * **Swift class names**: Uses Swift names by default instead of Objective-C mangled names (configurable via `useObjectiveCClassNames`) * **Shorter hierarchies**: Captures up to view controller/window instead of 30-level depth * **Live View only**: Visual Labeler not supported; hierarchy data now visible in Live View * **Opt-out by default**: Must call `CSQ.optIn()` to start tracking * **Separate storage**: Expect temporary spike in new users/installs during migration * **Removed properties**: No longer captures view controller `accessibilityIdentifier` and `accessibilityLabel` on pageviews ## Dependency upgrades Replace the Heap Classic SDK dependencies by the CSQ SDK dependency. CocoaPods support is ending CocoaPods trunk becomes read-only on December 2, 2026. After this date, Contentsquare will no longer publish new SDK versions via CocoaPods. [Migrate to Swift Package Manager (SPM)](https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/) to continue receiving updates. 1. In your Xcode project > `Package Dependencies`, update the repository location: ```diff https://github.com/heap/heap-ios-sdk.git https://github.com/ContentSquare/apple-sdk.git ``` 2. Set the Dependency Rule to `Exact Version` `1.12.2`. 3. To ensure the library can start properly, add `-ObjC` as a linker flag under `Build Settings` > `Linking - General` > `Other Linker Flags`. ## Library imports Replace the Heap Classic SDK import with the CSQ SDK import. ```diff import Heap import HeapIOSAutocapture import HeapNotificationAutocapture import ContentsquareSDK ``` ## SDK start Follow these steps to start the CSQ SDK with your current configuration. 1. Delete `Heap.init()` and migrate configuration to the unified `CSQ.start()` method. * Product Analytics ```swift Heap.init("YOUR_ENVIRONMENT_ID", with: [ // ...options ]) CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ...options ] ) ``` * CSQ Experience Platform (Early Access) ```swift Heap.init("YOUR_ENVIRONMENT_ID", with: [ // ...options ]) CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ // ...options ] ) ``` Deprecated configuration options The following Heap SDK configuration options are not ported to the CSQ SDK: * `startSessionImmediately` * `disableInteractionTextCapture` * `disableInteractionAccessibilityLabelCapture` * `enableInteractionReferencingPropertyCapture` * `interactionHierarchyCaptureLimit` * `captureVendorID` * `captureAdvertiserID` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `messageBatchByteLimit` * `resumePreviousSession` See [supported options](../command-reference/#sdk-configuration-options) for more information. 2. Recommended for UIKit Enable Autocapture with `.enableNativeAutocapture: true` and remove the call to `Heap.iOSAutocaptureSource.register()` * Product Analytics ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ...options .enableNativeAutocapture: true ] ) Heap.iOSAutocaptureSource.register(isDefault: true) ``` * CSQ Experience Platform (Early Access) ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ // ...options .enableNativeAutocapture: true ] ) Heap.iOSAutocaptureSource.register(isDefault: true) ``` 3. (Optional) To start HeapNotification, add `.enablePushNotificationAutocapture: true` and remove the call to `Heap.NotificationAutocaptureSource.register()`. * Product Analytics ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ...options .enablePushNotificationAutocapture: true ] ) Heap.NotificationAutocaptureSource.register() ``` * CSQ Experience Platform (Early Access) ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ // ...options .enablePushNotificationAutocapture: true ] ) Heap.NotificationAutocaptureSource.register() ``` 4. (Optional) Configure HeapNotification using `.enablePushNotificationTitleAutocapture` and `.enablePushNotificationBodyAutocapture` and remove the call to `Heap.NotificationAutocaptureSource.register()`. * Product Analytics ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ...options .enablePushNotificationAutocapture: true, .enablePushNotificationTitleAutocapture: true, .enablePushNotificationBodyAutocapture: true ] ) Heap.NotificationAutocaptureSource.register(captureTitle: true|false, captureBody: true|false) ``` * CSQ Experience Platform (Early Access) ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ // ...options .enablePushNotificationAutocapture: true, .enablePushNotificationTitleAutocapture: true, .enablePushNotificationBodyAutocapture: true ] ) Heap.NotificationAutocaptureSource.register(captureTitle: true|false, captureBody: true|false) ``` ## Get user consent Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. * Product Analytics ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` * CSQ Experience Platform (Early Access) ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more. Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code. ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. ```diff Heap.init("YOUR_ENVIRONMENT_ID") CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID") ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### GDPR / Identification | Heap Classic SDK | CSQ SDK | | - | - | | `Heap.shared.identify(string)` | `CSQ.identify(String)` | | `Heap.shared.resetIdentity()` | `CSQ.resetIdentity()` | | `Heap.shared.userId` | `CSQ.metadata.userID` | | `Heap.shared.sessionId` | `CSQ.metadata.sessionID` | | `Heap.shared.getEnvironmentId` | `CSQ.metadata.environmentID` | | `Heap.shared.identity` | `CSQ.metadata.identity` | ### Logging | Heap Classic SDK | CSQ SDK | | - | - | | `Heap.shared.logLevel { get set }` | `CSQ.debug.logLevel { get set }` | | `Heap.shared.logChannel { get set }` | `CSQ.debug.logChannel(LogChannel)` | | `Heap.shared.printLog()` | `LogChannel.printLog()` | ### Property tracking | Heap Classic SDK | CSQ SDK | | - | - | | `Heap.shared.addUserProperties(properties: [String: HeapPropertyValue])` | `CSQ.addUserProperties([Property])` | | `Heap.shared.addEventProperties(properties: [String: HeapPropertyValue])` | `CSQ.addEventProperties([Property])` | | `Heap.shared.removeEventProperty(name: String)` | `CSQ.removeEventProperty(name: String)` | | `Heap.shared.clearEventProperties()` | `CSQ.clearEventProperties()` | ### Event tracking | Heap Classic SDK | CSQ SDK | | - | - | | `Heap.shared.track()` | `CSQ.trackEvent(name: String, properties: [String, PropertyValue]?)` | ### Personal Data Handling and Masking | Heap Classic SDK | CSQ SDK | | - | - | | `View.heapIgnoreInteractions` | `CSQ.ignoreInteractions(View)` / `CSQ.ignoreInteractions(UIView)` / `UIView.csqIgnoreInteractions (UIKit)` / `View.csqIgnoreInteractions(shouldIgnore:Boolean)(SwiftUI)` | | `View.heapRedactText` / `View.heapRedactAccessibilityLabel` | `CSQ.mask(UIView)` / `UIView.csqMaskContents (UIKit)`/ `View.csqMaskContents(enable: boolean) (SwiftUI)` | | `view.setTag(R.id.heapRedactText, false)` | `CSQ.unmask(UIView)` / `UIView.csqMaskContents (UIKit)` / `View.csqMaskContents(enable: Boolean) (SwiftUI)` | | Initialization options `disableInteractionTextCapture` and `disableInteractionAccessibilityLabelCapture` | `CSQ.maskTexts(mask: Boolean)` | | `UIView.heapIgnoreInteractionsDefault` | `csqIgnoreInteractionsDefault` | | `UIView.heapIgnoreInnerHierarchy` | `csqIgnoreInnerHierarchy` | | `UIView.heapIgnoreInnerHierarchyDefault` | `csqIgnoreInnerHierarchyDefault` | ### SDK initialization and manipulation | Heap Classic SDK | CSQ SDK | | - | - | | Heap SDK initialization options | `CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID", options: AnalyticsOptions(...))` See [supported options](../command-reference/#sdk-configuration-options) for more information. | | `Heap.shared.init(context, id)` | `CSQ.start()` | | `Heap.shared.stopRecording(deleteUser = true)` | `CSQ.stop()` | | `Heap.shared.stopRecording(deleteUser = false)` | `CSQ.pauseTracking()` | ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that your build files no longer reference `https://github.com/heap/heap-ios-sdk.git`. Your `import Heap` declarations have been updated to `import ContentsquareSDK`. You no longer have references to `Heap.` methods in your codebase. All calls to the CSQ SDK use the `CSQ.` namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Classic SDK to CSQ SDK","description":"Steps to migrate from a Heap Classic install to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-from-heap-classic-sdk/","inLanguage":"en","dateModified":"2026-06-30T16:49:52+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Core SDK to CSQ SDK - iOS description: Steps to migrate from a Heap Core install to the CSQ SDK lastUpdated: 30 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-from-heap-core-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-from-heap-core-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-ios/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This guide provides a step-by-step upgrade process from your current installation of Heap Mobile to the latest version of the CSQ SDK.  **Heap Core SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. ## Dependency upgrades Replace the Heap Swift Core SDK by the CSQ SDK. CocoaPods support is ending CocoaPods trunk becomes read-only on December 2, 2026. After this date, Contentsquare will no longer publish new SDK versions via CocoaPods. [Migrate to Swift Package Manager (SPM)](https://docs.contentsquare.com/en/csq-sdk-ios/migrate-from-cocoapods/) to continue receiving updates. 1. In your Xcode project > `Package Dependencies`, update your packages: ```diff https://github.com/heap/heap-swift-core-sdk.git https://github.com/heap/heap-ios-autocapture-sdk.git https://github.com/heap/heap-notification-autocapture-sdk.git https://github.com/ContentSquare/apple-sdk.git ``` 2. Set the Dependency Rule to `Exact Version` `1.12.2`. 3. To ensure the library can start properly, add `-ObjC` as a linker flag under `Build Settings` > `Linking - General` > `Other Linker Flags`. ## Library imports Replace Heap Core and Autocapture SDK imports with the CSQ SDK import. ```diff import HeapSwiftCore import HeapIOSAutocapture import HeapNotificationAutocapture import ContentsquareSDK ``` ## SDK start Follow these steps to start the CSQ SDK with your current configuration. 1. Delete `Heap.shared.startRecording()` and migrate configuration to the unified `CSQ.start()` method. * Product Analytics ```swift Heap.shared.startRecording("YOUR_ENVIRONMENT_ID", with: [ // ...options ]) CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ...options ] ) ``` * CSQ Experience Platform (Early Access) ```swift Heap.shared.startRecording("YOUR_ENVIRONMENT_ID", with: [ // ...options ]) CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ // ...options ] ) ``` Deprecated configuration options The following Heap SDK configuration options are not ported to the CSQ SDK: * `startSessionImmediately` * `disableInteractionTextCapture` * `disableInteractionAccessibilityLabelCapture` * `enableInteractionReferencingPropertyCapture` * `interactionHierarchyCaptureLimit` * `captureVendorID` * `captureAdvertiserID` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `messageBatchByteLimit` * `resumePreviousSession` See [supported options](../command-reference/#sdk-configuration-options) for more information. 2. Recommended for UIKit Enable Autocapture with `.enableNativeAutocapture: true` and remove the call to `Heap.iOSAutocaptureSource.register()` * Product Analytics ```swift CSQ.start( environmentID: "YOUR_ENVIRONMENT_ID", options: [ // ...options .enableNativeAutocapture: true ] ) Heap.iOSAutocaptureSource.register(isDefault: true) ``` * CSQ Experience Platform (Early Access) ```swift CSQ.start( dataSourceID: "YOUR_DATASOURCE_ID", options: [ // ...options .enableNativeAutocapture: true ] ) Heap.iOSAutocaptureSource.register(isDefault: true) ``` ## Get user consent Implement the `optIn()` API to forward user consent to the SDK, generate a user ID, and initiate tracking. * Product Analytics ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` * CSQ Experience Platform (Early Access) ```swift import UIKit import ContentsquareSDK // In viewDidLoad() optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside) @objc func optInButtonTapped(_ sender: UIButton) { CSQ.start(dataSourceID: "YOUR_DATASOURCE_ID") CSQ.optIn() // Continue with post-consent navigation or UI update } ``` Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more. Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code. ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. ```diff Heap.shared.startRecording("YOUR_ENVIRONMENT_ID") CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID") ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### GDPR / Identification | Heap Core SDK | CSQ SDK | | - | - | | `Heap.shared.identify(string)` | `CSQ.identify(String)` | | `Heap.shared.resetIdentity()` | `CSQ.resetIdentity()` | | `Heap.shared.userId` | `CSQ.metadata.userID` | | `Heap.shared.sessionId` | `CSQ.metadata.sessionID` | | `Heap.shared.getEnvironmentId` | `CSQ.metadata.environmentID` | | `Heap.shared.identity` | `CSQ.metadata.identity` | ### Logging | Heap Core SDK | CSQ SDK | | - | - | | `Heap.shared.logLevel { get set }` | `CSQ.debug.logLevel { get set }` | | `Heap.shared.logChannel { get set }` | `CSQ.debug.logChannel(LogChannel)` | | `Heap.shared.printLog()` | `LogChannel.printLog()` | ### Property tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.shared.addUserProperties(properties: [String: HeapPropertyValue])` | `CSQ.addUserProperties([Property])` | | `Heap.shared.addEventProperties(properties: [String: HeapPropertyValue])` | `CSQ.addEventProperties([Property])` | | `Heap.shared.removeEventProperty(name: String)` | `CSQ.removeEventProperty(name: String)` | | `Heap.shared.clearEventProperties()` | `CSQ.clearEventProperties()` | ### Event tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.shared.track()` | `CSQ.trackEvent(name: String, properties: [String, PropertyValue]?)` | ### Personal Data Handling and Masking | Heap Core SDK | CSQ SDK | | - | - | | `View.heapIgnoreInteractions` | `CSQ.ignoreInteractions(View)` / `CSQ.ignoreInteractions(UIView)` / `UIView.csqIgnoreInteractions (UIKit)` / `View.csqIgnoreInteractions(shouldIgnore:Boolean)(SwiftUI)` | | `View.heapRedactText` / `View.heapRedactAccessibilityLabel` | `CSQ.mask(UIView)` / `UIView.csqMaskContents (UIKit)`/ `View.csqMaskContents(enable: boolean) (SwiftUI)` | | `view.setTag(R.id.heapRedactText, false)` | `CSQ.unmask(UIView)` / `UIView.csqMaskContents (UIKit)` / `View.csqMaskContents(enable: Boolean) (SwiftUI)` | | Initialization options `disableInteractionTextCapture` and `disableInteractionAccessibilityLabelCapture` | `CSQ.maskTexts(mask: Boolean)` | | `UIView.heapIgnoreInteractionsDefault` | `csqIgnoreInteractionsDefault` | | `UIView.heapIgnoreInnerHierarchy` | `csqIgnoreInnerHierarchy` | | `UIView.heapIgnoreInnerHierarchyDefault` | `csqIgnoreInnerHierarchyDefault` | ### SDK initialization and manipulation | Heap Core SDK | CSQ SDK | | - | - | | Heap SDK initialization options | `CSQ.start(environmentID: "YOUR_ENVIRONMENT_ID", options: AnalyticsOptions(...))` See [supported options](../command-reference/#sdk-configuration-options) for more information. | | `Heap.shared.startRecording(context, id)` | `CSQ.start()` | | `Heap.shared.stopRecording(deleteUser = true)` | `CSQ.stop()` | | `Heap.shared.stopRecording(deleteUser = false)` | `CSQ.pauseTracking()` | ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that your build files no longer reference `https://github.com/heap/heap-swift-core-sdk.git`. Your `import HeapSwiftCore` declarations have been updated to `import ContentsquareSDK`. You no longer have references to `Heap.` methods in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK to CSQ SDK","description":"Steps to migrate from a Heap Core install to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-from-heap-core-sdk/","inLanguage":"en","dateModified":"2026-06-30T16:49:52+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Upgrade your SDK - iOS description: Understand the benefits of upgrading to the CSQ SDK lastUpdated: 12 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-your-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-your-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Faster implementation using agent skills Use [Agent skills](https://docs.contentsquare.com/csq-sdk-ios/product-analytics/using-agent-skills/) to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. This section guides you through the upgrade from your current SDK implementation to our latest CSQ SDK. Upgrading has no impact on your current data collection (except for "Heap Classic SDK") and does not alter the data observed on the platform. It mainly consists of searching and replacing APIs according to the mappings provided in the upgrade guides. Get started by selecting the upgrade guide that corresponds to your current implementation: * **[Heap Core SDK](../upgrade-from-heap-core-sdk/)** - Upgrade from Heap Core SDK * **[Heap Classic SDK](../upgrade-from-heap-classic-sdk/)** - Upgrade from Heap Classic SDK * **[Heap SDK + Contentsquare SDK](../upgrade-from-heap-and-cs-sdk/)** - Upgrade from combined Heap and Contentsquare SDKs ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Upgrade your SDK","description":"Understand the benefits of upgrading to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/upgrade-your-sdk/","inLanguage":"en","dateModified":"2026-05-12T12:05:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Agent skills for iOS - iOS description: Use AI coding assistants to integrate, upgrade, and configure the Contentsquare iOS SDK with downloadable Agent skills lastUpdated: 16 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/using-agent-skills/ md: https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/using-agent-skills/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use the Contentsquare wizard or skills to set up, update, and configure iOS with your AI coding assistant. Disclaimer This skill guides your AI coding agent through the SDK installation and implementation. The agent you use (Cursor, Claude Code, Copilot) is your own tool and operates under your settings and permissions. Contentsquare is not responsible for how your agent interprets or applies the instructions contained in these files. ## Contentsquare wizard Run the wizard in your project directory. It configures your AI coding assistant, installs the matching Contentsquare integration, and verifies the installation. ```shell npx @contentsquare/wizard install ``` Supports GitHub Copilot, Cursor, and Claude Code. Requires Node.js ≥ 18 and an AI coding agent with MCP support. ## Manual setup Use this path when you prefer to configure your AI coding assistant yourself. ### 1. Add the Contentsquare skill Choose how to install the Contentsquare skill. * Copilot CLI Add the Contentsquare marketplace, then install the plugin for iOS: ```shell copilot plugin marketplace add ContentSquare/agents copilot plugin install contentsquare-ios@contentsquare ``` * Claude Code Add the Contentsquare marketplace, then install the plugin for iOS: ```shell /plugin marketplace add ContentSquare/agents /plugin install contentsquare-ios@contentsquare ``` * Cursor Install **contentsquare** from the [Cursor marketplace ↗](https://cursor.com/marketplace), or add the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents) directly. Cursor reads the `.cursor-plugin` catalog in the repository. * Other agents Install the Contentsquare skill pack with the open `skills.sh` ecosystem: ```shell npx skills add contentsquare/agents ``` * From source Download or clone the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents), then copy `skills/contentsquare-ios-sdk` into the location your AI coding assistant scans for skills: | AI coding assistant | Skill location | | - | - | | GitHub Copilot | `.github/skills/` or `.agents/skills/` | | Cursor | `.cursor/rules/` or the project root | | Claude Code | `.claude/skills/` or the project root | | Other compatible agents | `.agents/skills/` | ### 2. Ask your AI coding assistant After installing the skill, paste this prompt into your AI coding assistant: ```text Install Contentsquare for iOS. ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Agent skills for iOS","description":"Use AI coding assistants to integrate, upgrade, and configure the Contentsquare iOS SDK with downloadable Agent skills","url":"https://docs.contentsquare.com/en/csq-sdk-ios/product-analytics/using-agent-skills/","inLanguage":"en","dateModified":"2026-07-16T17:50:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Adobe Analytics - React Native description: Leverage our native integration to use Adobe Analytics segments in Contentsquare lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/adobe-analytics/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/adobe-analytics/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Analyze your data from anywhere in the customer journey using your Adobe Analytics segments. Contentsquare allows you to use your Adobe Analytics segments in every Contentsquare feature (Journey Analysis, Page Comparator, Session Replay). Warning Sessions without at least one screenview will be discarded. You should implement your screen tracking plan first, to have your Adobe Analytics integration work. See [Track screens](../track-screens/). ## Prerequisites 1. Follow the instructions from [Adobe Analytics for mobile apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271665881745) 2. Add the [React Native AEP ↗](https://github.com/adobe/aepsdk-react-native) to your project ## Code implementation Note **Adobe SDK code requirements** On the native Android and iOS parts of your React Native project, make sure you have registered at least `Edge Network` and `Edge Identity` extension before starting `MobileCore`. Check [React Native AEP repository ↗](https://github.com/adobe/aepsdk-react-native) for the code to put in the Android and iOS native parts. **Why 30 minutes before sending a new csMatchingKey** * 30 minutes is Contentsquare default session duration. * Setting a value **higher** than 30 minutes would cause overlapping on our sessions, and would impact negatively the data import from Adobe. * Setting a value **lower** than 30 minutes would make you to send more data to Adobe. This could cause the variable to reach Adobe's threshold, causing Adobe to filter values, and potentially impact your billing. See [Low-traffic value in Adobe Analytics ↗](https://experienceleague.adobe.com/docs/analytics/technotes/low-traffic.html) Add the following code snippet in your application code. **adobe-analytics.js** ```javascript import { Edge, ExperienceEvent } from "@adobe/react-native-aepedge"; import { CSQ } from "@contentsquare/react-native-bridge"; // TODO: Use local storage you prefer here import AsyncStorage from "@react-native-async-storage/async-storage"; export async function sendCSMatchingKeyIfNeeded() { const csMatchingKeyRecord = await AsyncStorage.getItem("csMatchingKey_creation_ts"); if (!csMatchingKeyRecord) { await submitNewCsMatchingKey(); return; } const { timestamp } = JSON.parse(csMatchingKeyRecord); if (Date.now() - timestamp > 30 * 60 * 1000) { // if the key is not valid anymore, submit a new one await submitNewCsMatchingKey(); } // if the key is still valid, do nothing } async function submitNewCsMatchingKey() { // Generate the matching key and store it in the local storage const csMatchingKeyValue = `${Math.random()}_${Date.now()}`; const newCsMatchingKeyRecord = { csMatchingKey: csMatchingKeyValue, timestamp: Date.now(), }; await AsyncStorage.setItem("csMatchingKey_creation_ts", JSON.stringify(newCsMatchingKeyRecord)); // Submit the matching key to Contentsquare and Adobe CSQ.addDDynamicVar("csMatchingKey", csMatchingKeyValue); const xdmData = { eventType: "csMatchingKey_state" }; const data = { csMatchingKey: csMatchingKeyValue }; const experienceEvent = new ExperienceEvent(xdmData, data); Edge.sendEvent(experienceEvent); } ``` Add a call to the `sendCSMatchingKeyIfNeeded()` from within the `index.js` file of your project root folder when app state changes to 'active'. **index.js** ```javascript import { AppState } from "react-native"; import { sendCSMatchingKeyIfNeeded } from "./adobe-analytics.js"; // Listen for app state changes to foreground AppState.addEventListener("change", (nextAppState) => { if (nextAppState === "active") { sendCSMatchingKeyIfNeeded(); } }); ``` How to use deprecated React Native AEP Analytics Extension Deprecated For [React Native AEP Analytics Extension ↗](https://github.com/adobe/react-native-acpanalytics), on the native Android and iOS parts of your React Native project, make sure you have registered at least `ACPIdentity` and `ACPAnalytics` before starting `ACPCore`. Check [React Native AEP Analytics Extension repository ↗](https://github.com/adobe/react-native-acpanalytics/tree/main/sample/ACPAnalyticsSampleApp) for the code to put in the Android and iOS native parts. Add the following code snippet in your application code. Add a call to the `updateCsMatchingKey()` from within the `index.js` file of your project root folder. **adobe-analytics.js** ```javascript import { ACPCore } from "@adobe/react-native-acpcore"; import { CSQ } from "@contentsquare/react-native-bridge"; // TODO: Use local storage you prefer here import AsyncStorage from "@react-native-community/async-storage"; export async function updateCsMatchingKey() { const csMatchingKeyRecord = await AsyncStorage.getItem("csMatchingKey_creation_ts"); if (!csMatchingKeyRecord) { await submitNewCsMatchingKey(); return; } const { timestamp } = JSON.parse(csMatchingKeyRecord); if (Date.now() - timestamp > 30 * 60 * 1000) { // if the key is not valid anymore, submit a new one await submitNewCsMatchingKey(); } // if the key is still valid, do nothing } async function submitNewCsMatchingKey() { // Generate the matching key and store it in the local storage const csMatchingKeyValue = `${Math.random()}_${Date.now()}`; const newCsMatchingKeyRecord = { csMatchingKey: csMatchingKeyValue, timestamp: Date.now(), }; await AsyncStorage.setItem("csMatchingKey_creation_ts", JSON.stringify(newCsMatchingKeyRecord)); // Submit the matching key to Contentsquare and Adobe CSQ.addDynamicVar("csMatchingKey", csMatchingKeyValue); ACPCore.trackState("csMatchingKey_state", { csMatchingKey: csMatchingKeyValue, }); } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Adobe Analytics","description":"Leverage our native integration to use Adobe Analytics segments in Contentsquare","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/adobe-analytics/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - React Native description: Requirements and limitations to develop with the Contentsquare React Native Bridge lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/compatibility/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Before implementing the SDK, make sure your app meets the following technical prerequisites to avoid integration issues and ensure optimal performance. ## Supported platforms Only React Native application on the following platforms are supported by the `CSQ React Native Bridge`: * Android * iOS If you need to use the SDK on another platform, contact our support team. Hybrid applications are not supported. By hybrid application, we mean [integrating React Native component ↗](https://reactnative.dev/docs/integration-with-existing-apps) to existing native applications. ## Compatibility matrix Each version of the CSQ bridge will be linked to specific, fixed versions of each native SDK. To make that clear, here is a compatibility table to consider when choosing your version of the bridge. Refer to the [React Native Bridge Changelog](https://docs.contentsquare.com/en/react-native/changelog/) to know what the changes are for each version. The CSQ bridge is validated against the latest React Native version. We support all React Native versions that are maintained and listed on the official [React Native documentation ↗](https://reactnative.dev/versions). | Bridge Version | iOS SDK Version | Android SDK Version | Min React Native Version | Max React Native Version | | - | - | - | - | - | | 6.4.2 | 1.11.1 | 1.11.2 | 0.71.0 | latest | | 6.4.1 | 1.11.0 | 1.11.2 | 0.71.0 | latest | | 6.4.0 | 1.11.0 | 1.11.0 | 0.71.0 | latest | | 6.3.0 | 1.10.0 | 1.10.1 | 0.71.0 | latest | | 6.2.0 | 1.6.3 | 1.5.1 | 0.71.0 | 0.85.x | | 6.1.0 | 1.6.0 | 1.5.0 | 0.71.0 | 0.84.x | | 6.0.5 | 1.5.1 | 1.4.7 | 0.71.0 | 0.82.x | | 6.0.3 | 1.5.1 | 1.4.2 | 0.71.0 | 0.82.x | | 6.0.2 | 1.5.1 | 1.4.2 | 0.71.0 | 0.82.x | | 6.0.1 | 1.5.1 | 1.4.2 | 0.71.0 | 0.81.x | ## Autocapture navigation libraries compatibility The React Native Bridge's autocapture feature is compatible with the following navigation libraries: * React Navigation 5.0 and later * React Native Navigation 7.0 and later ## Important note about React Native apps with native code Depending on if you created your app as a React Native first app, or if you gradually added some React Native code to your Native first app, you might be using some non JavaScript elements in your app, and a mix of native screens and JavaScript screens. If that is the case, it is your responsibility to track all of the screens, either by calling our native SDKs directly in the first case, or the bridge in the second. The same remark applies for other functionalities of the SDK - for example, you might need to send a Transaction Event via the native SDK or via the bridge, depending on the technology used to create your buying page. Have a look at the [Android](https://docs.contentsquare.com/en/android/) and [iOS](https://docs.contentsquare.com/en/ios/) SDKs to find out how to call them in native parts of your app. Also, we specifically cover the use of the JavaScript bridge in this documentation. You should never call the Bridge's NativeModule directly yourself. If for any reason you do so, know that we cannot certify that your implementation will work as expected. Only call our SDKs through the JavaScript CSQ module we provide in you JavaScript code (as explained in this document), or directly in your native code. ## Note about using CSQ along with Expo To use the SDK on an Expo app, you need to have an Expo project with EAS (Expo Application Services). The SDK compatibility with Expo projects requires the extra steps described below. ### Configuration Add the plugin and your CSQ bundle identifier to your app configuration file: **app.json** ```jsx { "expo": { ..., "ios": { "bundleIdentifier": "com.cs.expo.app", // replace with your bundle id ... }, "android": { "package": "com.cs.expo.app", // replace with your bundle id ... }, "plugins": [ "@contentsquare/react-native-bridge", ], } ``` ### Run To run your Expo app with the CSQ SDK, you can't use Expo Go since it needs native files and features. To run your app, use `expo run:ios` or `expo run:android`. Or, you can replace the scripts to your app in your project's `package.json`: **package.json** ```javascript "scripts": { ... "android": "expo run:android", "ios": "expo run:ios", }, ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Contentsquare React Native Bridge","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/compatibility/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - React Native description: The Contentsquare React Native SDK changelog lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/changelog/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. 📬 Stay updated! ## Opt-in to CSQ Experience Platform Already using the CSQ SDK in standalone mode? Follow these steps to switch to CSQ Experience Platform and combine Experience Analytics and Product Analytics under a single data source. CSQ Experience Platform is currently an Early Access program. To gain access, contact your Customer Success Manager. CSQ Experience Platform guidance Throughout the documentation, code samples highlight differences between standalone and CSQ Experience Platform integrations.  1. [Update the SDK package to 6.3.0 or later](../#install-the-sdk). 2. Replace your current `CSQ.start(StartConfig.withEnvironmentId(...))` call with the `dataSourceId` provided by your Customer Success Manager. This links your app to the CSQ Experience Platform data source. **App.js** ```javascript CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")); ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 3. Review changes [introduced in 6.3.0](#630---20260512) which notably removes support for several Product Analytics options. ## CSQ SDK ### 6.4.2 - 2026.07.21 * **Native SDKs:** * iOS: 1.11.0 → 1.11.1 ### 6.4.1 - 2026.07.10 * **Native SDKs:** * Android: 1.11.0 → 1.11.2 ### 6.4.0 - 2026.06.12 * **Native SDKs:** * Android: 1.10.1 → 1.11.0 * iOS: 1.10.0 → 1.11.0 Experience Analytics * **Session Replay** * Added new APIs to support Event-Triggered Replays (ETR) * **WebViews Bug fix** * Android: Fixed an issue when navigating back within WebViews ### 6.3.0 - 2026.05.12 Experience Analytics The Session timeout definition changes from "30 minutes after being in background" to **30 minutes after last event**. See [Session definition](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/data-collection/#session-definition). Product Analytics ### Configuration **Deprecated:** `CSQ.configureProductAnalytics()` still exists, but is now deprecated in favor of `CSQ.start()` which combines SDK configuration and initialization in a single call: * Product Analytics **App.js** ```javascript CSQ.configureProductAnalytics("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, }); CSQ.start(); CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, })); ``` * CSQ Experience Platform (Early Access) **App.js** ```javascript CSQ.configureProductAnalytics("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, }); CSQ.start(); CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true, })); ``` ### Options **Added:** `AnalyticsOptions.sessionReplayAutoStart` — set to `false` to disable automatic Session Replay start and control it manually using `CSQ.startSessionReplay()` and `CSQ.stopSessionReplay()`. Defaults to `true`. ```javascript CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { sessionReplayAutoStart: false, })); ``` **Removed - Breaking:** `disableScreenviewForwardToDXA`, `disableScreenviewForwardToPA`, `resumePreviousSession`, `captureVendorId`, `captureAdvertiserId`, `clearEventPropertiesOnNewUser`, `messageBatchMessageLimit`, `pruningLookBackWindow`, `maximumDatabaseSize`, and `maximumBatchCountPerUpload` options have been removed. Remove them from your `CSQ.start()` call if present: ```javascript CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { captureVendorId: true, captureAdvertiserId: true, clearEventPropertiesOnNewUser: true, messageBatchMessageLimit: 100, resumePreviousSession: true, pruningLookBackWindow: 6, maximumDatabaseSize: 10000000, maximumBatchCountPerUpload: 5, disableScreenviewForwardToDXA: true, disableScreenviewForwardToPA: true, })); ``` * **Native SDKs:** * Android: 1.5.1 → 1.10.1 * iOS: 1.6.3 → 1.10.0 * **Session Replay** * Support Image/Text remote masking configuration in the CSQ Console * **Bug fix** * iOS: Fixed an issue where number event properties will be parsed as boolean values in some cases ### 6.2.0 - 2026.04.22 @contentsquare/react-native-cli **v1.0.0** is now available. See [the dedicated changelog](#contentsquarereact-native-cli). * **Native SDKs:** * Android: 1.5.0 → 1.5.1 * iOS: 1.6.0 → 1.6.3 * **Bug fix** * Fixed a duplicate `hasListener` symbol conflict with third-party libraries * **WebViews** * Removed unnecessary super calls in bridge handlers * Removed the upper version limit for the React Native peer dependency. The CSQ SDK has been validated up to React Native version 0.85. ### 6.1.0 - 2026.02.26 * **Native SDKs:** * Android: 1.4.7 → 1.5.0 * iOS: 1.5.1 → 1.6.0 * **Bug fix** * Fixed iOS module headers to ensure compatibility with CocoaPods projects using `use_frameworks! :linkage => :static` * Fixed 0.82.x Session Replay compatibility issues * Official support for React Native up to 0.84.x Warning * Android: React Native crashes are not deobfuscated in Error Analysis. We are currently investigating this issue. ### 6.0.5 - 2026.02.11 * **Native SDKs:** * Android: 1.4.2 → 1.4.7 * **Bug fix** * Fixed a crash in Android WindowCallbackWrapper ### 6.0.3 - 2026.02.03 * **Bug fix** * WebViews: Fixed an issue with the `userAgent` prop being overwritten ### 6.0.2 - 2025.12.15 Contentsquare CLI * **v0.1.4** is now available. Update to this version if your app uses React Native 0.82 or above. See [Error Analysis](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/error-analysis/#source-maps) for more information. Session Replay * **iOS React Native 0.82.x** is not fully compatible with Session Replay feature. - **Bug fix** * Changed the default value of `disableInteractionAutocapture` to `false` to re-enable interaction capture by default - Fixed an issue with pod installation failing on React Native versions below 0.80 - Official support for React Native up to 0.82.x ### 6.0.1 - 2025.12.05 Contentsquare CLI * **v0.1.3** is now available for version 6.0.1 and above. See [Error Analysis](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/error-analysis/#source-maps) for more information. Initial release of the CSQ SDK. * Introduces the unified CSQ API, which combines `Product Analytics`, `Experience Analytics`, and `Monitoring` features into a single, cohesive library. *** ## `@contentsquare/react-native-cli` See [CLI configuration](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/error-analysis/#cli-configuration) for configuration details. ### 1.0.0 - 2026.04.21 **Breaking Change:** The CLI package name has changed from `@contentsquare/cli` to [`@contentsquare/react-native-cli` ↗](https://www.npmjs.com/package/@contentsquare/react-native-cli). If you already have the CLI installed: 1. Update the package name in your `package.json`: ```jsx "devDependencies": { "@contentsquare/cli": "<file_path_to_the_downloaded_.tgz_package>", "@contentsquare/react-native-cli": "1.0.0", } ``` 2. Update the paths in your [source maps](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/error-analysis/#source-maps) upload configuration: * Android **android/app/build.gradle** ```groovy apply from: "../../node_modules/@contentsquare/cli/scripts/contentsquare.gradle" apply from: "../../node_modules/@contentsquare/react-native-cli/scripts/contentsquare.gradle" ``` * iOS **Bundle React Native code and images** ```shell CONTENTSQUARE_XCODE="$SRCROOT/../node_modules/@contentsquare/cli/scripts/contentsquare-xcode.sh" CONTENTSQUARE_XCODE="$SRCROOT/../node_modules/@contentsquare/react-native-cli/scripts/contentsquare-xcode.sh" ``` * Fix support for Gradle 9+ ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare React Native SDK changelog","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/changelog/","inLanguage":"en","dateModified":"2026-07-08T17:11:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Data Collection - React Native description: Understand how the React Native SDK loads, tracks, and send data lastUpdated: 12 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/data-collection/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/data-collection/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The SDK starts automatically at launch, fetches its configuration, and sends collected analytics events in batches; a session ends after 30 minutes of inactivity. ## Configuration Once started, our SDK fetches it configuration from our servers. Then depending on the segmentation size (defined by our team when you sign a contract) and the user consent status, it will start collecting analytics data from system and user events it detects from the runtime. ## Data collection ### Analytics data collection The SDK monitors the application, lifecycle events, the view hierarchy, and generates data from the behavior of the app, the content of the screen and the user interactions. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. ### Session Replay data collection See [Session Replay Initialization](../session-replay/#data-collection) to learn how Session Replay data collection works. ## Sending data ### Sending analytics data Analytics data are sent in batches of maximum 50 events. Requests are triggered when network conditions allow for the server to be reached and: * The current batch of events has reached 50 * Or the app is put in background ### Sending Session Replay Data See [Session Replay Requests](../session-replay/#requests) to learn more about how Session Replay data is sent. ### Sending crash Data See [Send Crash data](../error-analysis/#sending-crash-data) to learn more about how crash data is sent. ## Session definition A session is one continuous period of user interaction. It starts upon app launch and persists through state changes, including putting the app in the background or terminating and restarting it. As long as users interact at least once every 30 minutes, it remains the same session. ## Collected data points * The events are in JSON format, which lists the properties and their description in comment. * Events are sent to the server in batches. * A batch is a subset of events originating from one session. A session can send events in more than one batch. * The batch size is defined in a run configuration file specific to each app (50 events by default). ### Requests meta data Each batch has a common header, a set of device specific, and repeatable information and an array of events, which is immutable. The header is composed at the moment of sending, so it has to be constant info ONLY. The array in the payload is data stored at the moment of collection. The structure of the batches of events will have the following format: ```javascript { pid:8, // int - ProjectId - represented in the mobile config format uid:"ac1529a7-59f6-49d9-b254-6f0a22f57284", // String - uuid Unique user ID dt:4, // int - device type (loosely enforced enum - [sdk-phone : 4, sdk-tablet :5]) dma:"Samsung", // String - device manufacturer. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. dmo:"SG", // String - device model. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. os:"10.0", // String - os version (Android version name 8.0, 9.0, 10.0) l:"en_US", // String - Language in iso-639 format https://www.ibabbleon.com/iOS-Language-Codes-ISO-639.html tz:"Europe/Paris", // String - timezone https://en.wikipedia.org/wiki/List_of_tz_database_time_zones now:1522159618000, // long - timestamp when the batch was sent to:{ // object - type origin of the event an:"appname" // String - application name st:"sdk-android", // String - type of sdk sf:"release", // string - sdk flavor/variant [release/debug/god] }, r:{ // Device - resolution. w:1080, // int - width h:1920 // int - height d: 1.5 // The device density as float. Its values can vary between (0.75 and 10) }, pl:[] // JSON array payload - list of event objects, see below } ``` ### Events meta data All events have a common first part (don't confuse it with the header explained above). This common section is data which is common for all events by type but is gathered at the moment the event occurred. This common section is a part of the actual event payload. ```javascript { upt:1522, // long - system update in milliseconds euid:"euid", // String - event UUID url:"app-and://identifier/mainPath/secondaryPath?title=screeName", // String - screenName is passed in the title query Parameter scn:4, // int - the number of screens already shown in the session c:3, // int - connectivity type [-1 - offline, 0 - error, 1 - wifi, 2 - 2g, 3 - 3g, 4 - 4g] ci:"verizon", // String - carrier_id when user is on mobile network o:1, // int - orientation [0 = portrait, 1 = landscape] vo:{ // object - version origin of the event sv:"2.1", // string version of the sdk sb:4, // int - sdk build number av:"appVersion", // String - application version af:"appFlavor" // String - application string - [release/debug/god] ab:1 // int - application build number }, sn:1, // int - session id (positive int) t:12894726459435 // long - timestamp of the event (in milliseconds) } ``` All event specific properties are appended to this JSON object. ### App Start This event describes the absolute start of the app. The trigger for this event is the absolute start of the app. This is the first event sent when the SDK is invoked. ```javascript ea: 0; // int - event action - defined above ``` ### App Show This event is sent when the user brings the app in the foreground (switching from another app, exiting lock screen, etc.). This event means the app is focused. ```javascript ea: 1; // int - event action - defined above ``` ### App Hide This event is sent when the user exits (minimizes) the app, or switches to something else. This event means the app is not focused and the session might end, but we have not completely ended the session yet, as the user might return. ```javascript ea: 2; // int - event action - defined above ``` ### Screenview Everything starts with a View event. This is an event which describes the equivalent of a "page view" on the web. This event is sent when the Track Screen API is called. ```javascript ea:4 // int - event action - defined above st:"title", // String - screen title sl:34543 // int - (load time) screen load time (diff between last action and this event) ``` ### Tap Single Finger gesture event, when the user is interacting with a loaded screen. This is an event which describes the equivalent of a "click" in the web. This event is defined by the following sequence of touch events: * Touch Down -> N x Touch Move -> Touch Up ```javascript ea:6 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ur: true, // boolean - was this a "responsive" touch event (the target view had a handler) ``` ### Long press Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Duration: > 500ms * Distance: < 24 dp ```javascript ea:8 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id ``` ### Drag (Slow Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity < 100 dp/s ```javascript ea:9 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance dragged tvv:100 // int - target view velocity while dragging dp/s ``` ### Flick (Fast Swipe) Single Finger gesture event, when the user is interacting with a loaded screen. This event is defined by the following sequence of touch events: * Touch Down → N x Touch Move → Touch Up * Distance: > 48 dp * Finger Velocity > 100 dp/s ```javascript ea:10 // int - event action - defined above tvp:"[root]>view#id>view2>", // String - target view graph path tvid:"btn_ok", // String - target view id fd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern] tvd:100, // int - target view distance scrolled tvv:100 // int - target view velocity while scrolling dp/s ``` ### Transaction To track transactions we provide a public API which can send a transaction object (see section [Track Transactions](../track-transactions/)). This object must contain the following parameters: ```javascript ea:16, // int - event action - defined above tr:{ // a json object with different properties defining the transaction made vl: 20.0, // mandatory - float - the value of the transaction cu: 978, // mandatory - int - the ISO 4217 code of the currency of the transaction id: "32akjkljklJ575775" // optional - string - an id for the transaction } ``` ### Dynamic variables To track dynamic variables we provide a public API (see section [Dynamic variables](../track-dynamic-variables/)). **Event with a string value** ```javascript ea:18, // int - event action - defined above k:"key", // String - Custom key assigned by client. v:"value" // String - Custom value assigned by client. ``` **Event with a number value** ```javascript ea:19, // int - event action - defined above k:"key", // String - Custom key assigned by client. v: 2344 // Integer - Custom value assigned by client. ``` ## Exposure Metrics In the Zoning Analysis module, Exposure Metrics provide information on the size of the display zone in the application, and data about content exposure in scrolling elements. ### Behavior for scrollable elements Exposure Metrics data for scrolling is only calculated on the first scrollable element on the screen. Other scrolling elements in the view hierarchy are not taken into account. This event is defined by the following content: ```javascript ea:23, // int - event action dx:10, // int - normalized x content offset dy:10, // int - normalized y content offset du: 5, // int - duration of the movement (in milliseconds) ``` #### Exclude `ScrollView`, `HorizontalScrollView`, `NestedScrollView`, or `RecyclerView` type object from Exposure Metrics To exclude a scrollable container from Exposure Metrics, use the `Contentsquare.excludeFromExposureMetric(View)` API. Call it from the `onCreate` method of the activity or the `onCreateView` method of the fragment. ```kotlin import com.contentsquare.CSQ public override fun onResume() { super.onResume() // ... val scrollView = findViewById<ScrollView>(R.id.scrollView) // or HorizontalScrollView, NestedScrollView, or RecyclerView CSQ.excludeFromExposureMetric(scrollView) } ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Data Collection","description":"Understand how the React Native SDK loads, tracks, and send data","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/data-collection/","inLanguage":"en","dateModified":"2026-05-12T12:17:17+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Error Analysis - React Native description: Implement error tracking and crash reporting in your React Native app with the CSQ SDK to identify and resolve issues affecting user experience lastUpdated: 06 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/error-analysis/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/error-analysis/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. Error Analysis automatically captures API errors and network failures in your React Native app and surfaces them in the Contentsquare platform. ## Prerequisites ### Screen tracking implemented Tracking will start at the 1st screenview event, it is required to have screen tracking implemented. Make sure to follow the [Track screens](../track-screens/) section. ### Reminder about User consent If you are in the process of implementing the SDK for the 1st time (or choose to take this update as an opportunity to review your Privacy related implementation), make sure to follow the [Privacy](../privacy/) section and use the [Opt-in API](../privacy/#opt-in) to get the user consent, otherwise no data will be collected. ## Get Started ### Add Contentsquare Error Analysis to your app If you have already integrated the Contentsquare SDK and enabled Error Analysis on Experience Analytics Mobile, the Error Analysis SDK should seamlessly function. However, additional configuration is required specifically for Android apps. #### Add Gradle plugin on Android With the use of a Gradle plugin, an instrumentation of your code will be performed to collect the data about network errors. Add the Contentsquare Network Gradle plugin to the plugins block in both your root-level and app-level Gradle files: * Groovy **build.gradle** ```groovy buildscript { repositories { maven { url "https://plugins.gradle.org/m2" } } dependencies { classpath("com.contentsquare.gradle:error-analysis-network:1.8.0") } } ``` * Kotlin **build.gradle.kts** ```kotlin buildscript { repositories { maven { url = uri("https://plugins.gradle.org/m2") } } dependencies { classpath("com.contentsquare.gradle:error-analysis-network:1.8.0") } } ``` - Groovy **app/build.gradle** ```groovy apply plugin: "com.contentsquare.error.analysis.network" ``` - Kotlin **app/build.gradle.kts** ```kotlin apply(plugin = "com.contentsquare.error.analysis.network") ``` ### Start the SDK You do not need to do anything to start the Error Analysis SDK, it will start itself with Contentsquare SDK. ## Sample App For best implementation practices of our library, explore the [Contentsquare for React Native sample app ↗](https://github.com/ContentSquare/react-native-sample-app). ## API errors ### Automatic network inspection API errors automatically collects failed network requests. ### Removing Personal Data in request URL path By default, the API Errors feature collects the URL path of the failed API requests. To prevent the collection of Personal Data in the URL path, you can rewrite the request URL path with the `CSQ.setUrlMaskingPatterns` SDK API. Replace a step of the path - meaning between two slashes (/) - containing Personal Data with a variable: * becomes CS\_ANONYMIZED\_USER\_ID * becomes CS\_ANONYMIZED\_ADDRESS #### Example ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.setUrlMaskingPatterns([ "https://www.contentsquare.com/users/:user_id/address/:address", ]); ``` ##### Result | URL before masking | URL after masking | | - | - | | `https://www.contentsquare.com/users/123/address/castle+black` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS` | | `https://www.contentsquare.com/users/123/address/castle+black/reset-token/abcdef123456` | `https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS/reset-token/abcdef123456` | ### Debugging and Logging If in-app features are enabled, a info log should appear with the details of the event (see [Debugging and Logging](../in-app-features/#debugging-and-logging) section): * Android ```text I/CSLIB: API Error - GET 401 https://api.client.com ``` * iOS ```text CSLIB ℹ️ Info: API Error - GET 401 https://api.client.com ``` ### How API Errors works #### Initialization The way our SDK works is by auto-starting with the application launch and automatically collects failed network requests. #### Configuration Once started, our SDK fetches its config from our servers. It will start collecting data from network events if the API Errors setting is enabled in the config (this is handled by the Contentsquare team). #### Tracking The SDK monitors only the API Errors with response code above 400, and generates analytics data. These events are then locally stored, and eventually sent to our servers in batches. Warning To make sure API Errors occurring at app launch are correctly tracked, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. #### Sending data For each network error, a new event will be sent in analytics and Session Replay data. Check the following sections to learn more about how data is processed and sent: * [Analytics requests](../data-collection/#sending-data) * [Session Replay requests](../session-replay/#requests) ### API Troubleshooting Details API Errors troubleshooting details enables you to collect more information about API errors so you can troubleshoot errors faster. With this feature you will be able to see three types of additional API error details in the Event Stream of Session Replay. * The HTTP headers of the request and the response. * The body (the data sent by the request or received in the response). * The query parameters of the request endpoint (of the URL of the information you request for). Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. See [API Troubleshooting Details ↗](https://support.contentsquare.com/hc/en-us/articles/37271885035537) for more details. #### Mask API Error By Template URL This method will mask URLs of failing API calls to URLs that match the template URL. Use colon (`:`) to indicate a dynamic parameter. ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.setUrlMaskingPatterns([ "https://<domain>/:status_code/person/:person_id/store/:store_id", ]); ``` ### Collected data points Only network calls in error (response code above 400) will be collected. Here the exhaustive list of data collected: * URL (without query strings) * HTTP method * Response code * Timestamp of the request * Timestamp of the response * HTTP headers of the request * HTTP headers of the response * HTTP body of the request * HTTP body of the response * Query parameters of the request endpoint ### Known limitations and recommendations #### Conflict with Firebase Performance Monitoring ##### Android Contentsquare Error Analysis is not compatible with Firebase Performance Monitoring auto-collection. Only one of the two will log events, and usually, the events will be automatically logged by the Contentsquare Error Analysis. To log events to Firebase Performance Monitoring, we suggest [logging it manually ↗](https://rnfirebase.io/perf/usage#http-request-tracing). ##### iOS Contentsquare Error Analysis is compatible with Firebase Performance auto-collection, but the HTTP body from the response won't be collected by the Error Analysis SDK. **Workaround**: Disable Firebase automatic monitoring: ```javascript // <project-root>/firebase.json { "react-native": { "perf_auto_collection_enabled": false } } ``` Contentsquare Error Analysis may not be compatible with other network auto-collection tools. ## Crash Reporter The Crash Reporter feature automatically captures and reports application crashes to help you identify and debug critical issues in your React Native app. It supports both native crashes (Android/iOS) and JavaScript crashes. ### Overview The Crash Reporter provides: * **Native crash collection**: Captures crashes occurring in the native Android and iOS layers * **JavaScript crash collection**: Captures unhandled JavaScript errors and exceptions * **Automatic symbolication**: Provides readable stack traces for easier debugging * **Session context**: Links crashes to user sessions for better context ### Native crashes Native crashes occur in the platform-specific code (Android or iOS) and require additional setup for proper symbolication. #### Requirements ##### Android To enable crash collection and symbolication for Android native crashes, you need to add the Contentsquare Crash Gradle plugin. Add the plugin to both your root-level and app-level Gradle files: * Groovy **build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.crash" version "1.9.1" apply false } ``` **app/build.gradle** ```groovy plugins { id "com.contentsquare.error.analysis.crash" } ``` * Kotlin **build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.crash") version "1.9.1" apply false } ``` **app/build.gradle.kts** ```kotlin plugins { id("com.contentsquare.error.analysis.crash") } ``` ##### iOS For iOS applications, crash collection is automatically enabled when you integrate the Contentsquare SDK. No additional dependencies or configuration are required. Note The iOS crash reporter is built into the Contentsquare SDK and will automatically start collecting crash data once the SDK is initialized. ### JavaScript crashes #### Validate JavaScript crashes integration ##### Validate JavaScript error handler is activated If the JavaScript Crash reporter has been successfully initialized an info log should appear in React Native logs: ```text CSLIB ℹ️ Info: CSErrorHandler is set as javascript global error handler. ``` ##### Validate JavaScript crash reporting To test that the JavaScript Crash Reporter is working properly, you can throw an unhandled JavaScript error in **production mode**. Development mode disables the crash reporter to reduce noise during development. The next time you start your application, the JavaScript crash will be sent to our servers. If you have logging enabled, you will see the upload reflected in the logs for iOS or Android. * Android ```text I/CSLIB: React Native Crash event detected and sent for userID: <user-id>, session: <session-number> on screen: <screen-number> crashID: <crash-id> ``` * iOS ```text CSLIB ℹ️ Info: React Native Crash event detected and sent for userID: <user-id>, session: <session-number> on screen: <screen-number> crashID: <crash-id> ``` #### Source Maps Check the [React Native documentation ↗](https://reactnative.dev/docs/debugging-release-builds?platform=ios#enabling-source-maps) on how to enable source maps generation for JavaScript, and make sure to adjust the following settings in your project for automatic source map upload: * Android **android/app/build.gradle** ```groovy ... apply plugin: "com.contentsquare.error.analysis.crash" apply from: "../../node_modules/@contentsquare/react-native-cli/scripts/contentsquare.gradle" ... react { // Ensure the following hermesFlags are present (hermesFlags = ['-O', '-output-source-map']) } ext { contentsquareConfigPath = "../contentsquare-cli.json" // default } ``` Use the `index.android.bundle.map` path in the `sourcemapPath` configuration for android. Example for default path: ```text ./android/app/build/generated/sourcemaps/react/release/index.android.bundle.map ``` * iOS **Bundle React Native code and images** ```shell ... export SOURCEMAP_FILE="$SRCROOT/main.jsbundle.map" WITH_ENVIRONMENT="$REACT_NATIVE_PATH/scripts/xcode/with-environment.sh" REACT_NATIVE_XCODE="$REACT_NATIVE_PATH/scripts/react-native-xcode.sh"; export CONTENTSQUARE_CONFIG_PATH="$SRCROOT/../contentsquare-cli.json" CONTENTSQUARE_XCODE="$SRCROOT/../node_modules/@contentsquare/react-native-cli/scripts/contentsquare-xcode.sh" /bin/sh -c "$WITH_ENVIRONMENT $REACT_NATIVE_XCODE" /bin/sh -c "$WITH_ENVIRONMENT $CONTENTSQUARE_XCODE" ... ``` Use the `main.jsbundle.map` path in the `sourcemapPath` configuration for ios. Example for default path: ```text ./ios/main.jsbundle.map ``` Follow the [iOS documentation](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/error-analysis/#set-up-xcode-to-automatically-upload-dsym-files) section for "Other dependency managers" to download `upload-symbols` script. Note The added script calls will trigger the Contentsquare CLI with the `update-sourcemap-id` command from the root of your project. This command creates or updates the `contentsquare-sourcemap-info.json` file, which contains the source map ID for both platforms. Add `contentsquare-sourcemap-info.json` to your `.gitignore` to prevent it from being committed to the repository: ```shell echo "contentsquare-sourcemap-info.json" >> .gitignore ``` ### CLI configuration Install the Contentsquare CLI package as a dev dependency to your project: * yarn ```shell yarn add @contentsquare/react-native-cli --dev ``` * npm ```shell npm install @contentsquare/react-native-cli --save-dev ``` The following information is required for the CLI to successfully upload the source maps: * **The targeted platform** `ios` or `android` * **The project ID** 1. Log on the Contentsquare platform on [https://app.contentsquare.com ↗](https://app.contentsquare.com) 2. Make sure to be on the right project 3. The project ID can be found in the URL query parameter `project`: `https://app.contentsquare.com/#/{MODULE_NAME}?project={PROJECT_ID}&hash={HASH}` * **Valid API credentials** Follow the dedicated documentation from the Help Center to get the client ID and client Secret: [How to create API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593). * **The source map path** The path to the source map file in the project. The path should be relative to the project root. To provide this information to the CLI script, either use a JSON configuration file or pass the required information as command line arguments. For automatic source map upload, the preferred way is to use the JSON configuration file. #### Using JSON configuration file Provide the required information by adding a `contentsquare-cli.json` file at the root of your project. **contentsquare-cli.json** ```json { "android": { "clientId": "ANDROID_CLIENT_ID", "clientSecret": "ANDROID_CLIENT_SECRET", "projectId": "ANDROID_PROJECT_ID", "sourcemapPath": "ANDROID_PROJECT_SOURCEMAP_PATH" }, "ios": { "clientId": "IOS_CLIENT_ID", "clientSecret": "IOS_CLIENT_SECRET", "projectId": "IOS_PROJECT_ID", "sourcemapPath": "IOS_PROJECT_SOURCEMAP_PATH" } } ``` #### Using command line arguments Alternatively, the required information can be added as arguments directly on the command line. | Option | Description | | - | - | | `--client-id` | The client ID of [API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593) | | `--client-secret` | The client secret of [API credentials ↗](https://support.contentsquare.com/hc/en-us/articles/37271728104593) | | `--config` | The path to the configuration file relative to project root. Default value: `contentsquare-cli.json` | | `--help` | Display the help message | | `--platform` | The platform to target: `ios` or `android` | | `--project-id` | The project ID | | `--sourcemap-path` | The path to the source map file | | `--uploadUrl` | The URL of the Contentsquare platform. Default value: `https://api.csq.io` | | `--verbose` | Display verbose output | Note These two solutions can be mixed if, for example, you want to use the multiple JSON files to store different configurations for different environments and pass the path to the file as a `config` argument. If same argument is used in both methods, the command line arguments will prevail over the same argument in the JSON file. How to use `@contentsquare/react-native-cli` to manually upload source maps Following exact steps is crucial to ensure the correct deobfuscation of the stack traces: 1. Invoke the Contentsquare CLI with the `update-sourcemap-id` command from the root of your project to create/update `contentsquare-sourcemap-info.json`, that contains the source map ID for both platforms. ```shell npx contentsquare-cli update-sourcemap-id ``` 2. Build a release version of your app. 3. Upload the source maps to the Contentsquare platform by invoking the `upload-sourcemaps` command from the root of your project. ```shell npx contentsquare-cli upload-sourcemaps ``` ### How Error Reporter works #### Initialization Error Reporter is started automatically and begins to collect the reported errors when your application is launched #### Configuration Once started, our SDK fetches its configuration from our servers. It will start reporting errors if the Error Reporter setting is enabled (this is handled by the Contentsquare team). #### Reporting When an error occurs, a report is created and stored locally in the device. The report is sent to our servers as soon as possible and then removed from the local storage. Warning To make sure errors are correctly tracked, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent. See [Track screens](../track-screens/) for more details. #### Sending crash data For each error, a new event will be sent to analytics and Session Replay data when the network conditions allow for the server to be reached. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Error Analysis","description":"Implement error tracking and crash reporting in your React Native app with the CSQ SDK to identify and resolve issues affecting user experience","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/error-analysis/","inLanguage":"en","dateModified":"2026-08-06T08:47:54+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: SDK API reference - React Native description: SDK commands reference including signature, parameter descriptions, and examples lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/command-reference/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/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:** `6.0.0` Get user consent. Calling this API generates a user ID and initiates tracking. Call [`optIn`](#csqoptin) after [`start`](#csqstart). ```javascript CSQ.optIn(); ``` ### CSQ.optOut **Added in:** `6.0.0` Revoke user consent, remove stored `userID`. Stop CSQ SDK, flush, and clear all data. ```javascript CSQ.optOut(); ``` ### CSQ.identify 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. 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`. ```javascript CSQ.identify("user_identity"); ``` #### Parameters * #### identity  string (<= 100 chars)   Identity to be associated with the current user. ### CSQ.resetIdentity **Added in:** `6.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. ```javascript CSQ.resetIdentity(); ``` ### CSQ.sendUserIdentifier Experience Analytics | **Added in:** `6.0.0` Associate the user identifier to the session. ```javascript CSQ.sendUserIdentifier("any_identifier") ``` #### Parameters * #### userIdentifier  string   The user identifier to track. Should be max 100 characters long. ### CSQ.onMetadataChange **Added in:** `6.0.0` Get all the information related to the user and project. Refer to the [`CSQMetadata`](#csqmetadata) object. ```javascript CSQ.onMetadataChange(callback: (metadata: CSQMetadata) => void) => { // Handle metadata change }); ``` #### Parameters * #### callback  (metadata: CSQMetadata) => void   Callback function triggered when metadata changes. ### `CSQMetadata` `CSQMetadata` object contains information related to the user and project. ```javascript interface CSQMetadata { userID: string | null; sessionID: string | null; identity: string | null; environmentID: string | null; projectID: string | null; sessionReplayURL: string | null; } ``` #### `userID` Identifier of the current user. This is an identifier from Product Analytics by default or Experience Analytics if PA is not active. #### `sessionID` Session identifier. This is an identifier from Experience Analytics by default or Product Analytics if Experience Analytics is not active. #### `projectID` Project identifier for Experience Analytics. #### `environmentID` Environment identifier for Product Analytics. #### `sessionReplayURL` URL of current Session Replay. #### `identity` Identity associated with the user by calling [`identify()`](#csqidentify). ## Property Tracking ### CSQ.addDynamicVar 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 ```javascript CSQ.addDynamicVar("key1", "value1") CSQ.addDynamicVar("key2", 2, (errorObject) => { console.log(errorObject.toString()); }); ``` #### Parameters * #### key  string   Dynamic variable key * #### value  string   Dynamic variable value * #### callback  (error: Error) => void (optional)   Optional callback function to handle errors. ### CSQ.addUserProperties Product Analytics | **Added in:** `6.0.0` Add a collection of properties to be associated with the current user. ```javascript CSQ.addUserProperties({ propertyKey: "propertyValue", }); ``` #### Parameters * #### properties  Record\<string, PropertyValue   A dictionary of user properties. `PropertyValue` can be `number`, `string`, `boolean`, `bigint` ### CSQ.addEventProperties Product Analytics | **Added in:** `6.0.0` Add a collection of properties to be associated with all future events. ```javascript CSQ.addEventProperties({ propertyKey: "propertyValue", }); ``` #### Parameters * #### properties  Record\<string, PropertyValue>   A dictionary of event properties. `PropertyValue` can be `number`, `string`, `boolean`, `bigint` ### CSQ.removeEventProperty Product Analytics | **Added in:** `6.0.0` Removes a single property from the collection of event-wide properties. ```javascript CSQ.removeEventProperty("propertyKey") ``` #### Parameters * #### name  string   The key of the property to remove. ### CSQ.clearEventProperties Product Analytics | **Added in:** `6.0.0` Removes all event-wide properties. ```javascript CSQ.clearEventProperties() ``` ## CSInApp ### CSQ.handleUrl 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](../../experience-analytics/in-app-features/). ```javascript CSQ.handleUrl("sample_url") ``` #### Parameters * #### urlString  string | null | undefined   The URL handled by [React Native Linking API ↗](https://reactnative.dev/docs/linking). ## Interoperability ### \<CSQWebView> Experience Analytics | **Added in:** `6.0.0` Allows Contentsquare SDK to track webviews. ```javascript <CSQWebView> <WebView source={{ uri: "https://test-url.com", }} /> </CSQWebView> ``` #### Parameters * #### children  ReactElement   The webview to register for tracking. CSQWebView supports [react-native-webview ↗](https://github.com/react-native-webview/react-native-webview). ## Event Tracking ### CSQ.trackTransaction Experience Analytics | **Added in:** `6.0.0` Send a transaction. ```javascript CSQ.trackTransaction(10, Currency.EUR, "transactionId"); ``` #### Parameters * #### 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. ### CSQ.trackScreenview **Added in:** `6.0.0` Send a screen view with or without custom variables. Requires Experience Analytics to be started. ```javascript CSQ.trackScreenview(name: "ScreenName", cvars: [{index: 0, key: "key", value: "value"}]) ``` #### Parameters * #### 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 ### CSQ.trackEvent Product Analytics | **Added in:** `6.0.0` Creates an event message to be tracked and sent to the API. ```javascript CSQ.trackEvent('event', { some_property: 100 }); ``` #### Parameters * #### 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`. ## Logging ### CSQ.logToConsole Product Analytics | **Added in:** `6.0.0` Enables logging to the console for Product Analytics events and diagnostics. ```javascript CSQ.logToConsole(); ``` ### CSQ.setLogChannel Product Analytics | **Added in:** `6.0.0` Sets the log channel for Product Analytics logging. ```javascript import { LogChannel } from '@contentsquare/react-native-bridge'; CSQ.setLogChannel(LogChannel.LOG); ``` #### Parameters * #### logChannel  LogChannel   The log channel to use. Available values: * `LogChannel.LOG` * `LogChannel.TRACE` * `LogChannel.DEBUG` * `LogChannel.INFO` * `LogChannel.WARN` * `LogChannel.ERROR` * `LogChannel.NONE` ### CSQ.setLogLevel Product Analytics | **Added in:** `6.0.0` Sets the log level for Product Analytics logging. ```javascript import { LogLevel } from '@contentsquare/react-native-bridge'; CSQ.setLogLevel(LogLevel.INFO); ``` #### Parameters * #### logLevel  LogLevel   The log level to use. Available values: * `LogLevel.TRACE` * `LogLevel.DEBUG` * `LogLevel.INFO` * `LogLevel.WARN` * `LogLevel.ERROR` * `LogLevel.NONE` ## Error tracking ### CSQ.setUrlMaskingPatterns Experience Analytics | **Added in:** `6.0.0` Sets URL masking patterns. ```javascript CSQ.setUrlMaskingPatterns(["pattern1", "pattern2"]) ``` #### Parameters * #### patterns  string\[]   A list of URL patterns to mask. ### CSQ.triggerNativeCrash Experience Analytics | **Added in:** `6.0.0` Trigger a native crash for testing purposes. ```javascript CSQ.triggerNativeCrash() ``` ## Session Replay ### CSQ.startSessionReplay **Added in:** `6.3.0` Starts Session Replay. Use this when you have set [`sessionReplayAutoStart`](#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. ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.startSessionReplay(); ``` ### CSQ.stopSessionReplay **Added in:** `6.3.0` Stops Session Replay collection. Any data collected before this call is preserved and uploaded according to the SDK upload schedule. ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.stopSessionReplay(); ``` ### CSQ.triggerReplayForCurrentSession **Added in:** `6.4.0` Triggers Session Replay for the entire current session, with the parameter name as "ETR event". ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.triggerReplayForCurrentSession("ETR event"); ``` ### CSQ.triggerReplayForCurrentScreen **Added in:** `6.4.0` Triggers Session Replay for the entire current screen, with the parameter name as "ETR event". ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.triggerReplayForCurrentScreen("ETR event"); ``` ## Personal Data/Masking ### CSQ.setDefaultMasking Experience Analytics | **Added in:** `6.0.0` Set the default masking state. All Views are fully masked by default. ```javascript CSQ.setDefaultMasking(true) ``` #### Parameters * #### masked  Bool   The default masking state to be set. ### `<CSQMask>` **Added in:** `6.0.0` 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. ```javascript <CSQMask> <View> ... </View> </CSQMask> ``` #### Props * #### 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. ### WithCSQMask Higher Order Component (HOC) to mask content for Session Replay and suppress events for view inside WithCSQMask and all its children. #### Props * #### 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. ## SDK Initialization and Management ### CSQ.configureProductAnalytics Deprecated | Product Analytics | **Added in:** `6.0.0` Deprecated `CSQ.configureProductAnalytics()` is deprecated since 6.3.0. Use `CSQ.start(StartConfig.withEnvironmentId(...))` to combine SDK configuration and initialization in a single call. See [`start`](#csqstart). Product Analytics is now configured using the `options` parameter of [`start()`](#csqstart). ### CSQ.start **Added in:** `6.0.0` Start and configure the SDK. Use `StartConfig` to specify the product configuration. ```javascript 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 (CSQ Experience Platform) CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")); // Product Analytics with options CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true })); ``` #### StartConfig * #### 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](#product-analytics-initialization-options). * #### StartConfig.withDataSourceId(id, options?)  CSQConfig   Start the SDK with Product Analytics using a data source ID (CSQ Experience Platform). * `id` *(string)* — Your CSQ Experience Platform data source ID. * `options` *(AnalyticsOptions, optional)* — Product Analytics [initialization options](#product-analytics-initialization-options). ### CSQ.stop **Added in:** `6.0.0` Stop all activity from the SDK. Once run no requests, telemetry collection, or logs will be generated. ```javascript CSQ.stop(); ``` ### CSQ.pauseTracking **Added in:** `6.0.0` Pause all tracking features. ```javascript CSQ.pauseTracking(); ``` ### CSQ.resumeTracking **Added in:** `6.0.0` Resume all tracking features. ```javascript CSQ.resumeTracking(); ``` ## Product Analytics initialization options CSQ SDK options for Product Analytics passed to [`start()`](#csqstart). ```javascript type AnalyticsOptions = { enableRNAutocapture?: boolean; disableInteractionAutocapture?: boolean; disablePageviewAutocapture?: boolean; baseUrl?: string; // EU: "https://mh.ba.contentsquare.net"; https://mh.bf.contentsquare.net (default) uploadInterval?: number; disableInteractionTextCapture?: boolean; disableInteractionAccessibilityLabelCapture?: boolean; sessionReplayAutoStart?: boolean; // Native specific options enablePushNotificationAutocapture?: boolean; enablePushNotificationTitleAutocapture?: boolean; enablePushNotificationBodyAutocapture?: boolean; enableViewAutocapture?: boolean; // iOS specific options disablePageviewTitleAutocapture?: boolean; }; ``` ## React Native Product Analytics initialization options ### `enableRNAutocapture` Enable React Native view autocapture. Defaults to false. ### `disableInteractionAutocapture` Disables autocapture of touch events on React Native Views. Defaults to false. ### `disablePageviewAutocapture` Whether source pageview events will be auto-captured. Defaults to false. ### `baseUrl` The CSQ API endpoint to use: * `https://mh.ba.contentsquare.net` — EU-hosted environments * `https://mh.bf.contentsquare.net` — all other environments (default) ### `uploadInterval` The interval, in milliseconds, between event uploads. ### `disableInteractionTextCapture` Disables text capture for React Native interactions. Defaults to false. ### `disableInteractionAccessibilityLabelCapture` Disables accessibility label capture for React Native interactions. Defaults to false. ### `sessionReplayAutoStart` Whether the SDK starts Session Replay automatically when the SDK starts. When set to `false`, you must call [`CSQ.startSessionReplay()`](#csqstartsessionreplay) to start Session Replay. Defaults to `true`. ## Native specific Product Analytics initialization options ### `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. ### `enableViewAutocapture` Whether the SDK will auto capture UI interactions and source pageviews. Defaults to false. ## iOS specific Product Analytics initialization options ### `disablePageviewTitleAutocapture` Disable pageview title capture. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"SDK API reference","description":"SDK commands reference including signature, parameter descriptions, and examples","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/command-reference/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Google Tag Manager - React Native description: Leverage our native integration to send Google Tag Manager events to Contentsquare lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/google-tag-manager/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/google-tag-manager/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Integrate Google Tag Manager with the CSQ SDK for React Native to forward GTM events to Contentsquare. ## Prerequisite If you are following this Google Tag Manager integration process, you should already have followed the React Native Firebase setup. We will assume that you are using [the officially supported Firebase bridge ↗](https://rnfirebase.io/) the officially supported Firebase bridge. We will also assume that you have added the native GTM library to your iOS and Android project (following the [iOS documentation ↗](https://developers.google.com/tag-manager/ios/v5) and the [Android documentation ↗](https://developers.google.com/tag-manager/android/v5#add-gtm-to-project)). Before anything, you also need to integrate the Contentsquare Bridge ([see section: Add Contentsquare to your app](../)). ## Integration The whole integration will happen in the native part of your app, and in the GTM interface. Here is how it will work (you need to do these steps twice, once for iOS and once for Android): * You will first setup custom tag, trigger, and variables in your GTM interface. * Then, you will have to add a custom Tag class in your native project. * In your JavaScript/TypeScript code, or in your native code, you will use the Firebase Analytics library to send events, as explained thereafter. * As you have created a trigger for that specific type of event, it will trigger the code in your native custom Tag class, where you will be calling the native SDK function corresponding to that event, thus allowing Contentsquare to collect those events. ### Screenview events Screenview events will be triggered in the Firebase React Native bridge [by calling setCurrentScreen ↗](https://rnfirebase.io/analytics/screen-tracking). As the integration is exactly the same as the native ones, you can refer directly to the SDKs' explanation of the [iOS integration](../../../csq-sdk-ios/experience-analytics/google-tag-manager/#screenview-events) and [Android integration](../../../csq-sdk-android/experience-analytics/google-tag-manager/#screenview-events). You will have to do both to have a similar behavior across both platforms. ### Transaction events Transaction events will be triggered in the Firebase React Native bridge [by calling `logEvent` ↗](https://rnfirebase.io/analytics/usage#custom-events) with a purchase event (for example, `analytics().logEvent('purchase', { currency: 'USD', value: 99.99 })`). As the integration is exactly the same as the native ones, you can refer directly to the SDKs' explanation of the [iOS integration](../../../csq-sdk-ios/experience-analytics/google-tag-manager/#transaction-events) and the [Android integration](../../../csq-sdk-android/experience-analytics/google-tag-manager/#transaction-events). You will have to do both to have a similar behavior across both platforms. ### Dynamic variable events Dynamic variables are generally custom, and as such can be used with any type of event that can be boiled down to a key/value pair with value types that are valid for the Contentsquare SDK (a string or an unsigned integer). The most common event in that case will thus be a custom event, sent [by calling `logEvent` ↗](https://rnfirebase.io/analytics/usage#custom-events) with a custom event name and parameters. As the integration is exactly the same as the native ones, you can refer directly to the SDKs' explanation of the [iOS integration](../../../csq-sdk-ios/experience-analytics/google-tag-manager/#dynamic-variable-events) and [Android integration](../../../csq-sdk-android/experience-analytics/google-tag-manager/#dynamic-variable-events). You will have to do both to have a similar behavior across both platforms. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Google Tag Manager","description":"Leverage our native integration to send Google Tag Manager events to Contentsquare","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/google-tag-manager/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Impact on performance - React Native description: Metrics to evaluate the impact on performance of the SDK on your apps lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/impact-on-performance/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/impact-on-performance/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The React Native CSQ SDK delegates performance tracking to native Android and iOS SDKs; see their respective pages below. *  ### [Android](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/impact-on-performance/) *  ### [iOS](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/impact-on-performance/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Impact on performance","description":"Metrics to evaluate the impact on performance of the SDK on your apps","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/impact-on-performance/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: In-app features - React Native description: Enable testing and debugging capabilities within your React Native app using in-app features for enhanced development workflow lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/in-app-features/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/in-app-features/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Alongside its tracking capabilities, the SDK embeds some features aimed at Contentsquare users such as Screenshot Capture and SDK Logs. To allow Contentsquare users to enable in-app features in your React Native app, the implementation depends on the native platform. ## Android To enable in-app features within your app, you have to **first make sure your app is launched in the background**. To do so, start it and press the Android home button. Then, follow the appropriate method described as follows. ### On a device: scan the QR code If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code with your phone.  Note On Android, some devices have a built-in QR code reader feature in the default camera app. If that is not the case for you, use [QR & Barcode Reader by TeaCapps ↗](https://play.google.com/store/apps/details?id=com.teacapps.barcodescanner\&hl=en\&gl=US). ### On an emulator: use the ADB command If you are using an emulator, you can use the ADB command to enable in-app features. If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and select "Copy this ADB command".  It will look like this: ```shell adb shell am start -W -a android.intent.action.VIEW -d "cs-{{packageName}}://contentsquare.com?activationKey={{uniqueActivationKey}}\&userId={{userId}}" ``` If you don't have access to the Contentsquare platform, you can ask the Contentsquare team to share the link with you. Note On Android, the in-app features are handled automatically by the native SDK. No React Native code implementation is required. ## iOS This implementation phase is required on the **iOS side only** You will have to do a few changes on the **native side of your app**: ### 1. Add the custom URL scheme to `Info.plist` In order for your application to open when you scan the QR code or enter the URL we provide in a web browser, you have to add the custom URL scheme to your app's `Info.plist` file. You can do this using one of the following methods: #### Xcode 1. Open your project settings 2. Select the app target 3. Select the `Info` settings 4. Scroll to `URL Types` 5. Set the URL scheme to `cs-$(PRODUCT_BUNDLE_IDENTIFIER)` #### Text editor 1. Open the `Info.plist` of your project 2. Add the following snippet: **Info.plist** ```xml <key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>cs-$(PRODUCT_BUNDLE_IDENTIFIER)</string> </array> </dict> </array> ``` ### 2. Call the SDK when your app is opened with the custom URL Then, you will need to link your app with our SDK. When your application is started via a deeplink, a specific delegate function is called in your AppDelegate file. In order for us to be able to handle it, you will need to call a function of our API that will handle it. Call either the React Native or the iOS native API: #### Call the React Native API Follow this [guide ↗](https://reactnative.dev/docs/linking) to call the React Native API. ```typescript import { Linking } from 'react-native'; import { CSQ } from '@contentsquare/react-native-bridge'; // Listen for deeplinks while the app is running Linking.addEventListener('url', (event: { url: string }) => { CSQ.handleUrl(event.url); }); // Handle deeplink when app is launched via a deeplink const initialUrl = await Linking.getInitialURL(); if (initialUrl) { CSQ.handleUrl(initialUrl); } ``` ## Enable in-app features Once the implementation is done, in-app features can be enabled in different ways: ### Scan the QR code If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code displayed with your iPhone.  ### Use the custom link for simulator If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and select "Copy link" (to copy the deeplink) and paste it in Safari on your Simulator to trigger the in-app features.  Note If you don't have access to the Contentsquare platform, you can ask the Contentsquare team to share the link with you. ### Using the Terminal In a Terminal console, open an URL in your current simulator with the following command (replacing `CUSTOM_LINK` with yours): ```shell xcrun simctl openurl booted "CUSTOM_LINK" ``` ## Debugging and Logging Contentsquare provides Logging capabilities that allow you to see the raw event data logged by your app in the macOS Console App, Xcode, or in the Contentsquare platform. Use this for validation purposes during the instrumentation phase of development and can help you discover errors and mistakes in your analytics implementation and confirm that all events are being logged correctly. ### Viewing local logs By default, almost all logs are disabled. There is only one log that is always visible to notify that the SDK has started: 1. Start your application, and check logs for this output: ```text [INFO] CSQ 6.4.2 for Experience Analytics is attempting to start. ``` To enable all logs, activate [in-app features](#enable-in-app-features). Logging is directly linked to in-app features state: it starts when in-app features are enabled and stops when you disable in-app features. ### Viewing logs in the Contentsquare platform To view logs directly on the platform, you can use Log visualizer. Log visualizer is a helper tool to see SDK logs without logging tools. It requires having platform access for your project and enabling in-app features. See the [SDK Log Visualizer Help Center Article ↗](https://support.contentsquare.com/hc/en-us/articles/37271699876625) for more information. ### Screenshot capture To unlock the full data-visualization capabilities of Contentsquare, the SDK provides a way to capture screenshots of your app screens. These screenshots can only be taken by Contentsquare's users on their device. They are not captured from your end-users device. It means your Personal Data is safe, as long as you use a test user account. Warning For screenshot capture to work, the session has to be tracked (included in tracked users and not opted-out) and a first screenview event has to be sent before. Note Screenshots require a screenview event to be triggered before they can be captured.  Screenshots are used in the **Zoning Analysis** module to look at zone-level metrics (Tap rate, Swipe rate...):  ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"In-app features","description":"Enable testing and debugging capabilities within your React Native app using in-app features for enhanced development workflow","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/in-app-features/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - React Native description: Configure privacy settings and user consent management in your React Native app with the CSQ SDK to ensure regulatory compliance lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/privacy/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Customers ("Customer(s)", "you," or "your"), as app developers and/or publishers, shall ensure compliance with applicable data privacy laws and regulatory guidelines while using Contentsquare SDK for your app. This section explains the data processing involved in the use of Contentsquare SDK and provides information to help you comply with data protection laws, including the GDPR, e-privacy directive, and the [French Data Protection authority (CNIL) guidelines on mobile applications ↗](https://www.cnil.fr/sites/cnil/files/2025-05/recommendation-mobiles-app.pdf). This section is for informational purposes only and is not legal advice. If you are not sure of how to comply with data protection laws that apply to you, refer to legal counsel. To learn about Contentsquare privacy practices, see our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Purpose of processing and categories of personal data collected Here is the list of categories of personal data Contentsquare collects by default that are part of our [privacy guidelines](../privacy/#privacy-guidelines). All collected personal data listed below is linked to the end-user via the [Contentsquare User ID](#contentsquare-user-id) we generate. Warning The Contentsquare SDK provides features that allow you to send to Contentsquare additional types of personal data (such as username, email address, customer ID, account number): [Dynamic variables](../../experience-analytics/track-dynamic-variables/), [Custom variables](../../experience-analytics/track-custom-variables/), [User identifier](../../experience-analytics/session-replay/#send-user-identifier), [Screen names](../../experience-analytics/track-screens/), [Session Replay (unmasking elements)](../../experience-analytics/session-replay/#personal-data-masking). If you decide to use these features to collect new types of personal data or use already collected data but for a different purpose, it is up to you to describe these privacy practices in your app manifest. | Categories | Data type | Purposes | | - | - | - | | Identifiers | User ID | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Product Interaction such as touch gestures (taps, swipes), user journey (pages visited), time of engagement, or transactions | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Other usage data (any other data about end-user activity in the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Other Data types | Other Data types (technical data, any other data inputted by customers in the dynamic variables, data used as part of the Session Replay feature where applicable) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Diagnostics | Crashes, such as crash logs | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Diagnostics | Performance data, such as launch time, freeze rate, or energy use | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/) | | Diagnostics | Other diagnostic data (any other data collected for the purposes of measuring technical diagnostics related to the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/) | | Search History | Information about searches performed by an end-user in the app | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Session Replay module](../../experience-analytics/session-replay/)) | | Purchase History | Transaction data about an end-user (such as order reference, amount, bought items) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | See how the data types and purposes are reflected in the [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy). Note Contentsquare is not designed to collect sensitive personal data (for example health, financial, or racial data). It is your responsibility to prevent any sensitive data from being sent to Contentsquare. If you accidentally send sensitive data, contact your customer success manager to immediately delete them from Contentsquare servers. ## User identifiers ### Contentsquare User ID The SDK generates a unique user ID (UUID) (random hash) which is specific to users on their device. Contentsquare cannot identify a user across devices. This user ID and all collected data are stored for 13 months. We don't persist the UUID when the app is deleted and re-installed. The SDK generates a new UUID after install or re-install. Contentsquare does not share this user ID with any third parties. ### IDFA Contentsquare does not collect the **IDFA** (Advertising ID) or any ad related information to identify the user. Check out our page about [10 Things to know about the Contentsquare solution's data processing ↗](https://contentsquare.com/privacy-center/10-things-to-know-cs-data-processing/). ### "User identifier" feature Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier provided by the customer. See [User identifier feature](../../experience-analytics/session-replay/#send-user-identifier) for more information. ## Data retention and storage location ### Data retention By default, end-users personal data are kept for 13 months. The retention of end-users personal data collected via the Session Replay is customizable by customers, from 3 to 24 months. ### Storage location End-users personal data are stored in Europe or in the US, depending on your location. For more details on applicable hosting locations, refer to our [subprocessors list ↗](https://contentsquare.com/privacy-center/subprocessors/). ## Informing your End-User The Contentsquare SDK collects end-user's personal data on your app. As a data controller, app developers, or app publishers, it is your responsibility to provide appropriate information to your end-users on how their personal data is handled when using the CSQ SDK, for example via a privacy policy or cookie banner. Contentsquare provides a sample [description of the services ↗](https://contentsquare.com/privacy-center/sample-cookie-description/) (including Experience Analytics and Product Analytics) to help customers meet their transparency obligations. This description is for information only and is not legal advice. ## Handling User Consent Contentsquare collects usage data on your app. **By default, the SDK will consider every new user to be opted-out.** To start tracking, the SDK [Opt-in API](#opt-in) must be called. You are responsible for handling the UI asking end-users for their consent and allowing them to manage their privacy settings. Use the following APIs to pass the user decision to the Contentsquare SDK. Note If data protection laws that apply to you do not require end-user consent for your app, discuss it during implementation with your Contentsquare contact (as this may have implications for app store privacy guidelines). ### Opt-in Use the Opt-in API to get end-user consent. Calling this API will generate a user ID and initiate tracking. ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; CSQ.optIn(); ``` ### Opt-Out When this API is called, tracking stops immediately, all settings are reset (Session number, Page number, and so on) and all files and directory including personal data collected via the SDK created by Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track and collect any data from the user's phone unless the Opt-in API is called again. ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; CSQ.optOut(); ``` ### Handling your end-user's data subject requests In case Contentsquare receives a request from an individual that identifies as an end-user of your app, Contentsquare will promptly refer such individual directly to you, as the data controller and will support you with any means available to resolve such request. Contentsquare has launched a portal for managing data subject requests to its customers respond to data subjects within the legal deadlines. Therefore, you can forward any data subject request (such as data deletion or data access request) you receive to Contentsquare via this Data Subject Portal at [https://contentsquare.com/privacy-center/data-subject-request-portal/ ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ### Get Contentsquare User ID Since Contentsquare SDK does not collect by default any directly identifiable personal data about your end-user, we cannot help you respond to an end-user's data subject request without their Contentsquare User ID. Use this API to get the Contentsquare User ID of your end-user and forward the end-user's data subject request (such as data deletion or data access request) via Contentsquare's [portal ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; CSQ.onMetadataChange((metadata) => { const userId = metadata.userId; // Forward userId with data subject request }); ``` Note You are able to get an ID only if the user is not Opted-out. ### Enrichment API [The Enrichment API](https://docs.contentsquare.com/en/api/enrichment/) allows for enriching the behavioural data tracked by Contentsquare client-side, with other session-based data that can be sent server-side. During a visit on an app, you can interact with Contentsquare's SDK to pull those identifiers with the following SDK APIs: ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; CSQ.onMetadataChange((metadata) => { const projectId = metadata.projectId; const sessionId = metadata.sessionId; // store these Contentsquare session identifiers in your backend }); ``` ### Pause / Resume Tracking To completely stop data collection of your end-users of your app, use the pause and resume tracking APIs. When `pauseTracking` is called, the Contentsquare SDK pauses all tracking (Analytics, Session Replay, Errors) of your end-users. When `resumeTracking` is called, the Contentsquare SDK resumes all tracking (Analytics, Session Replay, Errors) and starts collecting your end-users personal data again with the same Contentsquare user ID. ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; import { useEffect } from 'react'; function SensitiveScreen() { useEffect(() => { // Pause tracking when entering sensitive screen CSQ.pauseTracking(); return () => { // Resume tracking when exiting sensitive screen CSQ.resumeTracking(); }; }, []); return ( // your sensitive screen content ); } ``` Note As this mechanism pauses the tracking, make sure that you call resume once your user exits the sensitive screen. Best practice would be to link these method calls to component lifecycle events using `useEffect`. ## Disable user tracking across sessions If you don't want to link the different sessions of a user to the same userID, reset the userID at each app start: ```javascript import { CSQ, StartConfig } from '@contentsquare/react-native-bridge'; import { CSQ } from '@contentsquare/react-native-bridge'; import { useEffect } from 'react'; function App() { useEffect(() => { CSQ.start(StartConfig.dxa()); CSQ.optOut(); CSQ.optIn(); }, []); return ( // your app content ); } ``` Starting the SDK manually using `start()` will ensure that opt-out is called right after the start of the SDK (no event tracked in between). Calling `optOut()` will delete the previous userID. Calling `optIn()` will set a new one. Note If you are monitoring the network requests, you may see event requests being sent at app start. This is expected as there may be events from the previous session that haven't been sent yet. The [opt-out API](#opt-out) makes sure to send all data stored locally before stopping the tracking and wiping all data. ### Session Replay privacy APIs As part of Session Replay capabilities, Contentsquare provides masking mechanisms to prevent unwanted end-user's personal data from the Session Replay module from being transmitted to Contentsquare. See [Session Replay Personal data masking](../../experience-analytics/session-replay/#personal-data-masking) for more information. ## Privacy guidelines Warning For iOS apps, it is your responsibility to comply with the [App Store Privacy guidelines ↗](https://developer.apple.com/app-store/review/guidelines/#privacy). The Contentsquare SDK includes a [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy) describing the types of end-users personal data collected. For Android apps, follow [Google Play's Data safety requirements ↗](https://support.google.com/googleplay/android-developer/answer/10787469) when declaring data collection in your app. ### App Tracking Transparency (ATT) It is not required to ask for end-users' permission through ATT when using Contentsquare, as it does not fall under the "tracking" definition. The data collected by the Contentsquare SDK is not linked with third-party data for targeted advertising or advertising measurement purposes, nor shared with a data broker. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Configure privacy settings and user consent management in your React Native app with the CSQ SDK to ensure regulatory compliance","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/privacy/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Session Replay - React Native description: How to implement Session Replay with the Contentsquare React Native bridge lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/session-replay/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/session-replay/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Session Replay enables replaying real sessions to observe how users interact with your product, by capturing screen content - including text and images - as users navigate your mobile app. For more details, see [Introduction to Session Replay for Apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) in the Help Center. ## Starter guide ### Prerequisites #### Update to latest SDK version To enable Session Replay in your app and get the most stable version, it is required to [upgrade the SDK](../#install-the-sdk) to its latest version. #### Implement screen tracking Ensure screen tracking is implemented, since Session Replay collection starts at the first screenview event. See [Track screens](../track-screens/). #### Handle User consent Ensure user consent is handled for Contentsquare data collection, especially if you're implementing the SDK for the first time. See [Privacy](../privacy/) section. Note Mandatory data collection settings are configured by Contentsquare in your project parameters. [Learn more about Data collection configurations ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) on the Help Center. ### Define when Session Replay starts By default, Session Replay starts automatically when the SDK starts. To control Session Replay start manually — for example, to start it only after receiving specific user consent for Session Replay or when certain conditions are met (such as a specific geolocation) — set [`sessionReplayAutoStart`](../command-reference/#sessionreplayautostart) to `false` in your SDK options: **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { sessionReplayAutoStart: false, })); ``` Once your app has determined that Session Replay can start, call [`CSQ.startSessionReplay()`](../command-reference/#csqstartsessionreplay) to start Session Replay: ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.startSessionReplay(); ``` Calling `startSessionReplay()` does not force Session Replay data collection. It enables the Session Replay module, allowing it to begin checking whether the global Replay sampling rate or Event Triggered Replay conditions are met. Session Replay data collection will only start if these conditions are satisfied. For more information, see [Data collection for Session Replay (Apps) ↗](https://support.contentsquare.com/hc/en-us/articles/37271951720721) on the Help Center. To stop Session Replay collection, call [`CSQ.stopSessionReplay()`](../command-reference/#csqstopsessionreplay): ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.stopSessionReplay(); ``` ### Configure Session Replay masking #### Masking behavior By default, the Contentsquare SDK is configured to mask all content displayed on the user interface (UI) to prevent unnecessary data collection. For more details, see what a fully masked screen looks like in [Masking mechanisms](#masking-mechanisms). **For testing purposes**, we advise you to unmask all the content by setting the [default masking](#default-masking) status to false. **For more granular control in deployment mode**, you can use the [SDK public masking APIs](#public-masking-apis) to fine-tune exactly which elements remain masked. Warning Always keep sensitive data masked to ensure compliance with privacy regulations and to protect users' personal data. ### Configure Event-Triggered Replays (optional) If Event-Triggered Replays is included in your contract, you can set up ETR events to enable specific screen and session collection in Session Replay. See [Event-Triggered Replays (ETR)](#event-triggered-replays-etr). ### Configure Webviews (optional) If your mobile app includes Webviews, specific implementation steps are required to ensure they are properly reflected in Session Replay: * Implement [Webview tracking](https://docs.contentsquare.com/en/webview-tracking-tag/) * Handle [personal data within WebViews](https://docs.contentsquare.com/en/webview-tracking-tag/session-replay/#personal-data-handling) ### Configure UIKit custom fonts - iOS only To ensure UIKit text elements are rendered in Session Replay exactly as they appear in your app, you can add fonts in `otf`, `ttf`, `woff`, or `woff2` formats directly from the player. See [Managing iOS Fonts In The Player ↗](https://support.contentsquare.com/hc/en-us/articles/37271807874577) in the Help Center documentation. ### Test your setup #### Enable Session Replay on your device If the Session Replay sampling rate is less than 100%, only a portion of sessions are collected. To ensure data collection on your device for testing and debugging purposes, you can force it from the In-app Features settings by following these steps: 1. [Enable in-app features](../in-app-features/#enable-in-app-features) 2. Open in-app features settings with a long press on the screenshot button 3. Under "Session Replay", toggle "Enable Session Replay" on 4. Kill the app 5. Start app, a new session is starting with Session Replay enabled #### How do I know if Session Replay is enabled? * Android  There are 2 places where you can check if Session Replay is enabled: **In the logs:** The log `I/CSLIB|SessionReplay: Starting Session Replay.` will confirm that Session Replay is enabled. **In in-app features settings:** Below the "Enable "will start at next app start" *(see below [Access the replay](#access-the-replay))*, you will either see: * `No replay link available` which means Session Replay is not running for the current session * `Get Replay link` which means Session Replay is running for the current session * iOS  There are 2 places where you can check if Session Replay is enabled: **In the logs:** The log `Session Recording is starting.` will confirm that Session Replay is enabled. **In in-app features settings:** Below the "Enable "will start at next app start" *(see below [Access the replay](#access-the-replay))*, you will either see: * `No replay link available` which means Session Replay is not running for the current session * `Get Replay link` which means Session Replay is running for the current session #### Access the replay * Android The replay can be accessed by tapping on `Get replay link` button from the in-app features settings:  The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay your session up to the previous screenview if the session is still running. * iOS The session can be accessed by tapping on `Get replay link` button from the in-app features settings:  The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay your session up to the previous screenview if the session is still running. ## Personal Data Masking The Session Replay feature replays every interaction of your users with your app. To respect the user's right to privacy, the CSQ SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our [Masking rules](#masking-rules) Warning If you decide to unmask elements leading to collection of new data or use already collected data but for a different purpose, it is up to you to update your privacy declarations accordingly: * **iOS**: Update the privacy practices described in your app's Privacy Manifest. See [Types of data and purpose](../privacy/) already described in the Contentsquare React Native SDK Privacy documentation. * **Android**: Update your Google Play Data Safety declaration accordingly. Common examples of data collected via unmasked Session Replay include: search history, purchase history, advertising data, etc. **Important:** Contentsquare is not intended nor designed to collect sensitive personal data (such as health, financial, or racial data). It is the customer's responsibility not to send any sensitive personal data to Contentsquare. ### Masking mechanisms Although the implementation is done once for both iOS and Android on React Native, the visual appearance of the masking itself will be different for each platform: * Android Every single UI element is converted into a highly pixelated image to reach a very low resolution. Text and images will appear very blurry so that the content cannot be identified. #### Original vs Replay fully masked  * iOS * Images are not collected, a placeholder is sent instead of the content; the "IMG" placeholder will be displayed in the frame of the element. * Text: text is replaced by "la" repeated as many times as needed to equal the original character count. White characters are preserved. For instance `the lazy fox` is collected as `lal lala ala`. All other visual properties are collected (text color, background color, alignment, etc.). * TextFields: same as Text * For all other types: no specific data is collected but visual properties are collected. If you think a specific element can reveal personal data from one of these properties you have to mask it using one of the methods presented below. A good way to check how a view is rendered in replays is to navigate to the desired view with the CS SDK running then use the [quick replay link](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/session-replay/#access-the-replay). #### Original vs Replay fully masked  ### Masking rules Masking rules can be applied in two ways: 1. **Through remote masking configuration in the CSQ Console (for admin users):** These configurations are managed directly in the Console and take effect for all sessions as soon as the app is restarted or brought to the foreground See [How to customize masking rules from the Data Masking tab ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) in the Help Center. 2. **Using public masking APIs in the SDK (for mobile application developers):** These configurations require developer implementation and will be applied only after the mobile app has gone through its release cycle. Masking rules set via the CSQ Console or the public APIs are applied according to different priorities, as described below. The SDK determines whether a view is masked by evaluating the rules in the order specified below. Once a rule is triggered, the state is set, and subsequent rules are not applied: | Priority | Rule | Configured via | | - | - | - | | 1 | The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2 | Remote Text or Image masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3 | A [component](#maskingunmasking-specific-component) is specifically masked or unmasked | API | | 4 | A [parent](#masking-and-unmasking-behaviors-on-a-parent-view) is specifically masked or unmasked | API | | 5 | Remote Text or Image unmasking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 6 | Otherwise the [default masking state](#default-masking) is applied | API | ### Public masking APIs #### Default masking All components are initially masked by default. To modify this default masking state, use the `setDefaultMasking` API, preferably within a `useEffect` in the root file (such as `App.js`). This ensures proper initialization and handling when the component mounts. If you choose to unmask the entire app using the `setDefaultMasking` API, be aware that you will need to individually mask all personal data within the app. Additionally, ensure that you consistently mask personal data on new screens in the future, if necessary. ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; useEffect(() => { CSQ.setDefaultMasking(false); // Unmask all content }, []); ``` Note Even if you change the default masking state to `false`, the `TextInput` component will stay masked by default. #### Masking/Unmasking Specific Component Use `<CSQMask isSessionReplayMasked={true}>` (default) to mask or `{false}` to unmask all children components. In this example below, all children views inside `<CSQMask>` will follow the rule of the closest parent prop `isSessionReplayMasked`. ```jsx import { CSQMask } from '@contentsquare/react-native-bridge'; // Masks all child components <CSQMask isSessionReplayMasked={true}> <View> <Text style={styles.title}>Buy my amazing merch!</Text> <Text> Hurry up! This offer won't be available tomorrow. Only $99.98 to get your hands on a wonderful, brand-new, life-changing item. </Text> </View> </CSQMask> ``` #### Masking and Unmasking behaviors on a parent view The masking state of a parent view propagates to all nested views unless explicitly overridden by a nested `<CSQMask>` component. This enables flexible masking and unmasking behaviors within complex component structures. ```jsx import { CSQMask } from '@contentsquare/react-native-bridge'; // Masks or unmasks all child components based on isSessionReplayMasked prop <CSQMask isSessionReplayMasked={true}> <View> <Text>This content is masked.</Text> <CSQMask isSessionReplayMasked={false}> <Text>This specific content is unmasked, despite the parent mask.</Text> </CSQMask> </View> </CSQMask> ``` In this example, the inner `<CSQMask>` explicitly overrides the parent view's masking behavior. ### Implementation recommendations #### Avoid wrapping the Root Navigator `<CSQMask>` should not wrap the Root Navigator it could cause unwanted results. If you want to set the default masking behavior for the whole application you should use `CSQ.setDefaultMasking(boolean masked)`. `<CSQMask>` should be used at component level. #### Avoid dynamically changing `isSessionReplayMasked` prop While `<CSQMask>` supports toggling masking at the instance level, we do not recommend changing the `isSessionReplayMasked` prop dynamically based on conditions like this: ```jsx <CSQMask isSessionReplayMasked={someCondition ? true : false}>...</CSQMask> ``` This approach may lead to unexpected behavior, such as personal data leaks. Instead, structure your layout in a way that ensures predictable masking behavior without frequently modifying the `isSessionReplayMasked` prop dynamically. #### Keeping track of what is masked The SDK doesn't provide a list of what is currently masked. If you need to keep track of it, you probably will have to write your specific wrapper. ## Event-Triggered Replays (ETR) Event-Triggered Replays (ETR) is an add-on feature that allows you to selectively collect specific screens or sessions for Session Replay, based on predefined custom events. Once configured, ETR events can be used to filter specific replays, or view these events as they happen in the player event stream. To enable ETR, contact your CSM or Implementation Manager. For more information, see [Event-Triggered Replays ↗](https://support.contentsquare.com/hc/en-us/articles/4412027865874) in the Help Center. Note When ETR is enabled, the SDK collects data for the entire session even if none of the ETR methods described below are called. After collection, only the sessions or screens that match the global replay sampling rate or are associated with ETR events are retained. As a result, you may notice a network activity during all sessions, regardless of whether ETR has been triggered or not. Warning To protect end-user personal data, ensure that appropriate masking configurations are applied to all screens even the ones that are not associated with ETR events. ### Trigger Replay for the Session Use the following function to trigger Session Replay for the entire current session, with the parameter `name` as "ETR event". ```javascript CSQ.triggerReplayForCurrentSession(name); ``` ### Trigger Replay for the Screen Use the following function to trigger Session Replay for the entire current screen, with the parameter `name` as "ETR event". ```javascript CSQ.triggerReplayForCurrentScreen(name); ``` ## Advanced features for Experience Monitoring Note This feature is part of [Experience Monitoring ↗](https://contentsquare.com/platform/experience-monitoring/), which is only available on Enterprise plans or as an add-on to Pro plans. Contact your Customer Success Manager or [sales ↗](https://contentsquare.com/request-a-demo/) to learn more. ### Send user identifier Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier: email, phone number, customer ID… As these values are typically personal data, from the moment the SDK is collecting the User Identifier, we immediately encode the value using a hashing algorithm so that the information is hidden and can never be accessed. Use the following code to send a user identifier: ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; CSQ.sendUserIdentifier('any_identifier'); ``` When called, the SDK will log: * Android ```plaintext I/CSLIB: User identifier hashed sent {value} ``` * iOS ```plaintext CSLIB ℹ️ Info: User identifier hashed sent {value} ``` #### Sending a user identifier for each session You may want to send the user identifier for each session. While triggering the user identifier at app launch will cover most cases, it will not be enough. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See Session definition section for more information. That is why we also recommend sending the user identifier every time the app enters foreground. You can use [`AppState` API ↗](https://reactnative.dev/docs/appstate) to detect foreground and trigger a `sendUserIdentifier()`. #### Limitations * User identifier max length is 100 characters (if the limit is exceeded, the user identifier will not be handled and you will see an error message in the Console/Logcat) * Only the first 15 user identifiers per view will be processed on server side * The SDK will trim and lowercase user identifier * User identifier event are not visible in Log visualizer ## Integrations CSQ SDK provides the ability to retrieve the link of the replay to be attached to other vendors such as Voice of Customer or Crash reporting tools. ### Access Session Replay URL via metadata Use `onMetadataChange` to access the Session Replay URL through the metadata callback. The `sessionReplayURL` property will be updated whenever a new replay link is available. ```jsx import { CSQ } from '@contentsquare/react-native-bridge'; useEffect(() => { const unsubscribe = CSQ.onMetadataChange((metadata) => { if (metadata.sessionReplayURL) { console.log('Session Replay URL:', metadata.sessionReplayURL); // Use the replay URL for integrations currentSessionReplayLink = metadata.sessionReplayURL; } }); return () => { if (unsubscribe) { unsubscribe(); } }; }, []); ``` If you have a Contentsquare account, you can use this link to directly watch your current Session Replay on the Contentsquare Platform. The replay will be **available within 5 minutes**. Only the "ended screen views" are processed *(we know a screenview is ended when we start receiving data for the next screenview)*. This means that you will be able to replay the session up to the previous screenview if the session is still running. ### Initialization Sessions can be collected for Session Replay if the Session Replay feature has been enabled for your project and the session matches the collection criteria. The following conditions will have an impact on which sessions will be collected: * **User consent**: The users have given their **consent** (if required) * **Collection rate**: The session is being **drawn for collection** (see Collection rate below) * **Compatibility**: The **OS version** is supported. * **App version**: The **app version** is not part of the block list (see App version block list below) When Session Replay is turned off, no content specific to Session Replay is collected whatsoever. Other CSQ tracking remains unaffected by this. #### Collection rate Data collection for Session Replay is based on a percentage of the total sessions. By default data collection for Session Replay is disabled. During the early access phase, the percentage of collected sessions will be set to 1% at the beginning. It will then be adjusted according to: * The traffic on your app * The volume of collected sessions set in the contract #### Compatibility See [compatibility](../compatibility/). #### App version block list The Contentsquare team can add versions of your app in the block list to make sure Session Replay does not start on these versions. This is done when a problem is discovered on a specific version of your app, such as a Personal Data for which the masking was forgotten. This allows to keep Session Replay to work on the other app versions (especially the new ones with the fix). ### Data collection The SDK monitors the application lifecycle events and the view hierarchy, and generates Session Replay data from the behavior of the app, the content of the screen and the interaction of the user. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights. Tip Session collection will start at the 1st screenview event. ### Network and Storage By default, Session Replay data can be sent over **cellular network**. If the particular context of your app or users requires a very limited impact on cellular data consumption, **sending data over cellular network can be completely disabled**. Once disabled, data will be sent when the device is using Wi-Fi. Reach out to your Contentsquare contact that will make the adjustment in your project's configuration. #### Storage #### Android Before being sent, data is stored in local files on disk up to 20MB on Android. When the limit is reached, all collected data is dropped, and data collection continues. Then, every time the limit is reached again, the same process is applied. #### iOS Before being sent, data is stored in local files on disk up to 30MB on iOS. If the limit is reached, Session Replay is stopped. It will restart at the next app launch once the SDK is able to send the data. ### Requests The maximum request size is 1Mbyte. #### Android Requests are sent: * Every 5 seconds * On screen change * When [Replay Link API](#access-the-replay) is called #### iOS Requests are sent: * Every 10 seconds * At app hide * When [Replay Link API](#access-the-replay) is called ## Performance impact ### Android #### Performance impact mitigation Most operations related to Session Replay are performed on dedicated background threads, for a minimal impact on the main thread. If CPU usage is too high for background tasks, some expensive calculations will be discarded. To make sure of this, we run performance tests on testing applications, along with the Android profiler. If too much time is spent on the main thread, the quality level will decrease automatically: from high to medium to low to a complete stop if required. Once conditions are back to normal, quality level will be changed back to the default value set in the configuration. We defined our network strategy to have the lesser impact on CPU, memory, and data consumption of the users devices. We measure these impacts, using the Android profiler and dedicated logging system, for each release of our SDK. You can reduce the quality level if you want to favor performance impact over quality. #### Performance test results We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. The performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | Pixel 5 | | Android version | 34 (Android 14) | | Quality level | High | | Default Masking State | Disabled | Note That the numbers provided below will vary depending on the user's device and Android version. | Property | Value | | - | - | | Total % on main thread (CPU Profiling) | <15 % | | Memory overhead | 15 MB | | Session Replay data transmitted over network during 1 minute of use: | | | - with "High quality" level | <838 KB | | - with "Medium quality" level | <545 KB | | - with "Low quality" level | <369 KB | #### Additional info on performance test procedure **CPU Usage Test** We are profiling our Demo app with and without the SDK dependency by following the same use case. We are measuring the CPU peak for both versions of the app and we are computing the difference. **RAM Usage Test** We are profiling our Demo app with and without the SDK dependency by following the same use case. We are measuring the RAM usage peak for both versions of the app and we are computing the difference. **Memory Leak Test** We are profiling our demo app and we are using the ADB Monkey tool to create random user input events. During this time we are monitoring the RAM behavior for any anomaly. We are using the Memory Profiler to identify leaks. **Data consumption** We replay a predefined, repeatable, and automated user scenario on our demo app and all data sent is measured in kB/min. **JankStats** If you use the alpha library from Google to monitor the jank frames and you already have some jank frames in your application (main thread overwhelmed), you can expect an increase of 1% or 2% with Session Replay activated. Data collection for Session Replay requires to perform tasks on the main thread (screen capture and view hierarchy inspection). ### iOS We always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us. #### Performance impact mitigation Most operations related to Session Replay are performed on background threads, for the impact on the main thread to be minimal. To make sure of this, we run performance tests on testing applications, using XCTMetric and Hitch Time Ratio measures. We also set up mechanisms that stop Session Replay if we detect the feature is using too much memory. We defined our network strategy to have the lesser impact on CPU and battery of the users devices. We measure these impacts, using Apple Dev Tools, for each release of our SDK. Session Replay will also stop if we use up to 30Mbytes of local storage. You can reduce the quality level if you want to favor performance impact over quality. ### Performance test results The following performance results were obtained under the following conditions: | Condition | Value | | - | - | | Device model | iPhone 7 | | iOS version | 15.7.8 | | Test App built using Xcode version | 14.3.1 | | Test App built with Swift version | 5.8 | | Quality level | High | | Default Masking State | Disabled | We conducted the tests using a default `Master-Detail` app built using ad hoc distribution with no app thinning and with Swift symbols stripped. In the app, the SDK was making calls to the public APIs, running, and collecting data in its default state. Note The numbers provided below will vary depending on the user's device, iOS version, SDK version, and if you use Swift or not, which Swift version you use if you do, if you enabled bitcode or not and which options you used when building your IPA for App Store distribution. | Property | Value | | - | - | | Max CPU overhead | <10% | | Max RAM usage | <5MB | | Session Replay data transmitted over network during 1 minute of use | | | - with "High quality" level | <2Mbytes | | - with "Medium quality" level | <1Mbytes | | - with "Low quality" level | <900Kbytes | ## Known limitations ### Discrepancy of the default iOS Font There is a discrepancy of the default iOS Font between devices and Session Replay. ### Incomplete Animations on iOS In some cases, animations may appear incomplete or cut off in Session Replay on iOS. ### Gradient and Masked View Limitations on iOS When using `react-native-linear-gradient` or `@react-native-masked-view/masked-view` libraries, elements may not be fully displayed in your Session Replays: * Background, border, and text elements can be missing during element recreation. * Results may differ depending on whether the default masking is set to `true` or `false`. ## Troubleshooting ### Requests are not sent from an Android emulator / iOS simulator If you struggle to watch a replay collection on an emulator/simulator, it may be due to some network constraints applied on your computer (VPN, company network restrictions, etc.). Check your configuration or use a real device. See following sections for more information about our endpoints and requests: * [Android - Requests are failing](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/troubleshooting/#requests-are-failing) * [iOS - Requests are failing](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/troubleshooting/#requests-are-failing) ### Very long session on an Android emulator / iOS simulator It is important to remember that **an app kill does not end a session**. See [Session definition](../data-collection/#session-definition) for more information. If you leave the simulator/emulator running with the app in foreground, the session will not end, even if you are inactive. To better reflect actual end user behavior and avoid unusually long sessions (last hours), put the app in background or kill it. ### Elements being unmasked when scrolling on Android If you encounter an issue where elements positioned above a ScrollView appear unmasked when scrolling, it may be due to the ScrollView clipping behavior. To resolve this, add the `removeClippedSubviews={true}` property to the ScrollView. This will ensure that only the visible subviews are rendered, helping prevent masking issues. ```javascript <View> <Image source={{ uri: image }} /> <ScrollView removeClippedSubviews={true}> {items.map(item => ( <ListItem key={item.id} item={item} /> ))} </ScrollView> <View> ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Session Replay","description":"How to implement Session Replay with the Contentsquare React Native bridge","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/session-replay/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Security - React Native description: Data transfer and security information lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/security/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/security/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The React Native SDK requires specific Android permissions to function and follows Android security guidelines for deep link handling. ## App permissions The SDK includes the following permissions, which are mandatory for the SDK to operate properly: **AndroidManifest.xml** ```xml <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.READ_BASIC_PHONE_STATE" /> <uses-permission-sdk-23 android:name="android.permission.SYSTEM_ALERT_WINDOW" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> ``` | Permission | Required to | Associated with read/write operations under e-privacy directive | | - | - | - | | `android.permission.INTERNET` | Send collected data to Contentsquare servers | Yes. The end-user's data is collected for analytics purposes. | | `android.permission.READ_BASIC_PHONE_STATE` | Retrieve non-sensitive device information such as carrier name for analytics purposes | Yes. The end-user's data is collected for analytics purposes. | | `android.permission.SYSTEM_ALERT_WINDOW` | Use Contentsquare in-app features | No. This permission is solely used to display Contentsquare UI elements in our customers' apps. | | `android.permission.ACCESS_NETWORK_STATE` | Check network availability before sending data | No. This permission is solely used to check the network status check. | Note Some of these permissions involve read and write operations within the meaning of the e-privacy directive and article 82 of the French Data Protection Act, which may require the end-user's specific consent as specified above. This requirement applies in particular to customers based in the EU or targeting end-users in the EU. For more information on how to combine technical permission and legal consent, refer to the [CNIL (French data protection authority) recommendations ↗](https://www.cnil.fr/fr/permissions-applications-mobiles-recommandations-de-la-cnil-pour-respecter-la-vie-privee). ## Deep links usage in Contentsquare SDK As outlined in the [Android Security Guidelines ↗](https://developer.android.com/privacy-and-security/risks/unsafe-use-of-deeplinks), there are security risks associated with using deep links. To address these concerns, the Contentsquare SDK implements robust data validation for deep links and safeguards to prevent deep link hijacking, following these guidelines. If you have specific security concerns and prefer to remove the Contentsquare SDK deep link declaration from your application, add the following code snippet to your `AndroidManifest.xml` file inside the `<application>` tag: ```xml <application> <activity android:name="com.contentsquare.android.analytics.internal.features.deeplink.DeepLinkActivity" tools:node="remove" /> </application> ``` Removing the deep link will disable the In-app feature within your application. ## Transmission and hosting Our server uses HTTPS to make sure that data is encrypted in transport. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Security","description":"Data transfer and security information","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/security/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Third-party libraries license - React Native description: Contentsquare includes several third-party libraries, which are licensed under their own respective licenses lastUpdated: 16 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/third-party-libraries-license/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/third-party-libraries-license/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The React Native SDK delegates to native Android and iOS SDKs; see their respective license pages below. *  ### [Android](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/third-party-libraries-license/) *  ### [iOS](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/third-party-libraries-license/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Third-party libraries license","description":"Contentsquare includes several third-party libraries, which are licensed under their own respective licenses","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/third-party-libraries-license/","inLanguage":"en","dateModified":"2026-03-16T11:28:11+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track custom variables - React Native description: Enhance analytics by capturing custom variables for detailed user behavior analysis in your React Native app with the CSQ SDK lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-custom-variables/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-custom-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Custom variables attach additional information about the screen, user, or session to screenview events. For example, they can include information on the current layout of a screen, like dark or light mode. ## Defining custom variables To define and send custom variables, follow this: ```typescript import { CSQ, CustomVar } from "@contentsquare/react-native-bridge"; const customVar1: CustomVar = { index: 1, key: "CustomVarName1", value: "CustomVarValue1", }; const customVar2: CustomVar = { index: 2, key: "CustomVarName2", value: "CustomVarValue2", }; CSQ.trackScreenview("ScreenName", [customVar1, customVar2]); ``` Warning For consistent analytics, use the same index/name pair values across your application: **Screen A** ```typescript import { CSQ, CustomVar } from "@contentsquare/react-native-bridge"; const customVar: CustomVar = { index: 3, key: "hero_banner_type", value: "carousel", }; CSQ.trackScreenview("ScreenA", [customVar]) ``` **Screen B** ```typescript import { CSQ, CustomVar } from "@contentsquare/react-native-bridge"; const customVar: CustomVar = { index: 3, key: "hero_banner_type", value: "slider", }; CSQ.trackScreenview("ScreenB", [customVar]) ``` ## Limits ### On the server side * It is possible to save up to 20 distinct custom variables per screenview. If more are received, only the first 20 custom variables, based on their `index` value, will be kept. * The `index` value of custom variable is used to determine which custom variable to be kept. Only `index` value between 1 and 20 will be taken into account. ### On the SDK side * Every custom variable is composed of `index`, `name` and `value`. * If you are using the same `index` twice in a single screen only the first (`name`, `value`) pair associated with the `index` will be kept. * In case `name` (max. 512 characters) or `value` (max. 255 characters) maximum characters length is reached, the SDK will automatically trim the exceeding characters. * If `name` or `value` are empty, the SDK will instead send the literal string `"cs-empty"`. * Use a consistent `index` for a given variable within an application - for instance, if the "screen layout" is collected with an `index` of 3, use the slot 3 for this information on every screen of the application. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track custom variables","description":"Enhance analytics by capturing custom variables for detailed user behavior analysis in your React Native app with the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-custom-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track dynamic variables - React Native description: Learn how to implement dynamic variable tracking to enrich your analytics data in your React Native application with the CSQ SDK lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-dynamic-variables/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-dynamic-variables/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Dynamic variables are additional information on the session that can be used to segment sessions. For example, they can include information on the A/B Test variations displayed to the current user. ## Defining dynamic variables To define and send a dynamic variable, directly use the key and String/Integer value: ```typescript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.addDynamicVar("cart_value", 123) CSQ.addDynamicVar("user_account_status", "premium") CSQ.addDynamicVar("ab_test_variant", "control") CSQ.addDynamicVar("session_id", 456789) ``` **Type of the value** — The value can be either a **whole number** or a **string**. For each case, available features won't be the same in the Contentsquare app: * For **whole numbers**, you will be able to do some algebra. Example: *sessions with dynamic variable key = "numberOfFriends" and value >= 10* * For **strings**, auto-completion and Regular Expression will be available. Example: *sessions with dynamic variable key = "accountType" and value = "Premium"* ## Sending a dynamic variable for each session You may want to send a dynamic variable for each session (like the user's country or store). While **triggering the dynamic variable at app launch will cover most cases, it will not be enough**. A session can start when the app is put in foreground, after staying in background for more than 30 minutes. See [Session definition](../data-collection/#session-definition) section for more information. That is why we also recommend **sending such dynamic variable every time the app enters foreground**. You can use the [`AppState` API ↗](https://reactnative.dev/docs/appstate) to detect foreground and trigger a dynamic variable. ## Limits ### On the server side * It is possible to save up to 40 distinct *dynamic variable keys* per screenview. If more are received, only the first 40 keys will be kept. * If you are using the same key twice on the same screenview, the last value associated with the key will be collected. ### On the SDK side * Every dynamic variable is composed of a pair of key (max. 50 characters) and value (max. 255 characters string or number of type `Long` between 0 and 232 - 1). In case these maximums length are reached, the SDK will automatically trim the exceeding characters. * If key or value are empty, the SDK will instead send the literal string "cs-empty". ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track dynamic variables","description":"Learn how to implement dynamic variable tracking to enrich your analytics data in your React Native application with the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-dynamic-variables/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track screens - React Native description: Learn how to implement screen tracking in your React Native app with CSQ SDK to capture user navigation patterns and screen interactions lastUpdated: 03 August 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-screens/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-screens/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Contentsquare aggregates user behavior and engagement at the screen level. To achieve this, it is necessary to provide a name for each screen by calling a dedicated screenview API. Warning Sessions without at least one screenview will be discarded. ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.trackScreenview("ScreenName"); ``` ## Screen name handling The screen name is limited to 2083 characters. However, this limit is not enforced by the SDK, but rather by the Contentsquare servers. ## Screenview after app in background The SDK triggers a screenview automatically after the app is put in background and foreground, as long as a screenview with a screen name has been triggered previously. It will use the last screen name set. ## Implementation recommendations ### General rules From a functional standpoint, we expect a screenview to be sent when: * The screen appears on the device * A modal or pop-up is displayed * A modal or pop-up is closed, returning the user to the screen * The app is brought back to the foreground (after being minimized) ### When to send your first screenview Most events collected by the SDK require a screenview event to be sent first so they can be associated with that screen; otherwise, they will be discarded. If you need to collect events from the moment the app launches, you should trigger a screenview event immediately after the SDK has started: ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; CSQ.start(StartConfig.dxa()); CSQ.optIn(); CSQ.trackScreenview("ScreenName"); ``` ## How to name screens As a general rule, keep the number of distinct screen names under 100. Since these names are used to map your app in Contentsquare, choose names that are clear and comprehensive. ### Separate words with spaces, dashes, or underscores When generating screen names with multiple words, separate them using spaces, dashes, or underscores. For instance, use `Home & Living - Home Furnishings` instead of ~~`homeLivingHomeFurnishings`~~ for a sub-category in a retail app. ### Screen name limitations Casing sensitivity Screen names are not case sensitive and will appear in lowercase on the Contentsquare platform. ```javascript CSQ.trackScreenview("ScreenName") // screenname CSQ.trackScreenview("Screen Name") // screen name CSQ.trackScreenview("screen_name") // screen_name CSQ.trackScreenview("screenname") // screenname ``` ### Use screen template/layout names As a general recommendation, use names referring to the screen template/layout rather than referring to the specific content (data). This will help: * To keep the number of distinct screen names low and therefore make Contentsquare easier to use * Remove the risk of sending Personal Data to Contentsquare List of screen types falling into that category: Product detail, Event detail, Conversation/Chat, and User profile. ### Screens with multiple states/layouts Screens can have different layouts or states depending on the user context. In this case, append its value to the screen name. **Home screen** | State | Screen name | | - | - | | App landing layout | `Home` | | Women products layout | `Home - Women` | | Men products layout | `Home - Men` | | Sales layout | `Home - Sales` | **Product Detail screen (PDP)** | State | Screen name | | - | - | | Users on a Top for Women PDP | `PDP - Clothing - Women - Tops` | | Users on a Microwave PDP | `PDP - Kitchenware - Electrics - Microwave` | | Users on a Hotel details screen | `PDP - Holiday type - Season - Board` | **User account screen** | State | Screen name | | - | - | | Overview | `My Account - Dashboard` | | Order history | `My Account - Order history` | | Returns | `My Account - Returns` | **Search screen** | State | Screen name | | - | - | | Search | `Search` | | Search results for "Skincare" products | `Search - Skincare` | | Search results error screen | `Search - Error` | **Cart screen** | State | Screen name | | - | - | | Empty cart | `Cart - Empty` | | Items have been added to the cart | `Cart - Populated` | | Issues with availability or pricing | `Cart - Error` | **Checkout screen** | State | Screen name | | - | - | | User provides name, surname, and date of birth | `Checkout - User Details` | | User provides shipping address | `Checkout - Shipping Details` | | User inputs their credit card information | `Checkout - Payment` | ## How to track sessions and screen metadata **Custom Variables** Custom variables are designed to provide additional details about the screenview or user information during end-user engagement. These variables can encompass various aspects, including screen-specific attributes or user-related information, and serve to enhance data collection and analysis. Example: * Product name: "Acme Widget" * Product color: "red" * Product price: "$19.99" [Learn how to setup Custom Variables](../track-custom-variables/) **Dynamic Variables** Dynamic variables are used to provide additional information on the session, such as the name of a campaign or the version of a variation for an A/B test integration. They can be sent at any time during a session and do not require sending a screenview. dynamic variables should be used only in segments. Example: * Campaign name: "Summer Sale 2023" * Variation version: "Version A" [Learn how to setup Dynamic Variables](../track-dynamic-variables/) ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track screens","description":"Learn how to implement screen tracking in your React Native app with CSQ SDK to capture user navigation patterns and screen interactions","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-screens/","inLanguage":"en","dateModified":"2026-08-03T15:18:26+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Product Analytics data capture - React Native description: Access to acquisition analysis and lifetime metrics by implementing the Product Analytics data capture using the CSQ SDK lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/set-up-product-analytics-data-capture/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/set-up-product-analytics-data-capture/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This page instructs how to set up Product Analytics data capture in combination with Experience Analytics. 1. Add the React Native Babel Autocapture Plugin to instrument your app code: In your `babel.config.js` file, add `@contentsquare/react-native-bridge/babel` to the plugins array: **babel.config.js** ```javascript module.exports = { presets: ['module:@react-native/babel-preset'], plugins: ['@contentsquare/react-native-bridge/babel'], }; ``` Make sure to add the plugin to all relevant `babel.config.js` files in your project, including those in any packages that contain React Native code. Autocapture Plugin Note Autocapture's babel plugin depends on the @babel/plugin-transform-react-display-name to include component names in interaction events. This is typically provided by module:metro-react-native-babel-preset, babel-preset-expo, or @react-native/babel-preset. If you aren't including any of these, you should include @babel/plugin-transform-react-display-name alongside @contentsquare/react-native-bridge/babel in your plugins section. Compatibility Notes Autocapture's Babel plugin instruments the built-in React Native components. Instrumentation of similarly named components exported by third-party libraries (for example, `react-native-gesture-handler`'s `Pressable` or `TouchableWithoutFeedback`) is not guaranteed and depends on the library's implementation. As a result, interactions with these components may not be captured automatically. 2. Add your Product Analytics Environment ID using `start()`. * Product Analytics **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")); }, []); ``` Find your environment ID `YOUR_ENVIRONMENT_ID` is either provided to you by Contentsquare or you can find it in **Account** > **Manage** > **Projects** > \[Select your project] > **Environments** within the [Product Analytics web app ↗](https://heapanalytics.com/app/). * CSQ Experience Platform (Early Access) **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")); }, []); ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 3. To capture interactions and screenviews automatically, enable autocapture by setting `enableRNAutocapture` to `true`. * Product Analytics **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, })); }, []); ``` * CSQ Experience Platform (Early Access) **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true, })); }, []); ``` 4. (Optional) If your Product Analytics environment is hosted in the EU, set the `baseUrl` option to `https://mh.ba.contentsquare.net`. * Product Analytics **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, baseUrl: "https://mh.ba.contentsquare.net", })); }, []); ``` * CSQ Experience Platform (Early Access) **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true, baseUrl: "https://mh.ba.contentsquare.net", })); }, []); ``` 5. Add the `disablePageviewAutocapture: true` option to the configuration. * Product Analytics **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, disablePageviewAutocapture: true, })); }, []); ``` * CSQ Experience Platform (Early Access) **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true, disablePageviewAutocapture: true, })); }, []); ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Product Analytics data capture","description":"Access to acquisition analysis and lifetime metrics by implementing the Product Analytics data capture using the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/set-up-product-analytics-data-capture/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track transactions - React Native description: Track transactions with the Contentsquare bridge for React Native lastUpdated: 11 December 2025 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-transactions/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-transactions/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. To associate a user's session with their potential purchases (and corresponding revenue), you must send the transaction via a dedicated API. For each transaction, we send: * Price (number, mandatory) * Currency (Currency or string, mandatory) * Transaction ID (string, optional) ```typescript import { CSQ } from "@contentsquare/react-native-bridge"; // String currency: CSQ.trackTransaction(number, string, string?) CSQ.trackTransaction(10.99, "USD"); CSQ.trackTransaction(200.99, "eur", "my_transaction"); ``` Warning **Each transaction must only be sent once**. A common mistake is to trigger the sending when the confirmation screen is displayed. This leads to triggering the transaction each time the user puts the app in background and then in foreground on the confirmation screen. ## Currency The `Currency` enum provides a list of all supported currencies, conforming to the [ISO 4217 ↗](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) standard. ```typescript import { CSQ, Currency } from "@contentsquare/react-native-bridge"; // Numeric currency (enum-based): CSQ.trackTransaction(number, Currency, string?) CSQ.trackTransaction(10.99, Currency.USD); CSQ.trackTransaction(200.99, Currency.EUR, "my_transaction"); ``` Note If the currency passed for conversion doesn't match a supported currencies, the SDK will send a currency value of `-1`. It will be processed as the default currency of the project. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track transactions","description":"Track transactions with the Contentsquare bridge for React Native","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-transactions/","inLanguage":"en","dateModified":"2025-12-11T17:02:39+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track WebViews - React Native description: Track webviews with the Contentsquare React Native SDK lastUpdated: 23 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-webviews/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-webviews/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. WebView tracking links the Contentsquare SDK to the JavaScript tag running inside your WebViews to support analytics and Session Replay for web content displayed within your app. React Native compatibility Contentsquare only supports the [`react-native-webview` ↗](https://github.com/react-native-webview/react-native-webview) library for tracking WebView components in React Native apps. Contentsquare's implementation relies on `react-native-webview` internals and is not compatible with other WebView implementations. ## Enable tracking in WebViews ### Inject the Bridge between the CS Tag in WebView mode and the SDK To inject this JavaScript, you will use our `CSQWebView` component to render your WebView, as detailed bellow. Here is a screen with a `react-native-webview` WebView component. ```jsx import { WebView } from "react-native-webview"; const WebviewWithTagScreen = () => { return ( <> <WebView source={{ uri: "https://www.mywebpage.com" }} /> </> ); }; export default WebviewWithTagScreen; ``` Let's walk through how we can inject it with a custom JavaScript interface. #### CSQWebView component To inject your WebView with the Contentsquare JavaScript WebView interface you will need to wrap your original WebView with `CSQWebView` component. `CSQWebView` component will handle all. ```jsx import { WebView } from "react-native-webview"; import { CSQWebView } from "@contentsquare/react-native-bridge"; const WebviewWithTagScreen = () => { return ( <> <CSQWebView> <WebView source={{ uri: "https://www.mywebpage.com" }} /> </CSQWebView> </> ); }; export default WebviewWithTagScreen; ``` ### Inject the CS Tag in WebView mode into your HTML page After doing all the above, in order for the implementation to be completed, you will need to make sure our **CS Tag in WebView mode** is injected on your pages. To do so, refer to 📚 [Mobile Apps WebView Tracking Documentation](https://docs.contentsquare.com/en/webview-tracking-tag/). ## Migrating from version 4.X.X to 6.X.X If you are migrating from a previous version of the Contentsquare React Native SDK, update your `CSWebView` implementation to use `CSQWebView`: ```jsx import React from "react"; import { WebView } from "react-native-webview"; import { CSQWebView } from "@contentsquare/react-native-bridge"; const WebviewWithTagScreen = () => { return ( // This method is deprecated <CSWebView url="https://www.mywebpage.com" renderWebView={(onLayout, webViewUrl) => { return ( <WebView onLayout={onLayout} source={{ uri: webViewUrl }} /> ); }} /> <CSQWebView> <WebView source={{ uri: "https://www.mywebpage.com" }} /> </CSQWebView> ); }; export default WebviewWithTagScreen; ``` ## Validate WebView tracking To validate the tracking of WebViews, refer to the platform-specific instructions. * [📚 Android documentation](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-webviews/#validating-the-implementation-on-the-web-side) * [📚 iOS documentation](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/track-webviews/#on-the-web-side) ## Known limitations For iOS only An issue has been identified with the `goBack()` method of the React Native WebView component. When this method is called, it may not be registered by Session Replay in some cases, leading to some webview pages not being replayed correctly. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track WebViews","description":"Track webviews with the Contentsquare React Native SDK","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/track-webviews/","inLanguage":"en","dateModified":"2026-04-23T15:45:56+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Troubleshooting - React Native description: Need help? We share probable causes and recommended fixes lastUpdated: 29 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/troubleshooting/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/troubleshooting/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. When the SDK is not sending data as expected, use this page to identify probable causes and apply recommended fixes. ## Requests are failing In order for Contentsquare to work, you need to make sure the following endpoints are not blocked by your network (VPN): | Request | Endpoint | Detail | | - | - | - | | Config file | `https://mobile-production.content-square.net` | See [Configuration](../data-collection/#configuration) | | Experience Analytics data (EU) | `https://m.csqtrk.net` `https://m.ba.contentsquare.net` `https://m.aa.contentsquare.net` | See [Sending data](../data-collection/#sending-data) | | Experience Analytics data (US) | `https://m-aus1.contentsquare.net` `https://m.bf.contentsquare.net` `https://m.af.contentsquare.net` | See [Sending data](../data-collection/#sending-data) | | Product Analytics data | `https://mh.bf.contentsquare.net` | See [Product Analytics](../../product-analytics/) | | Monitoring | `https://l.contentsquare.net` | Used by the SDK to send SDK monitoring analysis in JSON format over HTTPS. | | Session Replay data (EU) | `https://ka-aeu1.contentsquare.net` `https://ka.ba.contentsquare.net` `https://ka.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Session Replay data (US) | `https://ka-aus1.contentsquare.net` `https://ka.bf.contentsquare.net` `https://ka.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Screenshot (EU) | `https://s.contentsquare.net` `https://b.ba.contentsquare.net` `https://b.aa.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Screenshot (US) | `https://s-aus1.contentsquare.net` `https://b.bf.contentsquare.net` `https://b.af.contentsquare.net` | See [Screenshot capture](../in-app-features/#screenshot-capture) | | Resources manager (EU) | `https://srm.ba.contentsquare.net` `https://srm.aa.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | | Resources manager (US) | `https://srm.bf.contentsquare.net` `https://srm.af.contentsquare.net` | See [Session Replay requests](../session-replay/#requests) | ## Known limitations ### React Native Webview goBack() Warning iOS only: When the `goBack()` method of the React Native WebView component is called, it may not be registered by Session Replay in some cases, leading to some webview pages not being replayed correctly. ### Use of PanResponder If you are using PanResponders in your app, a bug might appear on the element implementing it where it will only move for about a second and then freeze. This bug is caused by a conflict between the React Native SDK and our Bridge related to tracking swipe events. The workaround is to stop Contentsquare tracking when the pan gesture starts, and resume it as the gesture ends, as follows: ```javascript const panResponder = useRef( PanResponder.create({ [...] onPanResponderGrant: (evt, gestureState) => { Contentsquare.stopTracking(); [...] }, onPanResponderRelease: (evt, gestureState) => { Contentsquare.resumeTracking(); [...] }, [...] }) ).current; ``` Applying this workaround fixes the bug, but Contentsquare will no longer track swipes on views using the PanResponder. ### Long Screenshot Not Supported Long Screenshot is not currently supported in React Native. This feature captures and analyzes long scrollable screens such as product listing pages or user profiles for enhanced Zoning Analysis, and is only available in Flutter, iOS, and Android native SDKs. Warning If Long Screenshot has been enabled in your React Native project, expect limitations and inconsistencies in capturing extended scrollable views. Contact your Customer Success Manager to discuss mitigation strategies for your implementation. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Troubleshooting","description":"Need help? We share probable causes and recommended fixes","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/troubleshooting/","inLanguage":"en","dateModified":"2026-07-29T20:57:49+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Contentsquare SDK to CSQ SDK - React Native description: Learn how to migrate from the Contentsquare SDK to the CSQ SDK lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This guide provides a step-by-step upgrade process from your current installation of Contentsquare Mobile SDK to the latest version of the CSQ SDK.  **Contentsquare SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. ## Contentsquare React Native SDK 6.0.0 and later From version 6.0.0 onward, the Contentsquare React Native SDK includes the new CSQ SDK. Update your `package.json` to use the latest version of the Contentsquare React Native SDK: * yarn ```shell yarn add @contentsquare/react-native-bridge@latest ``` * npm ```shell npm install @contentsquare/react-native-bridge@latest ``` ## Library imports Replace the Contentsquare SDK import with a CSQ SDK import. ```diff import Contentsquare from "@contentsquare/react-native-bridge"; import { CSQ } from '@contentsquare/react-native-bridge'; ``` Replace the `Error Analysis` import if present: ```diff import { ErrorAnalysis } from "@contentsquare/react-native-bridge"; import { CSQ } from "@contentsquare/react-native-bridge"; ``` Replace masking component import if present: ```diff import { CSMask } from "@contentsquare/react-native-bridge"; import { CSQMask } from "@contentsquare/react-native-bridge"; ``` Replace webView injection component import if present: ```diff import { CSWebView } from "@contentsquare/react-native-bridge"; import { CSQWebView } from "@contentsquare/react-native-bridge"; ``` ## SDK start Start the CSQ SDK manually using `start()` — unlike earlier versions, it no longer starts automatically. **App.js** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.dxa()); }, []); ``` Note * Android (Optional) If you have chosen to deactivate the autostart of the Contentsquare SDK, you can now remove the entry in the manifest, as the CSQ SDK doesn't have an autostart. **AndroidManifest.xml** ```xml <application> ... <meta-data android:name="com.contentsquare.android.autostart" android:value="false" /> ... </application> ``` * iOS (Optional) If you were relying on the Contentsquare SDK autostart, remove the `CSDisableAutostart` property and calls to `Contentsquare.start()`. **Info.plist** ```xml <key>CSDisableAutostart</key> <true/> ``` **AppDelegate.swift** ```swift Contentsquare.start() ``` ## Get user consent The CSQ SDK treats users as opted-out by default. Implement the [`optIn()`](../command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. ```javascript import React, { useState } from "react"; import { View, Text, Button } from "react-native"; import { CSQ } from "@contentsquare/react-native-bridge"; const PolicyConsentScreen = () => { const [isTrackingAccepted, setIsTrackingAccepted] = useState(false); const handleAcceptPolicy = () => { setIsTrackingAccepted(true); CSQ.optIn(); }; return ( <View> <Text>Please accept our privacy policy to proceed.</Text> <Button title="Accept Policy" onPress={handleAcceptPolicy} /> </View> ); }; export default PolicyConsentScreen; ``` ## Number of sessions Session timeout definition changed: * **Before**: 30 minutes after app goes to background * **Now**: 30 minutes after last event This may affect session counts and aligns with web and market standards. ## Update APIs and components Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. In most cases, this process consists in updating the namespace and method names, with no changes to parameters. ```javascript Contentsquare.start() CSQ.start(StartConfig.dxa()) ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### GDPR / Identification | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.optIn()` | `CSQ.optIn()` | | `Contentsquare.optOut()` | `CSQ.optOut()` | | `Contentsquare.sendUserIdentifier(userIdentifier: string)` | `CSQ.sendUserIdentifier(userIdentifier: string)` | #### User id ```diff useEffect(() => { Contentsquare.getUserId(userId => { console.log(`Your Contentsquare UserID is ${userId}`); }); const onMetadataChangeUnsubscribe = CSQ.onMetadataChange(metadata => { console.log(`Your Contentsquare UserID is ${metadata.userID}`); }); return () => { onMetadataChangeUnsubscribe(); }; }, []); ``` ### Property tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.sendDynamicVar(key: string, value: string \| number, onError?: (error: Error))` | `CSQ.addDynamicVar(key: string, value: string \| number, onError?: (error: Error))` | ### Interoperability #### Session Replay URL ```diff useEffect(() => { const sessionReplayLinkSubscriber = Contentsquare.onSessionReplayLinkChange(link => { Alert.alert(`New link copied to the clipboard ${link}`); const onMetadataChangeUnsubscribe = CSQ.onMetadataChange(metadata => { Alert.alert(`New link copied to the clipboard ${metadata.sessionReplayUrl}`); }); return () => { if (sessionReplayLinkSubscriber) { sessionReplayLinkSubscriber.remove(); } if (onMetadataChangeUnsubscribe) { onMetadataChangeUnsubscribe(); } }; }, []); ``` #### Webview component ```diff import { CSWebView } from "@contentsquare/react-native-bridge"; import WebView from 'react-native-webview'; import { CSQWebView } from "@contentsquare/react-native-bridge"; <CSWebView> <CSQWebView> <WebView source={{ uri: 'https://www.example.com' }} /> </CSWebView> </CSQWebView> ``` ### Event tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.sendTransaction(value: number, currency: Currency \| string, id?: string \| null)` | `CSQ.trackTransaction(value: number, currency: Currency \| string, id?: string \| null)` | | `Contentsquare.send(screenName: string, cvars?: CustomVar[])` | `CSQ.trackScreenview(name: string, cvars?: CustomVar[])` | ### Error tracking | Contentsquare SDK | CSQ SDK | | - | - | | `ErrorAnalysis.setURLMaskingPatterns(patterns: string[])` | `CSQ.setURLMaskingPatterns(patterns: string[])` | | `ErrorAnalysis.triggerNativeCrash()` | `CSQ.triggerNativeCrash()` | ### Personal Data Handling and Masking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.setDefaultMasking(masked: Boolean)` | `CSQ.setDefaultMasking(masked: Boolean)` | #### Masking component ```diff import { CSMask } from "@contentsquare/react-native-bridge"; import { CSQMask } from "@contentsquare/react-native-bridge"; <CSMask isMasking={true}> <CSQMask isSessionReplayMasked={true}> {/* Your masked content goes here */} </CSMask> </CSQMask> ``` ### SDK initialization and manipulation | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.start()` | `CSQ.start(StartConfig.dxa())` | | `Contentsquare.stopTracking()` | `CSQ.pauseTracking()` | | `Contentsquare.resumeTracking()` | `CSQ.resumeTracking()` | ### CSInApp | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.handleUrl(urlString: string \| null \| undefined)` | `CSQ.handleUrl(urlString: string \| null \| undefined)` | ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that you are using a version 6.0.0 or later of the Contentsquare React Native SDK. Your `import Contentsquare from "@contentsquare/react-native-bridge"` and `import { ErrorAnalysis } from "@contentsquare/react-native-bridge"` declarations have been updated to `import { CSQ } from "@contentsquare/react-native-bridge"`. You no longer have references to `Contentsquare.` or `ErrorAnalysis.` methods in your codebase. You no longer have references to `CSMask` or `CSWebView` components in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Contentsquare SDK to CSQ SDK","description":"Learn how to migrate from the Contentsquare SDK to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-cs-sdk/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Core SDK + Contentsquare SDK to CSQ SDK - React Native description: Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK lastUpdated: 29 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-heap-and-cs-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-heap-and-cs-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This guide provides a step-by-step upgrade process from your current installation of Contentsquare and Heap Mobile to the latest version of the CSQ SDK.  **Heap Core SDK** \+  **Contentsquare SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. ## Dependency upgrades Replace Heap and Contentsquare SDK dependencies by the CSQ SDK: * yarn ```shell yarn remove @heap/heap-react-native-autocapture @heap/heap-react-native-bridge @heap/heap-react-native-cs-integration @heap/babel-plugin-heap-react-native-autocapture yarn add @contentsquare/react-native-bridge cd ios && pod install ``` * npm ```shell npm uninstall @heap/heap-react-native-autocapture @heap/heap-react-native-bridge @heap/heap-react-native-cs-integration @heap/babel-plugin-heap-react-native-autocapture npm install @contentsquare/react-native-bridge cd ios && pod install ``` ## Library imports Replace the Heap and Contentsquare dependency imports with a CSQ SDK import. ```diff import { Heap } from '@heap/heap-react-native-bridge'; import { registerHeapAutocapture } from '@heap/heap-react-native-autocapture'; import Contentsquare from "@contentsquare/react-native-bridge"; import { bind } from '@heap/heap-react-native-cs-integration'; import { CSQ } from "@contentsquare/react-native-bridge"; ``` ## SDK start Follow these steps to start the CSQ SDK with your current configuration. 1. Migrate your app ID and the config options from `Heap.startRecording()` to `start()`. * Product Analytics **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { Heap.startRecording("YOUR_ENVIRONMENT_ID"); CSQ.start( StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID") ); }, []); ``` * CSQ Experience Platform (Early Access) **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { Heap.startRecording("YOUR_ENVIRONMENT_ID"); CSQ.start( StartConfig.withDataSourceId("YOUR_DATASOURCE_ID") ); }, []); ``` Deprecated configuration options The following Heap SDK configuration options are not supported in the CSQ SDK: * `startSessionImmediately` * `resumePreviousSession` * `captureVendorId` * `captureAdvertiserId` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `pruningLookBackWindow` * `maximumDatabaseSize` * `maximumBatchCountPerUpload` * `disableScreenviewForwardToDXA` * `disableScreenviewForwardToPA` See [supported options](../command-reference/#product-analytics-initialization-options) for more information. 2. For React Native Autocapture, replace the babel plugin from `@heap/heap-react-native-autocapture` to `@contentsquare/react-native-bridge/babel` in your babel configuration. * babel.config.js **babel.config.js** ```diff module.exports = { presets: ['module:metro-react-native-babel-preset'], plugins: ['@heap/heap-react-native-autocapture'], plugins: ['@contentsquare/react-native-bridge/babel'], }; ``` * babel.config.json **babel.config.json** ```diff { "presets": [ "module:metro-react-native-babel-preset" ], "plugins": [ "@heap/heap-react-native-autocapture" "@contentsquare/react-native-bridge/babel" ] } ``` 3. For React Native Autocapture, replace `registerHeapAutocapture()` with `enableRNAutocapture = true` option: * Product Analytics **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { registerHeapAutocapture(); CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true })); }, []); ``` * CSQ Experience Platform (Early Access) **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { registerHeapAutocapture(); CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true })); }, []); ``` 4. Remove `HeapContentsquareIntegration.bind()`. Sending Heap screenviews to Contentsquare **App.tsx** ```javascript bind({ sendHeapPageviewsToContentsquare: true }); ``` Note Make sure you don't have calls to `CSQ.trackScreenview()` if you have React Native View autocapture enabled. Sending Contentsquare screenviews to Heap * Product Analytics **App.tsx** ```javascript bind({ sendHeapPageviewsToContentsquare: true }); CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { disablePageviewAutocapture: true, })); ``` * CSQ Experience Platform (Early Access) **App.tsx** ```javascript bind({ sendHeapPageviewsToContentsquare: true }); CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { disablePageviewAutocapture: true, })); ``` 5. (Optional) If you have chosen to deactivate the autostart of the Contentsquare SDK, you can now remove the entry in the manifest, as the CSQ SDK doesn't have an autostart. **AndroidManifest.xml** ```xml <application> ... <meta-data android:name="com.contentsquare.android.autostart" android:value="false" /> ... </application> ``` ## Get user consent The CSQ SDK treats users as opted-out by default. ```javascript import React, { useState } from "react"; import { View, Text, Button } from "react-native"; import { CSQ } from "@contentsquare/react-native-bridge"; const PolicyConsentScreen = () => { const [isTrackingAccepted, setIsTrackingAccepted] = useState(false); const handleAcceptPolicy = () => { setIsTrackingAccepted(true); CSQ.optIn(); }; return ( <View> <Text>Please accept our privacy policy to proceed.</Text> <Button title="Accept Policy" onPress={handleAcceptPolicy} /> </View> ); }; export default PolicyConsentScreen; ``` Implement the [`optIn()`](../command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. In most cases, this process consists in updating the namespace and method names, with no changes to parameters. * Product Analytics ```javascript Contentsquare.start() Heap.startRecording("YOUR_ENVIRONMENT_ID") CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")) ``` * CSQ Experience Platform (Early Access) ```javascript Contentsquare.start() Heap.startRecording("YOUR_ENVIRONMENT_ID") CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")) ``` The latest version of our CSQ SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. For more information on SDK methods, see the [SDK API reference](../command-reference/). ### Product Analytics ### GDPR / Identification | Heap Core SDK | CSQ SDK | | - | - | | `Heap.identify(identity: string)` | `CSQ.identify(identity: string)` | | `Heap.resetIdentity()` | `CSQ.resetIdentity()` | ```javascript const getUserInformation = async () => { const heapUserId = await Heap.getUserId(); const heapSessionId = await Heap.getSessionId(); const heapEnvId = await Heap.getEnvironmentId(); const heapIdentity = await Heap.getIdentity(); }; useEffect(() => { const onMetadataChangeUnsubscribe = CSQ.onMetadataChange(metadata => { const userId = metadata.userID; const sessionId = metadata.sessionID; const environmentId = metadata.environmentID; const identity = metadata.identity; }); return () => { onMetadataChangeUnsubscribe(); }; }, []); ``` ### Logging | Heap Core SDK | CSQ SDK | | - | - | | `import { Heap, LogLevel } from '@heap/heap-react-native-bridge'` | `import { CSQ, LogLevel } from "@contentsquare/react-native-bridge"` | | `Heap.logToConsole()` | `CSQ.logToConsole()` | | `Heap.setLogLevel(logLevel: LogLevel)` | `CSQ.setLogLevel(logLevel: LogLevel)` | | `Heap.setLogChannel(LogChannel: (logLevel: LogLevel, message: string, source: string \| null \| undefined) => void)` | `CSQ.setLogChannel(logChannel: (logLevel: LogLevel, message: string, source: string \| null \| undefined) => void)` | ### Property tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.addUserProperties(properties: Properties)` | `CSQ.addUserProperties(properties: Record<string, PropertyValue>)` | | `Heap.addEventProperties(properties: Properties)` | `CSQ.addEventProperties(properties: Record<string, PropertyValue>)` | | `Heap.removeEventProperty(name: string)` | `CSQ.removeEventProperty(name: string)` | | `Heap.clearEventProperties()` | `CSQ.clearEventProperties()` | ### Event tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.track(event: string, properties?: Properties \| null, timestamp?: Date \| null, sourceInfo?: SourceInfo \| null, pageview?: Pageview \| 'none' \| null)` | `CSQ.trackEvent(event: string, properties?: Record<string, PropertyValue>)` `CSQ.trackScreenview(name: string, cvars?: CustomVar[])` | ### Personal Data Handling and Masking | Heap Core SDK | CSQ SDK | | - | - | | `\<HeapIgnore>` | `\<CSQMask>` | | `\<HeapIgnoreText>` | `\<CSQMask ignoreTextOnly>` | | `withHeapIgnore` | `withCSQMask` | ### SDK initialization and manipulation | Heap Core SDK | CSQ SDK | | - | - | | Heap SDK initialization options | `CSQ.start(StartConfig.withEnvironmentId(id, options?))` See [supported options](../command-reference/#product-analytics-initialization-options) for more information. | | `Heap.startRecording(environmentId: string, options?: Options)` | `CSQ.start(StartConfig.withEnvironmentId(id))` | | `Heap.stopRecording()` | `CSQ.stop()` or `CSQ.pauseTracking()` | Deprecated `CSQ.configureProductAnalytics(environmentId, options?)` is deprecated since CSQ React Native SDK 6.3.0. Use `CSQ.start(StartConfig.withEnvironmentId(id, options?))` to combine SDK configuration and initialization in a single call. ### Autocapture options * Product Analytics ```javascript Heap.startRecording("YOUR_APP_ID", { disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, }); CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, })); ``` * CSQ Experience Platform (Early Access) ```javascript Heap.startRecording("YOUR_APP_ID", { disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, }); CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true, disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, })); ``` ### Experience Analytics ### GDPR / Identification | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.optIn()` | `CSQ.optIn()` | | `Contentsquare.optOut()` | `CSQ.optOut()` | | `Contentsquare.sendUserIdentifier(userIdentifier: string)` | `CSQ.sendUserIdentifier(userIdentifier: string)` | #### User id ```diff useEffect(() => { Contentsquare.getUserId(userId => { console.log(`Your Contentsquare UserID is ${userId}`); }); const onMetadataChangeUnsubscribe = CSQ.onMetadataChange(metadata => { console.log(`Your Contentsquare UserID is ${metadata.userID}`); }); return () => { onMetadataChangeUnsubscribe(); }; }, []); ``` ### Property tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.sendDynamicVar(key: string, value: string \| number, onError?: (error: Error))` | `CSQ.addDynamicVar(key: string, value: string \| number, onError?: (error: Error))` | ### Interoperability #### Session Replay URL ```diff useEffect(() => { const sessionReplayLinkSubscriber = Contentsquare.onSessionReplayLinkChange(link => { Alert.alert(`New link copied to the clipboard ${link}`); const onMetadataChangeUnsubscribe = CSQ.onMetadataChange(metadata => { Alert.alert(`New link copied to the clipboard ${metadata.sessionReplayUrl}`); }); return () => { if (sessionReplayLinkSubscriber) { sessionReplayLinkSubscriber.remove(); } if (onMetadataChangeUnsubscribe) { onMetadataChangeUnsubscribe(); } }; }, []); ``` #### Webview component ```diff import { CSWebView } from "@contentsquare/react-native-bridge"; import WebView from 'react-native-webview'; import { CSQWebView } from "@contentsquare/react-native-bridge"; <CSWebView> <CSQWebView> <WebView source={{ uri: 'https://www.example.com' }} /> </CSWebView> </CSQWebView> ``` ### Event tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.sendTransaction(value: number, currency: Currency \| string, id?: string \| null)` | `CSQ.trackTransaction(value: number, currency: Currency \| string, id?: string \| null)` | | `Contentsquare.send(screenName: string, cvars?: CustomVar[])` | `CSQ.trackScreenview(name: string, cvars?: CustomVar[])` | ### Error tracking | Contentsquare SDK | CSQ SDK | | - | - | | `ErrorAnalysis.setURLMaskingPatterns(patterns: string[])` | `CSQ.setURLMaskingPatterns(patterns: string[])` | | `ErrorAnalysis.triggerNativeCrash()` | `CSQ.triggerNativeCrash()` | ### Personal Data Handling and Masking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.setDefaultMasking(masked: Boolean)` | `CSQ.setDefaultMasking(masked: Boolean)` | #### Masking component ```diff import { CSMask } from "@contentsquare/react-native-bridge"; import { CSQMask } from "@contentsquare/react-native-bridge"; <CSMask isMasking={true}> <CSQMask isSessionReplayMasked={true}> {/* Your masked content goes here */} </CSMask> </CSQMask> ``` ### SDK initialization and manipulation | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.start()` | `CSQ.start(StartConfig.dxa())` | | `Contentsquare.stopTracking()` | `CSQ.pauseTracking()` | | `Contentsquare.resumeTracking()` | `CSQ.resumeTracking()` | ### CSInApp | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.handleUrl(urlString: string \| null \| undefined)` | `CSQ.handleUrl(urlString: string \| null \| undefined)` | ## Number of sessions Session timeout definition changed: * **Before**: 30 minutes after app goes to background * **Now**: 30 minutes after last event This may affect session counts and aligns with web and market standards. ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that you are using a version 6.0.0 or later of the Contentsquare React Native SDK. Your `import Contentsquare from "@contentsquare/react-native-bridge"` and `import { ErrorAnalysis } from "@contentsquare/react-native-bridge"` declarations have been updated to `import { CSQ } from "@contentsquare/react-native-bridge"`. Your `import { Heap } from '@heap/heap-react-native-bridge'` and `import { registerHeapAutocapture } from '@heap/heap-react-native-autocapture'` import declarations have been updated to `import { CSQ} from "@contentsquare/react-native-bridge"`. You no longer have references to `Heap.` or `Contentsquare.` methods in your codebase. You no longer have references to `CSMask` or `CSWebView` components in your codebase. You no longer have references to `<HeapIgnore>`, `<HeapIgnoreText>` or `withHeapIgnore` components in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK + Contentsquare SDK to CSQ SDK","description":"Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-from-heap-and-cs-sdk/","inLanguage":"en","dateModified":"2026-04-29T12:02:25+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Upgrade your SDK - React Native description: Understand the benefits of upgrading to the CSQ SDK lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-your-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-your-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This section guides you through the upgrade from your current SDK implementation to our latest CSQ SDK. Upgrading has no impact on your current data collection and does not alter the data observed on the platform. It mainly consists of searching and replacing APIs according to the mappings provided in the upgrade guides. Get started by selecting the upgrade guide that corresponds to your current implementation: * **[Contentsquare SDK](../upgrade-from-cs-sdk/)** - Upgrade from the legacy Contentsquare SDK * **[Heap SDK + Contentsquare SDK](../upgrade-from-heap-and-cs-sdk/)** - Upgrade from combined Heap and Contentsquare SDKs ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Upgrade your SDK","description":"Understand the benefits of upgrading to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/upgrade-your-sdk/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Agent skills for React Native - React Native description: Use AI coding assistants to integrate, upgrade, and configure the Contentsquare React Native SDK with downloadable Agent skills lastUpdated: 16 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/using-agent-skills/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/using-agent-skills/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use the Contentsquare wizard or skills to set up, update, and configure React Native with your AI coding assistant. Disclaimer This skill guides your AI coding agent through the SDK installation and implementation. The agent you use (Cursor, Claude Code, Copilot) is your own tool and operates under your settings and permissions. Contentsquare is not responsible for how your agent interprets or applies the instructions contained in these files. ## Contentsquare wizard Run the wizard in your project directory. It configures your AI coding assistant, installs the matching Contentsquare integration, and verifies the installation. ```shell npx @contentsquare/wizard install ``` Supports GitHub Copilot, Cursor, and Claude Code. Requires Node.js ≥ 18 and an AI coding agent with MCP support. ## Manual setup Use this path when you prefer to configure your AI coding assistant yourself. ### 1. Add the Contentsquare skill Choose how to install the Contentsquare skill. * Copilot CLI Add the Contentsquare marketplace, then install the plugin for React Native: ```shell copilot plugin marketplace add ContentSquare/agents copilot plugin install contentsquare-reactnative@contentsquare ``` * Claude Code Add the Contentsquare marketplace, then install the plugin for React Native: ```shell /plugin marketplace add ContentSquare/agents /plugin install contentsquare-reactnative@contentsquare ``` * Cursor Install **contentsquare** from the [Cursor marketplace ↗](https://cursor.com/marketplace), or add the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents) directly. Cursor reads the `.cursor-plugin` catalog in the repository. * Other agents Install the Contentsquare skill pack with the open `skills.sh` ecosystem: ```shell npx skills add contentsquare/agents ``` * From source Download or clone the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents), then copy `skills/contentsquare-reactnative-sdk` into the location your AI coding assistant scans for skills: | AI coding assistant | Skill location | | - | - | | GitHub Copilot | `.github/skills/` or `.agents/skills/` | | Cursor | `.cursor/rules/` or the project root | | Claude Code | `.claude/skills/` or the project root | | Other compatible agents | `.agents/skills/` | ### 2. Ask your AI coding assistant After installing the skill, paste this prompt into your AI coding assistant: ```text Install Contentsquare for React Native. ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Agent skills for React Native","description":"Use AI coding assistants to integrate, upgrade, and configure the Contentsquare React Native SDK with downloadable Agent skills","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/using-agent-skills/","inLanguage":"en","dateModified":"2026-07-16T17:50:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: SDK API reference - React Native description: SDK commands reference including signature, parameter descriptions, and examples lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/command-reference/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-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:** `6.0.0` Get user consent. Calling this API generates a user ID and initiates tracking. Call [`optIn`](#csqoptin) after [`start`](#csqstart). ```javascript CSQ.optIn(); ``` ### CSQ.optOut **Added in:** `6.0.0` Revoke user consent, remove stored `userID`. Stop CSQ SDK, flush, and clear all data. ```javascript CSQ.optOut(); ``` ### CSQ.identify 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. 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`. ```javascript CSQ.identify("user_identity"); ``` #### Parameters * #### identity  string (<= 100 chars)   Identity to be associated with the current user. ### CSQ.resetIdentity **Added in:** `6.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. ```javascript CSQ.resetIdentity(); ``` ### CSQ.sendUserIdentifier Experience Analytics | **Added in:** `6.0.0` Associate the user identifier to the session. ```javascript CSQ.sendUserIdentifier("any_identifier") ``` #### Parameters * #### userIdentifier  string   The user identifier to track. Should be max 100 characters long. ### CSQ.onMetadataChange **Added in:** `6.0.0` Get all the information related to the user and project. Refer to the [`CSQMetadata`](#csqmetadata) object. ```javascript CSQ.onMetadataChange(callback: (metadata: CSQMetadata) => void) => { // Handle metadata change }); ``` #### Parameters * #### callback  (metadata: CSQMetadata) => void   Callback function triggered when metadata changes. ### `CSQMetadata` `CSQMetadata` object contains information related to the user and project. ```javascript interface CSQMetadata { userID: string | null; sessionID: string | null; identity: string | null; environmentID: string | null; projectID: string | null; sessionReplayURL: string | null; } ``` #### `userID` Identifier of the current user. This is an identifier from Product Analytics by default or Experience Analytics if PA is not active. #### `sessionID` Session identifier. This is an identifier from Experience Analytics by default or Product Analytics if Experience Analytics is not active. #### `projectID` Project identifier for Experience Analytics. #### `environmentID` Environment identifier for Product Analytics. #### `sessionReplayURL` URL of current Session Replay. #### `identity` Identity associated with the user by calling [`identify()`](#csqidentify). ## Property Tracking ### CSQ.addDynamicVar 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 ```javascript CSQ.addDynamicVar("key1", "value1") CSQ.addDynamicVar("key2", 2, (errorObject) => { console.log(errorObject.toString()); }); ``` #### Parameters * #### key  string   Dynamic variable key * #### value  string   Dynamic variable value * #### callback  (error: Error) => void (optional)   Optional callback function to handle errors. ### CSQ.addUserProperties Product Analytics | **Added in:** `6.0.0` Add a collection of properties to be associated with the current user. ```javascript CSQ.addUserProperties({ propertyKey: "propertyValue", }); ``` #### Parameters * #### properties  Record\<string, PropertyValue   A dictionary of user properties. `PropertyValue` can be `number`, `string`, `boolean`, `bigint` ### CSQ.addEventProperties Product Analytics | **Added in:** `6.0.0` Add a collection of properties to be associated with all future events. ```javascript CSQ.addEventProperties({ propertyKey: "propertyValue", }); ``` #### Parameters * #### properties  Record\<string, PropertyValue>   A dictionary of event properties. `PropertyValue` can be `number`, `string`, `boolean`, `bigint` ### CSQ.removeEventProperty Product Analytics | **Added in:** `6.0.0` Removes a single property from the collection of event-wide properties. ```javascript CSQ.removeEventProperty("propertyKey") ``` #### Parameters * #### name  string   The key of the property to remove. ### CSQ.clearEventProperties Product Analytics | **Added in:** `6.0.0` Removes all event-wide properties. ```javascript CSQ.clearEventProperties() ``` ## CSInApp ### CSQ.handleUrl 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](../../experience-analytics/in-app-features/). ```javascript CSQ.handleUrl("sample_url") ``` #### Parameters * #### urlString  string | null | undefined   The URL handled by [React Native Linking API ↗](https://reactnative.dev/docs/linking). ## Interoperability ### \<CSQWebView> Experience Analytics | **Added in:** `6.0.0` Allows Contentsquare SDK to track webviews. ```javascript <CSQWebView> <WebView source={{ uri: "https://test-url.com", }} /> </CSQWebView> ``` #### Parameters * #### children  ReactElement   The webview to register for tracking. CSQWebView supports [react-native-webview ↗](https://github.com/react-native-webview/react-native-webview). ## Event Tracking ### CSQ.trackTransaction Experience Analytics | **Added in:** `6.0.0` Send a transaction. ```javascript CSQ.trackTransaction(10, Currency.EUR, "transactionId"); ``` #### Parameters * #### 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. ### CSQ.trackScreenview **Added in:** `6.0.0` Send a screen view with or without custom variables. Requires Experience Analytics to be started. ```javascript CSQ.trackScreenview(name: "ScreenName", cvars: [{index: 0, key: "key", value: "value"}]) ``` #### Parameters * #### 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 ### CSQ.trackEvent Product Analytics | **Added in:** `6.0.0` Creates an event message to be tracked and sent to the API. ```javascript CSQ.trackEvent('event', { some_property: 100 }); ``` #### Parameters * #### 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`. ## Logging ### CSQ.logToConsole Product Analytics | **Added in:** `6.0.0` Enables logging to the console for Product Analytics events and diagnostics. ```javascript CSQ.logToConsole(); ``` ### CSQ.setLogChannel Product Analytics | **Added in:** `6.0.0` Sets the log channel for Product Analytics logging. ```javascript import { LogChannel } from '@contentsquare/react-native-bridge'; CSQ.setLogChannel(LogChannel.LOG); ``` #### Parameters * #### logChannel  LogChannel   The log channel to use. Available values: * `LogChannel.LOG` * `LogChannel.TRACE` * `LogChannel.DEBUG` * `LogChannel.INFO` * `LogChannel.WARN` * `LogChannel.ERROR` * `LogChannel.NONE` ### CSQ.setLogLevel Product Analytics | **Added in:** `6.0.0` Sets the log level for Product Analytics logging. ```javascript import { LogLevel } from '@contentsquare/react-native-bridge'; CSQ.setLogLevel(LogLevel.INFO); ``` #### Parameters * #### logLevel  LogLevel   The log level to use. Available values: * `LogLevel.TRACE` * `LogLevel.DEBUG` * `LogLevel.INFO` * `LogLevel.WARN` * `LogLevel.ERROR` * `LogLevel.NONE` ## Error tracking ### CSQ.setUrlMaskingPatterns Experience Analytics | **Added in:** `6.0.0` Sets URL masking patterns. ```javascript CSQ.setUrlMaskingPatterns(["pattern1", "pattern2"]) ``` #### Parameters * #### patterns  string\[]   A list of URL patterns to mask. ### CSQ.triggerNativeCrash Experience Analytics | **Added in:** `6.0.0` Trigger a native crash for testing purposes. ```javascript CSQ.triggerNativeCrash() ``` ## Session Replay ### CSQ.startSessionReplay **Added in:** `6.3.0` Starts Session Replay. Use this when you have set [`sessionReplayAutoStart`](#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. ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.startSessionReplay(); ``` ### CSQ.stopSessionReplay **Added in:** `6.3.0` Stops Session Replay collection. Any data collected before this call is preserved and uploaded according to the SDK upload schedule. ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.stopSessionReplay(); ``` ### CSQ.triggerReplayForCurrentSession **Added in:** `6.4.0` Triggers Session Replay for the entire current session, with the parameter name as "ETR event". ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.triggerReplayForCurrentSession("ETR event"); ``` ### CSQ.triggerReplayForCurrentScreen **Added in:** `6.4.0` Triggers Session Replay for the entire current screen, with the parameter name as "ETR event". ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.triggerReplayForCurrentScreen("ETR event"); ``` ## Personal Data/Masking ### CSQ.setDefaultMasking Experience Analytics | **Added in:** `6.0.0` Set the default masking state. All Views are fully masked by default. ```javascript CSQ.setDefaultMasking(true) ``` #### Parameters * #### masked  Bool   The default masking state to be set. ### `<CSQMask>` **Added in:** `6.0.0` 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. ```javascript <CSQMask> <View> ... </View> </CSQMask> ``` #### Props * #### 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. ### WithCSQMask Higher Order Component (HOC) to mask content for Session Replay and suppress events for view inside WithCSQMask and all its children. #### Props * #### 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. ## SDK Initialization and Management ### CSQ.configureProductAnalytics Deprecated | Product Analytics | **Added in:** `6.0.0` Deprecated `CSQ.configureProductAnalytics()` is deprecated since 6.3.0. Use `CSQ.start(StartConfig.withEnvironmentId(...))` to combine SDK configuration and initialization in a single call. See [`start`](#csqstart). Product Analytics is now configured using the `options` parameter of [`start()`](#csqstart). ### CSQ.start **Added in:** `6.0.0` Start and configure the SDK. Use `StartConfig` to specify the product configuration. ```javascript 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 (CSQ Experience Platform) CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")); // Product Analytics with options CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true })); ``` #### StartConfig * #### 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](#product-analytics-initialization-options). * #### StartConfig.withDataSourceId(id, options?)  CSQConfig   Start the SDK with Product Analytics using a data source ID (CSQ Experience Platform). * `id` *(string)* — Your CSQ Experience Platform data source ID. * `options` *(AnalyticsOptions, optional)* — Product Analytics [initialization options](#product-analytics-initialization-options). ### CSQ.stop **Added in:** `6.0.0` Stop all activity from the SDK. Once run no requests, telemetry collection, or logs will be generated. ```javascript CSQ.stop(); ``` ### CSQ.pauseTracking **Added in:** `6.0.0` Pause all tracking features. ```javascript CSQ.pauseTracking(); ``` ### CSQ.resumeTracking **Added in:** `6.0.0` Resume all tracking features. ```javascript CSQ.resumeTracking(); ``` ## Product Analytics initialization options CSQ SDK options for Product Analytics passed to [`start()`](#csqstart). ```javascript type AnalyticsOptions = { enableRNAutocapture?: boolean; disableInteractionAutocapture?: boolean; disablePageviewAutocapture?: boolean; baseUrl?: string; // EU: "https://mh.ba.contentsquare.net"; https://mh.bf.contentsquare.net (default) uploadInterval?: number; disableInteractionTextCapture?: boolean; disableInteractionAccessibilityLabelCapture?: boolean; sessionReplayAutoStart?: boolean; // Native specific options enablePushNotificationAutocapture?: boolean; enablePushNotificationTitleAutocapture?: boolean; enablePushNotificationBodyAutocapture?: boolean; enableViewAutocapture?: boolean; // iOS specific options disablePageviewTitleAutocapture?: boolean; }; ``` ## React Native Product Analytics initialization options ### `enableRNAutocapture` Enable React Native view autocapture. Defaults to false. ### `disableInteractionAutocapture` Disables autocapture of touch events on React Native Views. Defaults to false. ### `disablePageviewAutocapture` Whether source pageview events will be auto-captured. Defaults to false. ### `baseUrl` The CSQ API endpoint to use: * `https://mh.ba.contentsquare.net` — EU-hosted environments * `https://mh.bf.contentsquare.net` — all other environments (default) ### `uploadInterval` The interval, in milliseconds, between event uploads. ### `disableInteractionTextCapture` Disables text capture for React Native interactions. Defaults to false. ### `disableInteractionAccessibilityLabelCapture` Disables accessibility label capture for React Native interactions. Defaults to false. ### `sessionReplayAutoStart` Whether the SDK starts Session Replay automatically when the SDK starts. When set to `false`, you must call [`CSQ.startSessionReplay()`](#csqstartsessionreplay) to start Session Replay. Defaults to `true`. ## Native specific Product Analytics initialization options ### `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. ### `enableViewAutocapture` Whether the SDK will auto capture UI interactions and source pageviews. Defaults to false. ## iOS specific Product Analytics initialization options ### `disablePageviewTitleAutocapture` Disable pageview title capture. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"SDK API reference","description":"SDK commands reference including signature, parameter descriptions, and examples","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/command-reference/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Changelog - React Native description: The Contentsquare React Native SDK changelog lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/changelog/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/changelog/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. 📬 Stay updated! ## Opt-in to CSQ Experience Platform Already using the CSQ SDK in standalone mode? Follow these steps to switch to CSQ Experience Platform and combine Experience Analytics and Product Analytics under a single data source. CSQ Experience Platform is currently an Early Access program. To gain access, contact your Customer Success Manager. CSQ Experience Platform guidance Throughout the documentation, code samples highlight differences between standalone and CSQ Experience Platform integrations.  1. [Update the SDK package to 6.3.0 or later](../#install-the-sdk). 2. Replace your current `CSQ.start(StartConfig.withEnvironmentId(...))` call with the `dataSourceId` provided by your Customer Success Manager. This links your app to the CSQ Experience Platform data source. **App.js** ```javascript CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")); ``` Find your data source ID `YOUR_DATASOURCE_ID` is either provided to you by Contentsquare or you can find it in **Definitions** > **Data sources** > \[Expand your mobile data source] > \[Copy the App ID in step 1] within the [CSQ Experience Platform web app ↗](https://app.contentsquare.com/). 3. Review changes [introduced in 6.3.0](#630---20260512) which notably removes support for several Product Analytics options. ## CSQ SDK ### 6.4.2 - 2026.07.21 * **Native SDKs:** * iOS: 1.11.0 → 1.11.1 ### 6.4.1 - 2026.07.10 * **Native SDKs:** * Android: 1.11.0 → 1.11.2 ### 6.4.0 - 2026.06.12 * **Native SDKs:** * Android: 1.10.1 → 1.11.0 * iOS: 1.10.0 → 1.11.0 Experience Analytics * **Session Replay** * Added new APIs to support Event-Triggered Replays (ETR) * **WebViews Bug fix** * Android: Fixed an issue when navigating back within WebViews ### 6.3.0 - 2026.05.12 Experience Analytics The Session timeout definition changes from "30 minutes after being in background" to **30 minutes after last event**. See [Session definition](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/data-collection/#session-definition). Product Analytics ### Configuration **Deprecated:** `CSQ.configureProductAnalytics()` still exists, but is now deprecated in favor of `CSQ.start()` which combines SDK configuration and initialization in a single call: * Product Analytics **App.js** ```javascript CSQ.configureProductAnalytics("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, }); CSQ.start(); CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, })); ``` * CSQ Experience Platform (Early Access) **App.js** ```javascript CSQ.configureProductAnalytics("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, }); CSQ.start(); CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true, })); ``` ### Options **Added:** `AnalyticsOptions.sessionReplayAutoStart` — set to `false` to disable automatic Session Replay start and control it manually using `CSQ.startSessionReplay()` and `CSQ.stopSessionReplay()`. Defaults to `true`. ```javascript CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { sessionReplayAutoStart: false, })); ``` **Removed - Breaking:** `disableScreenviewForwardToDXA`, `disableScreenviewForwardToPA`, `resumePreviousSession`, `captureVendorId`, `captureAdvertiserId`, `clearEventPropertiesOnNewUser`, `messageBatchMessageLimit`, `pruningLookBackWindow`, `maximumDatabaseSize`, and `maximumBatchCountPerUpload` options have been removed. Remove them from your `CSQ.start()` call if present: ```javascript CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { captureVendorId: true, captureAdvertiserId: true, clearEventPropertiesOnNewUser: true, messageBatchMessageLimit: 100, resumePreviousSession: true, pruningLookBackWindow: 6, maximumDatabaseSize: 10000000, maximumBatchCountPerUpload: 5, disableScreenviewForwardToDXA: true, disableScreenviewForwardToPA: true, })); ``` * **Native SDKs:** * Android: 1.5.1 → 1.10.1 * iOS: 1.6.3 → 1.10.0 * **Session Replay** * Support Image/Text remote masking configuration in the CSQ Console * **Bug fix** * iOS: Fixed an issue where number event properties will be parsed as boolean values in some cases ### 6.2.0 - 2026.04.22 @contentsquare/react-native-cli **v1.0.0** is now available. See [the dedicated changelog](#contentsquarereact-native-cli). * **Native SDKs:** * Android: 1.5.0 → 1.5.1 * iOS: 1.6.0 → 1.6.3 * **Bug fix** * Fixed a duplicate `hasListener` symbol conflict with third-party libraries * **WebViews** * Removed unnecessary super calls in bridge handlers * Removed the upper version limit for the React Native peer dependency. The CSQ SDK has been validated up to React Native version 0.85. ### 6.1.0 - 2026.02.26 * **Native SDKs:** * Android: 1.4.7 → 1.5.0 * iOS: 1.5.1 → 1.6.0 * **Bug fix** * Fixed iOS module headers to ensure compatibility with CocoaPods projects using `use_frameworks! :linkage => :static` * Fixed 0.82.x Session Replay compatibility issues * Official support for React Native up to 0.84.x Warning * Android: React Native crashes are not deobfuscated in Error Analysis. We are currently investigating this issue. ### 6.0.5 - 2026.02.11 * **Native SDKs:** * Android: 1.4.2 → 1.4.7 * **Bug fix** * Fixed a crash in Android WindowCallbackWrapper ### 6.0.3 - 2026.02.03 * **Bug fix** * WebViews: Fixed an issue with the `userAgent` prop being overwritten ### 6.0.2 - 2025.12.15 Contentsquare CLI * **v0.1.4** is now available. Update to this version if your app uses React Native 0.82 or above. See [Error Analysis](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/error-analysis/#source-maps) for more information. Session Replay * **iOS React Native 0.82.x** is not fully compatible with Session Replay feature. - **Bug fix** * Changed the default value of `disableInteractionAutocapture` to `false` to re-enable interaction capture by default - Fixed an issue with pod installation failing on React Native versions below 0.80 - Official support for React Native up to 0.82.x ### 6.0.1 - 2025.12.05 Contentsquare CLI * **v0.1.3** is now available for version 6.0.1 and above. See [Error Analysis](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/error-analysis/#source-maps) for more information. Initial release of the CSQ SDK. * Introduces the unified CSQ API, which combines `Product Analytics`, `Experience Analytics`, and `Monitoring` features into a single, cohesive library. *** ## `@contentsquare/react-native-cli` See [CLI configuration](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/error-analysis/#cli-configuration) for configuration details. ### 1.0.0 - 2026.04.21 **Breaking Change:** The CLI package name has changed from `@contentsquare/cli` to [`@contentsquare/react-native-cli` ↗](https://www.npmjs.com/package/@contentsquare/react-native-cli). If you already have the CLI installed: 1. Update the package name in your `package.json`: ```jsx "devDependencies": { "@contentsquare/cli": "<file_path_to_the_downloaded_.tgz_package>", "@contentsquare/react-native-cli": "1.0.0", } ``` 2. Update the paths in your [source maps](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/error-analysis/#source-maps) upload configuration: * Android **android/app/build.gradle** ```groovy apply from: "../../node_modules/@contentsquare/cli/scripts/contentsquare.gradle" apply from: "../../node_modules/@contentsquare/react-native-cli/scripts/contentsquare.gradle" ``` * iOS **Bundle React Native code and images** ```shell CONTENTSQUARE_XCODE="$SRCROOT/../node_modules/@contentsquare/cli/scripts/contentsquare-xcode.sh" CONTENTSQUARE_XCODE="$SRCROOT/../node_modules/@contentsquare/react-native-cli/scripts/contentsquare-xcode.sh" ``` * Fix support for Gradle 9+ ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Changelog","description":"The Contentsquare React Native SDK changelog","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/changelog/","inLanguage":"en","dateModified":"2026-07-08T17:11:15+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Compatibility - React Native description: Requirements and limitations to develop with the Contentsquare React Native Bridge lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/compatibility/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/compatibility/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Before implementing the SDK, make sure your app meets the following technical prerequisites to avoid integration issues and ensure optimal performance. ## Supported platforms Only React Native application on the following platforms are supported by the `CSQ React Native Bridge`: * Android * iOS If you need to use the SDK on another platform, contact our support team. Hybrid applications are not supported. By hybrid application, we mean [integrating React Native component ↗](https://reactnative.dev/docs/integration-with-existing-apps) to existing native applications. ## Compatibility matrix Each version of the CSQ bridge will be linked to specific, fixed versions of each native SDK. To make that clear, here is a compatibility table to consider when choosing your version of the bridge. Refer to the [React Native Bridge Changelog](https://docs.contentsquare.com/en/react-native/changelog/) to know what the changes are for each version. The CSQ bridge is validated against the latest React Native version. We support all React Native versions that are maintained and listed on the official [React Native documentation ↗](https://reactnative.dev/versions). | Bridge Version | iOS SDK Version | Android SDK Version | Min React Native Version | Max React Native Version | | - | - | - | - | - | | 6.4.2 | 1.11.1 | 1.11.2 | 0.71.0 | latest | | 6.4.1 | 1.11.0 | 1.11.2 | 0.71.0 | latest | | 6.4.0 | 1.11.0 | 1.11.0 | 0.71.0 | latest | | 6.3.0 | 1.10.0 | 1.10.1 | 0.71.0 | latest | | 6.2.0 | 1.6.3 | 1.5.1 | 0.71.0 | 0.85.x | | 6.1.0 | 1.6.0 | 1.5.0 | 0.71.0 | 0.84.x | | 6.0.5 | 1.5.1 | 1.4.7 | 0.71.0 | 0.82.x | | 6.0.3 | 1.5.1 | 1.4.2 | 0.71.0 | 0.82.x | | 6.0.2 | 1.5.1 | 1.4.2 | 0.71.0 | 0.82.x | | 6.0.1 | 1.5.1 | 1.4.2 | 0.71.0 | 0.81.x | ## Autocapture navigation libraries compatibility The React Native Bridge's autocapture feature is compatible with the following navigation libraries: * React Navigation 5.0 and later * React Native Navigation 7.0 and later ## Important note about React Native apps with native code Depending on if you created your app as a React Native first app, or if you gradually added some React Native code to your Native first app, you might be using some non JavaScript elements in your app, and a mix of native screens and JavaScript screens. If that is the case, it is your responsibility to track all of the screens, either by calling our native SDKs directly in the first case, or the bridge in the second. The same remark applies for other functionalities of the SDK - for example, you might need to send a Transaction Event via the native SDK or via the bridge, depending on the technology used to create your buying page. Have a look at the [Android](https://docs.contentsquare.com/en/android/) and [iOS](https://docs.contentsquare.com/en/ios/) SDKs to find out how to call them in native parts of your app. Also, we specifically cover the use of the JavaScript bridge in this documentation. You should never call the Bridge's NativeModule directly yourself. If for any reason you do so, know that we cannot certify that your implementation will work as expected. Only call our SDKs through the JavaScript CSQ module we provide in you JavaScript code (as explained in this document), or directly in your native code. ## Note about using CSQ along with Expo To use the SDK on an Expo app, you need to have an Expo project with EAS (Expo Application Services). The SDK compatibility with Expo projects requires the extra steps described below. ### Configuration Add the plugin and your CSQ bundle identifier to your app configuration file: **app.json** ```jsx { "expo": { ..., "ios": { "bundleIdentifier": "com.cs.expo.app", // replace with your bundle id ... }, "android": { "package": "com.cs.expo.app", // replace with your bundle id ... }, "plugins": [ "@contentsquare/react-native-bridge", ], } ``` ### Run To run your Expo app with the CSQ SDK, you can't use Expo Go since it needs native files and features. To run your app, use `expo run:ios` or `expo run:android`. Or, you can replace the scripts to your app in your project's `package.json`: **package.json** ```javascript "scripts": { ... "android": "expo run:android", "ios": "expo run:ios", }, ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Compatibility","description":"Requirements and limitations to develop with the Contentsquare React Native Bridge","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/compatibility/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Experience Analytics extension - React Native description: Understand the benefits of upgrading to the CSQ SDK lastUpdated: 12 June 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/dxae-setup/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/dxae-setup/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use this page to set up the Mobile Experience Analytics extension for Contentsquare Product Analytics. This will supercharge the Product Analytics platform with: * Powerful Session Replay * Analysis capabilities of Mobile API Errors and Crashes This guide assumes that you have already implemented the [CSQ SDK for Product Analytics](../). ## Enable the extension in the Product Analytics UI 1. In Product Analytics, navigate to **Account** > **Manage** > **Replays & Heatmaps**. 2. If this is your first time setting up Session Replay, select the checkbox to accept the terms and conditions. 3. Click **Add web or mobile app** to launch the setup wizard. There is one configuration per app. 4. Select **Mobile** as platform. 5. Give your app a name and choose a storage location (**US** or **EU**). 6. Set a sampling rate for how many sessions to record. 7. Configure replay settings: * **App ID**: enter the bundle ID of your app (for example, `com.companyname.appname`). * **Quality Settings**: choose the recording fidelity for Wi-Fi and Cellular connections. The default for both is Medium; keep Cellular equal to or lower than Wi-Fi. * **User Consent**: enable this if your app requires explicit opt-in before recording. See [Privacy docs](../privacy/#opt-in) for the opt-in API. 8. Click **Save and Continue** to finish the wizard. Two configurations required React Native apps require two separate mobile configurations — one for iOS and one for Android. Repeat the steps above for each platform, entering the appropriate bundle ID each time. ## Enable error and crash collection Error and crash collection is managed separately from the setup wizard. Navigate to **Account** > **Manage** > **Replays & Heatmaps**, click **Edit** next to your app configuration, then scroll to the relevant section under **General Settings**: * **Error Capture**: toggles for **API Errors** and **Custom Errors**. * **Crashes Capture**: toggle for **Crashes**. Click **Save** when finished. ## Session Replay masking The Session Replay feature replays every interaction of your users with your app. To respect the user's right to privacy, the CSQ SDK: * Masks everything by default * Allows you to control which part of the user interface is collected via our [Masking rules](#masking-rules) Warning If you decide to unmask elements leading to collection of new data or use already collected data but for a different purpose, it is up to you to update your privacy declarations accordingly: * **iOS**: Update the privacy practices described in your app's Privacy Manifest. See [Types of data and purpose](../privacy/) already described in the Contentsquare React Native SDK Privacy documentation. * **Android**: Update your Google Play Data Safety declaration accordingly. Common examples of data collected via unmasked Session Replay include: search history, purchase history, advertising data, etc. **Important:** Contentsquare is not intended nor designed to collect sensitive personal data (such as health, financial, or racial data). It is the customer's responsibility not to send any sensitive personal data to Contentsquare. ### Masking mechanisms Although the implementation is done once for both iOS and Android on React Native, the visual appearance of the masking itself will be different for each platform: * Android Every single UI element is converted into a highly pixelated image to reach a very low resolution. Text and images will appear very blurry so that the content cannot be identified. #### Original vs Replay fully masked  * iOS * Images are not collected, a placeholder is sent instead of the content; the "IMG" placeholder will be displayed in the frame of the element. * Text: text is replaced by "la" repeated as many times as needed to equal the original character count. White characters are preserved. For instance `the lazy fox` is collected as `lal lala ala`. All other visual properties are collected (text color, background color, alignment, etc.). * TextFields: same as Text * For all other types: no specific data is collected but visual properties are collected. If you think a specific element can reveal personal data from one of these properties you have to mask it using one of the methods presented below. A good way to check how a view is rendered in replays is to navigate to the desired view with the CS SDK running then use the [quick replay link](https://docs.contentsquare.com/en/csq-sdk-react-native/experience-analytics/session-replay/#access-the-replay). #### Original vs Replay fully masked  ### Masking rules Masking rules can be applied in two ways: 1. **Through remote masking configuration in the CSQ Console (for admin users):** These configurations are managed directly in the Console and take effect for all sessions as soon as the app is restarted or brought to the foreground See [How to customize masking rules from the Data Masking tab ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) in the Help Center. 2. **Using public masking APIs in the SDK (for mobile application developers):** These configurations require developer implementation and will be applied only after the mobile app has gone through its release cycle. Masking rules set via the CSQ Console or the public APIs are applied according to different priorities, as described below. The SDK determines whether a view is masked by evaluating the rules in the order specified below. Once a rule is triggered, the state is set, and subsequent rules are not applied: | Priority | Rule | Configured via | | - | - | - | | 1 | The app or SDK version is fully masked | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 2 | Remote Text or Image masking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 3 | A [component](#maskingunmasking-specific-component) is specifically masked or unmasked | API | | 4 | A [parent](#masking-and-unmasking-behaviors-on-a-parent-view) is specifically masked or unmasked | API | | 5 | Remote Text or Image unmasking is defined | [Data Masking tab in the CSQ Console ↗](https://support.contentsquare.com/hc/en-us/articles/37271848716561-How-to-customize-masking-rules-from-the-Data-Masking-tab-Apps) | | 6 | Otherwise the [default masking state](#default-masking) is applied | API | ### Public masking APIs #### Default masking All components are initially masked by default. To modify this default masking state, use the `setDefaultMasking` API, preferably within a `useEffect` in the root file (such as `App.js`). This ensures proper initialization and handling when the component mounts. If you choose to unmask the entire app using the `setDefaultMasking` API, be aware that you will need to individually mask all personal data within the app. Additionally, ensure that you consistently mask personal data on new screens in the future, if necessary. ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; useEffect(() => { CSQ.setDefaultMasking(false); // Unmask all content }, []); ``` Note Even if you change the default masking state to `false`, the `TextInput` component will stay masked by default. #### Masking/Unmasking Specific Component Use `<CSQMask isSessionReplayMasked={true}>` (default) to mask or `{false}` to unmask all children components. In this example below, all children views inside `<CSQMask>` will follow the rule of the closest parent prop `isSessionReplayMasked`. ```jsx import { CSQMask } from '@contentsquare/react-native-bridge'; // Masks all child components <CSQMask isSessionReplayMasked={true}> <View> <Text style={styles.title}>Buy my amazing merch!</Text> <Text> Hurry up! This offer won't be available tomorrow. Only $99.98 to get your hands on a wonderful, brand-new, life-changing item. </Text> </View> </CSQMask> ``` #### Masking and Unmasking behaviors on a parent view The masking state of a parent view propagates to all nested views unless explicitly overridden by a nested `<CSQMask>` component. This enables flexible masking and unmasking behaviors within complex component structures. ```jsx import { CSQMask } from '@contentsquare/react-native-bridge'; // Masks or unmasks all child components based on isSessionReplayMasked prop <CSQMask isSessionReplayMasked={true}> <View> <Text>This content is masked.</Text> <CSQMask isSessionReplayMasked={false}> <Text>This specific content is unmasked, despite the parent mask.</Text> </CSQMask> </View> </CSQMask> ``` In this example, the inner `<CSQMask>` explicitly overrides the parent view's masking behavior. ### Implementation recommendations #### Avoid wrapping the Root Navigator `<CSQMask>` should not wrap the Root Navigator it could cause unwanted results. If you want to set the default masking behavior for the whole application you should use `CSQ.setDefaultMasking(boolean masked)`. `<CSQMask>` should be used at component level. #### Avoid dynamically changing `isSessionReplayMasked` prop While `<CSQMask>` supports toggling masking at the instance level, we do not recommend changing the `isSessionReplayMasked` prop dynamically based on conditions like this: ```jsx <CSQMask isSessionReplayMasked={someCondition ? true : false}>...</CSQMask> ``` This approach may lead to unexpected behavior, such as personal data leaks. Instead, structure your layout in a way that ensures predictable masking behavior without frequently modifying the `isSessionReplayMasked` prop dynamically. #### Keeping track of what is masked The SDK doesn't provide a list of what is currently masked. If you need to keep track of it, you probably will have to write your specific wrapper. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Experience Analytics extension","description":"Understand the benefits of upgrading to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/dxae-setup/","inLanguage":"en","dateModified":"2026-06-12T11:40:35+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Privacy - React Native description: Configure privacy settings and user consent management in your React Native app with the CSQ SDK to ensure regulatory compliance lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/privacy/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/privacy/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Customers ("Customer(s)", "you," or "your"), as app developers and/or publishers, shall ensure compliance with applicable data privacy laws and regulatory guidelines while using Contentsquare SDK for your app. This section explains the data processing involved in the use of Contentsquare SDK and provides information to help you comply with data protection laws, including the GDPR, e-privacy directive, and the [French Data Protection authority (CNIL) guidelines on mobile applications ↗](https://www.cnil.fr/sites/cnil/files/2025-05/recommendation-mobiles-app.pdf). This section is for informational purposes only and is not legal advice. If you are not sure of how to comply with data protection laws that apply to you, refer to legal counsel. To learn about Contentsquare privacy practices, see our [Privacy Center ↗](https://contentsquare.com/privacy-center/) and [Privacy Policy ↗](https://contentsquare.com/privacy-center/privacy-policy/). ## Purpose of processing and categories of personal data collected Here is the list of categories of personal data Contentsquare collects by default that are part of our [privacy guidelines](../privacy/#privacy-guidelines). All collected personal data listed below is linked to the end-user via the [Contentsquare User ID](#contentsquare-user-id) we generate. Warning The Contentsquare SDK provides features that allow you to send to Contentsquare additional types of personal data (such as username, email address, customer ID, account number): [Dynamic variables](../../experience-analytics/track-dynamic-variables/), [Custom variables](../../experience-analytics/track-custom-variables/), [User identifier](../../experience-analytics/session-replay/#send-user-identifier), [Screen names](../../experience-analytics/track-screens/), [Session Replay (unmasking elements)](../../experience-analytics/session-replay/#personal-data-masking). If you decide to use these features to collect new types of personal data or use already collected data but for a different purpose, it is up to you to describe these privacy practices in your app manifest. | Categories | Data type | Purposes | | - | - | - | | Identifiers | User ID | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Product Interaction such as touch gestures (taps, swipes), user journey (pages visited), time of engagement, or transactions | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Usage Data | Other usage data (any other data about end-user activity in the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Other Data types | Other Data types (technical data, any other data inputted by customers in the dynamic variables, data used as part of the Session Replay feature where applicable) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | | Diagnostics | Crashes, such as crash logs | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/)) | | Diagnostics | Performance data, such as launch time, freeze rate, or energy use | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/) | | Diagnostics | Other diagnostic data (any other data collected for the purposes of measuring technical diagnostics related to the app) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Error Analysis module](../../experience-analytics/error-analysis/) | | Search History | Information about searches performed by an end-user in the app | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance (only when you use the [Session Replay module](../../experience-analytics/session-replay/)) | | Purchase History | Transaction data about an end-user (such as order reference, amount, bought items) | Analytics - using personal data from end-users interacting with your app, for analyzing their digital behavior and visualizing their journey to improve digital user experience and your app performance | See how the data types and purposes are reflected in the [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy). Note Contentsquare is not designed to collect sensitive personal data (for example health, financial, or racial data). It is your responsibility to prevent any sensitive data from being sent to Contentsquare. If you accidentally send sensitive data, contact your customer success manager to immediately delete them from Contentsquare servers. ## User identifiers ### Contentsquare User ID The SDK generates a unique user ID (UUID) (random hash) which is specific to users on their device. Contentsquare cannot identify a user across devices. This user ID and all collected data are stored for 13 months. We don't persist the UUID when the app is deleted and re-installed. The SDK generates a new UUID after install or re-install. Contentsquare does not share this user ID with any third parties. ### IDFA Contentsquare does not collect the **IDFA** (Advertising ID) or any ad related information to identify the user. Check out our page about [10 Things to know about the Contentsquare solution's data processing ↗](https://contentsquare.com/privacy-center/10-things-to-know-cs-data-processing/). ### "User identifier" feature Contentsquare provides the ability to search for sessions associated with a specific visitor, based on an identifier provided by the customer. See [User identifier feature](../../experience-analytics/session-replay/#send-user-identifier) for more information. ## Data retention and storage location ### Data retention By default, end-users personal data are kept for 13 months. The retention of end-users personal data collected via the Session Replay is customizable by customers, from 3 to 24 months. ### Storage location End-users personal data are stored in Europe or in the US, depending on your location. For more details on applicable hosting locations, refer to our [subprocessors list ↗](https://contentsquare.com/privacy-center/subprocessors/). ## Informing your End-User The Contentsquare SDK collects end-user's personal data on your app. As a data controller, app developers, or app publishers, it is your responsibility to provide appropriate information to your end-users on how their personal data is handled when using the CSQ SDK, for example via a privacy policy or cookie banner. Contentsquare provides a sample [description of the services ↗](https://contentsquare.com/privacy-center/sample-cookie-description/) (including Experience Analytics and Product Analytics) to help customers meet their transparency obligations. This description is for information only and is not legal advice. ## Handling User Consent Contentsquare collects usage data on your app. **By default, the SDK will consider every new user to be opted-out.** To start tracking, the SDK [Opt-in API](#opt-in) must be called. You are responsible for handling the UI asking end-users for their consent and allowing them to manage their privacy settings. Use the following APIs to pass the user decision to the Contentsquare SDK. Note If data protection laws that apply to you do not require end-user consent for your app, discuss it during implementation with your Contentsquare contact (as this may have implications for app store privacy guidelines). ### Opt-in Use the Opt-in API to get end-user consent. Calling this API will generate a user ID and initiate tracking. ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; CSQ.optIn(); ``` ### Opt-Out When this API is called, tracking stops immediately, all settings are reset (Session number, Page number, and so on) and all files and directory including personal data collected via the SDK created by Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track and collect any data from the user's phone unless the Opt-in API is called again. ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; CSQ.optOut(); ``` ### Handling your end-user's data subject requests In case Contentsquare receives a request from an individual that identifies as an end-user of your app, Contentsquare will promptly refer such individual directly to you, as the data controller and will support you with any means available to resolve such request. Contentsquare has launched a portal for managing data subject requests to its customers respond to data subjects within the legal deadlines. Therefore, you can forward any data subject request (such as data deletion or data access request) you receive to Contentsquare via this Data Subject Portal at [https://contentsquare.com/privacy-center/data-subject-request-portal/ ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ### Get Contentsquare User ID Since Contentsquare SDK does not collect by default any directly identifiable personal data about your end-user, we cannot help you respond to an end-user's data subject request without their Contentsquare User ID. Use this API to get the Contentsquare User ID of your end-user and forward the end-user's data subject request (such as data deletion or data access request) via Contentsquare's [portal ↗](https://contentsquare.com/privacy-center/data-subject-request-portal/). ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; CSQ.onMetadataChange((metadata) => { const userId = metadata.userId; // Forward userId with data subject request }); ``` Note You are able to get an ID only if the user is not Opted-out. ### Enrichment API [The Enrichment API](https://docs.contentsquare.com/en/api/enrichment/) allows for enriching the behavioural data tracked by Contentsquare client-side, with other session-based data that can be sent server-side. During a visit on an app, you can interact with Contentsquare's SDK to pull those identifiers with the following SDK APIs: ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; CSQ.onMetadataChange((metadata) => { const projectId = metadata.projectId; const sessionId = metadata.sessionId; // store these Contentsquare session identifiers in your backend }); ``` ### Pause / Resume Tracking To completely stop data collection of your end-users of your app, use the pause and resume tracking APIs. When `pauseTracking` is called, the Contentsquare SDK pauses all tracking (Analytics, Session Replay, Errors) of your end-users. When `resumeTracking` is called, the Contentsquare SDK resumes all tracking (Analytics, Session Replay, Errors) and starts collecting your end-users personal data again with the same Contentsquare user ID. ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; import { useEffect } from 'react'; function SensitiveScreen() { useEffect(() => { // Pause tracking when entering sensitive screen CSQ.pauseTracking(); return () => { // Resume tracking when exiting sensitive screen CSQ.resumeTracking(); }; }, []); return ( // your sensitive screen content ); } ``` Note As this mechanism pauses the tracking, make sure that you call resume once your user exits the sensitive screen. Best practice would be to link these method calls to component lifecycle events using `useEffect`. ## Disable user tracking across sessions If you don't want to link the different sessions of a user to the same userID, reset the userID at each app start: ```javascript import { CSQ, StartConfig } from '@contentsquare/react-native-bridge'; import { CSQ } from '@contentsquare/react-native-bridge'; import { useEffect } from 'react'; function App() { useEffect(() => { CSQ.start(StartConfig.dxa()); CSQ.optOut(); CSQ.optIn(); }, []); return ( // your app content ); } ``` Starting the SDK manually using `start()` will ensure that opt-out is called right after the start of the SDK (no event tracked in between). Calling `optOut()` will delete the previous userID. Calling `optIn()` will set a new one. Note If you are monitoring the network requests, you may see event requests being sent at app start. This is expected as there may be events from the previous session that haven't been sent yet. The [opt-out API](#opt-out) makes sure to send all data stored locally before stopping the tracking and wiping all data. ### Session Replay privacy APIs As part of Session Replay capabilities, Contentsquare provides masking mechanisms to prevent unwanted end-user's personal data from the Session Replay module from being transmitted to Contentsquare. See [Session Replay Personal data masking](../../experience-analytics/session-replay/#personal-data-masking) for more information. ## Privacy guidelines Warning For iOS apps, it is your responsibility to comply with the [App Store Privacy guidelines ↗](https://developer.apple.com/app-store/review/guidelines/#privacy). The Contentsquare SDK includes a [privacy manifest ↗](https://github.com/ContentSquare/CS_iOS_SDK/blob/master/ContentsquareModuleWrapper/PrivacyInfo.xcprivacy) describing the types of end-users personal data collected. For Android apps, follow [Google Play's Data safety requirements ↗](https://support.google.com/googleplay/android-developer/answer/10787469) when declaring data collection in your app. ### App Tracking Transparency (ATT) It is not required to ask for end-users' permission through ATT when using Contentsquare, as it does not fall under the "tracking" definition. The data collected by the Contentsquare SDK is not linked with third-party data for targeted advertising or advertising measurement purposes, nor shared with a data broker. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Privacy","description":"Configure privacy settings and user consent management in your React Native app with the CSQ SDK to ensure regulatory compliance","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/privacy/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Hide sensitive data - React Native description: Protect sensitive data in Contentsquare by disabling text capture, masking specific views, or ignoring interactions lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/privacy-and-sensitive-data/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/privacy-and-sensitive-data/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. When using autocapture, Product Analytics collects target text information about the element that was interacted with, and text data from UI elements further up in an element's ancestry. Similarly, Session Replay captures visual information from your app screens. However, some of these elements might contain sensitive user information, or Personal Data, that needs to be excluded from data capture. There are three options for hiding sensitive data: * Disabling text capture globally * Per-view text masking for Session Replay * Ignoring text and interactions for specific views in Product Analytics ## Disabling all text capture You have the option to disable text capture for all events that are automatically captured in Product Analytics. To do this, use the Product Analytics configuration when starting the SDK. * Product Analytics **App.js** ```javascript import { CSQ, StartConfig } from '@contentsquare/react-native-bridge'; useEffect(() => { CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, })); }, []); ``` * CSQ Experience Platform (Early Access) **App.js** ```javascript import { CSQ, StartConfig } from '@contentsquare/react-native-bridge'; useEffect(() => { CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true, disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, })); }, []); ``` ## Masking text for specific views If you don't want to disable all text capture for your app, you can take a more targeted approach of only masking text for specific views in your app that you know might contain sensitive data. When a view is masked for Session Replay, it will be obscured in the replay, and Product Analytics only captures data from it when explicitly allowed. ```jsx import React from 'react'; import { Text } from 'react-native'; import { CSQMask } from '@contentsquare/react-native-bridge'; const MyComponent = () => { return ( <CSQMask isSessionReplayMasked={true}> <Text>Sensitive Information</Text> </CSQMask> ); }; ``` Using the `CSQMask` component, you can wrap any view that might contain sensitive data to ensure that it is masked in Session Replay and ignored in Product Analytics. Its usage will impact all child views contained within the masked view. ```jsx import React from 'react'; import { Text, Button } from 'react-native'; import { CSQMask } from '@contentsquare/react-native-bridge'; const MyComponent = () => { return ( <CSQMask isSessionReplayMasked={true}> <Text>Sensitive Information</Text> <Button title="Submit" onPress={() => { console.log('Button pressed'); }} /> </CSQMask> ); }; ``` In this example, both the `Text` and `Button` views will have their content masked in Session Replay when displayed, as they are both children of the `CSQMask` component. In case of need you can also combine multiple masking configurations by nesting `CSQMask` components. ```jsx import React from 'react'; import { Text, Button } from 'react-native'; import { CSQMask } from '@contentsquare/react-native-bridge'; const MyComponent = () => { return ( <CSQMask isSessionReplayMasked={true}> <Text>Sensitive Information</Text> <CSQMask isSessionReplayMasked={false}> <Button title="Submit" onPress={() => { console.log('Button pressed'); }} /> </CSQMask> </CSQMask> ); }; ``` In this example, only the `Text` view will have its content masked in Session Replay, while the `Button` view will retain its original appearance, as it is wrapped in a nested `CSQMask` with `isSessionReplayMasked` set to `false`. Note By default, `CSQMask` masks content for Session Replay and ignores all data for Product Analytics. You need to explicitly allow specific data types using the `allow*` props if you want Product Analytics to capture information from masked views. ## Ignoring text for specific views If you want to allow interactions to be tracked in Product Analytics while hiding sensitive text content, you can use the `ignoreTextOnly` prop. This is helpful when you want to track user engagement with an element without capturing the actual text displayed. ```jsx import React from 'react'; import { TextInput } from 'react-native'; import { CSQMask } from '@contentsquare/react-native-bridge'; const MyComponent = () => { return ( <CSQMask ignoreTextOnly={true}> <TextInput placeholder="Enter sensitive data" /> </CSQMask> ); }; ``` Using `ignoreTextOnly={true}`, you can wrap any view where you want to track interactions but hide the text content and accessibility labels from Product Analytics. The view will still be visible in Session Replay according to the `isSessionReplayMasked` prop (defaulting to masked). ```jsx import React from 'react'; import { Text, TextInput, Button } from 'react-native'; import { CSQMask } from '@contentsquare/react-native-bridge'; const MyComponent = () => { return ( <CSQMask ignoreTextOnly={true}> <Text>Enter your password</Text> <TextInput placeholder="Password" secureTextEntry={true} /> <Button title="Login" onPress={() => { console.log('Login pressed'); }} /> </CSQMask> ); }; ``` In this example, all views will have their text content and accessibility labels ignored by Product Analytics, but interactions (button presses) will still be tracked. The component hierarchy and properties will also be captured. In case of need you can also combine multiple masking configurations by nesting `CSQMask` components. ```jsx import React from 'react'; import { Text, Button } from 'react-native'; import { CSQMask } from '@contentsquare/react-native-bridge'; const MyComponent = () => { return ( <CSQMask ignoreTextOnly={true}> <Text>Sensitive label text</Text> <CSQMask ignoreTextOnly={false}> <Button title="Submit" onPress={() => { console.log('Button pressed'); }} /> </CSQMask> </CSQMask> ); }; ``` In this example, the outer `Text` view will have its text content ignored by Product Analytics, while the `Button` view will capture all data including its title text, as it is wrapped in a nested `CSQMask` with `ignoreTextOnly` set to `false`. Note When using `ignoreTextOnly={true}`, the following data is ignored by Product Analytics: * Text content (`allowText` is set to `false`) * Accessibility labels (`allowAccessibilityLabel` is set to `false`) The following data is still captured: * Interactions (`allowInteraction` is set to `true`) * Component hierarchy (`allowInnerHierarchy` is set to `true`) * Component properties (`allowProps` is set to `true`) All `allow*` props are ignored when `ignoreTextOnly` is `true` and should not be set alongside it. ## Advanced masking control For fine-grained control over what data is captured by Product Analytics, you can use the individual `allow*` props. This is helpful when you need more specific control than `ignoreTextOnly` provides. ### Available control props * `allowText`: Controls whether text content is captured (default: `false`) * `allowAccessibilityLabel`: Controls whether accessibility labels are captured (default: `false`) * `allowInteraction`: Controls whether user interactions are tracked (default: `false`) * `allowInnerHierarchy`: Controls whether child components are included in the hierarchy (default: `false`) * `allowProps`: Controls whether component properties are captured (default: `false`) Warning When `ignoreTextOnly` is set to `true`, all `allow*` props are ignored and replaced with predefined values. Do not use `allow*` props together with `ignoreTextOnly={true}` as it will generate a warning and the `allow*` props will be ignored. ### Example: Allow interactions but ignore text ```jsx import React from 'react'; import { Button } from 'react-native'; import { CSQMask } from '@contentsquare/react-native-bridge'; const MyComponent = () => { return ( <CSQMask isSessionReplayMasked={true} allowInteraction={true} > <Button title="Sensitive Button Label" onPress={() => { console.log('Button pressed'); }} /> </CSQMask> ); }; ``` In this example, the button interaction will be tracked by Product Analytics, but the button's text label will not be captured. ### Example: Allow text and interactions ```jsx import React from 'react'; import { Text, Button } from 'react-native'; import { CSQMask } from '@contentsquare/react-native-bridge'; const MyComponent = () => { return ( <CSQMask isSessionReplayMasked={false} allowInteraction={true} allowText={true} allowInnerHierarchy={true} > <Text>Product Information</Text> <Button title="Add to Cart" onPress={() => { console.log('Add to cart'); }} /> </CSQMask> ); }; ``` In this example, the view is unmasked in Session Replay, and Product Analytics will capture interactions, text content, and the inner component hierarchy. ### Example: Nested masking with different configurations ```jsx import React from 'react'; import { Text, TextInput, Button } from 'react-native'; import { CSQMask } from '@contentsquare/react-native-bridge'; const MyComponent = () => { return ( <CSQMask allowInteraction={true} allowInnerHierarchy={true} > <Text>Form Title</Text> <CSQMask allowInteraction={true} allowText={false} allowProps={true} > <TextInput placeholder="Enter sensitive data" /> </CSQMask> <Button title="Submit" onPress={() => { console.log('Submit pressed'); }} /> </CSQMask> ); }; ``` In this example, the outer `CSQMask` allows interactions and inner hierarchy capture, while the nested `CSQMask` around the `TextInput` prevents text capture but allows component properties to be captured. ## Default behavior By default, when you use `CSQMask`: * **Session Replay**: Content is masked (`isSessionReplayMasked={true}`) * **Product Analytics**: All data is ignored unless explicitly allowed using `allow*` props If you don't set any props: ```jsx <CSQMask> <Text>This content is masked</Text> </CSQMask> ``` Is equivalent to: ```jsx <CSQMask isSessionReplayMasked={true} allowText={false} allowAccessibilityLabel={false} allowInteraction={false} allowInnerHierarchy={false} allowProps={false} > <Text>This content is masked</Text> </CSQMask> ``` ## Implementation recommendations ### Avoid dynamically changing masking props While `CSQMask` supports toggling masking props, we do not recommend changing the props dynamically based on conditions: ```jsx // ❌ Not recommended <CSQMask isSessionReplayMasked={someCondition ? true : false}> ... </CSQMask> ``` This approach may lead to unexpected behavior, such as personal data leaks. Instead, structure your layout in a way that ensures predictable masking behavior without frequently modifying the masking props dynamically. ### Using ignoreTextOnly vs. allow\* props **Use `ignoreTextOnly={true}`** when you want to: * Track interactions while hiding text content * Use the predefined configuration (interactions allowed, text/labels ignored) * Simplify your code with a common use case **Use individual `allow*` props** when you need: * Fine-grained control over specific data types * Custom combinations not covered by `ignoreTextOnly` * To allow text but ignore other data types **Never combine them:** ```jsx // ❌ This will generate a warning <CSQMask ignoreTextOnly={true} allowText={true}> ... </CSQMask> ``` ### Nesting behavior When nesting `CSQMask` components, the inner component's props override the outer component's behavior for its children: ```jsx <CSQMask isSessionReplayMasked={true}> <Text>This is masked</Text> <CSQMask isSessionReplayMasked={false}> <Text>This is NOT masked</Text> </CSQMask> </CSQMask> ``` However, for Product Analytics `allow*` props, the rules are cumulative - if a parent denies access (`allowText={false}`), a nested child cannot override it to allow access. Both must allow for data to be captured. ### TextInput components `TextInput` components are masked by default for Session Replay, even when the default masking is set to `false` globally. If you need to unmask a `TextInput`, you must explicitly wrap it: ```jsx <CSQMask isSessionReplayMasked={false}> <TextInput placeholder="This input is visible in replays" /> </CSQMask> ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Hide sensitive data","description":"Protect sensitive data in Contentsquare by disabling text capture, masking specific views, or ignoring interactions","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/privacy-and-sensitive-data/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Security - React Native description: Data transfer and security information lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/security/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/security/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The React Native SDK requires specific Android permissions to function and follows Android security guidelines for deep link handling. ## App permissions The SDK includes the following permissions, which are mandatory for the SDK to operate properly: **AndroidManifest.xml** ```xml <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.READ_BASIC_PHONE_STATE" /> <uses-permission-sdk-23 android:name="android.permission.SYSTEM_ALERT_WINDOW" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> ``` | Permission | Required to | Associated with read/write operations under e-privacy directive | | - | - | - | | `android.permission.INTERNET` | Send collected data to Contentsquare servers | Yes. The end-user's data is collected for analytics purposes. | | `android.permission.READ_BASIC_PHONE_STATE` | Retrieve non-sensitive device information such as carrier name for analytics purposes | Yes. The end-user's data is collected for analytics purposes. | | `android.permission.SYSTEM_ALERT_WINDOW` | Use Contentsquare in-app features | No. This permission is solely used to display Contentsquare UI elements in our customers' apps. | | `android.permission.ACCESS_NETWORK_STATE` | Check network availability before sending data | No. This permission is solely used to check the network status check. | Note Some of these permissions involve read and write operations within the meaning of the e-privacy directive and article 82 of the French Data Protection Act, which may require the end-user's specific consent as specified above. This requirement applies in particular to customers based in the EU or targeting end-users in the EU. For more information on how to combine technical permission and legal consent, refer to the [CNIL (French data protection authority) recommendations ↗](https://www.cnil.fr/fr/permissions-applications-mobiles-recommandations-de-la-cnil-pour-respecter-la-vie-privee). ## Deep links usage in Contentsquare SDK As outlined in the [Android Security Guidelines ↗](https://developer.android.com/privacy-and-security/risks/unsafe-use-of-deeplinks), there are security risks associated with using deep links. To address these concerns, the Contentsquare SDK implements robust data validation for deep links and safeguards to prevent deep link hijacking, following these guidelines. If you have specific security concerns and prefer to remove the Contentsquare SDK deep link declaration from your application, add the following code snippet to your `AndroidManifest.xml` file inside the `<application>` tag: ```xml <application> <activity android:name="com.contentsquare.android.analytics.internal.features.deeplink.DeepLinkActivity" tools:node="remove" /> </application> ``` Removing the deep link will disable the In-app feature within your application. ## Transmission and hosting Our server uses HTTPS to make sure that data is encrypted in transport. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Security","description":"Data transfer and security information","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/security/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track events manually - React Native description: Learn how to implement custom event tracking in your React Native app with the CSQ SDK for capturing user interactions and business events lastUpdated: 14 April 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/track-events-manually/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/track-events-manually/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. In addition to autocaptured events, use the `CSQ.trackEvent()` API to send custom events and attach properties to them for use in Product Analytics. ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.trackEvent("purchase_completed"); ``` It doesn't matter what you call your event, there are ways in Product Analytics to cross-track events regardless of name. See our [guide on combo events ↗](https://help.heap.io/hc/en-us/articles/37271999013009-How-to-combine-events-using-a-combo-event) to learn more. ## Adding Properties to Custom Events Custom events can be enhanced with a set of properties that will correspond to the tracked event when passed into the `CSQ.trackEvent()` API call. ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; const properties = { property1: "sample value", property2: 10, property3: false } CSQ.trackEvent("custom_event_with_properties", properties); ``` ## Adding Properties to All Events In some cases, you might want to add a property, or a collection of properties, to all events tracked by Product Analytics. Adding a global event property can be accomplished using `CSQ.addEventProperties()`. ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; const globalProperties = { property1: "sample value", property2: 10, property3: false } CSQ.addEventProperties(globalProperties); ``` Properties that are added using the `CSQ.addEventProperties()` API will be attached to all events tracked by Product Analytics, including any events that are automatically tracked by a CSQ autocapture SDK. ## Removing a Property Once a property is no longer needed in the global collection, use `CSQ.removeEventProperty()` to remove properties one at a time. ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.removeEventProperty("property1"); ``` ## Removing All Properties On the other hand, if you want to remove all properties added with `CSQ.addEventProperties()` at once, you can achieve this by using `CSQ.clearEventProperties()`. ```javascript import { CSQ } from "@contentsquare/react-native-bridge"; CSQ.clearEventProperties(); ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track events manually","description":"Learn how to implement custom event tracking in your React Native app with the CSQ SDK for capturing user interactions and business events","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/track-events-manually/","inLanguage":"en","dateModified":"2026-04-14T10:59:20+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track identity - React Native description: Enhance user tracking with identify and addUserProperties APIs. Link anonymous and identified user data across sessions and devices for comprehensive analytics lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/track-identity/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/track-identity/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Product Analytics assigns every visitor a random user ID; call `identify` to merge anonymous and identified profiles, and `addUserProperties` to attach custom attributes. ## User Identities and Properties Contentsquare Product Analytics empowers you to use the rich information about your users to better understand how users interact with your app, and build charts to continually track engagement. There are two primary APIs for enriching user data in Product Analytics: * The [`CSQ.identify()`](../command-reference/#csqidentify) API allows you to attach a unique identity and maintain user histories across sessions and devices under a single profile, * The [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) API allows you to attach custom properties to your users, whether they are identified or still anonymous. ## Read This First: Key Considerations Before implementing our APIs, check the following explanations on how these APIs work and common implementation mistakes to avoid. ### Anonymous Users When a person interacts with your app, Product Analytics generates a random unique user ID and stores it locally on the device. In Product Analytics, these users will appear in the [Users ↗](https://developers.heap.io/docs/users) view as "User 123456" where the 123456 is their user ID. We refer to these users as anonymous users throughout this document. Tip Though this guide focuses on React Native use cases, the same principles apply to other mobile platforms. The user ID may be stored differently depending on the platform. If a user installs your app on multiple devices (for example, their phone and tablet), Product Analytics will recognize 2 different anonymous users because each device will have a different locally stored ID. We can identify these users on both devices and link the two anonymous users into a single identified user. ### Identified Users You can use the `identify` API to attach your own unique identifier to a user. The `identify` API takes a single string value as an argument. Examples are provided further down in this guide in the [Examples section ↗](https://developers.heap.io/docs/using-identify#examples). Warning When a user is identified, their past sessions and event activity from when they were anonymous are now tied to that identity. This allows the user to use multiple devices to access your app with a single identity. ### User Properties The `addUserProperties` API can be used to attach properties to users' profiles. Product Analytics sets some of these properties automatically, such as Initial Location, Initial Referrer, Initial Marketing Channel, and more. A full list of all user properties captured by default is available in [Autocaptured Data ↗](https://help.heap.io/getting-started/how-heap-works/autocaptured-data/). The `addUserProperties` API allows you to attach any string or number as a user property that's not automatically captured. Some practical properties to use include: payment plan, marketing segment, or A/B experiment. Once set, these properties can be used in charts to [group by ↗](https://developers.heap.io/docs/group-bys) and [filter ↗](https://developers.heap.io/docs/filters) against. Check out some specific examples further down this page. ### Common Identify Implementation Errors Below we've listed the most common mistakes developers may make when implementing the `identify` API. #### Using a Non-Unique Identifier A common assumption is that a unique identifier attached via `CSQ.identify()` is required in order for the `addUserProperties` API to attach properties to a user. In cases where a unique identifier isn't available, we've seen people include a specific name, like 'guest', or 'Anonymous User'. This can cause irreversible behavior with how Product Analytics merges user profiles. You can call [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) at any time, whether the user has been given a unique identity. For this reason, the following identify calls are blocklisted: * `anonymous` * `guest` * `null` * `true` * `false` * `not_authenticated` * `NaN` * `' '` (empty string) * `0` * `None` * `none` * `Email` * `email` As an example of how this would impact your setup: let's say that you have a marketing campaign, and you want to associate it with a user when they open your app from a deep link. They aren't logged in, so you don't have a unique identifier. **Don't do this:** ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; import { useEffect } from 'react'; useEffect(() => { CSQ.identify("guest"); CSQ.addUserProperties({ campaign: "Campaign Name" }); }, []); ``` This will merge all users into a single user profile called 'guest', which will break any metrics that rely on user flow, or the unique user count. **Instead, do this:** ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; import { useEffect } from 'react'; useEffect(() => { CSQ.addUserProperties({ campaign: "Campaign Name" }); }, []); ``` Now the campaign property will be associated with the anonymous user. ### Adding an Anonymous Unique Identifier of Your Own Some tools require a unique identifier to be provided to add user-level properties. This leads people to add their own unique identifier to all users. Product Analytics automatically assigns each unidentified user a unique user ID so that you aren't required to call `identify` to add user-level properties. Assigning an identity to a user when it isn't required can lead to undesirable or unexpected behavior. Product Analytics does not allow you to change an already applied identity or assign multiple identities to the same user. If you call `identify` with an anonymized identity, such as a `uuid` or random hash, this will be their permanent identity in Product Analytics. If you call the identify API at another time for the same user with a different identity, such as an internal user ID or username, this will create a new user in Product Analytics, splitting this user into two identified users: one with the random `uuid` containing all of the historical events, and another with the user ID or username which has events going forward. Since Product Analytics automatically creates a randomized unique identifier, it's not necessary for you to send your own identifier unless you are certain it is a unique, permanent identifier for the user. If you want to add properties to a user using `addUserProperties`, you can do so without providing a unique identifier. Calling `CSQ.addUserProperties({property: 'value'})` will add this property to the anonymous user's Product Analytics profile automatically. ## When and Where to Call identify and addUserProperties The `identify` and `addUserProperties` APIs can be called anytime and anywhere the data is available about that user. The typical place for an identify call that includes a unique identifier is after a successful login or signup. Make an identify call each time the user's authentication state is established as opposed to only on first app launch. When setting properties, it's OK to call the `addUserProperties` API on any screen, though you should add user properties on identified users. This will greatly improve your experience when analyzing your user base. ### Identity Examples #### Anonymous to New Identity Let's say we have an internal user ID from our own database, and we want to identify a user based on that ID. We can do that like this: ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; // userId = '12345' CSQ.identify(userId); ``` Now, their profile in the **Users** view will look like this:  #### Anonymous to Existing Identity In the last example, we identified a user with the unique user ID of 12345. Let's say that this person installs your app on a second device for the first time. Product Analytics will generate a new, random, unique userID, in this case it's 5404281197559477. In Product Analytics' users view, this visitor looks like this:  When this person logs in, and you recognize that their internal user ID is 12345, you can call identify like this: ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; //userId = '12345' CSQ.identify(userId); ``` The previous user's profile with the random user ID of 1565941335949135 is merged, along with its previous sessions and events into the Product Analytics profile of the identified user with the identity of 12345. ### addUserProperties Examples #### Common User Properties User properties can be used to capture additional data about a user, such as first and last name, email address, time zone, and account plan. The following example covers how to add an account plan user property using the client-side `CSQ.addUserProperties()` API, and this can be modified to capture any of the previously mentioned user properties. #### Account Plan Many products include some sort of tiered pricing plan. Using the [`CSQ.addUserProperties()`](../command-reference/#csqadduserproperties) API to attach this information to your users' profiles can help you compare and contrast usage between different segments. When someone uses your app, we pull their account tier from our database and inject that into an addUserProperties call like this: ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; import { useEffect } from 'react'; useEffect(() => { CSQ.addUserProperties({ plan: "Startup" }); }, []); ``` This lets us build powerful charts, like this bar chart showing sign-ups split by plan type. ### Industry Recommendations Call `CSQ.addUserProperties()` in the part of your app flow where the data you want to capture is being presented. Below are some examples of places to call the API, based on industry. | Industry | API Use Case | API Call Placement | | - | - | - | | e-Commerce | Improve personalization and recommendation algorithms. | On user login or significant actions (such as a purchase). Attach properties like login info, purchase amount, and spender type. | | Social media platform | Enhance user engagement and content personalization. | When a user updates their profile, adds interests, or engages in specific types of content. Attach custom properties like user interests or content preferences. | | Subscription-based service | Understand user demographics and preferences to optimize its offerings. | When a user signs up, completes a survey, or changes subscription preferences. Attach custom properties such as geographical location, email, or subscription plan details. | ## What about the identity API? Once you have the identify API set up, you can use `CSQ.onMetadataChange()` to access a specific user's identity. ```javascript import { CSQ } from '@contentsquare/react-native-bridge'; import { useEffect } from 'react'; useEffect(() => { const unsubscribe = CSQ.onMetadataChange((metadata) => { if (metadata.userId) { console.log('User ID:', metadata.userId); } }); return () => { if (unsubscribe) { unsubscribe(); } }; }, []); ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track identity","description":"Enhance user tracking with identify and addUserProperties APIs. Link anonymous and identified user data across sessions and devices for comprehensive analytics","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/track-identity/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Track push notifications - React Native description: Learn how to track mobile notification interactions automatically with Contentsquare lastUpdated: 08 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/track-push-notifications/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/track-push-notifications/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. After completing the setup process you will be able to: * Automatically track interactions on your mobile notifications * Define and analyze notification interaction events in Contentsquare ## Initializing Notification Autocapture Notification autocapture can be initialized with `enablePushNotificationAutocapture: true` in `start()`. * Product Analytics ```javascript import { CSQ, StartConfig } from '@contentsquare/react-native-bridge'; CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enablePushNotificationAutocapture: true })); ``` * CSQ Experience Platform (Early Access) ```javascript import { CSQ, StartConfig } from '@contentsquare/react-native-bridge'; CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enablePushNotificationAutocapture: true })); ``` Capture the title or body text of the notification where an interaction was performed using `enablePushNotificationTitleAutocapture` and `enablePushNotificationBodyAutocapture`. * Product Analytics ```javascript import { CSQ, StartConfig } from '@contentsquare/react-native-bridge'; CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enablePushNotificationAutocapture: true, enablePushNotificationTitleAutocapture: true, enablePushNotificationBodyAutocapture: true })); ``` * CSQ Experience Platform (Early Access) ```javascript import { CSQ, StartConfig } from '@contentsquare/react-native-bridge'; CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enablePushNotificationAutocapture: true, enablePushNotificationTitleAutocapture: true, enablePushNotificationBodyAutocapture: true })); ``` Once registered, Contentsquare will begin collecting interaction events on notifications. ## What's Next? With notification data flowing, you'll want to jump into Product Analytics and start defining notification interaction events. These events will show up as a special "Notification Interaction" event type in Product Analytics and have several properties available to create definitions: * **Notification Title**: The title text of the notification. Capture can be enabled/disabled via a config option as described above. * **Notification Body**: The body text of the notification. Capture can be enabled/disabled via a config option as described above. * **Notification Action**: The text of the notification action that was interacted with, if any. * **Notification Source**: What caused the notification to fire. This could be a push service, a geofence, or unknown. * **Notification Handling Component**: The name of the component in code that handled the notification interaction. * **Notification Category**: This is the notification channel that the notification was delivered to. This typically denotes the type of notification that with which the interaction occurred. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Track push notifications","description":"Learn how to track mobile notification interactions automatically with Contentsquare","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/track-push-notifications/","inLanguage":"en","dateModified":"2026-07-08T20:51:53+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Core SDK + Contentsquare SDK to CSQ SDK - React Native description: Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK lastUpdated: 04 May 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-from-heap-and-cs-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-from-heap-and-cs-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This guide provides a step-by-step upgrade process from your current installation of Contentsquare and Heap Mobile to the latest version of the CSQ SDK.  **Heap Core SDK** \+  **Contentsquare SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. ## Dependency upgrades Replace Heap and Contentsquare SDK dependencies by the CSQ SDK: * yarn ```shell yarn remove @heap/heap-react-native-autocapture @heap/heap-react-native-bridge @heap/heap-react-native-cs-integration @heap/babel-plugin-heap-react-native-autocapture yarn add @contentsquare/react-native-bridge cd ios && pod install ``` * npm ```shell npm uninstall @heap/heap-react-native-autocapture @heap/heap-react-native-bridge @heap/heap-react-native-cs-integration @heap/babel-plugin-heap-react-native-autocapture npm install @contentsquare/react-native-bridge cd ios && pod install ``` ## Library imports Replace the Heap and Contentsquare dependency imports with a CSQ SDK import. ```diff import { Heap } from '@heap/heap-react-native-bridge'; import { registerHeapAutocapture } from '@heap/heap-react-native-autocapture'; import Contentsquare from "@contentsquare/react-native-bridge"; import { bind } from '@heap/heap-react-native-cs-integration'; import { CSQ } from "@contentsquare/react-native-bridge"; ``` ## SDK start Follow these steps to start the CSQ SDK with your current configuration. 1. Migrate your app ID and the config options from `Heap.startRecording()` to `start()`. * Product Analytics **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { Heap.startRecording("YOUR_ENVIRONMENT_ID"); CSQ.start( StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID") ); }, []); ``` * CSQ Experience Platform (Early Access) **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { Heap.startRecording("YOUR_ENVIRONMENT_ID"); CSQ.start( StartConfig.withDataSourceId("YOUR_DATASOURCE_ID") ); }, []); ``` Deprecated configuration options The following Heap SDK configuration options are not supported in the CSQ SDK: * `startSessionImmediately` * `resumePreviousSession` * `captureVendorId` * `captureAdvertiserId` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `pruningLookBackWindow` * `maximumDatabaseSize` * `maximumBatchCountPerUpload` * `disableScreenviewForwardToDXA` * `disableScreenviewForwardToPA` See [supported options](../command-reference/#product-analytics-initialization-options) for more information. 2. For React Native Autocapture, replace the babel plugin from `@heap/heap-react-native-autocapture` to `@contentsquare/react-native-bridge/babel` in your babel configuration. * babel.config.js **babel.config.js** ```diff module.exports = { presets: ['module:metro-react-native-babel-preset'], plugins: ['@heap/heap-react-native-autocapture'], plugins: ['@contentsquare/react-native-bridge/babel'], }; ``` * babel.config.json **babel.config.json** ```diff { "presets": [ "module:metro-react-native-babel-preset" ], "plugins": [ "@heap/heap-react-native-autocapture" "@contentsquare/react-native-bridge/babel" ] } ``` 3. For React Native Autocapture, replace `registerHeapAutocapture()` with `enableRNAutocapture = true` option: * Product Analytics **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { registerHeapAutocapture(); CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true })); }, []); ``` * CSQ Experience Platform (Early Access) **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { registerHeapAutocapture(); CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true })); }, []); ``` 4. Remove `HeapContentsquareIntegration.bind()`. Sending Heap screenviews to Contentsquare **App.tsx** ```javascript bind({ sendHeapPageviewsToContentsquare: true }); ``` Note Make sure you don't have calls to `CSQ.trackScreenview()` if you have React Native View autocapture enabled. Sending Contentsquare screenviews to Heap * Product Analytics **App.tsx** ```javascript bind({ sendHeapPageviewsToContentsquare: true }); CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { disablePageviewAutocapture: true, })); ``` * CSQ Experience Platform (Early Access) **App.tsx** ```javascript bind({ sendHeapPageviewsToContentsquare: true }); CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { disablePageviewAutocapture: true, })); ``` 5. (Optional) If you have chosen to deactivate the autostart of the Contentsquare SDK, you can now remove the entry in the manifest, as the CSQ SDK doesn't have an autostart. **AndroidManifest.xml** ```xml <application> ... <meta-data android:name="com.contentsquare.android.autostart" android:value="false" /> ... </application> ``` ## Get user consent The CSQ SDK treats users as opted-out by default. ```javascript import React, { useState } from "react"; import { View, Text, Button } from "react-native"; import { CSQ } from "@contentsquare/react-native-bridge"; const PolicyConsentScreen = () => { const [isTrackingAccepted, setIsTrackingAccepted] = useState(false); const handleAcceptPolicy = () => { setIsTrackingAccepted(true); CSQ.optIn(); }; return ( <View> <Text>Please accept our privacy policy to proceed.</Text> <Button title="Accept Policy" onPress={handleAcceptPolicy} /> </View> ); }; export default PolicyConsentScreen; ``` Implement the [`optIn()`](../command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. In most cases, this process consists in updating the namespace and method names, with no changes to parameters. * Product Analytics ```javascript Contentsquare.start() Heap.startRecording("YOUR_ENVIRONMENT_ID") CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID")) ``` * CSQ Experience Platform (Early Access) ```javascript Contentsquare.start() Heap.startRecording("YOUR_ENVIRONMENT_ID") CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID")) ``` The latest version of our CSQ SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. For more information on SDK methods, see the [SDK API reference](../command-reference/). ### Product Analytics ### GDPR / Identification | Heap Core SDK | CSQ SDK | | - | - | | `Heap.identify(identity: string)` | `CSQ.identify(identity: string)` | | `Heap.resetIdentity()` | `CSQ.resetIdentity()` | ```javascript const getUserInformation = async () => { const heapUserId = await Heap.getUserId(); const heapSessionId = await Heap.getSessionId(); const heapEnvId = await Heap.getEnvironmentId(); const heapIdentity = await Heap.getIdentity(); }; useEffect(() => { const onMetadataChangeUnsubscribe = CSQ.onMetadataChange(metadata => { const userId = metadata.userID; const sessionId = metadata.sessionID; const environmentId = metadata.environmentID; const identity = metadata.identity; }); return () => { onMetadataChangeUnsubscribe(); }; }, []); ``` ### Logging | Heap Core SDK | CSQ SDK | | - | - | | `import { Heap, LogLevel } from '@heap/heap-react-native-bridge'` | `import { CSQ, LogLevel } from "@contentsquare/react-native-bridge"` | | `Heap.logToConsole()` | `CSQ.logToConsole()` | | `Heap.setLogLevel(logLevel: LogLevel)` | `CSQ.setLogLevel(logLevel: LogLevel)` | | `Heap.setLogChannel(LogChannel: (logLevel: LogLevel, message: string, source: string \| null \| undefined) => void)` | `CSQ.setLogChannel(logChannel: (logLevel: LogLevel, message: string, source: string \| null \| undefined) => void)` | ### Property tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.addUserProperties(properties: Properties)` | `CSQ.addUserProperties(properties: Record<string, PropertyValue>)` | | `Heap.addEventProperties(properties: Properties)` | `CSQ.addEventProperties(properties: Record<string, PropertyValue>)` | | `Heap.removeEventProperty(name: string)` | `CSQ.removeEventProperty(name: string)` | | `Heap.clearEventProperties()` | `CSQ.clearEventProperties()` | ### Event tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.track(event: string, properties?: Properties \| null, timestamp?: Date \| null, sourceInfo?: SourceInfo \| null, pageview?: Pageview \| 'none' \| null)` | `CSQ.trackEvent(event: string, properties?: Record<string, PropertyValue>)` `CSQ.trackScreenview(name: string, cvars?: CustomVar[])` | ### Personal Data Handling and Masking | Heap Core SDK | CSQ SDK | | - | - | | `\<HeapIgnore>` | `\<CSQMask>` | | `\<HeapIgnoreText>` | `\<CSQMask ignoreTextOnly>` | | `withHeapIgnore` | `withCSQMask` | ### SDK initialization and manipulation | Heap Core SDK | CSQ SDK | | - | - | | Heap SDK initialization options | `CSQ.start(StartConfig.withEnvironmentId(id, options?))` See [supported options](../command-reference/#product-analytics-initialization-options) for more information. | | `Heap.startRecording(environmentId: string, options?: Options)` | `CSQ.start(StartConfig.withEnvironmentId(id))` | | `Heap.stopRecording()` | `CSQ.stop()` or `CSQ.pauseTracking()` | Deprecated `CSQ.configureProductAnalytics(environmentId, options?)` is deprecated since CSQ React Native SDK 6.3.0. Use `CSQ.start(StartConfig.withEnvironmentId(id, options?))` to combine SDK configuration and initialization in a single call. ### Autocapture options * Product Analytics ```javascript Heap.startRecording("YOUR_APP_ID", { disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, }); CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, })); ``` * CSQ Experience Platform (Early Access) ```javascript Heap.startRecording("YOUR_APP_ID", { disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, }); CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true, disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, })); ``` ### Experience Analytics ### GDPR / Identification | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.optIn()` | `CSQ.optIn()` | | `Contentsquare.optOut()` | `CSQ.optOut()` | | `Contentsquare.sendUserIdentifier(userIdentifier: string)` | `CSQ.sendUserIdentifier(userIdentifier: string)` | #### User id ```diff useEffect(() => { Contentsquare.getUserId(userId => { console.log(`Your Contentsquare UserID is ${userId}`); }); const onMetadataChangeUnsubscribe = CSQ.onMetadataChange(metadata => { console.log(`Your Contentsquare UserID is ${metadata.userID}`); }); return () => { onMetadataChangeUnsubscribe(); }; }, []); ``` ### Property tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.sendDynamicVar(key: string, value: string \| number, onError?: (error: Error))` | `CSQ.addDynamicVar(key: string, value: string \| number, onError?: (error: Error))` | ### Interoperability #### Session Replay URL ```diff useEffect(() => { const sessionReplayLinkSubscriber = Contentsquare.onSessionReplayLinkChange(link => { Alert.alert(`New link copied to the clipboard ${link}`); const onMetadataChangeUnsubscribe = CSQ.onMetadataChange(metadata => { Alert.alert(`New link copied to the clipboard ${metadata.sessionReplayUrl}`); }); return () => { if (sessionReplayLinkSubscriber) { sessionReplayLinkSubscriber.remove(); } if (onMetadataChangeUnsubscribe) { onMetadataChangeUnsubscribe(); } }; }, []); ``` #### Webview component ```diff import { CSWebView } from "@contentsquare/react-native-bridge"; import WebView from 'react-native-webview'; import { CSQWebView } from "@contentsquare/react-native-bridge"; <CSWebView> <CSQWebView> <WebView source={{ uri: 'https://www.example.com' }} /> </CSWebView> </CSQWebView> ``` ### Event tracking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.sendTransaction(value: number, currency: Currency \| string, id?: string \| null)` | `CSQ.trackTransaction(value: number, currency: Currency \| string, id?: string \| null)` | | `Contentsquare.send(screenName: string, cvars?: CustomVar[])` | `CSQ.trackScreenview(name: string, cvars?: CustomVar[])` | ### Error tracking | Contentsquare SDK | CSQ SDK | | - | - | | `ErrorAnalysis.setURLMaskingPatterns(patterns: string[])` | `CSQ.setURLMaskingPatterns(patterns: string[])` | | `ErrorAnalysis.triggerNativeCrash()` | `CSQ.triggerNativeCrash()` | ### Personal Data Handling and Masking | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.setDefaultMasking(masked: Boolean)` | `CSQ.setDefaultMasking(masked: Boolean)` | #### Masking component ```diff import { CSMask } from "@contentsquare/react-native-bridge"; import { CSQMask } from "@contentsquare/react-native-bridge"; <CSMask isMasking={true}> <CSQMask isSessionReplayMasked={true}> {/* Your masked content goes here */} </CSMask> </CSQMask> ``` ### SDK initialization and manipulation | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.start()` | `CSQ.start(StartConfig.dxa())` | | `Contentsquare.stopTracking()` | `CSQ.pauseTracking()` | | `Contentsquare.resumeTracking()` | `CSQ.resumeTracking()` | ### CSInApp | Contentsquare SDK | CSQ SDK | | - | - | | `Contentsquare.handleUrl(urlString: string \| null \| undefined)` | `CSQ.handleUrl(urlString: string \| null \| undefined)` | ## Number of sessions Session timeout definition changed: * **Before**: 30 minutes after app goes to background * **Now**: 30 minutes after last event This may affect session counts and aligns with web and market standards. Breaking changes in 6.3.0 The following options have been removed from `AnalyticsOptions` in CSQ React Native SDK 6.3.0: * `disableScreenviewForwardToDXA` * `disableScreenviewForwardToPA` * `resumePreviousSession` * `captureVendorId` * `captureAdvertiserId` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `pruningLookBackWindow` * `maximumDatabaseSize` * `maximumBatchCountPerUpload` Remove them from your `CSQ.start()` call if present. ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that you are using a version 6.0.0 or later of the Contentsquare React Native SDK. Your `import Contentsquare from "@contentsquare/react-native-bridge"` and `import { ErrorAnalysis } from "@contentsquare/react-native-bridge"` declarations have been updated to `import { CSQ } from "@contentsquare/react-native-bridge"`. Your `import { Heap } from '@heap/heap-react-native-bridge'` and `import { registerHeapAutocapture } from '@heap/heap-react-native-autocapture'` import declarations have been updated to `import { CSQ} from "@contentsquare/react-native-bridge"`. You no longer have references to `Heap.` or `Contentsquare.` methods in your codebase. You no longer have references to `CSMask` or `CSWebView` components in your codebase. You no longer have references to `<HeapIgnore>`, `<HeapIgnoreText>` or `withHeapIgnore` components in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK + Contentsquare SDK to CSQ SDK","description":"Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-from-heap-and-cs-sdk/","inLanguage":"en","dateModified":"2026-05-04T16:24:38+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Classic SDK to CSQ SDK - React Native description: Learn how to migrate from the Heap Classic SDK to the CSQ SDK lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-from-heap-classic-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-from-heap-classic-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This guide provides a step-by-step upgrade process from your current installation of Heap Mobile to the latest version of the CSQ SDK.  **Heap Classic SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. Key differences from Heap Classic SDK * **Custom tracking first**: CSQ SDK starts with custom tracking APIs; you should use autocapture (vs Classic's autocapture-by-default approach) * **Live View only**: Visual Labeler is no longer supported * **Opt-out by default**: Must call `CSQ.optIn()` to start tracking * **Separate storage**: Expect temporary spike in new users/installs during migration ## Dependency upgrades Replace the Heap Classic SDK dependency by the CSQ SDK. * yarn ```shell yarn remove @heap/react-native-heap yarn add @contentsquare/react-native-bridge cd ios && pod install ``` * npm ```shell npm uninstall@heap/react-native-heap npm install @contentsquare/react-native-bridge cd ios && pod install ``` ## Library imports Replace Heap Classic imports with a CSQ SDK import. ```diff import Heap, { HeapIgnore, HeapIgnoreTargetText, withHeapIgnore } from '@heap/react-native-heap'; import { CSQ, CSQMask, withCSQMask } from "@contentsquare/react-native-bridge"; ``` After updating the import, some APIs used in your development environment may show errors. The next steps in this guide will help you update them to the latest versions. ## SDK start Follow these steps to start the CSQ SDK with your current configuration. 1. Migrate your app ID and the config options from `Heap.setAppId()` to `start()`. * Product Analytics **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { Heap.setAppId("YOUR_ENVIRONMENT_ID"); CSQ.start( StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID") ); }, []); ``` * CSQ Experience Platform (Early Access) **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { Heap.setAppId("YOUR_ENVIRONMENT_ID"); CSQ.start( StartConfig.withDataSourceId("YOUR_DATASOURCE_ID") ); }, []); ``` 2. For React Native Autocapture, replace the babel plugin from `@heap/react-native-heap` to `@contentsquare/react-native-bridge/babel` in your babel configuration. * babel.config.js **babel.config.js** ```diff module.exports = { plugins: ['./node_modules/@heap/react-native-heap/instrumentor/src/index.js'], plugins: ['@contentsquare/react-native-bridge/babel'], }; ``` * babel.config.json **babel.config.json** ```diff { "plugins": [ "./node_modules/@heap/react-native-heap/instrumentor/src/index.js", "@contentsquare/react-native-bridge/babel" ] } ``` 3. Remove Heap from `app.json` plugins array **app.json** ```diff { "plugins": [ "@heap/react-native-heap" ] } ``` 4. Remove `Heap.withReactNavigationAutotrack()` from navigation ```javascript import Heap from '@heap/react-native-heap'; const HeapNavigationContainer = Heap.withReactNavigationAutotrack( NavigationContainer ); ``` 5. Migrate your app ID and the config options from `Heap.setAppId()` to `start()`. Deprecated configuration options The following Heap SDK configuration options are not supported in the CSQ SDK: * `startSessionImmediately` * `resumePreviousSession` * `captureVendorId` * `captureAdvertiserId` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `pruningLookBackWindow` * `maximumDatabaseSize` * `maximumBatchCountPerUpload` * `disableScreenviewForwardToDXA` * `disableScreenviewForwardToPA` See [supported options](../command-reference/#product-analytics-initialization-options) for more information. 6. To start Autocapture set `enableRNAutocapture = true` option: * Product Analytics **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true })); }, []); ``` * CSQ Experience Platform (Early Access) **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true })); }, []); ``` ## Get user consent The CSQ SDK treats users as opted-out by default. Implement the [`optIn()`](../command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. ```javascript import React, { useState } from "react"; import { View, Text, Button } from "react-native"; import { CSQ } from "@contentsquare/react-native-bridge"; const PolicyConsentScreen = () => { const [isTrackingAccepted, setIsTrackingAccepted] = useState(false); const handleAcceptPolicy = () => { setIsTrackingAccepted(true); CSQ.optIn(); }; return ( <View> <Text>Please accept our privacy policy to proceed.</Text> <Button title="Accept Policy" onPress={handleAcceptPolicy} /> </View> ); }; export default PolicyConsentScreen; ``` ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. In most cases, this process consists in updating the namespace and method names, with no changes to parameters. ```javascript Heap.identify("some_identity") CSQ.identify("some_identity") ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### GDPR / Identification | Heap Classic SDK | CSQ SDK | | - | - | | `Heap.identify(identity: String)` | `CSQ.identify(identity: String)` | | `Heap.resetIdentity()` | `CSQ.resetIdentity()` | | `Heap.getUserId()` | `CSQ.onMetadataChange(metadata => metadata.userID)` | | `Heap.getSessionId()` | `CSQ.onMetadataChange(metadata => metadata.sessionID)` | | `Heap.getIdentity()` | `CSQ.onMetadataChange(metadata => metadata.identity)` | ### Property tracking | Heap Classic SDK | CSQ SDK | | - | - | | `Heap.addUserProperties(properties: Properties)` | `CSQ.addUserProperties(properties: Record<string PropertyValue>)` | | `Heap.addEventProperties(properties: Properties)` | `CSQ.addEventProperties(properties: Record<string, PropertyValue>)` | | `Heap.removeEventProperty(name: string)` | `CSQ.removeEventProperty(name: string)` | | `Heap.clearEventProperties()` | `CSQ.clearEventProperties()` | ### Event tracking | Heap Classic SDK | CSQ SDK | | - | - | | `Heap.track(event: string, properties?: Properties \| null, timestamp?: Date \| null, sourceInfo?: SourceInfo \| null, pageview?: Pageview \| 'none' \| null)` | `CSQ.trackEvent(event: string, properties?: Record<string, PropertyValue>)` `CSQ.trackScreenview(name: string, cvars?: CustomVar[])` | ### Personal Data Handling and Masking | Heap Classic SDK | CSQ SDK | | - | - | | `\<HeapIgnore>` | `\<CSQMask>` | | `\<HeapIgnoreTargetText>` | `\<CSQMask ignoreTextOnly>` | | `withHeapIgnore` | `withCSQMask` | ### SDK initialization and manipulation | Heap Classic SDK | CSQ SDK | | - | - | | `Heap.setAppId("YOUR_ENVIRONMENT_ID")` | `CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID"))` | | `Heap.setTrackingEnabled(true)` | `CSQ.resumeTracking()` | | `Heap.setTrackingEnabled(false)` | `CSQ.pauseTracking()` | ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that you are using a version 6.0.0 or later of the Contentsquare React Native SDK. Your `import { Heap } from '@heap/react-native-heap'` import declarations have been updated to `import { CSQ } from '@contentsquare/react-native-bridge'`. You no longer have references to `Heap.` methods in your codebase. You no longer have references to `<HeapIgnore>`, `<HeapIgnoreTargetText>` or `withHeapIgnore` components in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Classic SDK to CSQ SDK","description":"Learn how to migrate from the Heap Classic SDK to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-from-heap-classic-sdk/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: From Heap Core SDK to CSQ SDK - React Native description: Learn how to migrate from the Heap Core SDK to the CSQ SDK lastUpdated: 13 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-from-heap-core-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-from-heap-core-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This guide provides a step-by-step upgrade process from your current installation of Heap Mobile to the latest version of the CSQ SDK.  **Heap Core SDK** →  **CSQ SDK** The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions. Upgrading to the latest version ensures you benefit from all our newest features and product enhancements. ## Dependency upgrades Replace Heap SDK dependencies with the CSQ SDK: * yarn ```shell yarn remove @heap/heap-react-native-autocapture @heap/heap-react-native-bridge @heap/babel-plugin-heap-react-native-autocapture yarn add @contentsquare/react-native-bridge cd ios && pod install ``` * npm ```shell npm uninstall @heap/heap-react-native-autocapture @heap/heap-react-native-bridge @heap/babel-plugin-heap-react-native-autocapture npm install @contentsquare/react-native-bridge cd ios && pod install ``` - babel.config.js **babel.config.js** ```diff module.exports = { presets: ['module:metro-react-native-babel-preset'], plugins: ['@heap/heap-react-native-autocapture'], plugins: ['@contentsquare/react-native-bridge/babel'], }; ``` - babel.config.json **babel.config.json** ```diff { "presets": [ "module:metro-react-native-babel-preset" ], "plugins": [ "@heap/heap-react-native-autocapture" "@contentsquare/react-native-bridge/babel" ] } ``` ## Library imports Replace Heap Core and Autocapture SDK imports with the CSQ SDK import. ```diff import { Heap } from '@heap/heap-react-native-bridge'; import { HeapIgnore, HeapIgnoreText, withHeapIgnore, } from '@heap/heap-react-native-autocapture'; import { CSQMask, withCSQMask, } from "@contentsquare/react-native-bridge"; ``` ## SDK start Follow these steps to start the CSQ SDK with your current configuration. 1. Migrate your app ID and the config options from `Heap.startRecording()` to `start()`. * Product Analytics **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { Heap.startRecording("YOUR_ENVIRONMENT_ID"); CSQ.start( StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID") ); }, []); ``` * CSQ Experience Platform (Early Access) **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { Heap.startRecording("YOUR_ENVIRONMENT_ID"); CSQ.start( StartConfig.withDataSourceId("YOUR_DATASOURCE_ID") ); }, []); ``` Deprecated configuration options The following Heap SDK configuration options are not supported in the CSQ SDK: * `startSessionImmediately` * `resumePreviousSession` * `captureVendorId` * `captureAdvertiserId` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `pruningLookBackWindow` * `maximumDatabaseSize` * `maximumBatchCountPerUpload` * `disableScreenviewForwardToDXA` * `disableScreenviewForwardToPA` See [supported options](../command-reference/#product-analytics-initialization-options) for more information. 2. For React Native Autocapture, replace the babel plugin from `@heap/heap-react-native-autocapture` to `@contentsquare/react-native-bridge/babel` in your babel configuration. * babel.config.js **babel.config.js** ```diff module.exports = { presets: ['module:metro-react-native-babel-preset'], plugins: ['@heap/heap-react-native-autocapture'], plugins: ['@contentsquare/react-native-bridge/babel'], }; ``` * babel.config.json **babel.config.json** ```diff { "presets": [ "module:metro-react-native-babel-preset" ], "plugins": [ "@heap/heap-react-native-autocapture" "@contentsquare/react-native-bridge/babel" ] } ``` 3. For React Native Autocapture, replace `registerHeapAutocapture()` with `enableRNAutocapture = true` option: * Product Analytics **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { registerHeapAutocapture(); CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true })); }, []); ``` * CSQ Experience Platform (Early Access) **App.tsx** ```javascript import { CSQ, StartConfig } from "@contentsquare/react-native-bridge"; useEffect(() => { registerHeapAutocapture(); CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true })); }, []); ``` ## Get user consent The CSQ SDK treats users as opted-out by default. ```javascript import React, { useState } from "react"; import { View, Text, Button } from "react-native"; import { CSQ } from "@contentsquare/react-native-bridge"; const PolicyConsentScreen = () => { const [isTrackingAccepted, setIsTrackingAccepted] = useState(false); const handleAcceptPolicy = () => { setIsTrackingAccepted(true); CSQ.optIn(); }; return ( <View> <Text>Please accept our privacy policy to proceed.</Text> <Button title="Accept Policy" onPress={handleAcceptPolicy} /> </View> ); }; export default PolicyConsentScreen; ``` Implement the [`optIn()`](../command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID. ## Update APIs Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption. In most cases, this process consists in updating the namespace and method names, with no changes to parameters. ```javascript Heap.identify("some_identity") CSQ.identify("some_identity") ``` For more information on SDK methods, see the [SDK API reference](../command-reference/). ### GDPR / Identification | Heap Core SDK | CSQ SDK | | - | - | | `Heap.identify(identity: string)` | `CSQ.identify(identity: string)` | | `Heap.resetIdentity()` | `CSQ.resetIdentity()` | ```javascript const getUserInformation = async () => { const heapUserId = await Heap.getUserId(); const heapSessionId = await Heap.getSessionId(); const heapEnvId = await Heap.getEnvironmentId(); const heapIdentity = await Heap.getIdentity(); }; useEffect(() => { const onMetadataChangeUnsubscribe = CSQ.onMetadataChange(metadata => { const userId = metadata.userID; const sessionId = metadata.sessionID; const environmentId = metadata.environmentID; const identity = metadata.identity; }); return () => { onMetadataChangeUnsubscribe(); }; }, []); ``` ### Logging | Heap Core SDK | CSQ SDK | | - | - | | `import { Heap, LogLevel } from '@heap/heap-react-native-bridge'` | `import { CSQ, LogLevel } from "@contentsquare/react-native-bridge"` | | `Heap.logToConsole()` | `CSQ.logToConsole()` | | `Heap.setLogLevel(logLevel: LogLevel)` | `CSQ.setLogLevel(logLevel: LogLevel)` | | `Heap.setLogChannel(LogChannel: (logLevel: LogLevel, message: string, source: string \| null \| undefined) => void)` | `CSQ.setLogChannel(logChannel: (logLevel: LogLevel, message: string, source: string \| null \| undefined) => void)` | ### Property tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.addUserProperties(properties: Properties)` | `CSQ.addUserProperties(properties: Record<string, PropertyValue>)` | | `Heap.addEventProperties(properties: Properties)` | `CSQ.addEventProperties(properties: Record<string, PropertyValue>)` | | `Heap.removeEventProperty(name: string)` | `CSQ.removeEventProperty(name: string)` | | `Heap.clearEventProperties()` | `CSQ.clearEventProperties()` | ### Event tracking | Heap Core SDK | CSQ SDK | | - | - | | `Heap.track(event: string, properties?: Properties \| null, timestamp?: Date \| null, sourceInfo?: SourceInfo \| null, pageview?: Pageview \| 'none' \| null)` | `CSQ.trackEvent(event: string, properties?: Record<string, PropertyValue>)` `CSQ.trackScreenview(name: string, cvars?: CustomVar[])` | ### Personal Data Handling and Masking | Heap Core SDK | CSQ SDK | | - | - | | `\<HeapIgnore>` | `\<CSQMask>` | | `\<HeapIgnoreText>` | `\<CSQMask ignoreTextOnly>` | | `withHeapIgnore` | `withCSQMask` | ### SDK initialization and manipulation | Heap Core SDK | CSQ SDK | | - | - | | Heap SDK initialization options | `CSQ.start(StartConfig.withEnvironmentId(id, options?))` See [supported options](../command-reference/#product-analytics-initialization-options) for more information. | | `Heap.startRecording(environmentId: string, options?: Options)` | `CSQ.start(StartConfig.withEnvironmentId(id))` | | `Heap.stopRecording()` | `CSQ.stop()` or `CSQ.pauseTracking()` | Deprecated `CSQ.configureProductAnalytics(environmentId, options?)` is deprecated since CSQ React Native SDK 6.3.0. Use `CSQ.start(StartConfig.withEnvironmentId(id, options?))` to combine SDK configuration and initialization in a single call. ### Autocapture options * Product Analytics ```javascript Heap.startRecording("YOUR_APP_ID", { disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, }); CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", { enableRNAutocapture: true, disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, })); ``` * CSQ Experience Platform (Early Access) ```javascript Heap.startRecording("YOUR_APP_ID", { disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, }); CSQ.start(StartConfig.withDataSourceId("YOUR_DATASOURCE_ID", { enableRNAutocapture: true, disableInteractionTextCapture: true, disableInteractionAccessibilityLabelCapture: true, })); ``` ## 6.3.0 breaking changes Breaking changes in 6.3.0 The following options have been removed from `AnalyticsOptions` in CSQ React Native SDK 6.3.0: * `disableScreenviewForwardToDXA` * `disableScreenviewForwardToPA` * `resumePreviousSession` * `captureVendorId` * `captureAdvertiserId` * `clearEventPropertiesOnNewUser` * `messageBatchMessageLimit` * `pruningLookBackWindow` * `maximumDatabaseSize` * `maximumBatchCountPerUpload` Remove them from your `CSQ.start()` call if present. ## Checklist Congratulations! You're all set. Use this checklist to ensure everything is correctly updated. Ensure that you are using a version 6.0.0 or later of the Contentsquare React Native SDK. Your `import { Heap } from '@heap/heap-react-native-bridge'` and `import { registerHeapAutocapture } from '@heap/heap-react-native-autocapture'` import declarations have been updated to `import { CSQ } from "@contentsquare/react-native-bridge"`. You no longer have references to `Heap.` methods in your codebase. You no longer have references to `<HeapIgnore>`, `<HeapIgnoreText>` or `withHeapIgnore` components in your codebase. All calls to the CSQ SDK use the `CSQ.`namespace. ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"From Heap Core SDK to CSQ SDK","description":"Learn how to migrate from the Heap Core SDK to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-from-heap-core-sdk/","inLanguage":"en","dateModified":"2026-07-13T21:36:29+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Upgrade your SDK - React Native description: Understand the benefits of upgrading to the CSQ SDK lastUpdated: 11 March 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-your-sdk/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-your-sdk/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. This section guides you through the upgrade from your current SDK implementation to our latest CSQ SDK. Upgrading has no impact on your current data collection (except for "Heap Classic SDK") and does not alter the data observed on the platform. It mainly consists of searching and replacing APIs according to the mappings provided in the upgrade guides. Get started by selecting the upgrade guide that corresponds to your current implementation: * **[Heap Core SDK](../upgrade-from-heap-core-sdk/)** - Upgrade from Heap Core SDK * **[Heap Classic SDK](../upgrade-from-heap-classic-sdk/)** - Upgrade from Heap Classic SDK * **[Heap SDK + Contentsquare SDK](../upgrade-from-heap-and-cs-sdk/)** - Upgrade from combined Heap and Contentsquare SDKs ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Upgrade your SDK","description":"Understand the benefits of upgrading to the CSQ SDK","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/upgrade-your-sdk/","inLanguage":"en","dateModified":"2026-03-11T15:27:52+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page> <page> --- title: Agent skills for React Native - React Native description: Use AI coding assistants to integrate, upgrade, and configure the Contentsquare React Native SDK with downloadable Agent skills lastUpdated: 16 July 2026 source_url: html: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/using-agent-skills/ md: https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/using-agent-skills/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. Use the Contentsquare wizard or skills to set up, update, and configure React Native with your AI coding assistant. Disclaimer This skill guides your AI coding agent through the SDK installation and implementation. The agent you use (Cursor, Claude Code, Copilot) is your own tool and operates under your settings and permissions. Contentsquare is not responsible for how your agent interprets or applies the instructions contained in these files. ## Contentsquare wizard Run the wizard in your project directory. It configures your AI coding assistant, installs the matching Contentsquare integration, and verifies the installation. ```shell npx @contentsquare/wizard install ``` Supports GitHub Copilot, Cursor, and Claude Code. Requires Node.js ≥ 18 and an AI coding agent with MCP support. ## Manual setup Use this path when you prefer to configure your AI coding assistant yourself. ### 1. Add the Contentsquare skill Choose how to install the Contentsquare skill. * Copilot CLI Add the Contentsquare marketplace, then install the plugin for React Native: ```shell copilot plugin marketplace add ContentSquare/agents copilot plugin install contentsquare-reactnative@contentsquare ``` * Claude Code Add the Contentsquare marketplace, then install the plugin for React Native: ```shell /plugin marketplace add ContentSquare/agents /plugin install contentsquare-reactnative@contentsquare ``` * Cursor Install **contentsquare** from the [Cursor marketplace ↗](https://cursor.com/marketplace), or add the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents) directly. Cursor reads the `.cursor-plugin` catalog in the repository. * Other agents Install the Contentsquare skill pack with the open `skills.sh` ecosystem: ```shell npx skills add contentsquare/agents ``` * From source Download or clone the [Contentsquare agents repository ↗](https://github.com/ContentSquare/agents), then copy `skills/contentsquare-reactnative-sdk` into the location your AI coding assistant scans for skills: | AI coding assistant | Skill location | | - | - | | GitHub Copilot | `.github/skills/` or `.agents/skills/` | | Cursor | `.cursor/rules/` or the project root | | Claude Code | `.claude/skills/` or the project root | | Other compatible agents | `.agents/skills/` | ### 2. Ask your AI coding assistant After installing the skill, paste this prompt into your AI coding assistant: ```text Install Contentsquare for React Native. ``` ```json {"@context":"https://schema.org","@type":"TechArticle","headline":"Agent skills for React Native","description":"Use AI coding assistants to integrate, upgrade, and configure the Contentsquare React Native SDK with downloadable Agent skills","url":"https://docs.contentsquare.com/en/csq-sdk-react-native/product-analytics/using-agent-skills/","inLanguage":"en","dateModified":"2026-07-16T17:50:48+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}} ``` </page>