TechnologyJul 23, 2026 | FlexyConsent

Heap Auto-Capture Product Analytics Cookie Consent Integration Guide: 2026 Playbook for Publishers

Heap is unusual in the product-analytics ecosystem because of what it does by default. Where Mixpanel, Amplitude, and PostHog ask the publisher to instrument the events that matter, Heap captures everything automatically and lets the analyst define events retroactively from the captured stream. That auto-capture model is the product's defining feature and the reason teams pick it; it is also the reason a default Heap deployment carries one of the broadest behavioural data surfaces of any tool a publisher is likely to install. Every click, tap, scroll, form interaction, page transition, and rage-click is captured against a persistent identifier within milliseconds of page load — which means every one of those operations engages a consent obligation. The good news is that Heap, since its acquisition by Contentsquare, ships with one of the more granular consent APIs in the product-analytics space; the work is in actually wiring it correctly across the auto-capture surface, the identity layer, and the session-replay module that the Contentsquare integration adds.

Why Heap requires consent — and why the answer is broader than typical analytics

A default Heap initialisation does several things in the first paint of the page. It sets a first-party cookie under _hp2_id.{envId} containing the persistent user identifier, a session cookie under _hp2_ses_id.{envId} with the session identifier, a sample-rate cookie under _hp2_props.{envId}, and a _hp2_loaded marker indicating that the SDK has initialised. It generates the distinct identifier if one does not already exist, captures the initial pageview with referrer, UTM parameters, and click identifiers, and immediately begins recording every subsequent interaction against that identifier — clicks, taps, form changes, route changes, custom events, and, when the Contentsquare integration is enabled, the full rendered DOM diff for session replay.

Each of those activities engages a separate consent gate. Persisting the user identifier is a storage-and-access operation under Article 5(3) of the ePrivacy Directive and requires prior, freely given, specific, informed, and unambiguous consent across the EEA, the UK, and any jurisdiction that has imported the same standard. Capturing the auto-capture event stream is processing of personal data under the GDPR because the combination of identifier, IP address, and behavioural trace is sufficient to single out an individual. Session replay sits in a separate, stricter category under the EDPB's session-replay guidance — replay captures rendered DOM and any unmasked input field and requires explicit, granular consent that is distinct from generic analytics consent. The CCPA and CPRA treat the same processing as a sale or share unless the publisher has the relevant service-provider contract with Heap — which Heap offers, but the contract only takes effect when the integration is configured for service-provider mode.

What Heap writes before consent — and what must be suppressed

The standard quickstart that ships with the Heap dashboard installs the tracking snippet directly into the page <head>. That works as documented and is the source of the most common compliance failure on Heap deployments: the snippet runs before the cookie banner has rendered, the _hp2_ cookies are written within milliseconds, and the auto-capture stream begins flowing to heapanalytics.com regardless of what the user later decides. Every European regulator that has ruled on this pattern has ruled the same way: cookies set before consent are unlawful, and the publisher carries the liability.

A compliant integration must therefore prevent the Heap snippet from loading until the relevant consent category has been granted. The two patterns that work in production are conditional script injection — the snippet is added to the DOM only after the CMP signals consent — and pre-loading the snippet with heap.load(appId, { disableTextCapture: true, secureCookie: true, autocapture: false }) as a deferred bootstrap and then calling heap.startAutoCapture() once consent is recorded. The conditional-injection pattern is cleaner and the one the Heap documentation now recommends. The deferred-bootstrap pattern is the right choice when the publisher needs a stable global reference for identity stitching but cannot allow auto-capture to fire before consent.

The cookies and storage Heap writes

The Heap snippet writes the following identifiers on initialisation, all of which are non-essential and require consent: _hp2_id.{envId} with a 14-month expiry containing the user identifier, _hp2_ses_id.{envId} with a 30-minute session expiry, _hp2_props.{envId} for sample-rate and property propagation, and _hp2_loaded as the load marker. The Contentsquare-integrated session-replay module adds an in-memory recording buffer that flushes to the Heap endpoint every few seconds and may persist a small replay-session identifier separately. Withdrawing consent must therefore both expire the _hp2_ cookies and signal a deletion request through Heap's GDPR API for the user's prior recordings and event stream.

Mapping Heap to consent frameworks

Heap does not natively implement IAB TCF or the IAB Global Privacy Platform — it is a first-party product-analytics platform, not an ad-tech vendor — but it does integrate with Google Consent Mode v2 through publisher-side bridging, exposes a native opt-in and opt-out API, and supports a sensitive-property redaction layer that operates regardless of consent state. The pattern that survives a regulator's review treats each Heap module as a separate gate bound to a specific CMP signal.

The integration pattern that works

The reference deployment has four parts: a CMP that exposes a real-time consent change event, a deferred bootstrap that loads Heap with auto-capture disabled, a consent listener that flips auto-capture on and starts the session-replay buffer when the relevant gates open, and a withdrawal path that calls heap.resetIdentity(), stops auto-capture, expires the _hp2_ cookies, and dispatches a deletion request via Heap's GDPR endpoint.

Web implementation

On the web the cleanest pattern is to load the Heap snippet conditionally — the <script> tag is injected only after the analytics category has been granted. Subscribe to the CMP's consent change event. When the analytics category transitions to true, inject the Heap snippet with secureCookie: true, disableTextCapture: false for full auto-capture, and any environment-specific configuration. When session-replay consent transitions to true and the Contentsquare integration is enabled, the replay buffer activates automatically. When either gate withdraws, call heap.resetIdentity() followed by removal of the Heap script element, expire the _hp2_ cookies via document.cookie, and invoke the GDPR-deletion API for the user's identifier.

Sensitive-property redaction

Heap ships with a redaction layer that operates regardless of consent state and that publishers should use even when consent has been granted. The data-heap-redact-text attribute on a form field suppresses the captured text content; the data-heap-redact-attributes attribute suppresses the element attributes. Under the GDPR's special-category rules and the CCPA's sensitive-personal-information definition, any field that could capture health information, financial detail, government identifiers, biometric data, precise geolocation, or contents of private communications must use the redaction attributes regardless of the user's consent state. Setting the attributes at the form level is the safest pattern — it suppresses the entire form even when a developer adds a new field they forget to mark individually.

Region selection: EU vs US data residency

Heap operates separate EU and US ingestion endpoints. For EEA and UK traffic the EU endpoint is the right default; it keeps ingestion, processing, and storage inside the EEA and reduces the Schrems II exposure that any US-region analytics deployment carries. The endpoint is set via the snippet configuration and cannot be changed retroactively — existing data stays where it was first ingested. For publishers planning a Heap rollout it is therefore worth confirming the region before scaling, and worth documenting the choice in the privacy notice so the lawful-basis chain is clean from collection through to storage.

Validating the integration and the audit trail

The validation step is what regulators check and what publishers most often skip. A correctly integrated Heap deployment must pass four tests in sequence. First, a clean browser session with the banner shown but no choice made must produce zero requests to heapanalytics.com beyond the SDK file fetch and zero _hp2_ cookies in document.cookie. Second, declining analytics must keep that state — no auto-capture, no identifier, no recording. Third, accepting analytics must produce the expected _hp2_id cookie with correct SameSite attributes and event traffic flowing to the configured region endpoint. Fourth, withdrawing consent must immediately stop further auto-capture and replay, expire the _hp2_ cookies, and trigger a deletion request via Heap's GDPR API.

The audit-trail expectation under the EDPB's 2023 cookie banner guidelines and the renewed 2026 task force priorities is that the publisher can prove, for any given event in the Heap project, that the user who generated it had given valid consent at the moment of capture. The standard pattern is to set the consent version and timestamp as user properties on the distinct ID via heap.addUserProperties({ consent_version: 'v3', consent_ts: ts }) so that any individual event is traceable back to a specific consent log entry. A correctly gated deployment, paired with redaction attributes that suppress sensitive fields by default and a deletion path that activates on withdrawal, is what turns Heap's auto-capture model from a regulatory concentration risk into one of the most powerful and defensible parts of a publisher's product-analytics stack.

← Blog Read All →