From Heap Classic SDK to CSQ SDK

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

→

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

Heap Classic SDK (`com.heapanalytics.android:heap-android-client`)

Replace the Heap Classic SDK dependency by the CSQ SDK.

Kotlin
Groovy

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

implementation 'com.heapanalytics.android:heap-android-client:1.10.+'
implementation 'com.contentsquare.android:sdk:1.0.0'

Library imports

Replace Heap Classic imports with a CSQ SDK import.

Kotlin
Java

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

import com.heapanalytics.android.Heap;
import com.contentsquare.CSQ;

SDK start

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

Migrate your app ID from Heap.init() to CSQ.configureProductAnalytics().

Kotlin
Java

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

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

    Heap.init(this, "YOUR_ENVIRONMENT_ID")
    CSQ.configureProductAnalytics(
      context = this,
      envId = "YOUR_ENVIRONMENT_ID"
    )
  }
}

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

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

    Heap.init(this, "YOUR_ENVIRONMENT_ID");
    CSQ.configureProductAnalytics(
      this,
      "YOUR_ENVIRONMENT_ID"
    );
  }
}

To maintain autocapture functionality, add the enableViewAutocapture = true option:

Kotlin
Java

import android.app.Application
import com.contentsquare.CSQ
import com.contentsquare.api.model.ProductAnalyticsOptions

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

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

import android.app.Application;
import com.contentsquare.CSQ;
import com.contentsquare.api.model.ProductAnalyticsOptions;

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

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

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

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

Kotlin
Java

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(
        enableViewAutocapture = true
      )
    )

    CSQ.start(this)
  }
}

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

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

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

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

    CSQ.start(this);
  }
}

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

Kotlin
Java

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

// ...
CSQ.start(context)
// ...

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

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

// ...
CSQ.start(context);
// ...

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

Implement the optIn() 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.

Heap.track("some_event", mapOf("prop1" to "value1"))
CSQ.trackEvent("some_event", mapOf("prop1" to "value1"))

For more information on SDK methods, see the SDK API reference.

GDPR / Identification

Heap Classic SDK	CSQ SDK
`Heap.identify(string)`	`CSQ.identify(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)`

SDK initialization and manipulation

Heap Classic SDK	CSQ SDK
`Heap.init(context, id)`	`CSQ.start(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.