From Heap Core 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 Core 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

Replace Heap SDK dependencies with the CSQ SDK:

Kotlin
Groovy

implementation("io.heap.core:heap-android-core:0.8.+")
implementation("io.heap.core.web:webview-heapjs:0.8.+")
implementation("io.heap.core.identifier:ad-id-google:0.8.+")
implementation("io.heap.core.identifier:vendor-id-google:0.8.+")
implementation("io.heap.autocapture:heap-autocapture-view:0.8.+")
implementation("io.heap.autocapture:heap-autocapture-notification:0.8.+")
implementation("io.heap.autocapture:heap-autocapture-compose:0.8.+")
implementation("com.contentsquare.android:sdk:1.10.0")
implementation("com.contentsquare.android:sdk-compose:1.10.0")

implementation 'io.heap.core:heap-android-core:0.8.+'
implementation 'io.heap.core.web:webview-heapjs:0.8.+'
implementation 'io.heap.core.identifier:ad-id-google:0.8.+'
implementation 'io.heap.core.identifier:vendor-id-google:0.8.+'
implementation 'io.heap.autocapture:heap-autocapture-view:0.8.+'
implementation 'io.heap.autocapture:heap-autocapture-notification:0.8.+'
implementation 'io.heap.autocapture:heap-autocapture-compose:0.8.+'
implementation 'com.contentsquare.android:sdk:1.10.0'
implementation 'com.contentsquare.android:sdk-compose:1.10.0'

If you're using autocapture, the Heap Gradle plugin must remain in your project configuration.

Kotlin
Groovy

plugins {
  id("io.heap.gradle") version "1.1.1"
  // ...
}

plugins {
  id 'io.heap.gradle' version "1.1.1"
  // ...
}

Library imports

Replace Heap Core and Autocapture SDK imports with a unified CSQ SDK import.

import io.heap.core.Heap
import io.heap.autocapture.ViewAutocaptureSDK
import io.heap.autocapture.notification.NotificationAutocaptureSDK
import com.contentsquare.CSQ

SDK start

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

Delete Heap.startRecording() and migrate configuration options to CSQ.start().

Standalone
Unified CSQ

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

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

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

Standalone
Unified CSQ

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

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

  ViewAutocaptureSDK.register()

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

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

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

  ViewAutocaptureSDK.register()

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

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

Standalone
Unified CSQ

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
        )
      )
    )
  }
}

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
        )
      )
    )
  }
}

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

Standalone
Unified CSQ

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))
}

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.

Heap.startRecording("YOUR_ENVIRONMENT_ID")
CSQ.start(this, StartConfig.withEnvironmentId("YOUR_ENVIRONMENT_ID"))

For more information on SDK methods, see the SDK API 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.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)`

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.AnalyticsOptions`
Heap SDK initialization options	`CSQ.start(context, StartConfig.withEnvironmentId(id = "envId", options = AnalyticsOptions()))` See supported options for more information.
`Heap.startRecording(context: Context, envId: String, options: Options)`	`CSQ.start(context, StartConfig.withEnvironmentId(id = "envId", options = AnalyticsOptions()))`
`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()`

Checklist

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

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

Your io.heap.* import 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.