---
title: From Heap Classic SDK to CSQ SDK - Android
description: Learn how to migrate from the Heap Classic SDK to the CSQ SDK
lastUpdated: 12 May 2026
source_url:
  html: https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/upgrade-from-heap-classic-sdk/
  md: https://docs.contentsquare.com/en/csq-sdk-android/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.

Tip

**Integrate faster with AI skills** Beta — Use the Contentsquare AI skills to let your AI coding assistant handle SDK setup, version migration, and feature implementation automatically. [Explore AI skills](https://docs.contentsquare.com/csq-sdk-android/product-analytics/using-agent-skills/)

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)
* **Different autocapture events**: Captures slider/date/time picker changes instead of menu/carousel/tab clicks, with enhanced UI hierarchy data
* **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
* **Removed properties**: No longer captures `ANDROID_ID`, `Build Type`, or `Build Flavor`

## Dependency upgrades

Replace the Heap Classic SDK dependency by the CSQ SDK.

* Kotlin

  **build.gradle.kts**

  ```diff
  implementation("com.heapanalytics.android:heap-android-client:1.10.+")
  implementation("com.contentsquare.android:sdk:1.10.1")
  ```

* Groovy

  **build.gradle**

  ```diff
  implementation 'com.heapanalytics.android:heap-android-client:1.10.+'
  implementation 'com.contentsquare.android:sdk:1.10.1'
  ```

## Library imports

Replace Heap Classic imports with a CSQ SDK import.

```diff
import com.heapanalytics.android.Heap
import com.contentsquare.CSQ
```

## SDK start

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

1. Migrate your app ID from `Heap.init()` to `CSQ.start()`.

   * Standalone

     **MyApplication.kt**

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


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


       Heap.init(this, "YOUR_ENVIRONMENT_ID")
       CSQ.start(
         context = this,
         StartConfig.withEnvironmentId(
           id = "YOUR_ENVIRONMENT_ID"
         )
       )
     }
     }
     ```

   * Unified CSQ

     **MyApplication.kt**

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


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


       Heap.init(this, "YOUR_ENVIRONMENT_ID")
       CSQ.start(
         context = this,
         StartConfig.withDataSourceId(
           id = "YOUR_DATASOURCE_ID"
         )
       )
     }
     }
     ```

2. To maintain autocapture functionality, add the `enableViewAutocapture` option:

   * Standalone

     **MyApplication.kt**

     ```kotlin
     import android.app.Application
     import com.contentsquare.CSQ
     import com.contentsquare.api.model.AnalyticsOptions


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


       CSQ.start(
         context = this,
         StartConfig.withEnvironmentId(
           id = "YOUR_ENVIRONMENT_ID",
           options = AnalyticsOptions(
             // ...options
             enableViewAutocapture = true
           )
         )
       )
     }
     }
     ```

   * Unified CSQ

     **MyApplication.kt**

     ```kotlin
     import android.app.Application
     import com.contentsquare.CSQ
     import com.contentsquare.api.model.AnalyticsOptions


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


       CSQ.start(
         context = this,
         StartConfig.withDataSourceId(
           id = "YOUR_DATASOURCE_ID",
           options = AnalyticsOptions(
             // ...options
             enableViewAutocapture = true
           )
         )
       )
     }
     }
     ```

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

   * Standalone

     **MyApplication.kt**

     ```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.start(
           context = this,
           StartConfig.withEnvironmentId(
             id = "YOUR_ENVIRONMENT_ID",
             options = AnalyticsOptions(
               // ...options
               enableViewAutocapture = true
             )
           )
         )
       }
     }
     ```

   * Unified CSQ

     **MyApplication.kt**

     ```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.start(
           context = this,
           StartConfig.withDataSourceId(
             id = "YOUR_DATASOURCE_ID",
             options = AnalyticsOptions(
               // ...options
               enableViewAutocapture = true
             )
           )
         )
       }
     }
     ```

## Get user consent

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

* Standalone

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


  class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        CSQ.start(this, StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID"))
    }
  }


  // ConsentActivity
  val optinButton: Button = findViewById(R.id.btn_accept_tracking)


  optinButton.setOnClickListener {
    CSQ.optIn()
    startActivity(Intent(this, MainActivity::class.java))
  }
  ```

* Unified CSQ

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


  class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        CSQ.start(this, StartConfig.withDataSourceId("YOUR_DATASOURCE_ID"))
    }
  }


  // ConsentActivity
  val optinButton: Button = findViewById(R.id.btn_accept_tracking)


  optinButton.setOnClickListener {
    CSQ.optIn()
    startActivity(Intent(this, MainActivity::class.java))
  }
  ```

Once tracking has started, you're able to take full advantage of the CSQ SDK API to identify users, track custom events, and more.

Contentsquare's Product Analytics module will also automatically start tracking a wide range of user interactions, view controller changes, and app version changes without any additional code.

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

```diff
Heap.init("YOUR_ENVIRONMENT_ID")
CSQ.start(this, StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID"))
```

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

### 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.getIdentity()` | `CSQ.metadata.identity` |

### Property tracking

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

### Event tracking

| Heap Classic SDK | CSQ SDK |
| - | - |
| `Heap.track(event: String, properties: Map<String, String>)` | `CSQ.trackEvent(name: String, properties: Map<String, PropertyValue>?)` |

### Personal Data Handling and Masking

| Heap Classic SDK | CSQ SDK |
| - | - |
| `Heap.ignore(view: View)` | `CSQ.ignoreInteractions(view: View)` |

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

### SDK initialization and manipulation

| Heap Classic SDK | CSQ SDK |
| - | - |
| `Heap.init(context: Context, id: String)` | `CSQ.start(context: Context)` |
| `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 your build files no longer reference `com.heapanalytics.android:heap-android-client`.

Your `import com.heapanalytics.android.Heap` declarations have been updated to `import com.contentsquare.CSQ`.

You no longer have references to `Heap.` methods in your codebase.

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