Heap analytics for apps with Contentsquare SDKs

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

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

Send Contentsquare generated screen views and custom variables to Heap.
Take full advantage of the Heap API to track custom events and manage user identity.

Before you begin

In order to sync data from Contentsquare to Heap, you must be using one of the below versions of the Contentsquare SDK in your application. If you're using an older version, you will need to upgrade in order to continue.

Android - 4.29.1
iOS - 4.33.0
React Native - 4.6.0
Flutter - 3.11.1

Installing the Heap SDK

Follow the steps in the Heap quick start guide for your target platform. Quick start guides for all supported platforms and app configurations can be found in the left nav under GETTING STARTED -> Mobile installation.

Installing the Integration SDK

Once you have both the Contentsquare and Heap 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.
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.

Initializing the Integration SDK and setting options

The integration SDK contains a single API call that needs to be made in order to initialize data flow between Contentsquare and Heap 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.

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';
import { Heap } from '@heap/heap-react-native-bridge';

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

In addition to the bind() call, you'll need to add one or two options to your startRecording() call depending on your installation. In all cases, you'll need to enable the option to resume previous sessions. This allows the Heap SDK to adopt the Contentsquare SDK behavior of resuming an unexpired session between application launches instead of always creating a new one. If you have an autocapture SDK installed, you'll also want to set the option to turn off pageview autocapture. This will stop the Heap SDK from generating its own pageviews and instead rely entirely on the screen views from Contentsquare that are sent using Contentsquare.send().

Heap.startRecording(
  applicationContext,
  "YOUR_APP_ID",
  Options(
    restorePreviousSession = true,
    disablePageviewAutocapture = true
  )
)

Heap.shared.startRecording("YOUR_APP_ID", with: [
  .resumePreviousSession: true,
  .disablePageviewAutocapture: true,
])

import { Heap } from '@heap/heap-react-native-bridge';

Heap.startRecording('YOUR_APP_ID', { resumePreviousSession: true, disablePageviewAutocapture: true });

That's it! All relevant Contentsquare data will now be synced to the Heap environment for your application and you should start to see Heap users, sessions, pageviews, and events in your account immediately.

What next?

The Heap SDK enables product analytics features in your application, including the ability to track semantically meaningful events and track users across sessions and devices. We recommend reading some of our tracking guides such as: