From Heap Core SDK + Contentsquare SDK to CSQ SDK

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

Contentsquare 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

Upgrade your dependency based on your current SDK.

CSQ SDK

Upgrade to the latest CSQ SDK version:

Kotlin
Groovy

implementation("com.contentsquare.android:sdk:0.7.1")
implementation("com.contentsquare.android:sdk-compose:0.7.1")
implementation("com.contentsquare.android:sdk:1.0.1")
implementation("com.contentsquare.android:sdk-compose:1.0.1")

implementation 'com.contentsquare.android:sdk:0.7.1'
implementation 'com.contentsquare.android:sdk-compose:0.7.1'
implementation 'com.contentsquare.android:sdk:1.0.1'
implementation 'com.contentsquare.android:sdk-compose:1.0.1'

Heap Core and Contentsquare SDKs

Replace Heap SDK dependencies by the CSQ SDK:

Kotlin
Groovy

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.0.1")
implementation("com.contentsquare.android:sdk-compose:1.0.1")

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.0.1'
implementation 'com.contentsquare.android:sdk-compose:1.0.1'

Library imports

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

Kotlin
Java

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

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.

Migrate your app ID and the config options from Heap.startRecording() to CSQ.configureProductAnalytics().

Kotlin
Java

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

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

    Heap.startRecording(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.startRecording(this, "YOUR_ENVIRONMENT_ID");
    CSQ.configureProductAnalytics(
      this,
      "YOUR_ENVIRONMENT_ID"
    );
  }
}

For Android View Autocapture, replace ViewAutocaptureSDK.register() with enableViewAutocapture = true option:

Kotlin
Java

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

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()
      .enableViewAutocapture(true)
      .build();

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

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

Kotlin
Java

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

      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()
              .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);
  }
}

Remove HeapContentsquareIntegration.bind().

Case 1: Sending Heap screenviews to Contentsquare:

Kotlin
Java

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

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

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

Case 2: Sending Contentsquare screenviews to Heap:

Kotlin
Java

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

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

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

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

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

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

Kotlin
Java

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

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

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

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

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

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

(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.
AndroidManifest.xml
```
<application>
  ...
    <meta-data
      android:name="com.contentsquare.android.autostart"
      android:value="false"
    />
  ...
</application>
```

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

Kotlin
Java

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

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.

Transactions

Update your transaction imports:

Kotlin
Java

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

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

Update your currency imports:

Kotlin
Java

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

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

Replace the currency type from Int to Currency enum:

Kotlin
Java

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

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

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

Kotlin
Java

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

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.

Contentsquare.start(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.

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

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 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
`ErrorAnalysis.setUrlMaskingPatterns(patterns: List<String>)`	`CSQ.setUrlMaskingPatterns(patterns: List<String>)`
`import com.contentsquare.android.error.analysis.ErrorAnalysis`	`import com.contentsquare.api.model.NetworkMetric`
`ErrorAnalysis.getInstance().newNetworkMetric(url: String, httpMethod: HttpMethod)`	`NetworkMetric(url: String, httpMethod: HttpMethod)`
`networkMetric.stop()`	`CSQ.trackNetworkMetric(NetworkMetric)`

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<*>)`

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.

Dependency upgrades

CSQ SDK

Heap Core and Contentsquare SDKs

Library imports

SDK start

Get user consent

Transactions

Update APIs

Product Analytics

GDPR / Identification

Logging

Property tracking

Event tracking

Personal Data Handling and Masking

Jetpack compose

SDK initialization and manipulation

Experience Analytics

GDPR / Identification

Property tracking

View tracking

Interoperability

Event tracking

Error tracking

Personal Data Handling and Masking

Jetpack compose

SDK initialization and manipulation

Checklist

Number of sessions