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

**Heap Classic 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.

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

   * Standalone

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

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

   * Standalone

     **App.tsx**

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


     useEffect(() => {
       CSQ.start(StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID", {
         enableRNAutocapture: true
       }));
     }, []);
     ```

   * CSQ Experience Platform

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