Heap analytics for apps with Contentsquare

📘
This guide assumes that you already have the Contentsquare Unified SDK installed in your application with screen view tracking setup and you're using Heap 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 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 Contentsquare SDK installed for your platform.

Android - 4.29.1 (unified version 0.1.0)
iOS - 4.33.0 (unified version 0.1.0)
React Native - 4.6.0
Flutter - 3.11.1

Setting Up Heap

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 (Cross-Platform Only)

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.

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 and setting options

The integration 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 Heap to adopt the Contentsquare behavior of resuming an unexpired session between application launches instead of always creating a new one. If you're using autocapture, you'll also want to set the option to turn off pageview autocapture. This will stop Heap 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?

Heap 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: