Contentsquare Heap (Pixel)
Introduction
The Heap Pixel destination loads the Heap browser SDK directly in the visitor's browser (device mode) and sends events client-side. Unlike the server-side Heap destination, device-mode events originate from the browser, enabling Heap's automatic interaction capture, session replay, and heatmap features.
Use this destination alongside the server-side Heap destination for maximum coverage.
Getting Started
This is a device-mode destination. The Heap JavaScript SDK is loaded automatically — no manual script installation is required. You will need:
- App ID (Environment ID) — found in Account > Manage > Projects in the Heap dashboard. Each project (environment) has its own App ID.
Connecting to the Heap Pixel CDP Destination
Before connecting destinations in the Chord CDP, please verify with all Destination owners that all non-Chord CDP configured destinations are disabled. Running external destinations alongside configured Chord CDP destinations can result in duplicate events downstream.
- Log into the Chord data platform.
- Navigate to the CDP.
- Click the "Add" button next to Destinations.
- Select Heap (Device Mode) from the destination catalog.
- Enter the destination name and App ID.
- Click "Create" to connect.
Events
Event Mapping
Chord Event Type | Heap SDK Method | Notes |
|---|---|---|
track | heap.track(eventName, properties) | Event name and properties forwarded as-is |
page | heap.track("Page View", properties) | Page metadata included in properties |
identify | heap.identify(identity) + heap.addUserProperties(traits) | Identity resolved from userId > email trait |
Track Events
Track events call heap.track() with the event name and properties.
Heap Argument | Chord Source | Notes |
|---|---|---|
eventName | event (event name) | |
properties | properties | All event properties forwarded |
Page Events
Page events call heap.track("Page View", ...) with page metadata merged into properties.
Heap Argument | Chord Source | Notes |
|---|---|---|
eventName | (hardcoded) "Page View" | |
properties | properties merged with page context | Includes url, path, referrer, title from context.page |
Identify Events
Identify events call both heap.identify() to set the user identity and heap.addUserProperties() to attach traits.
Heap Method | Chord Source (Priority Order) | Notes |
|---|---|---|
heap.identify(identity) | userId > context.traits.email > traits.email | If no identity can be resolved, the call is skipped |
heap.addUserProperties(traits) | traits merged with context.traits | All user traits forwarded |
Initialization
On first event, the plugin:
- Injects the Heap SDK stub queue (window.heap) into the page
- Loads the Heap SDK script from https://cdn.heapanalytics.com/js/heap-0.js
- Calls heap.load(appId) to initialize Heap with your App ID
The plugin tracks SDK loading state (fresh → loading → loaded / failed) using a shared state flag (window.__chordCDPHeapState) to prevent duplicate script loads across concurrent events. Events that arrive while the SDK is loading are queued and processed after initialization completes. If the SDK fails to load, subsequent events are silently dropped.
CSP Requirements
If your site uses a Content Security Policy, allow the following domains:
Directive | Domain |
|---|---|
script-src | https://cdn.heapanalytics.com |
connect-src | https://cdn.heapanalytics.com https://heapanalytics.com |
img-src | https://heapanalytics.com |
Combining with Server-Side Heap
Running both the Heap Pixel (device mode) and the server-side Heap destination provides redundancy:
- Device mode captures browser-native interactions and enables session replay / heatmaps
- Server-side captures events that may be blocked by ad blockers or occur outside the browser
Heap deduplicates events that share the same identity and timestamp, so duplicate counting is generally not a concern when running both in parallel.