---
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: 11 March 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
---

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](https://docs.contentsquare.com/heap-logo.png)

**Heap Core SDK**

\+

![Contentsquare SDK](https://docs.contentsquare.com/cs-logo.png)

**Contentsquare SDK**

→

![CSQ SDK](https://docs.contentsquare.com/csq-logo.png)

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

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

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

   **App.tsx**

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


   useEffect(() => {
     Heap.startRecording("YOUR_ENVIRONMENT_ID");
     CSQ.configureProductAnalytics(
       "YOUR_ENVIRONMENT_ID"
     )
   }, []);
   ```

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:

   **App.tsx**

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


   useEffect(() => {
     registerHeapAutocapture();
     CSQ.configureProductAnalytics(
       "YOUR_ENVIRONMENT_ID",
       {
         enableRNAutocapture: true
       }
     )
   }, []);
   ```

4. Add a call to `CSQ.start()` after the configuration call.

   **App.tsx**

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


   useEffect(() => {
     CSQ.configureProductAnalytics(
       "YOUR_ENVIRONMENT_ID",
       {
         enableRNAutocapture: true
       }
     )


     CSQ.start();
   }, []);
   ```

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

   **App.tsx**

   ```javascript
   bind({ sendHeapPageviewsToContentsquare: true });
   CSQ.configureProductAnalytics("YOUR_ENVIRONMENT_ID", {
     disablePageviewAutocapture: true,
     resumePreviousSession: 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

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.

```kotlin
Contentsquare.start()
Heap.startRecording("YOUR_ENVIRONMENT_ID")
CSQ.start()
```

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.configureProductAnalytics(envId: string, productAnalyticsOptions: ProductAnalyticsOptions)` See [supported options](../command-reference/#product-analytics-initialization-options) for more information. |
| `Heap.startRecording(environmentId: string, options?: Options)` | `CSQ.start()` |
| `Heap.stopRecording()` | `CSQ.stop()` or `CSQ.pauseTracking()` |

### Autocapture options

```javascript
Heap.startRecording("YOUR_APP_ID", {
  disableInteractionTextCapture: true,
  disableInteractionAccessibilityLabelCapture: true,
});


CSQ.configureProductAnalytics("YOUR_ENVIRONMENT_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()` |
| `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"`.

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.