Session Replay for apps with Heap analytics SDKs

📘
This guide assumes that you already have the Heap SDK installed in your application and you're installing the Contentsquare SDK for the first time.

After completing the setup process, you'll be able to:

Send Heap generated pageviews to Contentsquare.
Use CS features, including session replay, in your application.

Before you begin

📘
Syncing data with Contentsquare is only possible if you're using Heap's latest SDK offerings. If you're using Heap Classic, you will need to switch to our latest offering before following this guide.

In order to sync data from Heap to Contentsquare, you must be using version 0.6.0 or above of the Heap SDK. If you're using an older version, you will need to upgrade in order to continue.

Installing the Contentsquare SDK

Follow the steps in the Contentsquare "Getting Started" guide for your target platform:

Android (minimum version 4.29.1)
iOS (minimum version 4.33.0)
React Native (minimum version 4.6.0)
Flutter (minimum version 3.11.1)

Be sure to follow through on the entire "Getting Started" guide, including the section on validating your installation.

Installing the Integration SDK

Once you have both the Heap and Contentsquare SDKs installed and validated as working in your application, it's time to hook them up to each other. This is accomplished using a lightweight bridge SDK that facilitates communication between the SDKs to allow the synchronization of sessions and pageviews across both technologies.

Android

On Android, the integration artifact can be added via Gradle from Maven Central, the same as our other SDKs. The artifact version should match the version of heap-android-core included in your application.

dependencies {
  implementation 'io.heap.core:heap-android-core:0.6.1'
  implementation 'io.heap.contentsquare.csbridge:contentsquare-bridge:0.6.1'
}

dependencies {
  implementation("io.heap.core:heap-android-core:0.6.0")
  implementation("io.heap.contentsquare.csbridge:contentsquare-bridge:0.6.0")
}

iOS

Swift Package Manager

In Xcode, open the package manager however you are accustomed to. The most direct path is navigating to File → Add Packages… in the menu.
Paste https://github.com/heap/heap-ios-cs-integration-sdk.git into the Search or Enter Package URL text field at the top right corner of the dialog.
Select a Dependency Rule. We recommend Up to Next Major Version.
Click Add Package.
In the next dialog, check the checkbox next to HeapContentsquareIntegrationSDK and confirm that it will be added to your app target.
Click Add Package.
Before continuing, build your app target to help Swift resolve the modules.

CocoaPods

Add pod 'HeapContentsquareIntegrationSDK', '~> 0.6' to your app target in your Podfile.
1. pod 'HeapContentsquareIntegrationSDK_static', '~> 0.6' if installing for React Native.
Run pod install within your project directory.
Before continuing, build your app target to help Swift resolve the modules.

React Native

Add the integration artifact.

yarn add @heap/heap-react-native-cs-integration

npm install @heap/heap-react-native-cs-integration

If using a bare React Native workflow, call pod install in your ios/ directory.

Flutter

Installation for Flutter apps currently happens at the native layer. To install, follow the instructions for each platform above, adding the dependencies to your Android or iOS application module. Be sure to clean and rebuild to ensure all changes are picked up by the individual platforms.

Initializing the Integration SDK

The integration SDK contains a single API call that needs to be made in order to initialize data flow between Heap and Contentsquare and declare the direction in which data should flow. These options are currently mutually exclusive, so be sure to only enable the one defined below.

Wherever you are calling Heap.startRecording() or Heap.shared.startRecording(), add a call to the integration's bind() method. If you're using Android's automatic initialization, we recommend placing this call in your app's entry point, such as the onCreate() method of your Application class.

Using Heap with an autocapture SDK

Heap's autocapture SDKs can capture pageviews and send them to Contentsquare as screen views (the corresponding construct in Contentsquare) using the integration SDK.

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

HeapContentsquareIntegration.bind(
    sendHeapPageviewsToContentsquare: true,
    sendContentsquareScreenviewsToHeap: false
)
Heap.shared.startRecording(...)

import { bind } from '@heap/heap-react-native-cs-integration';

bind({ sendHeapPageviewsToContentsquare: true });
Heap.startRecording(...)

Using Heap with manual tracking only

If you're not using one of Heap's autocapture SDKs, you'll need to implement manual screen view tracking using the Contentsquare SDK in order to enable session replay and other digital experience analytics features. You can find the docs here for Android, iOS, and React Native. Once that's setup, you can pass those screen views to Heap using the integration.

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

HeapContentsquareIntegration.bind(
    sendHeapPageviewsToContentsquare: false,
    sendContentsquareScreenviewsToHeap: true
)
Heap.shared.startRecording(...)

import { bind } from '@heap/heap-react-native-cs-integration';

bind({ sendContentsquareScreenviewsToHeap: true });
Heap.startRecording(...)

That's it! All relevant Heap data will now be synced to the Contentsquare project for your application and you should start to see replays for Heap sessions in your account when they're available from Contentsquare.

What next?

The Contentsquare SDK contains several "privacy-first" features that you'll want to consider when using their SDK.

User opt-in/out

The Contentsquare SDK will not collect any data until a user has opted into tracking. If your app contains a user opt-in flow, you can use Contentsquare.optIn() and Contentsquare.optOut() to handle user consent. If your application does not contain a user opt-in flow, you'll still need to call Contentsquare.optIn() before any replays will be generated.

You can find the Contentsquare privacy docs here: Android, iOS, and React Native

Session replay masking

By default the entire user interface is masked when using session replay. The Contentsquare SDK offers two approaches to manage masking of the UI:

Un-mask the UI on a per element basis using the data masking APIs.
Set masking to be turned off by default, then re-mask parts of the UI that might contain PII using the data masking APIs.

You can find the Contentsquare data masking API docs, as well as sample masked and un-masked screenshots, here: Android, iOS, and React Native.