From Heap Core SDK + Contentsquare SDK to 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.

Replace Heap and Contentsquare SDK dependencies by the CSQ SDK:

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

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

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

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

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

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

   • Standalone
   • Unified CSQ

     Onboard to Unified CSQ, our latest, all-in-one platform offering.

     Reach out to your Customer Success Manager for more information.

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

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

   • Standalone
   • Unified CSQ

     Onboard to Unified CSQ, our latest, all-in-one platform offering.

     Reach out to your Customer Success Manager for more information.

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

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

   • Standalone
   • Unified CSQ

     Onboard to Unified CSQ, our latest, all-in-one platform offering.

     Reach out to your Customer Success Manager for more information.

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

4. Remove HeapContentsquareIntegration.bind().
   Sending Heap screenviews to Contentsquare

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

   Sending Contentsquare screenviews to Heap

   • Standalone
   • Unified CSQ

     Onboard to Unified CSQ, our latest, all-in-one platform offering.

     Reach out to your Customer Success Manager for more information.

   HeapContentsquareIntegration.bind(
     applicationContext,
     sendHeapPageviewsToContentsquare = false,
     sendContentsquareScreenviewsToHeap = true
   )
   
   CSQ.start(
     context = this,
     StartConfig.withEnvironmentId(
       id = "YOUR_ENVIRONMENT_ID",
       options = AnalyticsOptions(
         disablePageviewAutocapture = true
       )
     )
   )

5. (Optional) For Autocapture notifications, replace NotificationAutocaptureSDK.register() with these options:
   • Standalone
   • Unified CSQ

     Onboard to Unified CSQ, our latest, all-in-one platform offering.

     Reach out to your Customer Success Manager for more information.

   NotificationAutocaptureSDK.register(
     captureTitleText = true,
     captureBodyText = true
   )
   
   CSQ.start(
     context = this,
     StartConfig.withEnvironmentId(
       id = "YOUR_ENVIRONMENT_ID",
       options = AnalyticsOptions(
         // ...options
         enablePushNotificationAutocapture = true,
         enablePushNotificationTitleAutocapture = true,
         enablePushNotificationBodyAutocapture = true
       )
     )
   )

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

   <application>
     ...
       <meta-data
         android:name="com.contentsquare.android.autostart"
         android:value="false"
       />
     ...
   </application>

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

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

class MyApplication : Application() {
  override fun onCreate() {
      super.onCreate()
      CSQ.start(this)
  }
}

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

1. Update your transaction imports:

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

2. Update your currency imports:

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

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

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

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

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

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.

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

Logging

Property tracking

Event tracking

Personal Data Handling and Masking

Jetpack compose

@Composable
HeapRedact(redact: Boolean)

@Composable
CsqMask(enable: Boolean)

@Composable
HeapIgnore(ignore: Boolean)

@Composable
CsqIgnoreInteraction(ignore: Boolean)

SDK initialization and manipulation

GDPR / Identification

Property tracking

View tracking

Interoperability

Event tracking

Error tracking

Personal Data Handling and Masking

Jetpack compose

SDK initialization and manipulation

Session timeout definition changed:

• Before: 30 minutes after app goes to background
• Now: 30 minutes after last event

This may affect session counts and aligns with web and market standards.

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.

Session timeout definition changed:

• Before: 30 minutes after app goes to background
• Now: 30 minutes after last event

This may affect session counts and aligns with web and market standards.