--- 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: 05 February 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 --- 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 is automatically included in the Contentsquare React Native SDK and is available for both Android and iOS. ## 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, note that 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 ```groovy buildscript { repositories { maven { url "https://plugins.gradle.org/m2" } } dependencies { classpath("com.contentsquare.gradle:error-analysis-network:1.7.0") } } ``` * Kotlin ```kotlin buildscript { repositories { maven { url = uri("https://plugins.gradle.org/m2") } } dependencies { classpath("com.contentsquare.gradle:error-analysis-network:1.7.0") } } ``` - Groovy ```groovy apply plugin: "com.contentsquare.error.analysis.network" ``` - Kotlin ```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` | ### 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:///: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 // /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 ```groovy plugins { id "com.contentsquare.error.analysis.crash" version "1.7.0" apply false } ``` ```groovy plugins { id "com.contentsquare.error.analysis.crash" } ``` * Kotlin ```kotlin plugins { id("com.contentsquare.error.analysis.crash") version "1.7.0" apply false } ``` ```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 unhandled JavaScript error. 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: , session: on screen: crashID: ``` * iOS ```text CSLIB ℹ️ Info: React Native Crash event detected and sent for userID: , session: on screen: crashID: ``` #### 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 ```groovy ... apply plugin: "com.contentsquare.error.analysis.crash" apply from: "../../node_modules/@contentsquare/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 ```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/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 ``` 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 Download the [`contentsquare-cli-v0.1.4.tgz`](https://docs.contentsquare.com/contentsquare-cli-v0.1.4.tgz) package and install it as a dev dependency to your project. ```text yarn add --dev ``` Replace `` with the actual path to the tarball file on your system. 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. ```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 ``` ### 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.