🍪 Cookies & Consent (CMP) — Integration Guide

Consent-aware chat, without CMP lock-in

HEA runs in an iframe, often cross-origin. To respect your users’ choices, the host page publishes a vendor-agnostic consent signal to HEA. This guide explains how it works and how to integrate with common CMPs.

What you typically need to do:
Install your CMP as usual (Cookiebot / OneTrust / Usercentrics / …), then add a tiny HEA “connector” script on the host page before the HEA widget snippet.
✅ Practical overview

What consent affects in HEA

Always allowed Essential rendering of the widget, security protections, and basic functionality. The chat can run without optional storage.
Optional storage Persisting chat history, UI preferences and convenience features on the user’s device (local/session storage) may require consent depending on jurisdiction & your policy.
Analytics / marketing If your HEA deployment uses analytics tags or marketing pixels, those should follow your CMP. (HEA does not force third-party trackers.)
What exactly is stored locally?
HEA can store (depending on configuration and consent):
  • Chat history (to let users resume a conversation)
  • UI preferences (open/closed state, theme, small layout preferences)
  • Technical cache (to reduce load time)
In strict mode (“deny all”), HEA avoids optional persistence.
How does HEA enforce consent?
The widget listens for a stable consent signal (see architecture below). A single controller decides whether optional persistence is enabled, and applies it consistently across modules.
🧩 Architecture

How consent reaches the iframe

This is the contract HEA relies on. The host page owns CMP; HEA consumes a stable signal. 

Cookiebot / CMP vendor
  ↓
/public/CMP_connectors/hea_consent_*.js (host page)
  ↓  window.dispatchEvent('hea:consent', {detail})
hea_embed.js / hea_askbar_embed.js  (host)
  ↓  postMessage('HEA_CONSENT_UPDATE', detail)
iframe (widget / simple / askbar)
  ↓
hea_consent.js  ← SINGLE SOURCE OF TRUTH
  ↓
hea_cookies_data_controller.js
Consent payload contract (detail)
HEA expects a small payload (vendor-agnostic): 
{
  necessary: true,
  preferences: boolean,
  analytics: boolean,
  marketing: boolean,
  source: "cookiebot" | "generic" | ...,
  ts: number
}
✅ Recommended

Auto mode (CMP connector)

Use when you already have a CMP. Add the connector before the HEA widget snippet.
Generate snippets in the app
Other CMPs (template)
If your CMP isn’t Cookiebot yet, start from the generic connector template:
🛡️ Strict mode

Deny all (no optional storage)

Use for ultra-strict deployments or testing. HEA will avoid optional persistence on the device.
(Place before the HEA widget snippet)
Allow all (internal/testing only)
Use only for internal environments where you already have a valid consent basis.
🔧 Troubleshooting

Common issues

1) CSP errors
If the widget doesn’t load, allow https://hea-world.com in: script-src and frame-src.
2) Consent not applied
Ensure the connector script is included before the HEA widget snippet on the host page. Consent is then forwarded to the iframe via postMessage.
3) Multiple CMPs or multiple widgets
Avoid loading more than one CMP or more than one HEA widget on the same page unless intentional. Check the console for conflicts.
Why does Cookiebot show such a long list?
Cookiebot typically builds the list using a combination of:
  • Scanning pages and detecting scripts/tags that set cookies
  • Observing cookies/local storage entries created by integrated tools
  • Using known vendor libraries and classification rules
It can look overwhelming, but it’s often a reflection of all third-party tools on a site (analytics, video, maps, tag managers, A/B testing, etc.), not only HEA.
Cookie declaration (details)

The full cookie declaration can be long. We keep it here for transparency.

📩 Need help?

We can help you integrate your CMP

If you use a CMP that isn’t supported yet, start with the generic template and tell us which vendor you use. We’ll provide a connector or a mapping snippet.