---
title: From Heap Core SDK + Contentsquare SDK to CSQ SDK - Flutter
description: Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK
lastUpdated: 05 January 2026
source_url:
  html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-heap-and-cs-sdk/
  md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-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.

Migration script

Contentsquare provides a migration path using a script that automates most of the common API replacements from your current project to CSQ SDK 4.0.

Follow these steps:

1. Back up your project.

2. Download and save the [migration script](https://docs.contentsquare.com/csq_flutter_4.0.0_migration.dart) on your machine.

3. Open your terminal and navigate to the script directory:

   ```bash
   cd </path/to/directory/with/migration/script>
   ```

4. Run the script with your Flutter project path as an argument:

   ```bash
   dart migration.dart <path_to_your_flutter_project>
   ```

5. Once the script completes, you'll need to:

   **Review all generated comments** - The script adds comments (marked with `//`) where manual updates are required

   **Fix compilation errors** - Address any errors that the automated migration couldn't handle

   **Test your application thoroughly** - Verify that all functionality works as expected

   **Update custom implementations** - Review and update any custom code that may have been affected by the migration

This script does is provided as-is and does not cover all pattens or edge cases including:

* Custom wrapper implementations around legacy SDKs
* Complex conditional logic using deprecated APIs
* Dynamic method calls or reflection-based usage
* Platform-specific custom implementations beyond standard patterns

Support tickets regarding this migration path will not be considered.

## Dependency upgrades

Increment the Contentsquare SDK in `pubspec.yaml` to the latest version.

```diff
dependencies:
  heap_flutter_bridge: ^0.4.0
  heap_flutter_autocapture: ^0.6.0
  contentsquare: ^3.19.1
  contentsquare: ^4.0.0
```

Sync your dependencies by running `flutter pub get`.

Replace the Contentsquare SDK import with a CSQ SDK import.

```diff
import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';
import 'package:heap_flutter_autocapture/heap_flutter_autocapture.dart';
import 'package:contentsquare/contentsquare.dart';
import 'package:contentsquare/csq.dart';
```

Warning

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

1. `Optional`: If you were using `ContentsquareRoot` widget - remove it from your widget tree.

   ```dart
   void main() {
     runApp(const MyApp());
   }


   class MyApp extends StatelessWidget {
     @override
     Widget build(BuildContext context) {
       return ContentsquareRoot(
         child: MaterialApp(
       return MaterialApp(
         title: 'My Flutter App',
         home: Home()
         ),
       );
     }
   }
   ```

2. Delete `Heap().startRecording()` and migrate options to `CSQ().configureProductAnalytics()`.

   ```dart
   import 'package:contentsquare/csq.dart';


   void main() async {
     await Heap().startRecording('YOUR_ENVIRONMENT_ID', {
       // your previous options
     });
     await CSQ().configureProductAnalytics(
       environmentId: 'YOUR_ENVIRONMENT_ID',
       options: ProductAnalyticsOptions(
         // Migrate options here
       ),
     );
   }
   ```

3. Start the CSQ SDK manually.

   Add the `CSQ().start()` call after the configuration (and remove `Contentsquare().start()` if you had it before):

   ```dart
   import 'package:contentsquare/csq.dart';


   void main() async {
     await CSQ().configureProductAnalytics(
       environmentId: 'YOUR_ENVIRONMENT_ID',
       options: ProductAnalyticsOptions(
         // Migrate options here
       ),
     );


     await Contentsquare().start();
     await CSQ().start();
   }
   ```

4. Remove `HeapAutocapture` registration:

   ```dart
   await HeapAutocapture.register();
   ```

5. Update pageview autocapture setup

   ```dart
   import 'package:contentsquare/csq.dart';


   await HeapAutocapture.register();


   MaterialApp(
     navigatorObservers: [
       HeapNavigatorObserver(),
       CSQNavigatorObserver(),
     ],
     home: MyHomePage(),
   )
   ```

6. Recommended In order to enable automatic capture of user interactions, add the option `enableInteractionsAutocapture: true` to your `ProductAnalyticsOptions` configuration:

   ```dart
   import 'package:contentsquare/csq.dart';


   void main() async {
     await CSQ().configureProductAnalytics(
       environmentId: 'YOUR_ENVIRONMENT_ID',
       options: ProductAnalyticsOptions(
         enableInteractionsAutocapture: true,
       ),
     );
     await CSQ().start();
   }
   ```

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

   * Swift

     ```xml
     <key>CSDisableAutostart</key>
     <true/>
     ```

     ```swift
     Contentsquare.start()
     ```

   * Objective-C

     ```xml
     <key>CSDisableAutostart</key>
     <true/>
     ```

     ```objc
     [Contentsquare start];
     ```

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

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

9. Remove Heap Android dependencies

   ```kotlin
   dependencies {
     implementation("io.heap.core:heap-android-core:+")
     implementation("io.heap.contentsquare.csbridge:contentsquare-bridge:+")
   }
   ```

10. Remove Heap iOS dependencies:

    * Swift Package Manager

      1. In Xcode, navigate to your project settings.
      2. Select your app target, then go to the **Frameworks, Libraries, and Embedded Content** section.
      3. Find `HeapContentsquareIntegrationSDK` in the list and click the **-** button to remove it.
      4. Go to **File → Packages → Resolve Package Versions** to update your package dependencies.

    * CocoaPods

      1. Remove the line that contains `pod 'HeapContentsquareIntegrationSDK'` from your app target in your `Podfile`.
      2. Run `pod install` within your project directory to update your dependencies.

11. Remove Initializing Integration:

    * Kotlin

      ```kotlin
      HeapContentsquareIntegration.bind(
        applicationContext,
        sendHeapPageviewsToContentsquare = false,
        sendContentsquareScreenviewsToHeap = true
      )
      ```

    * Swift

      ```swift
      HeapContentsquareIntegration.bind(
        sendHeapPageviewsToContentsquare: false,
        sendContentsquareScreenviewsToHeap: true
      )
      ```

## Get user consent

Implement the [`optIn()`](../command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID.

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

It can be done immediately after `start` is called:

```dart
void main() async {
  // ...
  await CSQ().start();
  await CSQ().optIn();
  // ...
}
```

Alternatively, you can call `optIn()` in response to a user action, such as tapping an "I agree" button:

```dart
class UserConsentScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('User Consent'),
      ),
      body: Center(
        child: ElevatedButton(
          onPressed: () async {
            await CSQ().optIn();
          },
          child: Text('Agree with Terms and Conditions'),
        ),
      ),
    );
  }
}
```

## Update API

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.

```diff
Contentsquare().start()
CSQ().start()
```

For more information on SDK methods, see the [SDK API reference](../command-reference/).

### Update Contentsquare SDK APIs

### GDPR / Identification

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare().optIn()` | `CSQ().optIn()` |
| `Contentsquare().optOut()` | `CSQ().optOut()` |
| `Contentsquare().sendUserIdentifier()` | `CSQ().sendUserIdentifier()` |
| `Contentsquare().getUserId()` | `CSQ().metadata.userID` |

Removed

**Contentsquare().forgetMe()**

You can use `CSQ().optOut()` instead to forget user id and stop tracking. If needed call `CSQ().optIn()` when you want to resume tracking.

### Property tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare().sendDynamicVar(key: String, intValue: int)`. | `CSQ().addDynamicVar(DynamicVar.fromIn(key: String, value: int))` |
| `Contentsquare().sendDynamicVar(key: String, stringValue: String)`. | `CSQ().addDynamicVar(DynamicVar.fromString(key: String, value: String))` |

### CSInApp (iOS only)

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.handle(url: URL)` | `CSQ.handle(url: URL)` |
| `Contentsquare.csInApp` | `CSQ.csInApp` |

### Interoperability

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare().onSessionReplayLinkChange(callback)` | `CSQ().metadata.onChange(Metadata)` |
| `Contentsquare().currentSessionReplayUrl` | `CSQ().metadata.onChange(Metadata)` |
| `Contentsquare().setURLMaskingPatterns()` | `CSQ().setURLMaskingPatterns()` |
| `ContentsquareNavigatorObserver()`. | `CSQNavigatorObserver()` |
| `ContentsquareWebViewWrapper()`. | `CSQWebViewWrapper()` |

### Event tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.sendTransaction(double, String, String, String?)` | `CSQ.trackTransaction(Transaction(price: double, currency: Currency, id: String))` |
| `Contentsquare.send(String)` | `CSQ.trackScreenview(screenName: String)` |
| `Contentsquare.send(String, List<CustomVar>?)` | `CSQ.trackScreenview(screenName: String, customVars: List<CustomVar>)` |

### Error tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `ContentsquareHttpOverrides()` | `CSQHttpOverrides()` |
| `Contentsquare().collectFlutterError(details: FlutterErrorDetails, presentErrorDetails: bool)` | `CSQ().collectFlutterError(details: FlutterErrorDetails, presentErrorDetails: bool)`. |
| `Contentsquare().collectError(error: Object, stackTrace: StackTrace)` | `CSQ().collectError(error: Object, stackTrace: StackTrace)` |

### Personal Data Handling and Masking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `MaskingConfig()` | `CSQMaskingConfig()` |
| `SessionReplayMaskingScope` | `CSQMask` |

### SDK initialization and manipulation

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare().start()` | `CSQ().start()` |
| `Contentsquare().stopTracking()` | `CSQ().pauseTracking()` |
| `Contentsquare().resumeTracking()` | `CSQ().resumeTracking()` |
| `Contentsquare().triggerReplayForCurrentSession(name: String)` | `CSQ().triggerReplayForCurrentSession(name: String)` |
| `Contentsquare().triggerReplayForCurrentScreen(name: String)` | `CSQ().triggerReplayForCurrentScreen(name: String)` |

### Update Heap Core SDK APIs

### GDPR / Identification

| Heap SDK | CSQ SDK |
| - | - |
| `Heap().identify(string)` | `CSQ().identify(userIdentifier: String)` |
| `Heap().resetIdentity()` | `CSQ().resetIdentity()` |
| `Heap().getUserId()` | `CSQ().metadata.userId` |
| `Heap().getSessionId()` | `CSQ().metadata.sessionId` |
| `Heap().getEnvironmentId()` | `CSQ().metadata.environmentId` |
| `Heap().getIdentity()` | `CSQ().metadata.identity` |

### Logging

| Heap SDK | CSQ SDK |
| - | - |
| `Heap().setLogLevel(LogLevel)` | `CSQ().debug.logLevel { get set }` |

### Property tracking

| Heap SDK | CSQ SDK |
| - | - |
| `Heap().addUserProperties(Map<String, dynamic>)` | `CSQ().addUserProperties(properties: Map<String, dynamic>)` |
| `Heap().addEventProperties(Map<String, dynamic>)` | `CSQ().addEventProperties(properties: Map<String, dynamic>)` |
| `Heap().removeEventProperty(name: String)` | `CSQ().removeEventProperty(name: String)` |
| `Heap().clearEventProperties()` | `CSQ().clearEventProperties()` |

### Event tracking

| Heap SDK | CSQ SDK |
| - | - |
| `Heap().track(String, [Map<String, dynamic>])` | `CSQ().trackEvent(eventName: String, properties: Map<String, dynamic>?)` |

### Personal Data Handling and Masking

| Heap SDK | CSQ SDK |
| - | - |
| `HeapRedact(redact: bool)` | `CSQMask(config: CSQMaskingConfig(maskTexts: true))` |
| `HeapIgnore(ignore: bool)` | `CSQMask(config: CSQMaskingConfig(maskInteractions: true))` |

### SDK initialization and manipulation

| Heap SDK | CSQ SDK |
| - | - |
| `Heap().startRecording(id, options)` | CSQ().configureProductAnalytics(environmentID: String, options: ProductAnalyticsOptions)`+`CSQ().start()\` |
| `Heap().stopRecording(deleteUser = true)` | `CSQ().stop()` |
| `Heap().stopRecording(deleteUser = false)` | `CSQ().pauseTracking()` |