---
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: 11 December 2025
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
---

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.

Upgrading

See our guide to upgrade to the CSQ SDK from the [CS SDK](upgrade-from-cs-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

  ```bash
  yarn add @contentsquare/react-native-bridge
  cd ios && pod install
  ```

* npm

  ```bash
  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 [`CSQ.start()`](command-reference/#csqstart) within a `useEffect` hook in your main component, such as `App.js` or `index.js`:

   ```javascript
   import { CSQ } from "@contentsquare/react-native-bridge";


   useEffect(() => {
       CSQ.start();
   }, []);
   ```

2. Start your application, and check logs for this output:

   ```text
   [INFO] CSQ 6.1.0 is attempting to start Digital eXperience Analytics.
   ```

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