---
title: From Heap Core SDK + Contentsquare SDK to CSQ SDK - Android
description: Learn how to migrate from the Heap Core and Contentsquare SDKs to the CSQ SDK
lastUpdated: 13 November 2025
source_url:
  html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-from-heap-and-cs-sdk/
  md: https://docs.contentsquare.com/en/csq-sdk-android/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:

* Kotlin

  ```diff
  implementation("io.heap.core:heap-android-core:0.8.+")
  implementation("io.heap.contentsquare.csbridge:contentsquare-bridge:0.8.+)
  implementation("io.heap.autocapture:heap-autocapture-view:0.8.+")
  implementation("io.heap.autocapture:heap-autocapture-compose:0.8.+")
  implementation("com.contentsquare.android:library:4.39.1")
  implementation("com.contentsquare.android:compose:4.39.1")
  implementation("com.contentsquare.android:sdk:1.5.1")
  implementation("com.contentsquare.android:sdk-compose:1.5.1")
  ```

* Groovy

  ```diff
  implementation 'io.heap.core:heap-android-core:0.8.+'
  implementation 'io.heap.contentsquare.csbridge:contentsquare-bridge:0.8.+'
  implementation 'io.heap.autocapture:heap-autocapture-view:0.8.+'
  implementation 'io.heap.autocapture:heap-autocapture-compose:0.8.+'
  implementation 'com.contentsquare.android:library:4.39.1'
  implementation 'com.contentsquare.android:sdk-compose:4.39.1'
  implementation 'com.contentsquare.android:sdk:1.5.1'
  implementation 'com.contentsquare.android:sdk-compose:1.5.1'
  ```

## Library imports

Replace the Heap and Contentsquare dependency imports with a CSQ SDK import.

* Kotlin

  ```diff
  import io.heap.core.Heap
  import io.heap.autocapture.ViewAutocaptureSDK
  import io.heap.contentsquare.csbridge.HeapContentsquareIntegration
  import com.contentsquare.android.Contentsquare
  import com.contentsquare.CSQ
  ```

* Java

  ```diff
  import io.heap.core.Heap;
  import io.heap.autocapture.ViewAutocaptureSDK;
  import io.heap.contentsquare.csbridge.HeapContentsquareIntegration;
  import com.contentsquare.android.Contentsquare;
  import com.contentsquare.CSQ;
  ```

## SDK start

Follow these steps to start the CSQ SDK with your current configuration.

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

   * Kotlin

     ```kotlin
     import android.app.Application
     import com.contentsquare.CSQ


     class MyApplication : Application() {
       override fun onCreate() {
         super.onCreate()


         Heap.startRecording(
           context = this,
           "YOUR_ENVIRONMENT_ID",
           Options(
             // ...options
           )
         )


         CSQ.configureProductAnalytics(
           context = this,
           envId = "YOUR_ENVIRONMENT_ID",
           options = ProductAnalyticsOptions(
             // ...options
           )
         )
       }
     }
     ```

   * Java

     ```java
     import android.app.Application;
     import com.contentsquare.CSQ;


     public class MyApplication extends Application {
       @Override
       public void onCreate() {
         super.onCreate();


         Heap.startRecording(
           this,
           "YOUR_ENVIRONMENT_ID",
           new Options.Builder()
             // .option1(value1)
             // .option2(value2)
             .build()
         );


         ProductAnalyticsOptions options = new ProductAnalyticsOptions.Builder()
           // .option1(value1)
           // .option2(value2)
           .build();


         CSQ.configureProductAnalytics(this, "YOUR_ENVIRONMENT_ID", options);
       }
     }
     ```

   Deprecated configuration options

   The following Heap SDK configuration options are not supported in the CSQ SDK:

   * `startSessionImmediately`
   * `disableInteractionTextCapture`
   * `disableInteractionAccessibilityLabelCapture`

   See [supported options](../command-reference/#product-analytics-initialization-options) for more information.

2. Enable Autocapture with `enableViewAutocapture = true` and remove the call to `ViewAutocaptureSDK.register()`

   * Kotlin

     ```kotlin
     import android.app.Application
     import com.contentsquare.CSQ


     class MyApplication : Application() {
       override fun onCreate() {
         super.onCreate()


         ViewAutocaptureSDK.register()


         CSQ.configureProductAnalytics(
           context = this,
           envId = "YOUR_ENVIRONMENT_ID",
           options = ProductAnalyticsOptions(
             // ...options
             enableViewAutocapture = true
           )
         )
       }
     }
     ```

   * Java

     ```java
     import android.app.Application;
     import com.contentsquare.CSQ;


     public class MyApplication extends Application {
       @Override
       public void onCreate() {
         super.onCreate();


         ViewAutocaptureSDK.register();


         ProductAnalyticsOptions options = new ProductAnalyticsOptions.Builder()
           // ...options
           .enableViewAutocapture(true)
           .build();


         CSQ.configureProductAnalytics(this, "YOUR_ENVIRONMENT_ID", options);
       }
     }
     ```

3. (Optional) For Autocapture Jetpack Compose, register the Compose Autocapture SDK.

   * Kotlin

     ```kotlin
     import android.app.Application
     import com.contentsquare.CSQ
     import io.heap.autocapture.compose.ComposeAutocaptureSDK


     class MyApplication : Application() {
       override fun onCreate() {
         super.onCreate()


         ComposeAutocaptureSDK.register()


         CSQ.configureProductAnalytics(
           context = this,
           envId = "YOUR_ENVIRONMENT_ID",
           options = ProductAnalyticsOptions(
             // ...options
             enableViewAutocapture = true
           )
         )
       }
     }
     ```

   * Java

     ```java
     import android.app.Application;
     import com.contentsquare.CSQ;
     import io.heap.autocapture.compose.ComposeAutocaptureSDK;


     public class MyApplication extends Application {
       @Override
       public void onCreate() {
         super.onCreate();


         ComposeAutocaptureSDK.register();


         ProductAnalyticsOptions options = new ProductAnalyticsOptions.Builder()
           // ...options
           .enableViewAutocapture(true)
           .build();


         CSQ.configureProductAnalytics(this, "YOUR_ENVIRONMENT_ID", options);
       }
     }
     ```

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

   * Kotlin

     ```kotlin
     import android.app.Application
     import com.contentsquare.CSQ


     class MyApplication : Application() {
       override fun onCreate() {
         super.onCreate()


         CSQ.configureProductAnalytics(
           context = this,
           envId = "YOUR_ENVIRONMENT_ID",
           options = ProductAnalyticsOptions(
             // ...options
           )
         )


         CSQ.start(this)
       }
     }
     ```

   * Java

     ```java
     import android.app.Application;
     import com.contentsquare.CSQ;


     public class MyApplication extends Application {
       @Override
       public void onCreate() {
         super.onCreate();


         ProductAnalyticsOptions options = new ProductAnalyticsOptions.Builder()
           // ...options
           .build();


         CSQ.configureProductAnalytics(this, "YOUR_ENVIRONMENT_ID", options);


         CSQ.start(this);
       }
     }
     ```

5. Remove `HeapContentsquareIntegration.bind()`.

   Sending Heap screenviews to Contentsquare

   * Kotlin

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

   * Java

     ```java
     HeapContentsquareIntegration.bind(
       applicationContext,
       true, // sendHeapPageviewsToContentsquare
       false // sendContentsquareScreenviewsToHeap
     );
     ```

   Note

   Make sure you don't have calls to `CSQ.trackScreenview()` if you have Android View autocapture enabled.

   Sending Contentsquare screenviews to Heap

   * Kotlin

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


     CSQ.configureProductAnalytics(
       context = this,
       envId = "YOUR_ENVIRONMENT_ID",
       options = ProductAnalyticsOptions(
         resumePreviousSession = true,
         disablePageviewAutocapture = true
       )
     )
     ```

   * Java

     ```java
     HeapContentsquareIntegration.bind(
       applicationContext,
       false, // sendHeapPageviewsToContentsquare
       true // sendContentsquareScreenviewsToHeap
     );


     ProductAnalyticsOptions options = new ProductAnalyticsOptions.Builder()
       .resumePreviousSession(true)
       .disablePageviewAutocapture(true)
       .build();


     CSQ.configureProductAnalytics(this, "YOUR_ENVIRONMENT_ID", options);
     ```

6. (Optional) For Autocapture notifications, replace `NotificationAutocaptureSDK.register()` with these options:

   * Kotlin

     ```kotlin
     NotificationAutocaptureSDK.register(
       captureTitleText = true,
       captureBodyText = true
     )


     CSQ.configureProductAnalytics(
       context = this,
       envId = "YOUR_ENVIRONMENT_ID",
       options = ProductAnalyticsOptions(
         // ...options
         enablePushNotificationAutocapture = true,
         enablePushNotificationTitleAutocapture = true,
         enablePushNotificationBodyAutocapture = true
       )
     )
     ```

   * Java

     ```java
     NotificationAutocaptureSDK.register(
       captureTitleText = true,
       captureBodyText = true
     );


     ProductAnalyticsOptions options = new ProductAnalyticsOptions.Builder()
       // ...options
       .enablePushNotificationAutocapture(true)
       .enablePushNotificationTitleAutocapture(true)
       .enablePushNotificationBodyAutocapture(true)
       .build();


     CSQ.configureProductAnalytics(this, "YOUR_ENVIRONMENT_ID", options);
     ```

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

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

* Kotlin

  ```kotlin
  CSQ.start(context)
  // ...
  val optinButton: Button = ...
  optinButton.setOnClickListener {
      CSQ.optIn(it.context)
      // Then finish initialization and move to the next screen...
  }
  ```

* Java

  ```java
  CSQ.start(context);
  // ...
  Button optinButton = ...
  optinButton.setOnClickListener(view -> {
      CSQ.optIn(view.getContext());
      // Then finish initialization and move to the next screen...
  });
  ```

## Transactions

1. Update your transaction imports:

   * Kotlin

     ```diff
     import com.contentsquare.android.api.model.Transaction
     import com.contentsquare.api.model.Transaction
     ```

   * Java

     ```diff
     import com.contentsquare.android.api.model.Transaction;
     import com.contentsquare.api.model.Transaction;
     ```

2. Update your currency imports:

   * Kotlin

     ```diff
     import com.contentsquare.android.api.Currencies
     import com.contentsquare.api.model.Currency
     ```

   * Java

     ```diff
     import com.contentsquare.android.api.Currencies;
     import com.contentsquare.api.model.Currency;
     ```

3. Replace the currency type from `Int` to `Currency` enum:

   * Kotlin

     ```diff
     val currency: Int = Currencies.USD
     val currency: Currency = Currency.USD
     ```

   * Java

     ```diff
     int oldCurrency = Currencies.USD;
     Currency newCurrency = Currency.USD;
     ```

4. Replace `Transaction.builder` by `Transaction` and `Contentsquare.send()` by `CSQ.trackTransaction()`:

   * Kotlin

     ```diff
     val builder = Transaction.builder(100f, Currency.EUR).id("optionalId")
     Contentsquare.send(builder.build())
     val transaction = Transaction(100f, Currency.EUR, "optionalId")
     CSQ.trackTransaction(transaction)
     ```

   * Java

     ```diff
     Transaction.TransactionBuilder builder = Transaction.Companion.builder(100f, Currency.EUR).id("optionalId");
     Contentsquare.send(builder.build());
     Transaction transaction = new Transaction(100f, Currency.EUR, "optionalId");
     CSQ.trackTransaction(transaction);
     ```

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

```diff
Contentsquare.start(this)
Heap.startRecording(this)
CSQ.start(this)
```

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()` |
| `Heap.getUserId()` | `CSQ.metadata.userId` |
| `Heap.getSessionId()` | `CSQ.metadata.sessionId` |
| `Heap.getEnvironmentId()` | `CSQ.metadata.environmentId` |
| `Heap.getIdentity()` | `CSQ.metadata.identity` |

### Logging

| Heap Core SDK | CSQ SDK |
| - | - |
| `import io.heap.core.logs.LogLevel` | `import com.contentsquare.api.contract.LogLevel` |
| `Heap.setLogLevel()` | `CSQ.debug.logLevel = LogLevel.{LEVEL}` Possible values: - `LogLevel.NONE`
- `LogLevel.TRACE`
- `LogLevel.DEBUG`
- `LogLevel.INFO`
- `LogLevel.WARN`
- `LogLevel.ERROR` |
| `import io.heap.core.logs.LogChannel` | `import com.contentsquare.api.contract.LogChannel` |
| `Heap.setLogChannel(logChannel: LogChannel)` | `interface LogChannel` `CSQ.debug.logChannel = LogChannel()` |

### Property tracking

| Heap Core SDK | CSQ SDK |
| - | - |
| `Heap.addUserProperties(properties: Map<String, Any>)` | `CSQ.addUserProperties(properties: Map<String, Any>)` |
| `Heap.addEventProperties(properties: Map<String, Any>)` | `CSQ.addEventProperties(properties: Map<String, Any>)` |
| `Heap.removeEventProperty(name: String)` | `CSQ.removeEventProperty(name: String)` |
| `Heap.clearEventProperties()` | `CSQ.clearEventProperties()` |
| `import io.heap.core.api.contract.HeapProperty` | `import com.contentsquare.api.contract.Property` |

### Event tracking

| Heap Core SDK | CSQ SDK |
| - | - |
| `Heap.trackPageview()` | `CSQ.trackScreenview(name: String, customVars: List<CustomVar>)` |
| `Heap.track()` | `CSQ.trackEvent(name: String, properties: Map<String, PropertyValue>?)` |

### Personal Data Handling and Masking

| Heap Core SDK | CSQ SDK |
| - | - |
| `ViewAutocaptureSDK.ignoreInteractions(view: View)` | `CSQ.ignoreInteractions(view: View)` |
| `ViewAutocaptureSDK.redactText(view: View)` | `CSQ.mask(view: View)` |
| `view.setTag(R.id.heapRedactText, false)` | `CSQ.unmask(view: View)` |
| Initialization options `disableInteractionTextCapture` and `disableInteractionAccessibilityLabelCapture` | `CSQ.maskTexts(mask: Boolean)` |

Kotlin extension functions

If you use Kotlin, the CSQ SDK comes with Extension functions for:

* `CSQ.ignoreInteractions(view: View)` -> `View.csqIgnoreInteractions(shouldIgnore: Boolean)`
* `CSQ.unmask(view: View)` -> `View.csqMaskContents(true)`
* `CSQ.unmask(view: View)` -> `View.csqMaskContents(false)`

### Jetpack compose

| Heap Core SDK | CSQ SDK |
| - | - |
| ```
@Composable
HeapRedact(redact: Boolean)
``` | ```
@Composable
CsqMask(enable: Boolean)
``` |
| ```
@Composable
HeapIgnore(ignore: Boolean)
``` | ```
@Composable
CsqIgnoreInteraction(ignore: Boolean)
``` |

### SDK initialization and manipulation

| Heap Core SDK | CSQ SDK |
| - | - |
| `import io.heap.core.Options` | `import com.contentsquare.api.model.ProductAnalyticsOptions` |
| Heap SDK initialization options | `CSQ.configureProductAnalytics(context: Context, envId: String, options: ProductAnalyticsOptions)` See [supported options](../command-reference/#product-analytics-initialization-options) for more information. |
| `Heap.startRecording(context: Context, envId: String, options: Options)` | `CSQ.start(Context)` |
| `Heap.startRecording(context: Context, envId: String, options: Options)` with `resumePreviousSession = true` | `CSQ.resumeTracking()` |
| `Heap.stopRecording()` | `CSQ.stop()` or `CSQ.pauseTracking()` |
| `Heap.stopRecording(deleteUser = true)` | `CSQ.stop()` + `CSQ.optOut()` |

### Experience Analytics

### GDPR / Identification

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.optIn(context: Context)` | `CSQ.optIn(context: Context)` |
| `Contentsquare.optOut(context: Context)` | `CSQ.optOut()` |
| `Contentsquare.getUserId()` | `CSQ.metadata.userId` |
| `Contentsquare.getProjectId()` | `CSQ.metadata.projectId` |
| `Contentsquare.getSessionNumber()` | `CSQ.metadata.sessionId` |
| `Contentsquare.sendUserIdentifier(identifier: String)` | `CSQ.sendUserIdentifier(identifier: String)` |

### Property tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.send(key: String, value: Long)` | `CSQ.addDynamicVar(key: String, value: Long)` |
| `Contentsquare.send(key: String, value: String)` | `CSQ.addDynamicVar(key: String, value: String)` |

### View tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.excludeFromExposureMetric(view: View)` | `CSQ.excludeFromExposureMetric(view: View)` |

### Interoperability

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.onSessionReplayLinkChange(callback: Consumer<String>)` | `CSQ.metadata.onChanged(metadata: Metadata)` |
| `CsWebViewManager.injectEventTrackingInterface(webView: WebView)` | `CSQ.registerWebView(webView: WebView)` |
| `CsWebViewManager.removeEventTrackingInterface(webView: WebView)` | `CSQ.unregisterWebView(webView: WebView)` |

### Event tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.send(transaction: Transaction)` | `CSQ.trackTransaction(transaction: Transaction)` |
| `Contentsquare.send(screenName: String)` / `Contentsquare.send(screenName: String, customVars: Array<CustomVar>)` | `CSQ.trackScreenview(name: String, customVars: List<CustomVar>)` |
| `Contentsquare.consumeEvent(motionEvent: MotionEvent)` | `CSQ.trackMotionEvent(motionEvent: MotionEvent)` |

Jetpack compose

| Contentsquare SDK | CSQ SDK |
| - | - |
| `import com.contentsquare.android.compose.analytics.TriggeredOnResume` `TriggeredOnResume(block: () -> Unit)` | `import com.contentsquare.api.compose.screen.TriggeredOnResume` `TriggeredOnResume(block: () -> Unit)` |

### Error tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `import com.contentsquare.android.error.analysis.network.ErrorAnalysisInterceptor` | `import com.contentsquare.api.contract.CsqOkHttpInterceptor` |
| `import com.contentsquare.android.error.analysis.ErrorAnalysis` | `import com.contentsquare.api.model.NetworkMetric` |
| `ErrorAnalysis.setUrlMaskingPatterns(patterns: List<String>)` | `CSQ.setUrlMaskingPatterns(patterns: List<String>)` |
| `ErrorAnalysis.getInstance().newNetworkMetric(url: String, httpMethod: HttpMethod)` | `NetworkMetric(url: String, httpMethod: HttpMethod)` |
| `ErrorAnalysisInterceptor()` | `CsqOkHttpInterceptor()` |

### Personal Data Handling and Masking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.doNotTrack(vararg activitiesClasses: Class<Activity?>)` | `CSQ.ignoreInteractions(view: View)` |
| `Contentsquare.setDefaultMasking(masked: Boolean)` | `CSQ.setDefaultMasking(masked: Boolean)` |
| `Contentsquare.mask(view: View)` | `CSQ.mask(view: View)` |
| `Contentsquare.mask(type: Class<*>)` | `CSQ.mask(type: Class<*>)` |
| `Contentsquare.unMask(view: View)` | `CSQ.unmask(view: View)` |
| `Contentsquare.unmask(type: Class<*>)` | `CSQ.unmask(type: Class<*>)` |

Kotlin extension functions

If you use Kotlin, the CSQ SDK comes with Extension functions for:

* `CSQ.ignoreInteractions(view: View)` -> `View.csqIgnoreInteractions(shouldIgnore: Boolean)`
* `CSQ.unmask(view: View)` -> `View.csqMaskContents(true)`
* `CSQ.unmask(view: View)` -> `View.csqMaskContents(false)`

### Jetpack compose

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Modifier.sessionReplayMask(enableMasking: Boolean)` | `@Composable
CsqMask(enable: Boolean) { }` |
| `Modifier.excludeFromGestureRecognition()` | `@Composable
CsqIgnoreInteraction(ignore: Boolean)` |

### SDK initialization and manipulation

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.start(context: Context)` | `CSQ.start(context: Context)` |
| `Contentsquare.stopTracking()` | `CSQ.pauseTracking()` |
| `Contentsquare.resumeTracking()` | `CSQ.resumeTracking()` |

## Checklist

Congratulations! You're all set. Use this checklist to ensure everything is correctly updated.

Ensure that your build files no longer reference `io.heap.core:heap-android-core`, `io.heap.autocapture:heap-autocapture-view`, `com.contentsquare.android:library`, or `com.contentsquare.android:sdk-compose`.

Your `import io.heap.core.Heap`, `import io.heap.autocapture.ViewAutocaptureSDK`, and `com.contentsquare.android.Contentsquare;` declarations have been updated to `import com.contentsquare.CSQ`.

You no longer have references to `Heap.` (except if you are using webviews), `HeapContentsquareIntegration.`, or `Contentsquare.` methods in your codebase.

All calls to the CSQ SDK use the `CSQ.`namespace.

## Number of sessions

After adding Product Analytics to your implementation, you may observe a change in the number of sessions collected due to a change of the session timeout definition:

* (previously) Session would timeout 30 minutes after app is in background
* (now) Session would timeout 30 minutes after last event

This is part of our strategy to have a behavior that is more aligned with market standards and web definition.