Session Replay for apps with Heap analytics

📘
This guide assumes that you already have the Contentsquare Unified SDK installed in your application and you're using Contentsquare 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 our latest SDK offering, the Contentsquare Unified SDK. 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.1.0 or above of the Contentsquare Unified SDK for native platforms. If you're using a cross-platform framework, you must have the latest version of the Heap SDK installed for your platform. Quick start guides can be found in the Mobile Installation section of these docs.

Setting Up Contentsquare

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

Android (minimum version 4.29.1, unified version 0.1.0)
iOS (minimum version 4.33.0, unified version 0.1.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 (Cross-Platform Only)

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.

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 below, 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.

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.7.+'
  implementation 'io.heap.contentsquare.csbridge:contentsquare-bridge:0.7.+'
}

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

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.
Run pod install within your project directory.
Before continuing, build your app target to help Swift resolve the modules.

Initializing the Integration

The integration 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 Autocapture

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

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 Heap's autocapture, you'll need to implement manual screen view tracking using Contentsquare 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?

Contentsquare contains several "privacy-first" features that you'll want to consider when using the Unified SDK or the Contentsquare SDK for your platform.

User opt-in/out

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