From Contentsquare SDK to CSQ SDK

Last updated Sep 15, 2026View as Markdown Set up with AI

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.

Upgrade with agents

Run the wizard in your project directory:
```
npx @contentsquare/wizard install
```

Paste this prompt into your AI coding assistant:

Upgrade my React Native app from the Contentsquare SDK to the CSQ SDK.

Prefer to install our skill manually or need custom prompts? See AI setup for React Native.

Manual upgrade

Once you've completed these steps, your app will be fully migrated to the CSQ SDK — with no impact on your existing data collection.

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
npm

yarn add @contentsquare/react-native-bridge@latest

npm install @contentsquare/react-native-bridge@latest

Library imports

Replace the Contentsquare SDK import with a CSQ SDK import.

import Contentsquare from "@contentsquare/react-native-bridge";
import { CSQ } from '@contentsquare/react-native-bridge';

Replace the Error Analysis import if present:

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

Replace masking component import if present:

import { CSMask } from "@contentsquare/react-native-bridge";
import { CSQMask } from "@contentsquare/react-native-bridge";

Replace webView injection component import if present:

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.

import { CSQ, StartConfig } from "@contentsquare/react-native-bridge";

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

Android
iOS

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

<application>
  ...
    <meta-data
      android:name="com.contentsquare.android.autostart"
      android:value="false"
    />
  ...
</application>

(Optional) If you were relying on the Contentsquare SDK autostart, remove the CSDisableAutostart property and calls to Contentsquare.start().

<key>CSDisableAutostart</key>
<true/>

Contentsquare.start()

The CSQ SDK treats users as opted-out by default.

Implement the optIn() API to forward user consent to the SDK and generate a user ID.

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.

Contentsquare.start()
CSQ.start(StartConfig.dxa())

For more information on SDK methods, see the SDK API 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

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

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

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

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.