# Introduction (/docs)



import { Rocket, LayoutDashboard, Code, ShieldCheck } from "lucide-react"
import { REGULATION_COUNT_DISPLAY, JURISDICTION_COUNT_DISPLAY, US_STATES_COUNT, SDK_GZIP_DISPLAY } from "@/lib/headline-numbers"

Privacy regulations like GDPR, CCPA, and dozens of others now require websites to collect informed consent before running tracking scripts. Getting this wrong means legal exposure, broken user trust, and fines that scale with your traffic.

But most consent tools are expensive, bloated, and built around dark patterns: pre-checked boxes, hidden reject buttons, confusing language. They solve the wrong problem: checking a compliance box instead of genuinely respecting your visitors.

ConsentStack is a modern consent management platform that handles the full lifecycle: displaying a consent banner, blocking scripts until consent is given, logging every decision for audit trails, and automatically adapting to the right regulations based on where your visitors are.

Choose your path [#choose-your-path]

<Cards>
  <Card icon={<Rocket />} title="Getting Started" description="Add ConsentStack to your site in under five minutes. A quick setup guide for everyone." href="/docs/getting-started" />

  <Card icon={<LayoutDashboard />} title="Dashboard" description="Configure your banner, manage sites, review consent activity, and control script categories, no code required." href="/docs/dashboard/overview" />

  <Card icon={<Code />} title="Developers" description="Integrate the SDK, customize behavior, and connect platforms like Google Consent Mode." href="/docs/developers" />

  <Card icon={<ShieldCheck />} title="Compliance" description={`GDPR across 32 countries, ${US_STATES_COUNT} US state laws, Brazil, Canada, Japan, India, Singapore, Australia, and federal regulations like HIPAA and COPPA.`} href="/docs/compliance" />
</Cards>

Key capabilities [#key-capabilities]

| Capability                                                                                   | Why it matters                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Automatic geo-detection**                                                                  | Detects visitor location at the network edge and applies the correct consent model, no manual rules needed.                                                                                                                                         |
| **Script blocking**                                                                          | Third-party scripts are blocked before they execute, so nothing runs without consent.                                                                                                                                                               |
| **{REGULATION_COUNT_DISPLAY} regulations across {JURISDICTION_COUNT_DISPLAY} jurisdictions** | GDPR, {US_STATES_COUNT} US state laws, LGPD, APPI, HIPAA, COPPA, and more, all built in and kept current.                                                                                                                                           |
| **Privacy-first audit logs**                                                                 | Every consent decision is logged with cryptographically hashed visitor IDs (stored as a SHA-256 hash by the consent edge function before persistence; see supabase/functions/consent/index.ts:230-233), no personal data stored, fully audit-ready. |
| **{SDK_GZIP_DISPLAY} SDK gzipped (stub + core)**                                             | Executes synchronously at parse time so trackers can be intercepted before they fire. Your visitors' experience stays fast.                                                                                                                         |


# API Reference (/docs/api-reference)



ConsentStack exposes three edge-function endpoints that power the consent banner on your site. The SDK calls these automatically. You only need this reference if you are building a custom integration or debugging network requests.

**Base URL:** `https://origins.consentstack.io`

The SDK fetches its config from `https://config.consentstack.io` first, with `https://origins.consentstack.io/functions/v1/config` as a fallback. Both endpoints serve the same response shape (defined below). See `packages/sdk/src/constants.ts:14-17` for the resolution order.

All endpoints return JSON and include CORS headers. Every request that references a site must include a valid `Origin` header matching a domain registered in your dashboard.

GET /functions/v1/config [#get-functionsv1config]

Returns the published consent configuration for a site, resolved for the visitor's region and language.

```
GET https://origins.consentstack.io/functions/v1/config?site_key=YOUR_SITE_KEY
```

Query parameters [#query-parameters]

| Parameter  | Type   | Required | Description                                                                                |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `site_key` | string | Yes      | Your public site key (found in the dashboard under Site Settings).                         |
| `region`   | string | No       | Override automatic geo-detection with a specific region ID (e.g. `gdpr`, `us_state_laws`). |
| `lang`     | string | No       | Override automatic language detection with a language code (e.g. `de`, `fr`).              |

Request headers [#request-headers]

| Header   | Required | Description                                                          |
| -------- | -------- | -------------------------------------------------------------------- |
| `Origin` | Yes      | The requesting domain. Must match a domain registered for this site. |

Response (200) [#response-200]

```json
{
  "config": { ... },
  "sdkCategories": [
    {
      "id": "essential",
      "name": "Essential",
      "description": "Required for the website to function properly.",
      "consentModel": "exempt"
    },
    {
      "id": "analytics",
      "name": "Analytics",
      "description": "Help us understand how visitors interact with our website.",
      "consentModel": "opt_in"
    }
  ],
  "resolvedRegion": "gdpr",
  "resolvedLanguage": "en",
  "resolvedContent": {
    "title": "We value your privacy",
    "description": "...",
    "acceptAllText": "Accept All",
    "rejectAllText": "Reject All",
    "customizeText": "Customize",
    "savePreferencesText": "Save Preferences",
    "closeText": "Close"
  },
  "resolvedUi": {
    "required": "Required"
  },
  "showBranding": true,
  "version": 3,
  "site_name": "My Website",
  "scriptRules": [
    { "pattern": "google-analytics.com", "category": "analytics" }
  ]
}
```

Response fields [#response-fields]

| Field              | Type           | Description                                                                                                                                                                                               |
| ------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config`           | object         | The full published config object (appearance, content, categories, regions, consent rules). Falls back to built-in defaults if no config is published.                                                    |
| `sdkCategories`    | array          | Consent categories resolved for the visitor's region. Each entry includes `id`, `name`, `description`, and the applicable `consentModel` (`opt_in`, `opt_out`, `notice`, `notice_required`, or `exempt`). |
| `resolvedRegion`   | string \| null | The region ID matched from the visitor's location (e.g. `gdpr`, `us_state_laws`, `default`). `null` if no region matched.                                                                                 |
| `resolvedLanguage` | string         | The language code used for content (e.g. `en`, `de`). Determined by the `lang` parameter, the visitor's browser language, or the region's default language.                                               |
| `resolvedContent`  | object         | Banner and preferences UI strings in the resolved language, with consent-model-specific overrides applied.                                                                                                |
| `resolvedUi`       | object         | Translated UI labels (e.g. the "Required" badge text).                                                                                                                                                    |
| `showBranding`     | boolean        | Whether to display ConsentStack branding. `true` for free-tier sites.                                                                                                                                     |
| `version`          | number         | The published config version number. `0` if no config has been published.                                                                                                                                 |
| `site_name`        | string         | The site name from your dashboard.                                                                                                                                                                        |
| `scriptRules`      | array          | Active script blocking rules. Each entry has a `pattern` (domain pattern to match) and a `category` (the consent category that governs it).                                                               |

Error responses [#error-responses]

| Status | Body                                               | Condition                                                  |
| ------ | -------------------------------------------------- | ---------------------------------------------------------- |
| 400    | `{"error": "site_key is required"}`                | Missing or invalid `site_key` parameter.                   |
| 403    | `{"error": "Site is paused"}`                      | The site has been paused in the dashboard.                 |
| 403    | `{"error": "Missing Origin header"}`               | No `Origin` header in the request.                         |
| 403    | `{"error": "Origin not registered for this site"}` | The requesting domain is not registered for this site key. |
| 404    | `{"error": "Site not found"}`                      | No site matches the provided `site_key`.                   |
| 500    | `{"error": "Internal server error"}`               | Unexpected server error.                                   |

Caching [#caching]

Responses include `Cache-Control: private, no-store`. Config changes take effect immediately. There is no CDN caching layer between publish and delivery.

Usage cap [#usage-cap]

Free-tier sites that exceed their monthly active user cap receive a `200` response with `{"disabled": true, "reason": "cap_exceeded"}` instead of the config payload. The SDK gracefully hides the banner when it receives this response.

***

POST /functions/v1/consent [#post-functionsv1consent]

Records a visitor's consent decision. The SDK calls this endpoint when a visitor interacts with the banner (accept, reject, customize) and on page load for returning visitors.

```
POST https://origins.consentstack.io/functions/v1/consent
Content-Type: application/json
```

Request body [#request-body]

| Field                 | Type    | Required | Description                                                                                                                                                           |
| --------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `site_key`            | string  | Yes      | Your public site key.                                                                                                                                                 |
| `anon_id`             | string  | Yes      | A client-generated anonymous visitor ID (max 100 chars). Hashed server-side before storage.                                                                           |
| `categories`          | object  | Yes      | A map of category IDs to booleans representing the visitor's consent choices. Example: `{"essential": true, "analytics": false, "marketing": false}`. Max 50 entries. |
| `event_type`          | string  | Yes      | One of `initial` (first interaction), `update` (changed preferences), or `impression` (banner was shown).                                                             |
| `event_action`        | string  | No       | The action taken: `opt_in`, `opt_out`, `partial`, or `acknowledge`.                                                                                                   |
| `config_version`      | number  | No       | The config version the visitor saw (for audit trail).                                                                                                                 |
| `region`              | string  | No       | The resolved region ID at the time of consent.                                                                                                                        |
| `consent_model`       | string  | No       | The active consent model: `opt_in`, `opt_out`, `notice`, or `notice_required`.                                                                                        |
| `regulation`          | string  | No       | The regulation that applied (e.g. `gdpr`, `us_state_laws`).                                                                                                           |
| `time_to_action_ms`   | number  | No       | Milliseconds between banner display and visitor action.                                                                                                               |
| `interaction`         | string  | No       | How the visitor interacted (e.g. `accept_all`, `reject_all`, `save_preferences`). Max 50 chars.                                                                       |
| `preferences_opened`  | boolean | No       | Whether the visitor opened the preferences panel before deciding.                                                                                                     |
| `banner_load_time_ms` | number  | No       | Milliseconds the banner took to render.                                                                                                                               |
| `banner_position`     | string  | No       | Banner layout position (e.g. `bottom-full`, `center-modal`).                                                                                                          |
| `page_url`            | string  | No       | The page URL where consent was given. Max 2000 chars.                                                                                                                 |
| `sdk_version`         | string  | No       | The SDK version that sent the request.                                                                                                                                |
| `language`            | string  | No       | The visitor's browser language.                                                                                                                                       |
| `resolved_language`   | string  | No       | The language the banner was displayed in.                                                                                                                             |

Request headers [#request-headers-1]

| Header   | Required | Description                                  |
| -------- | -------- | -------------------------------------------- |
| `Origin` | Yes      | Must match a registered domain for the site. |

Example request [#example-request]

```json
{
  "site_key": "<YOUR_SITE_KEY>",
  "anon_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "categories": {
    "essential": true,
    "analytics": true,
    "marketing": false
  },
  "event_type": "initial",
  "event_action": "partial",
  "config_version": 3,
  "region": "gdpr",
  "consent_model": "opt_in",
  "time_to_action_ms": 4200,
  "interaction": "save_preferences",
  "preferences_opened": true,
  "page_url": "https://example.com/pricing",
  "sdk_version": "0.3.6"
}
```

Server-side enrichment [#server-side-enrichment]

The server adds several fields before storing the consent log:

* **Visitor ID hashing.** The `anon_id` is hashed with SHA-256 before storage. The raw ID is never persisted.
* **User-Agent parsing.** Browser name, OS, and device type (desktop, mobile, tablet) are extracted from the `User-Agent` header.
* **Country detection.** The visitor's country code is read from infrastructure headers at the network edge.
* **Config linkage.** The consent log is linked to the published config ID for a complete audit trail.

Response codes [#response-codes]

| Status | Body                                               | Condition                                                              |
| ------ | -------------------------------------------------- | ---------------------------------------------------------------------- |
| 201    | `{"success": true}`                                | Consent log recorded successfully.                                     |
| 400    | `{"error": "..."}`                                 | Validation error (missing fields, unknown category IDs, invalid JSON). |
| 403    | `{"error": "Site is paused"}`                      | The site is paused.                                                    |
| 403    | `{"error": "Origin not registered for this site"}` | Domain not registered.                                                 |
| 404    | `{"error": "Site not found"}`                      | No site matches the provided `site_key`.                               |
| 405    | `{"error": "Method not allowed"}`                  | Request used a method other than POST.                                 |
| 500    | `{"error": "Internal server error"}`               | Unexpected server error.                                               |

<Callout type="info">
  Category IDs in the `categories` object are validated against your published config. Sending an unknown category ID returns a `400` error with the invalid IDs listed in the message. Impression events skip this validation.
</Callout>

***

POST /functions/v1/scripts [#post-functionsv1scripts]

Reports third-party scripts detected on the page. The SDK scans the DOM for script elements, extracts their domains, and sends them to this endpoint. The server upserts each script and auto-categorizes known tracker domains.

```
POST https://origins.consentstack.io/functions/v1/scripts
Content-Type: application/json
```

Query parameters [#query-parameters-1]

| Parameter | Type          | Required | Description                                                               |
| --------- | ------------- | -------- | ------------------------------------------------------------------------- |
| `sync_id` | string (UUID) | No       | Links this report to a tracker sync session initiated from the dashboard. |

Request body [#request-body-1]

| Field       | Type   | Required | Description                                                                           |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `site_key`  | string | Yes      | Your public site key.                                                                 |
| `page_url`  | string | Yes      | The page URL where scripts were detected. Max 500 chars.                              |
| `scripts`   | array  | Yes      | Array of detected scripts (max 100). Each entry contains the fields below.            |
| `timestamp` | number | Yes      | Unix timestamp of the detection.                                                      |
| `sync_id`   | string | No       | UUID linking to a dashboard-initiated sync (deprecated in body; use query parameter). |
| `error`     | string | No       | Error message if the scan encountered issues. Max 500 chars.                          |

Script entry fields [#script-entry-fields]

| Field      | Type           | Description                                                                            |
| ---------- | -------------- | -------------------------------------------------------------------------------------- |
| `src`      | string         | The full script `src` URL. Max 2000 chars.                                             |
| `domain`   | string         | The extracted domain of the script (e.g. `google-analytics.com`). Max 500 chars.       |
| `category` | string \| null | The SDK's best-guess category from its local known-tracker list, or `null` if unknown. |
| `blocked`  | boolean        | Whether the SDK blocked this script from executing.                                    |

Example request [#example-request-1]

```json
{
  "site_key": "<YOUR_SITE_KEY>",
  "page_url": "https://example.com/",
  "scripts": [
    {
      "src": "https://www.google-analytics.com/analytics.js",
      "domain": "google-analytics.com",
      "category": "analytics",
      "blocked": true
    },
    {
      "src": "https://cdn.example.com/widget.js",
      "domain": "cdn.example.com",
      "category": null,
      "blocked": false
    }
  ],
  "timestamp": 1709654400
}
```

Server-side behavior [#server-side-behavior]

For each reported script, the server:

1. **Upserts by domain.** If the domain has been seen before for this site, the existing record is updated. New domains are inserted.
2. **Auto-categorizes.** Known tracker domains are matched against a built-in database and assigned a category automatically.
3. **Updates sync status.** If a `sync_id` is provided, the corresponding tracker sync record is marked as complete (or failed, if an `error` was included).

Response codes [#response-codes-1]

| Status | Body                                 | Condition                                           |
| ------ | ------------------------------------ | --------------------------------------------------- |
| 200    | `{"success": true}`                  | Scripts processed successfully.                     |
| 400    | `{"error": "..."}`                   | Validation error (invalid body or sync\_id format). |
| 404    | `{"error": "Site not found"}`        | No site matches the provided `site_key`.            |
| 405    | `{"error": "Method not allowed"}`    | Request used a method other than POST.              |
| 500    | `{"error": "Internal server error"}` | Unexpected server error.                            |

***

Rate limiting [#rate-limiting]

All endpoints are rate-limited at the CDN edge: **20 requests per 10 seconds per IP address** (\~120 requests/minute). This limit is for abuse prevention and should not affect normal SDK usage.

What's next [#whats-next]

* [Getting started](/docs/getting-started). Install the SDK and publish your first config.
* [Dashboard guide](/docs/dashboard/overview). Manage sites, configs, and view consent logs.


# Changelog (/docs/changelog)



import { REGULATION_COUNT_DISPLAY, JURISDICTION_COUNT_DISPLAY } from "@/lib/headline-numbers"

All notable changes to ConsentStack are documented here.

***

October 2026: Privacy Policy Generator [#october-2026-privacy-policy-generator]

* New **Policies** page in the dashboard. Generate a privacy policy from a short business profile and the services detected on your site, with a live preview while you answer. Available on every plan.
* Every published version is hosted by ConsentStack at its own address, with an embed code for your own policy page that shows each new version as you publish it.
* The banner's policy link now follows your published policy. The Policies page replaces the old Documents page.
* [Read the guide](/docs/dashboard/policy-generator), or [see what the generator does](/privacy-policy-generator).

August 2026: Theming Override Tokens [#august-2026-theming-override-tokens]

* New CSS override tokens for per-role theming: checked and unchecked toggle track, toggle thumb, focus ring, primary button border, and preferences modal size. Each inherits from your existing theme colors until you set it, so existing configurations are unaffected.
* Disabled toggles now stay legible on dark themes.

March 2026: Initial Release [#march-2026-initial-release]

* Consent banner with opt-in, opt-out, notice, notice-required, and exempt models, plus the dynamic resolver for visitor-region-aware behavior
* Script blocking for the standard categories (essential, analytics, marketing, functional)
* {REGULATION_COUNT_DISPLAY} regulations across {JURISDICTION_COUNT_DISPLAY} jurisdictions
* Geo-detection at the network edge
* Dashboard for managing sites, configs, and consent logs
* JavaScript SDK (\~30 KB gzipped total: stub + core) with synchronous parse-time execution for pre-consent script blocking
* React SDK for Next.js and other React frameworks


# Compliance Scanner (/docs/compliance/compliance-scanner)



import { Step, Steps } from "fumadocs-ui/components/steps"
import { Callout } from "@/components/fumadocs/callout"
import { Radar, Cookie, ShieldCheck, Activity, Scale, Globe } from "lucide-react"
import { REGULATION_COUNT_DISPLAY } from "@/lib/headline-numbers"

The compliance scanner is a free tool that checks whether your website respects visitor consent. Enter a domain and, in about a minute, you get a plain report on what your site loads before and after a visitor makes a choice, checked from both the EU and the US. No signup required.

You can run it on any site, including your own, as many times as you want. It's a fast way to confirm your consent setup actually works, and to verify a fix after you make one.

What it checks [#what-it-checks]

<Cards>
  <Card icon={<Radar />} title="Third-party trackers" description="Detects scripts loaded from external domains, including analytics, advertising, and social widgets, and identifies the vendor behind each one." />

  <Card icon={<Cookie />} title="Cookie analysis" description="Examines every cookie set during page load, including expiration, security flags, and whether it is first or third party." />

  <Card icon={<ShieldCheck />} title="Consent banner detection" description="Identifies which consent platform you use, or flags that there isn't one, and measures how it behaves." />

  <Card icon={<Activity />} title="Pre-consent leakage" description="The most common violation: trackers and cookies that fire before the visitor has made any consent choice." />

  <Card icon={<Scale />} title="Regulation coverage" description={`Evaluates your site against GDPR, CCPA and CPRA, ePrivacy, and ${REGULATION_COUNT_DISPLAY} more applicable regulations.`} />

  <Card icon={<Globe />} title="Geo-variant behavior" description="Scans from both EU and US servers to catch sites that behave differently for visitors in different regions." />
</Cards>

Running a scan [#running-a-scan]

<Steps>
  <Step>
    Enter your domain [#enter-your-domain]

    Go to the [compliance scanner](/compliance-scanner) and type in a domain, for example `example.com`. You can paste a full URL too. The scan starts immediately, no account needed.
  </Step>

  <Step>
    The scanner runs both choices, from both regions [#the-scanner-runs-both-choices-from-both-regions]

    The scanner visits your site the way a real visitor would, twice. Once it clicks **Reject**, once it clicks **Accept**, and it records what loads each time. It does this from both an EU and a US vantage point, because the rules and the expected behavior differ by region.
  </Step>

  <Step>
    Read your report [#read-your-report]

    In about a minute you get a full report: a compliance score, a verdict for each region, and a list of every issue found with what it means and how to fix it. See [Reading your report](#reading-your-report) below.
  </Step>
</Steps>

Reading your report [#reading-your-report]

Your report opens with a **compliance score** from 0 to 100 and two **regional verdicts**, one for the EU and one for the US. The rules differ by region, so a site can pass in one place and fail in the other. When either region fails, the overall score is capped so a regulator-level failure can never read as passing.

Each regional verdict is one of:

| Verdict       | What it means                                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Compliant     | A working banner is present, Reject blocks non-essential tracking, and nothing fires before a choice is made.            |
| Non-compliant | Something is wrong: no banner, Reject doesn't work, trackers fire after a Reject, or tracking happens before any choice. |
| Not graded    | The scan couldn't complete, usually because bot protection blocked it. It is not a pass or a fail.                       |

<Callout type="info" title="What &#x22;non-compliant&#x22; means">
  A non-compliant verdict is not a legal judgment or a fine. It means the scanner observed tracking in a way the law in that region doesn't allow, usually data collection before consent or after a Reject. Treat it as a signal of where to look.
</Callout>

Below the verdicts, the report breaks everything out:

* **Critical issues** are listed first, in order of severity, each with why it matters and how to fix it.
* **Cookies** are listed individually with their domain, party, expiration, and whether they respect the visitor's choice.
* **Trackers** are listed with their vendor, category, and whether they fire in the Reject and Accept phases.
* **Regulations** show a pass, partial, or fail verdict for each law that applies to your site.

Common findings and what they mean [#common-findings-and-what-they-mean]

| Finding                 | What it means                                                                                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tracking before consent | Trackers or cookies fired before the visitor made any choice. Under EU rules, non-essential tracking must wait for opt-in. This is the most common failure. |
| Tracking after Reject   | Trackers or cookies kept going after the visitor clicked Reject. The visitor's choice is being ignored.                                                     |
| No banner detected      | No consent banner was found on a site that loads tracking which needs one.                                                                                  |
| Over-strict             | A warning, not a failure. Something is blocked more aggressively than the law requires, which costs you data or analytics without adding compliance.        |

Reporting a missed banner [#reporting-a-missed-banner]

The scanner recognizes a wide range of consent platforms, but it can miss less common or custom ones. If your report says no banner was detected and you know you have one, use the **Report a missed banner** button on the report. Add your email and, if you can, which platform you use. That goes straight to our team and helps us improve detection.

What's next [#whats-next]

* [Compliance overview](/docs/compliance): how ConsentStack applies the right rules in {REGULATION_COUNT_DISPLAY} regulations worldwide.
* [Script blocking](/docs/concepts/script-blocking): how trackers are stopped before they run, which is what a clean scan depends on.
* [Testing & verification](/docs/guides/testing-and-verification): confirm your own setup is working as expected.


# Global Privacy Control (/docs/compliance/global-privacy-control)



What is Global Privacy Control [#what-is-global-privacy-control]

Global Privacy Control (GPC) is a browser-level signal that tells websites the user wants to opt out of the sale or sharing of their personal information. It is expressed two ways:

* An HTTP request header: `Sec-GPC: 1`
* A JavaScript property: `navigator.globalPrivacyControl === true`

A site that receives the signal has to treat it as a valid opt-out request. It does not get to ask again, and it does not get to wait for the visitor to click anything.

{/* Verified 2026-07-31 against the CPPA approved regulation text (CCPA Updates, Cyber, Risk, ADMT and Insurance Regulations, OAL-approved 2025-09-22, effective 2026-01-01) and the internal regulation catalog audit of 2026-07-21. */}

Which US states require GPC [#which-us-states-require-gpc]

Twelve US states require businesses to recognize an opt-out preference signal such as GPC: California, Colorado, Connecticut, Delaware, Maryland, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon and Texas.

Two more are already scheduled. Louisiana requires recognition when its Data Privacy Act takes effect on January 1, 2027, and Vermont when the Data Privacy and Online Surveillance Act takes effect on January 1, 2028. Alabama's law takes effect on May 1, 2027 but does not require signal recognition until 2028, and Oklahoma's law, effective January 1, 2027, does not require it at all.

The [US state privacy law tracker](/regulations/region/us-state-laws) compares all of these laws side by side, including which require signal recognition and when each takes effect.

Outside the US, GPC is arguably binding under GDPR Article 21(5) for processing grounded in legitimate interest.

The practical answer for most sites is to honor GPC everywhere rather than sorting visitors by state first. ConsentStack does that by default. Geo-gating the signal costs more engineering than honoring it globally and gives everyone outside those twelve states a worse experience.

Browser support [#browser-support]

| Browser                     | Support        | Default                                                                                       |
| --------------------------- | -------------- | --------------------------------------------------------------------------------------------- |
| Brave                       | Native         | On                                                                                            |
| DuckDuckGo Browser          | Native         | On                                                                                            |
| Firefox                     | Native         | Off (user opts in at Settings, then Privacy, then Tell websites not to sell or share my data) |
| Chrome, Edge, Safari, Opera | Extension only | Requires installing a privacy extension                                                       |

That last row has an expiry date. California's AB 566, the Opt Me Out Act, was approved by the Governor on October 8, 2025 and becomes operative on January 1, 2027. It says a business "shall not develop or maintain a browser that does not include" a setting that lets the user send an opt-out preference signal. Once Chrome, Safari and Edge ship that setting, GPC stops being a privacy-enthusiast signal and starts arriving from ordinary visitors.

How ConsentStack detects GPC [#how-consentstack-detects-gpc]

ConsentStack reads GPC from both surfaces at every page load:

1. **Edge detection** at the config-delivery worker. The `Sec-GPC: 1` header is read and included in the config response.
2. **Client detection** in the SDK. `navigator.globalPrivacyControl` is read at initialization.

The effective GPC state is the OR of both signals. This belt-and-suspenders approach catches proxies that strip the header and extensions that inject GPC after the config fetch.

What ConsentStack does when GPC is detected [#what-consentstack-does-when-gpc-is-detected]

Behavior branches on the visitor's jurisdiction.

Opt-out jurisdictions (CA, CO, CT, DE, MD, MN, MT, NE, NH, NJ, OR, TX, and other US states) [#opt-out-jurisdictions-ca-co-ct-de-md-mn-mt-ne-nh-nj-or-tx-and-other-us-states]

* The consent banner does not show.
* A small toast appears at the bottom of the page confirming the opt-out, with a link to manage preferences.
* All non-essential cookie categories are set to denied.
* Consent Mode v2, Meta LDU, TikTok Limited Data Use, Pinterest Limited Data Sharing, and equivalent downstream signals fire automatically.

Opt-in jurisdictions (EU GDPR, UK, EEA) [#opt-in-jurisdictions-eu-gdpr-uk-eea]

* The consent banner does show, as it always has in these jurisdictions. Non-essential categories are pre-denied by default, which is the normal opt-in behavior.
* If the visitor has previously saved an explicit consent choice on this site, that choice is preserved. GPC sets the default for first-time visitors but does not wipe a prior, explicit decision. This matches CCPA section 7025(c)(3), which lets a business obtain consent where the signal conflicts with a visitor's own site-specific setting, and the W3C GPC spec's stance that explicit user choices override the default signal.

All other jurisdictions [#all-other-jurisdictions]

ConsentStack defaults to honoring GPC globally. This is configurable per site: in the dashboard under Config, then Settings, then Geo and compliance, the Global Privacy Control setting offers three modes. "Honor everywhere" is the default and our recommendation. "Only where legally required" limits automatic honoring to jurisdictions whose privacy law requires opt-out-signal recognition, tracked against our regulation catalog so new state laws are picked up as they take effect. "Off" disables automatic handling entirely; if you choose it, your team is responsible for honoring the signal another way, and the dashboard shows a warning to that effect. Changes take effect when you publish.

How to check if GPC is working on your site [#how-to-check-if-gpc-is-working-on-your-site]

Turn GPC on in your browser, open your site in a fresh session, and check three things in order: that your browser is sending the signal, that your site received it, and that trackers actually stopped firing. Most checks stop after the first two. That is how a site can pass a spot check and still be leaking data to advertising vendors.

1. **Turn the signal on.** Brave and the DuckDuckGo browser send GPC by default. In Firefox, go to Settings, then Privacy and Security, then turn on "Tell websites not to sell or share my data". Chrome, Edge, Safari and Opera need a privacy extension for now.

2. **Confirm your browser is sending it.** Open developer tools. In the Console, run `navigator.globalPrivacyControl` and expect `true`. Then open the Network tab, reload, click any request to your own domain, and look for `Sec-GPC: 1` in the request headers. Some setups send one and not the other, which is exactly why ConsentStack reads both and takes either as a yes.

3. **Confirm your site received it.** Reload the page. In a US opt-out state you should see the confirmation toast instead of the cookie banner. In the EU or UK you should still see the banner, with every non-essential category switched off before you touch anything. Opening the preferences panel should show those categories off, not on.

4. **Confirm trackers actually stopped.** This is the step that decides whether you are compliant. With GPC on, reload and do not click anything on the banner. In the Network tab, look for requests to your analytics and advertising vendors. There should be none. If Google Analytics, Meta Pixel or an ad tag fires before you interact with the page, the signal was received and then ignored somewhere downstream. The [free cookie checker](/tools/cookie-checker) runs this same test for you and lists every tracker that fires before consent.

5. **Check what your site publishes.** Load `https://yoursite.com/.well-known/gpc.json` in a browser. It should return `{ "gpc": true, ... }`. Automated compliance scanners look for that file, and its absence is a common reason a site that honors GPC correctly still gets marked down.

6. **Keep the receipt.** Every consent event ConsentStack records carries two audit fields: `gpc_detected`, which shows whether the signal was present on that event, and `signal_source`, which shows whether the decision came from an honored GPC signal or from a banner click. Both are included in the [JSON consent-log export](/docs/dashboard/activity-and-insights), so if a regulator asks whether a specific visitor's signal was honored, you can answer with that visitor's own records rather than a re-test.

When a passing site looks like it is failing [#when-a-passing-site-looks-like-it-is-failing]

Three things produce a false alarm:

* **You tested in a session that already had a saved consent choice.** An explicit decision the visitor made on your site outranks the signal, by design and by regulation. Test in a private window, or clear site data first.
* **Your extension injects GPC after the page starts loading.** The header will be missing on the first request even though the JavaScript property is set. ConsentStack still catches this because it reads both surfaces.
* **You tested from a jurisdiction your configuration does not treat as opt-out.** The banner showing in the EU with everything pre-denied is correct behavior, not a failure.

The 2026 confirmation requirement [#the-2026-confirmation-requirement]

Since January 1, 2026, quietly honoring the signal is no longer enough in California. Amended CCPA regulations changed section 7025(c)(6) from "a business **may** display" to "a business **must** display" whether it has processed the visitor's opt-out preference signal, and section 7026(g) changed the same way for opt-out requests generally. The regulations give the example of showing "Opt-Out Preference Signal Honored" on the page and reflecting the opted-out state through a toggle in the visitor's privacy settings. The amendment also swapped "or" for "and" between those two, so both are expected rather than either.

ConsentStack ships both halves with no configuration:

* The toast reads "We have honored your browser's Global Privacy Control signal and opted you out of the sale or sharing of your personal information." It is announced to screen readers as a status message rather than an alert.
* The preferences panel, reachable from that toast, shows every non-essential category switched off. Bulk Accept and Reject buttons are hidden in this state, so the panel reflects a decision that has already been made instead of inviting the visitor to make it again.

This is worth checking on whatever CMP you use. A banner that simply stops firing tags on a GPC visit satisfies the old rule and not the current one.

What publishers need to do [#what-publishers-need-to-do]

Nothing. GPC handling is fully automatic once ConsentStack is installed.

Three optional steps improve your compliance posture:

1. Publish /.well-known/gpc.json on your site [#1-publish-well-knowngpcjson-on-your-site]

Automated compliance scanners look for this file at the root of your domain. Add a static file at `https://yoursite.com/.well-known/gpc.json`:

```json
{ "gpc": true, "lastUpdate": "2026-01-01" }
```

2. Show visitors their signal status [#2-show-visitors-their-signal-status]

The SDK exposes the effective GPC status so you can reflect it in your own UI, for example on your privacy policy page:

```js
const gpc = window.consentstack.getGpcStatus()
// { detected: boolean, honored: boolean } or null before init
```

React sites get the same via `useConsent().gpc`. Three states fall out of it: no signal (`detected` is false), signal honored (`honored` is true, show "Opt-Out Preference Signal Honored"), and signal detected but overridden by the visitor's own explicit choice (`detected` true, `honored` false). See the [JavaScript API reference](/docs/developers/javascript-api#getgpcstatus) for details.

3. Update your privacy policy [#3-update-your-privacy-policy]

If you generate your privacy policy with the [Policy Generator](/docs/dashboard/policy-generator), it adds a Global Privacy Control section for you while your banner honors GPC. Otherwise, add a paragraph like this to your privacy policy:

> This website honors Global Privacy Control (GPC) signals. When we detect a GPC signal from your browser, we treat it as a valid opt-out of the sale or sharing of your personal information under applicable US state privacy laws, and as an objection to processing based on legitimate interest under the GDPR. We will not sell or share your personal information for the purposes GPC covers while your browser continues to send the signal. You may revisit this choice at any time through our preferences center.

Microsoft Clarity users: one additional step [#microsoft-clarity-users-one-additional-step]

If you use Microsoft Clarity alongside ConsentStack, configure your Clarity project dashboard with "cookies off by default." ConsentStack will call `clarity("consentv2", true)` only when the user grants consent. This matches Microsoft's recommended integration pattern and ensures Clarity does not fire cookie-based tracking pre-consent.

FAQ [#faq]

Does my banner still show if the visitor has GPC enabled [#does-my-banner-still-show-if-the-visitor-has-gpc-enabled]

In EU and other opt-in jurisdictions, yes. The banner is still required to collect affirmative consent for consent-based processing. Non-essential categories are pre-denied.

In US opt-out jurisdictions, no. A toast appears instead, and all non-essential tracking is denied.

What if a visitor previously accepted tracking, then enables GPC later [#what-if-a-visitor-previously-accepted-tracking-then-enables-gpc-later]

Their prior explicit consent is preserved. Under CCPA section 7025(c)(3), where the signal conflicts with a visitor's own site-specific setting, a business may obtain the visitor's consent and continue, and that explicit choice persists. New visitors with GPC enabled get default-deny on opt-out categories; they can still grant per-category exceptions through the preferences panel, and that exception survives reloads. To reset their state, the visitor clears site data or revokes individual categories from the preferences UI.

Do I need to change my Google Ads or Meta Pixel setup [#do-i-need-to-change-my-google-ads-or-meta-pixel-setup]

No. ConsentStack automatically sets Google Consent Mode v2 to denied and applies Meta Limited Data Use when GPC is honored. No changes to your pixel code are required.

Do I need to do anything to satisfy the 2026 confirmation requirement [#do-i-need-to-do-anything-to-satisfy-the-2026-confirmation-requirement]

No. The opt-out confirmation toast and the preferences panel state are on by default for every site running ConsentStack, so the display obligation under CCPA sections 7025(c)(6) and 7026(g) is met without configuration.

What percentage of my traffic has GPC enabled [#what-percentage-of-my-traffic-has-gpc-enabled]

Today, typically 2 to 8 percent for consumer sites, and higher for tech-niche audiences. Most of it comes from Brave and DuckDuckGo Browser, where the signal is on by default, plus privacy-extension users on Chrome and Firefox.

Treat that as a floor rather than a stable number. California's AB 566 requires browser developers to include an opt-out preference signal setting from January 1, 2027, and the share of GPC traffic will move once Chrome, Safari and Edge ship it. Sites that handle the signal correctly now will not need to do anything when that happens.


# Compliance (/docs/compliance)



import { REGULATION_COUNT_DISPLAY, JURISDICTION_COUNT_DISPLAY, US_STATES_COUNT } from "@/lib/headline-numbers"

ConsentStack comes with {REGULATION_COUNT_DISPLAY} privacy regulations built in, covering {JURISDICTION_COUNT_DISPLAY} jurisdictions worldwide, from GDPR across all 32 EU/EEA countries to {US_STATES_COUNT} US state privacy laws, plus Brazil, Canada, Japan, India, Singapore, Australia, and federal regulations like HIPAA and COPPA. It detects where your visitors are and automatically applies the correct consent rules for their location.

GDPR (European Union, EEA, UK & Switzerland) [#gdpr-european-union-eea-uk--switzerland]

The General Data Protection Regulation is the world's most well-known privacy law, and one of the strictest. It requires websites to obtain **prior opt-in consent** before running any non-essential tracking, meaning scripts like analytics and marketing pixels stay blocked until a visitor actively says yes.

GDPR also requires granular, per-category consent (visitors must be able to accept analytics but reject marketing, for example), a clearly visible reject button, the right to withdraw consent at any time, and documented proof that consent was collected.

ConsentStack satisfies all of this automatically. Visitors in GDPR regions see an opt-in banner with per-category toggles, a prominent "Reject All" button, and a re-entry button so they can change their mind later. Every consent decision is logged with a timestamp for your audit trail.

This applies to visitors from all 32 covered countries: Austria, Belgium, Bulgaria, Croatia, Cyprus, Czechia, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Iceland, Ireland, Italy, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden, Switzerland, and the United Kingdom.

US State Privacy Laws [#us-state-privacy-laws]

The US doesn't have a single federal privacy law. Instead, {US_STATES_COUNT} states have enacted their own: 20 are in force, and Oklahoma, Louisiana, Alabama and Vermont take effect in 2027 and 2028. Each has slightly different thresholds and requirements.

The key difference from GDPR: most US state laws use an **opt-out** model rather than opt-in. Visitors can use your site normally, but must have a clear way to opt out of data sales, targeted advertising, and profiling. California is the notable exception: CPRA requires opt-in consent for sensitive personal information, layering an extra step on top of the standard opt-out flow.

ConsentStack covers all {US_STATES_COUNT} states, and applies the four newest before their effective dates:

| State         | Law     | Consent Model                     | Effective Date |
| ------------- | ------- | --------------------------------- | -------------- |
| California    | CPRA    | Opt-out (opt-in for sensitive PI) | Jan 2023       |
| Virginia      | VCDPA   | Opt-out                           | Jan 2023       |
| Connecticut   | CTDPA   | Opt-out                           | Jul 2023       |
| Colorado      | CPA     | Opt-out                           | Jul 2023       |
| Utah          | UCPA    | Opt-out                           | Dec 2023       |
| Florida       | FDBR    | Opt-out                           | Jul 2024       |
| Texas         | TDPSA   | Opt-out                           | Jul 2024       |
| Oregon        | OCPA    | Opt-out                           | Jul 2024       |
| Montana       | MCDPA   | Opt-out                           | Oct 2024       |
| Delaware      | DPDPA   | Opt-out                           | Jan 2025       |
| Iowa          | ICDPA   | Opt-out                           | Jan 2025       |
| Nebraska      | NDPA    | Opt-out                           | Jan 2025       |
| New Jersey    | NJDPA   | Opt-out                           | Jan 2025       |
| Minnesota     | MNCDPA  | Opt-out                           | Jul 2025       |
| Tennessee     | TIPA    | Opt-out                           | Jul 2025       |
| Maryland      | MODPA   | Opt-out                           | Oct 2025       |
| Kentucky      | KCDPA   | Opt-out                           | Jan 2026       |
| Rhode Island  | RIDTPPA | Opt-out                           | Jan 2026       |
| Indiana       | INCDPA  | Opt-out                           | Jan 2026       |
| New Hampshire | NHPA    | Opt-out                           | Jan 2025       |
| Oklahoma      | OKCDPA  | Opt-out                           | Jan 2027       |
| Louisiana     | LDPA    | Opt-out                           | Jan 2027       |
| Alabama       | APDPA   | Opt-out                           | May 2027       |
| Vermont       | VDPOSA  | Opt-out                           | Jan 2028       |

When a visitor arrives from a covered US state, the banner automatically adapts to the correct consent model. You don't need to track which states have passed laws or what each one requires. ConsentStack stays current and applies the right rules.

Other Major Regulations [#other-major-regulations]

Beyond GDPR and US state laws, ConsentStack includes regulations from around the world:

| Regulation | Jurisdiction          | Consent Model |
| ---------- | --------------------- | ------------- |
| LGPD       | Brazil                | Opt-in        |
| PIPEDA     | Canada (excl. Quebec) | Opt-out       |
| Law 25     | Quebec, Canada        | Opt-in        |
| APPI       | Japan                 | Opt-out       |
| DPDPA      | India                 | Opt-in        |
| PDPA       | Singapore             | Opt-out       |
| APP        | Australia             | Opt-out       |
| UK DPA     | United Kingdom        | Opt-in        |

{/* AUDIT: PIPEDA scope claim flagged for legal review on 2026-04-28 */}

PIPEDA covers 12 Canadian provinces and territories, while Quebec's Law 25 applies separately with stricter opt-in requirements aligned with GDPR.

US Federal Regulations [#us-federal-regulations]

ConsentStack also includes four US federal regulations that apply based on industry rather than geography:

| Regulation | Sector                        | Consent Model |
| ---------- | ----------------------------- | ------------- |
| HIPAA      | Healthcare                    | Opt-in        |
| COPPA      | Children's privacy (under 13) | Opt-in        |
| GLBA       | Financial services            | Opt-out       |
| FISMA      | Federal agencies              | Opt-in        |

These are available in the regulation library for organizations in regulated industries who need to layer industry requirements on top of geographic consent rules.

Default Region [#default-region]

Not every country has a specific privacy law. For visitors from countries without one, ConsentStack shows a **notice** banner. This informs visitors about your use of cookies and tracking without requiring them to take action. It's a respectful, transparent approach that keeps your site compliant by default.

Geo-Detection [#geo-detection]

ConsentStack detects visitor location at the network edge using IP-based geolocation. No GPS, no third-party tracking services, just fast, private location detection that happens before the page loads.

If you prefer to show the same experience to all visitors regardless of location, you can disable geo-detection in your config. When disabled, every visitor sees your default region's consent model.

Proof of Consent [#proof-of-consent]

Privacy regulations don't just require you to collect consent. They require you to **prove** you collected it. If a regulator or auditor asks, you need records showing what each visitor consented to, when, and what version of your consent configuration was active at the time.

ConsentStack logs every consent decision automatically. Each log entry includes the visitor's anonymized ID (cryptographically hashed, no personal data stored), their consent choices per category, the timestamp, and the config version.

You can review consent activity in the [Activity & Insights](/docs/dashboard/activity-and-insights) section of your dashboard. Data retention varies by plan. Check your plan details for specifics.

What's Next [#whats-next]

* [Getting started](/docs/getting-started): add ConsentStack to your site in under five minutes
* [Banner & Preferences](/docs/concepts/banner-and-preferences): customize what visitors see
* [Dashboard overview](/docs/dashboard/overview): manage sites, review logs, and configure consent


# Banner & Preferences (/docs/concepts/banner-and-preferences)



Your consent banner is often the first interaction a visitor has with your brand. ConsentStack gives you full control over what they see, how they interact with it, and how they can update their choices later.

The consent banner [#the-consent-banner]

When someone visits your site for the first time, ConsentStack displays a consent banner. This is where visitors make their initial privacy choice.

ConsentStack detects each visitor's location and automatically shows the right version of the banner:

| Visitor location                | What they see                                 | Why                                                 |
| ------------------------------- | --------------------------------------------- | --------------------------------------------------- |
| **EU / UK / EEA**               | Accept All, Reject All, and Customize buttons | GDPR requires explicit opt-in consent               |
| **US states with privacy laws** | Accept All, Reject All, and Customize buttons | State laws like CCPA/CPRA require an opt-out option |
| **Everyone else**               | A simple "Got it" acknowledgement             | No consent collection required, just a notice       |

You don't need to configure this per region. ConsentStack handles the logic automatically based on your consent rules.

Banner layouts [#banner-layouts]

Choose from five layout options to match your site's design:

* **Bottom bar**: a full-width strip along the bottom of the page. The default, and the most common choice.
* **Bottom left / Bottom right**: a compact card in the corner. Less intrusive, good for content-heavy sites.
* **Bottom center**: a floating card centered at the bottom. A balanced middle ground.
* **Center modal**: a dialog in the middle of the screen with a dimmed background overlay. Impossible to miss.

All layouts are fully responsive. On smaller screens, they adapt automatically so buttons remain tappable and text stays readable.

The preferences center [#the-preferences-center]

When a visitor clicks "Customize" on the banner, the preferences center opens. This is where they get granular control over which cookie categories to allow.

Each consent category is listed with its name, a plain-language description, and a toggle. Essential cookies are always on and clearly marked as required, so visitors can see them but can't disable them. This transparency builds trust.

The preferences center has its own layout options:

* **Modal**: a centered dialog, the default
* **Side panel (left or right)**: slides in from either edge of the screen
* **Full page**: takes over the entire viewport for maximum clarity

At the top, bulk "Accept All" and "Reject All" buttons give visitors a quick way to set everything at once. A "Save Preferences" button at the bottom confirms their choices.

The re-entry button [#the-re-entry-button]

After a visitor makes their choice and the banner closes, a small floating button appears in the corner of your site. This is the re-entry button. It lets returning visitors reopen the preferences center anytime to update their choices.

You can customize the re-entry button's position (bottom-left or bottom-right), choose from eight built-in icons (shield, cookie, fingerprint, settings, and more), or upload your own. Background color, icon color, and border radius are all configurable to match your brand.

Customization overview [#customization-overview]

Every visual detail of the banner, preferences center, and re-entry button is configurable from the dashboard, with no code required:

* **Colors**: primary, secondary, background, text, borders, and link colors
* **Typography**: heading and body fonts, font sizes, line height
* **Layout**: banner position, preferences center style, re-entry button placement
* **Buttons and toggles**: border radius, padding, sizing
* **Banner dimensions**: max width, max height, padding, border width, shadow style
* **Content**: title, description, and button text for every consent model. Automatic translations for 25 languages built in (every official EU language plus Japanese), with per-language fine-tuning when you want different wording in a specific language.

Changes preview instantly in the Config Builder before you publish.

Built for everyone [#built-for-everyone]

The banner and preferences center are designed to work for all visitors:

* **Accessibility-first design** (semantic ARIA roles, keyboard navigation, prefers-reduced-motion support; full WCAG 2.1 AA audit pending)
* **Keyboard navigable**: every action is reachable via Tab and Enter, with Escape to close panels
* **Respects motion preferences**: animations are disabled automatically for visitors who prefer reduced motion
* **Works on all devices**: responsive layouts that adapt from desktop to mobile without configuration

Next steps [#next-steps]

Ready to customize your banner? Open the [Config Builder](/docs/dashboard/config-builder) in your dashboard to start adjusting colors, layouts, and content with a live preview.


# Categories & Regions (/docs/concepts/categories-and-regions)



ConsentStack uses two building blocks to decide how consent works on your site: **categories** (what you collect) and **regions** (where your visitors are). Together, they determine which consent rules apply to every visitor automatically.

Categories [#categories]

A category is a group of cookies or scripts that share a common purpose. When a visitor makes a consent choice, they accept or reject an entire category at once, not individual cookies.

Built-in categories [#built-in-categories]

ConsentStack ships with **four built-in categories**: essential, analytics, marketing, and functional. New sites are seeded with three of these (essential, analytics, marketing); functional is available in the schema and can be enabled per-site from the dashboard's Config Builder.

| Category       | Purpose                                                                      | Requires consent? |
| -------------- | ---------------------------------------------------------------------------- | ----------------- |
| **Essential**  | Cookies your site needs to function (session cookies, security tokens)       | No, always active |
| **Analytics**  | Help you understand how visitors use your site (page views, traffic sources) | Yes               |
| **Marketing**  | Used to deliver personalized ads and track campaigns                         | Yes               |
| **Functional** | Enhanced features like chat widgets and saved preferences                    | Yes               |

Essential vs. optional [#essential-vs-optional]

Essential categories are always active. Visitors cannot disable them, and they do not appear as toggles in the preferences panel. Every other category is optional, and visitors can accept or reject it, depending on the consent rules for their region.

Custom categories [#custom-categories]

Need something more specific? You can create custom categories (like "Social Media" or "Personalization") that work exactly like the built-in ones. Add them in the Config Builder's compliance tab.

Regions [#regions]

A region is a geographic grouping tied to a privacy regulation. ConsentStack detects where each visitor is located and matches them to the right region, no configuration needed on your part.

Built-in regions [#built-in-regions]

| Region                    | Covers                                                                                  | Regulation                        |
| ------------------------- | --------------------------------------------------------------------------------------- | --------------------------------- |
| **GDPR**                  | 32 countries: the EU, EEA, UK, and Switzerland                                          | GDPR / UK GDPR                    |
| **US State Privacy Laws** | 24 US states with privacy legislation (California, Virginia, Colorado, Texas, and more) | CCPA/CPRA, VCDPA, CPA, and others |
| **Everyone else**         | All countries and states not covered above (the default)                                | No specific regulation            |

The "Everyone else" region acts as a catch-all. Any visitor who does not fall into a more specific region is handled here.

How categories and regions work together [#how-categories-and-regions-work-together]

Each category has a **consent model** that can vary by region. The consent model controls what the visitor sees and whether scripts run before consent is given.

Here are the defaults:

| Category      | GDPR   | US State Laws | Everyone else |
| ------------- | ------ | ------------- | ------------- |
| **Essential** | Exempt | Exempt        | Exempt        |
| **Analytics** | Opt-in | Per-state     | Notice        |
| **Marketing** | Opt-in | Per-state     | Notice        |

What each model means for your visitors:

* **Exempt**: No consent needed. Scripts run immediately. The category does not appear in the preferences panel.
* **Opt-in**: Scripts are blocked until the visitor actively accepts. They see Accept and Reject buttons.
* **Per-state**: ConsentStack checks which US state the visitor is in and applies the correct model for that state's law automatically.
* **Notice**: An informational banner with an Acknowledge button. Scripts run by default.

<Callout type="info">
  You do not need to memorize these rules. ConsentStack applies the right model for each visitor based on their location, and your defaults are already compliant out of the box.
</Callout>

Customization [#customization]

The defaults cover the most common setup, but you have full control:

* **Add custom categories** to match how your site uses cookies (e.g., "Social Media", "A/B Testing").
* **Add custom regions** if you need to treat a specific country or group of countries differently.
* **Override any rule** in the matrix. For example, you could set Analytics to opt-in everywhere, or set a stricter model for a specific region.

All of these changes are made in the [Config Builder's compliance tab](/docs/dashboard/config-builder).

What's next [#whats-next]

* [Banner & Preferences](/docs/concepts/banner-and-preferences): Learn how the consent banner and preferences panel appear to your visitors.


# Importing consent from your previous CMP (/docs/concepts/consent-import)



Switching consent platforms should not mean re-prompting every visitor who
already made a choice. When consent import is enabled for your site,
ConsentStack reads the consent record your previous CMP stored in the
visitor's browser and honors it: visitors who accepted stay accepted,
visitors who declined stay declined, and nobody sees a second banner for a
decision they already made.

How it works [#how-it-works]

1. On the first page load after your cutover, the SDK looks for your previous
   CMP's first-party consent cookie (for Cookiebot, the `CookieConsent`
   cookie).
2. If it finds a valid, explicit decision that has not expired, it maps the
   categories to your ConsentStack categories and applies them immediately,
   before any tracking scripts can run. The banner is not shown.
3. The decision is converted into a native ConsentStack record and logged to
   your consent log with the original evidence attached (the previous CMP's
   consent ID, timestamp, and region), so your audit trail stays continuous
   even after you cancel the old vendor.
4. From the second page load on, the native ConsentStack record is used. The
   old cookie is left in place and simply expires on its own.

What gets imported [#what-gets-imported]

| Previous CMP category | ConsentStack category |
| --------------------- | --------------------- |
| Necessary             | Essential             |
| Preferences           | Functional            |
| Statistics            | Analytics             |
| Marketing             | Marketing             |

Only explicit decisions are imported. Records marked as implied consent,
malformed records, and records older than your consent lifetime setting are
ignored; those visitors see your banner as normal.

Declines are imported faithfully. A visitor who rejected tracking under your
previous CMP stays rejected under ConsentStack, with no re-prompt.

Supported vendors [#supported-vendors]

Consent import works through one connector per previous platform. Each
connector reads that platform's own consent cookie and maps it onto your
ConsentStack categories.

* **Cookiebot.** Built, and running in production today.
* **Any other platform.** We build the connector for you, before your
  cutover. Tell us what you are migrating from and it will be ready for
  your go-live.

There is no roadmap queue to join, and nothing here for your developers to
build. A connector is a reader for a cookie format we can go and inspect,
which is why we write them on request rather than shipping a fixed list. The
one requirement is technical: your previous platform has to store its
decision somewhere readable in the visitor's own browser. Nearly every
platform does. If yours does not, we will tell you before you switch rather
than after.

Your historical consent log [#your-historical-consent-log]

Consent import covers the decision your visitors are carrying right now. Your
historical consent log is a separate thing, and we move that for you too,
during onboarding. Pull the export from your old provider before you cancel,
because we cannot sign into their dashboard for you and most providers cut
access at the end of the billing period. We will tell you exactly what to
export and take it from there, so your evidence from before the switch ends up
in the same place as everything after it.

We are not the only platform that carries consent over, and it is worth
knowing what the alternatives commit to before you switch. See
[do you lose your visitors' consent when you switch CMPs?](/compare/consent-migration)
for what each major CMP does, read from its own documentation.

Enabling consent import [#enabling-consent-import]

Consent import is enabled per site by our team during onboarding. Contact
support with the name of your previous CMP and we will switch it on before
your cutover.


# Consent Models (/docs/concepts/consent-models)



Consent models are the rules that determine what your visitors see in the consent banner and whether scripts run before or after they give consent.

The six consent models [#the-six-consent-models]

Every cookie category on your site is assigned a consent model. The model controls the visitor's experience and when scripts are allowed to execute.

| Model                 | What visitors see                                                                                                                                                                         | Scripts run before consent?   | When it applies                                                                                                                                                                          |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Opt-in**            | A banner with Accept and Reject buttons. Visitors must actively accept before anything runs.                                                                                              | No                            | GDPR countries (EU, EEA, UK, Switzerland)                                                                                                                                                |
| **Opt-out**           | A banner with Accept and Reject buttons. Scripts run immediately, but visitors can choose to reject.                                                                                      | Yes                           | US states with opt-out frameworks (e.g., California under CCPA/CPRA)                                                                                                                     |
| **Notice**            | An informational banner with a "Got it" button. No accept/reject choice.                                                                                                                  | Yes                           | Countries with no specific consent regulation                                                                                                                                            |
| **Notice (required)** | Banner is shown but visitors cannot dismiss it without acknowledging the notice. Used in jurisdictions where pre-consent disclosure is required but a click-to-acknowledge is sufficient. | Yes (after acknowledgement)   | Jurisdictions that mandate visible disclosure but allow acknowledgement instead of opt-in (see `packages/sdk/src/types.ts:162` and runtime usage at `packages/sdk/src/types.ts:266,459`) |
| **Exempt**            | Nothing: visitors never see this category. It is always active and does not appear in the preferences panel.                                                                              | Yes (always on)               | Essential cookies required for your site to function (e.g., session cookies, security tokens)                                                                                            |
| **Dynamic**           | Varies, resolved automatically based on the visitor's US state.                                                                                                                           | Depends on the resolved model | US states with privacy laws, where requirements differ by state and data type                                                                                                            |

How models are assigned [#how-models-are-assigned]

You do not need to figure out which model applies to which visitor. ConsentStack detects each visitor's location automatically and applies the correct consent model based on the privacy laws in their region.

Here is what the defaults look like out of the box:

|               | GDPR countries | US state privacy laws | Everyone else |
| ------------- | -------------- | --------------------- | ------------- |
| **Essential** | Exempt         | Exempt                | Exempt        |
| **Analytics** | Opt-in         | Dynamic               | Notice        |
| **Marketing** | Opt-in         | Dynamic               | Notice        |

You can customize these rules in the **Compliance** tab of the Config Builder. For example, you might set Analytics to opt-in everywhere, or add a custom category with its own rules per region.

Dynamic consent in the US [#dynamic-consent-in-the-us]

Privacy laws in the United States are not uniform. Each state has its own rules, and those rules can vary depending on the *type* of data involved. This is why the US region uses the **dynamic** model instead of a single fixed rule.

When a visitor arrives from a US state with a privacy law, ConsentStack checks the specific requirements for that state and resolves each cookie category to the appropriate model. The result is that different categories can end up with different models for the same visitor.

For example, a visitor from California might see:

* **Analytics** resolved to **opt-out** (CCPA/CPRA allows data collection with an opt-out option)
* **Marketing** resolved to **opt-out** (with opt-in required for sensitive personal information per CPRA)

This all happens automatically. You do not need to configure state-level rules manually. ConsentStack has the requirements for all 24 US states with a privacy law built in.

<Callout type="info">
  Dynamic is never a visitor-facing model. Your visitors always see one of the concrete models: opt-in, opt-out, or notice. Dynamic is just how ConsentStack knows to check state-level rules before deciding.
</Callout>

What's next [#whats-next]

* Learn about [cookie categories](/docs/concepts/categories-and-regions) and how to organize the scripts on your site
* Set up your consent rules in the [Config Builder](/docs/dashboard/config-builder)


# Core Concepts (/docs/concepts)



ConsentStack works out three things on every page load: where your visitor is, which consent rules apply there, and which scripts have to stay blocked until they choose. These pages explain the moving parts behind that.

If you are setting up for the first time, start with [Getting Started](/docs/getting-started). Come back here when you want to understand why the banner behaved the way it did.

Consent Models [#consent-models]

Opt-in, opt-out, and notice-only are three different legal defaults, and the right one depends on where your visitor is sitting. This page covers how ConsentStack picks a model per visitor and what each one changes about the banner.

Categories & Regions [#categories--regions]

Every cookie and script is sorted into a category, and every visitor is matched to a region. Together those two decide what runs before consent. This page covers the category definitions, how regional rules are resolved, and what happens when a visitor's location is unclear.

Script Blocking [#script-blocking]

The part that does the actual work. ConsentStack detects third-party scripts and holds them until consent allows them, including tags injected by Google Tag Manager. This page explains the blocking mechanism and how to check it is working.

Banner & Preferences [#banner--preferences]

What your visitors see and interact with: the banner itself, the preferences center, and the re-entry control that lets someone change their mind later.

Importing Consent [#importing-consent]

Switching from another CMP does not have to reset every visitor. ConsentStack can read the consent record your previous platform left behind and honor it, so returning visitors are not asked again. This page covers which platforms are supported and what carries over.


# Script Blocking (/docs/concepts/script-blocking)



import { TRACKER_PATTERN_COUNT_DISPLAY, VENDOR_COUNT_DISPLAY } from "@/lib/headline-numbers"

ConsentStack finds the third-party scripts running on your site and blocks them until your visitors consent to the relevant category. No manual tagging required for known scripts. It just works.

How scripts are detected and categorized [#how-scripts-are-detected-and-categorized]

When a visitor loads your page, ConsentStack checks every third-party script in the browser, as it loads, against a built-in database of **{TRACKER_PATTERN_COUNT_DISPLAY} known tracker patterns** from **{VENDOR_COUNT_DISPLAY} vendors**. If a script belongs to a recognized vendor (Google Analytics, Meta Pixel, HubSpot, and hundreds more) it is automatically assigned to the right consent category.

Scripts from domains that are not in the database are flagged as **unassigned** in your dashboard so you can review and categorize them yourself.

What happens when you add a new tracker? [#what-happens-when-you-add-a-new-tracker]

It is checked the first time it loads. ConsentStack does not crawl your site on a schedule and does not carry a list of trackers from a last scan. The check runs in the visitor's browser on every page load, against the {TRACKER_PATTERN_COUNT_DISPLAY} tracker patterns built into the script itself, so there is no rescan to wait for and nothing to republish. A scan-based consent tool works the other way round: it re-crawls your site on a schedule (commonly monthly, with daily scans sold as an add-on) and can only block what its last crawl found, so a tag added between two crawls fires before consent until the next one.

Say your marketing team adds a new pixel through Google Tag Manager on a Tuesday afternoon. On the very next page load, whether that visitor is the first or the millionth:

* **If the tracker is in the catalog**, it is blocked before it executes, on that first load, until the visitor consents to its category. This covers tags injected at runtime by a tag manager, an A/B testing tool or a chat widget, not only script tags written into your HTML, and it covers the network calls the tracker would make (`fetch`, `XMLHttpRequest`, `sendBeacon`, pixels, iframes), as described further down this page.
* **If the tracker is not in the catalog**, it is recorded but not blocked. It appears in your dashboard's tracker inventory as **Unassigned** (uncategorized) the first time any visitor loads it, with the date it was first seen, the date it was last seen and the pages it appeared on. Assigning it a category, or blocking it outright, is one click. Your configuration regenerates automatically and the tracker is blocked before consent on every page load from then on.

That second case is the honest boundary, stated in the terms people use when they compare tools:

| Approach                                                         | When a new tracker is noticed | What happens before it is categorized                                                                                     |
| ---------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Scan-based** (crawl on a schedule, block what the crawl found) | On the next scheduled crawl   | It runs. The gap is everything added since the last scan.                                                                 |
| **Runtime catalog** (ConsentStack)                               | On its first page load        | A catalog tracker is blocked before execution. An unknown one is recorded as Unassigned and runs until you categorize it. |
| **Default-deny** (block every unknown request)                   | On its first page load        | It is blocked, and so is any legitimate script the tool has not seen, until someone allows it.                            |

ConsentStack is a known-tracker blocklist evaluated at runtime, not a default-deny firewall: a script from a domain the catalog has never seen runs until you categorize it. That default means a new script cannot silently break your checkout, chat or embeds before a person has looked at it. The trade is that the gap for a scan-based tool is "anything added since the last scan", while the gap here is "anything outside a {VENDOR_COUNT_DISPLAY}-vendor catalog", and you see the second gap in your dashboard on the first page load that carries it, not weeks later.

Two things help when you want to be strict about it:

* **Test mode** runs the same checks in report-only mode, recording what would have been blocked without blocking anything, so you can review the inventory before you enforce. See [testing on a live site without showing the banner](/docs/guides/testing-and-verification#test-on-a-live-site-without-showing-the-banner).
* **Load order.** ConsentStack has to be the first script in your `<head>`. A tracker that loads before it can fire before the check exists, whichever consent tool you use. See [SDK installation](/docs/developers/sdk-installation).

To see the behaviour for yourself, add a throwaway tag through your tag manager, open the Network panel in a fresh private window, and confirm that nothing leaves the browser before you click anything on the banner. The steps are in [how to verify any consent tool actually blocks before consent](/docs/guides/testing-and-verification#how-do-you-verify-any-consent-tool-actually-blocks-before-consent).

Two ways to categorize scripts [#two-ways-to-categorize-scripts]

| Method           | How it works                                                                                              | When to use it                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Automatic**    | ConsentStack recognizes the script's domain and assigns a category based on its known vendor database.    | Works out of the box for the vast majority of third-party scripts. No action needed. |
| **Manual rules** | You create a custom rule in the dashboard for a specific domain, assigning it to any category you choose. | For proprietary or niche scripts that the vendor database does not cover.            |

Manual rules always take priority. If you create a custom rule for a domain that is already auto-categorized, your rule wins.

Pattern syntax for manual rules [#pattern-syntax-for-manual-rules]

A manual rule's pattern is matched against the hostname of each script request. Two forms are supported:

| Form               | Example              | Matches                               | Does not match                      |
| ------------------ | -------------------- | ------------------------------------- | ----------------------------------- |
| **Plain domain**   | `zi-scripts.com`     | `zi-scripts.com`, `js.zi-scripts.com` | `zi-scripts.com.evil.net`           |
| **Wildcard (`*`)** | `s3-*.amazonaws.com` | `s3-us-west-2.amazonaws.com`          | `bucket.s3-us-west-2.amazonaws.com` |

Rules of thumb:

* A plain domain covers itself and every subdomain. This is the right form for almost all rules.
* `*` matches any run of characters, including dots. Wildcard patterns must describe the whole hostname: `s3-*.amazonaws.com` does not cover `bucket.s3-us-west-2.amazonaws.com`. Add a `*.` variant (`*.s3-*.amazonaws.com`) when you need subdomain coverage too.
* When several rules match the same hostname, the longest pattern wins.
* Rules assigned to the essential category never block anything; essential is always allowed.
* A pattern of just `*` matches every third-party hostname on your site. That gates everything under one category, which is almost never what you want.

What blocking looks like in practice [#what-blocking-looks-like-in-practice]

Scripts are stopped **before they execute**, not cleaned up after the fact. This is an important distinction: no tracking code runs until your visitor has actively given consent for that category.

When a visitor gives consent:

* **Blocked scripts activate immediately.** There is no page reload required. Scripts in the consented category start running right away, in their original page order. If a tracker has multiple scripts (for example, a config script and a pageview script), they execute in the correct sequence: the config script loads and finishes before the pageview script starts.

When a visitor revokes consent:

* **Already-executed scripts cannot be un-run.** A script that has already loaded and sent data cannot be retroactively stopped. ConsentStack shows the visitor a gentle reminder to refresh the page, which clears the scripts from memory and re-applies blocking.

<Callout type="info">
  The key trust signal: scripts are blocked *before* execution, not cleaned up afterward. Your visitors' data is never sent to a third party without their consent.
</Callout>

What does "blocks scripts before consent" actually mean? [#what-does-blocks-scripts-before-consent-actually-mean]

It describes three different mechanisms, and they do not protect visitors equally. A consent tool can rewrite script tags so the browser skips them, intercept the network calls a tracker makes, or let everything load and then tell the vendor what the visitor chose. Only the first two stop data leaving the browser.

| Mechanism                | What it does                                                                                                     | What still gets through                                                                                                                     |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tag rewriting**        | Rewrites `<script>` elements so the browser will not execute them until consent is given.                        | Anything that is not a script tag: `fetch()` and `XMLHttpRequest` calls, `navigator.sendBeacon`, tracking pixels loaded as images, iframes. |
| **Request interception** | Wraps the browser APIs a tracker uses to reach the network, so a blocked call never leaves the page at all.      | Tags written directly into the initial HTML, which the browser's preload scanner fetches before any JavaScript runs (see the caveat below). |
| **Consent signalling**   | Lets tags load and run, then tells the vendor what the visitor chose. Google Consent Mode is the common example. | Everything. The request reaches the third party either way. The vendor decides what to do with it.                                          |

Consent signalling is worth having, and ConsentStack sends those signals too. But it is not blocking, and the two get described with the same words. Under GDPR the connection itself is the disclosure: once a request reaches an ad network, that network has your visitor's IP address and can set cookies on its own domain, whatever the payload said about consent.

This is why "blocks scripts" and "blocks requests" are different claims. A tool that only rewrites `<script>` tags will still let a `fetch()` call to an ad endpoint through, because no script tag was ever involved.

What ConsentStack intercepts [#what-consentstack-intercepts]

ConsentStack wraps the network-reaching browser APIs, not just script tags:

| Surface                                              | Covered                                |
| ---------------------------------------------------- | -------------------------------------- |
| `<script>`, `<iframe>`, `<img>`                      | Yes, intercepted when the `src` is set |
| `fetch()`, `XMLHttpRequest`                          | Yes                                    |
| `navigator.sendBeacon()`                             | Yes                                    |
| `WebSocket`, `EventSource`                           | Yes                                    |
| `document.cookie`, `localStorage` / `sessionStorage` | Yes, writes are gated by category      |

Blocked calls fail at the wrapper. Nothing is sent and no connection is opened, so there is no request for a third party to log.

For developers [#for-developers]

If you need more control, you can manually tag any script with a `data-cs-category` attribute to assign it to a specific consent category. This is useful for inline scripts or cases where you want to override automatic detection.

For implementation details, see [SDK installation](/docs/developers/sdk-installation).

The preload-scanner caveat [#the-preload-scanner-caveat]

ConsentStack intercepts third-party scripts at the moment their `src` is set in JavaScript. This catches every standard tracker bootstrap pattern (Google Tag Manager, HubSpot, Microsoft Clarity, Meta Pixel, and so on) when they are injected via JS. It does **not** catch tags written directly into the initial HTML such as `<script async src="...">` or `<link rel="preload" as="script">`. The browser's preload scanner walks the markup ahead of the parser and dispatches fetches for those URLs before any JavaScript runs. The third party receives the request and may set cookies on its own domain even though the script's execution is later blocked.

Two situations make this matter:

1. **Plain HTML / Webflow / WordPress / Squarespace** where you paste a vendor's `<script async src="...">` snippet straight into the head.
2. **SSR'd Next.js layouts** where `<Script>` and `@next/third-parties` (`<GoogleTagManager>`, `<GoogleAnalytics>`) emit `<link rel="preload" as="script">` into the rendered HTML.

Iframes written into the HTML behave the same way. A form, booking or review widget embedded as `<iframe src="...">` starts loading the moment the browser reads the tag. ConsentStack stops the frame before its page loads, so nothing inside it runs (no pixels, no session tracking), and it loads the frame once the visitor consents. The frame's first request still reaches the vendor, though. To prevent that, use `data-cs-src` below.

Solution: opt-in markup with application/cs-resolve [#solution-opt-in-markup-with-applicationcs-resolve]

For tags written directly in HTML, mark them with a non-executable type so the preload scanner ignores them. ConsentStack walks these tags after consent is determined and rewrites them to the executable form for any category the visitor has granted.

```html
<!-- External script: parser will not fetch -->
<script type="application/cs-resolve" async
        src="https://www.googletagmanager.com/gtag/js?id=AW-XXXXX"></script>

<!-- Inline script: requires data-cs-category since there is no src to look up -->
<script type="application/cs-resolve" data-cs-category="analytics">
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date()); gtag('config', 'AW-XXXXX');
</script>

<!-- Stylesheet: parser will not fetch until rel is rewritten -->
<link rel="cs-stylesheet" href="https://example.com/widget.css">

<!-- Iframe: put the URL in data-cs-src and leave src off. Nothing loads until consent -->
<iframe data-cs-src="https://forms.example.com/embed/123"
        style="width:100%;height:500px;border:none"></iframe>
```

How classification works:

1. If `data-cs-category` is set, that category is used (always wins).
2. Otherwise, the tag's `src` (or `href`, or `data-cs-src` for iframes) domain is matched against the catalog. Hundreds of common vendors are auto-classified.
3. If neither resolves a category, the tag stays dormant.

Inline scripts have no `src` to classify, so they require an explicit `data-cs-category`. External scripts and stylesheets from known vendors do not.

Many widget libraries (Calendly, Intercom, HubSpot, Drift) inject their own styles when their script initializes, so a separate `<link>` for the stylesheet is often redundant. Try removing the `<link>` first; only mark it with `rel="cs-stylesheet"` if the widget visibly breaks without it.

Solution: SSR-emitted preloads in Next.js [#solution-ssr-emitted-preloads-in-nextjs]

For frameworks that auto-emit preloads, two patterns avoid the leak:

* **Inline the bootstrap snippet** with `dangerouslySetInnerHTML`. The inline `<script>` has no `src`, so no preload is emitted, and the runtime injection it performs is intercepted normally. This is the simplest pattern for layout-level trackers. See [Framework Guides](/docs/developers/framework-guides#loading-third-party-trackers-in-your-layout) for the full pattern.
* **Gate `<Script>` on a consent hook.** Wrap it in a client component that returns `null` until `useConsentValue` reports the relevant category as granted. The SSR pass renders `null`, so no preload appears in the initial HTML.

What's next [#whats-next]

* Check the difference yourself: [how to verify any consent tool actually blocks before consent](/docs/guides/testing-and-verification#how-do-you-verify-any-consent-tool-actually-blocks-before-consent)
* Read why [Google Analytics is not GDPR compliant by default](/blog/is-google-analytics-gdpr-compliant), and how often scanned sites fire it before consent
* Learn about [consent models](/docs/concepts/consent-models) and how ConsentStack decides what your visitors see
* See how to review and manage detected scripts in the [dashboard](/docs/dashboard/overview)


# Activity & Insights (/docs/dashboard/activity-and-insights)



import { Callout } from '@/components/fumadocs/callout';
import { TRACKER_PATTERN_COUNT_DISPLAY } from "@/lib/headline-numbers"

ConsentStack gives you three tools to understand and prove your compliance: an analytics dashboard for trends, consent logs for audit-ready records, and tracker detection for managing third-party scripts.

Consent Analytics [#consent-analytics]

The analytics dashboard shows you how visitors are responding to your consent banner at a glance.

KPI Cards [#kpi-cards]

Four key metrics sit at the top of the page:

* **Total Events.** The number of consent interactions during the selected period.
* **Consent Rate.** The percentage of visitors who opted in (accepted all categories).
* **Time to Action.** The average time between seeing the banner and making a decision.
* **Bounce Rate.** The percentage of visitors who left without interacting with the banner at all.

Each card shows a delta indicator when comparison mode is on, so you can see whether a metric is trending up or down versus the prior period.

Trend Chart [#trend-chart]

Below the KPIs, a trend chart plots your selected metric over time. Use the time range selector to view the last 24 hours, 7 days, 30 days, or 90 days.

Turn on **comparison mode** to overlay the current period against the previous one. This helps you spot the impact of banner changes or seasonal shifts.

Breakdown Charts [#breakdown-charts]

Two breakdown panels round out the dashboard:

* **Devices.** Consent events split by desktop, mobile, and tablet.
* **Top Countries.** Consent events by visitor country, with the applicable regulation and per-country consent rate shown inline.

Export [#export]

Click **Export CSV** to download the current dataset. Useful for sharing with legal or plugging into your own reporting tools.

<Callout type="info">
  Analytics is available on Pro plans and above.
</Callout>

Consent Logs [#consent-logs]

Every consent decision a visitor makes is recorded as an individual log entry. Logs are your proof of consent: the record you hand to an auditor or regulator when they ask, "Can you prove this visitor consented?"

How do I prove a specific visitor consented? [#how-do-i-prove-a-specific-visitor-consented]

Export your consent logs and filter by the visitor's `anon_id_hash`, the SHA-256 hash of their anonymous ConsentStack ID. Every decision that visitor ever made on your site is a row under that one key, each carrying the timestamp, the action taken, the category-level choices, the regulation that applied, and the exact banner configuration version they saw. Those rows are the evidence package.

What Gets Logged: The Export Schema [#what-gets-logged-the-export-schema]

The CSV export contains exactly 29 columns per consent record. These are the literal column names, in export order:

| Column                      | What it records                                                                    |
| --------------------------- | ---------------------------------------------------------------------------------- |
| `id`                        | Unique identifier for this log entry                                               |
| `site_id`                   | The site the event belongs to                                                      |
| `config_id`                 | The consent configuration that was live when the visitor decided                   |
| `config_version`            | Version number of that configuration                                               |
| `event_type`                | `initial` for a visitor's first decision, `update` for a later change              |
| `event_action`              | The decision itself: `opt_in`, `opt_out`, `partial`, or `acknowledge`              |
| `interaction`               | The control the visitor used (accept button, reject button, preferences save)      |
| `categories`                | The visitor's per-category choices, as JSON                                        |
| `consent_model`             | The model the banner enforced: `opt_in`, `opt_out`, `notice`, or `notice_required` |
| `anon_id_hash`              | SHA-256 hash of the visitor's anonymous ID. The single-visitor lookup key          |
| `device_type`               | Desktop, mobile, or tablet                                                         |
| `browser`                   | Browser family                                                                     |
| `os`                        | Operating system                                                                   |
| `country_code`              | Visitor country, derived from infrastructure headers                               |
| `region`                    | The consent region that matched                                                    |
| `regulation`                | The regulation that applied (GDPR, CCPA, and so on)                                |
| `language`                  | The visitor's browser language                                                     |
| `resolved_language`         | The language the banner actually displayed                                         |
| `domain`                    | The domain the event was recorded on                                               |
| `page_url`                  | The page the visitor was on when they decided                                      |
| `banner_position`           | The banner layout shown                                                            |
| `banner_load_time_ms`       | How long the banner took to load, in milliseconds                                  |
| `time_to_action_ms`         | Time between seeing the banner and deciding, in milliseconds                       |
| `preferences_opened`        | Whether the visitor opened the preferences center first                            |
| `sdk_version`               | The SDK version that recorded the event                                            |
| `site_key`                  | The public site key the event was logged under                                     |
| `global_compliance_enabled` | Whether global compliance mode was on                                              |
| `instant_updates`           | Whether instant configuration updates were enabled                                 |
| `created_at`                | Timestamp of the decision                                                          |

CSV and JSON exports are not the same schema [#csv-and-json-exports-are-not-the-same-schema]

The CSV is a fixed 29-column report. The JSON export returns the complete stored record, a superset of the CSV. The extra fields include the [Global Privacy Control](/docs/compliance/global-privacy-control) audit pair (`gpc_detected`, which records whether a GPC signal was present on the event, and `signal_source`, which records whether the decision came from an honored signal, a banner click, or the preferences center) and, when the geo-details setting is enabled for your site, city-level location fields (`geo_city`, `geo_postal_code`, `geo_latitude`, `geo_longitude`, `geo_timezone`, `geo_continent`). Choose JSON when the audit question involves GPC or location detail.

Exporting Consent Logs [#exporting-consent-logs]

In the dashboard, open your site's **Activity** area, go to **Consent Logs**, and click **Export**. Two formats are available:

* **Consent Logs (CSV)**: the 29-column report above, RFC 4180 escaped, with a header row.
* **Consent Logs (JSON)**: newline-delimited JSON (NDJSON), one complete record per line.

Both formats stream your site's entire log, not just the page of results you are viewing. The download is named `consent-logs-<site>-<date>.csv` or `.ndjson`.

Browsing and Inspecting Logs [#browsing-and-inspecting-logs]

Logs appear in a paginated table sorted by most recent. Click any row to open the **inspector panel** on the right, which shows the full detail of that consent event, including the interaction timeline (banner shown, preferences opened, decision made) and metadata like SDK version and banner position.

Privacy by Design [#privacy-by-design]

Visitor IDs are cryptographically hashed before they are stored. No names, emails, IP addresses, or other personally identifiable information ever touches your logs. This means your consent records are audit-ready without creating a privacy liability.

How long are consent logs kept? [#how-long-are-consent-logs-kept]

Retention is enforced by a nightly cleanup job, so these numbers are the storage reality, not a dashboard display setting: **Business keeps consent logs for one year, Pro keeps 30 days, and Basic keeps logs for the current billing period.** The logs dashboard itself is available on Pro plans and above.

Tracker Detection [#tracker-detection]

ConsentStack automatically detects third-party scripts running on your site and reports them back to the dashboard. This gives you a clear picture of what is loading on your pages, and whether those scripts are properly gated behind consent.

How It Works [#how-it-works]

The SDK monitors your site for third-party scripts and reports their domains to the dashboard. Those domains are matched against a database of **{TRACKER_PATTERN_COUNT_DISPLAY} known tracker patterns** and auto-categorized (e.g., Analytics, Advertising, Social Media). Recognized scripts show the vendor name, logo, and a link to the vendor's site.

Scripts that don't match a known domain are flagged as **uncategorized** and surfaced at the top of the page for your review. You can assign a consent category to any script with a single click.

Triggering a Scan [#triggering-a-scan]

Trackers appear automatically as visitors browse your site. If you want results immediately (for example, after launching or connecting a new domain), click the **Sync** button to trigger a fresh scan on demand.

Custom Rules [#custom-rules]

For scripts that aren't auto-detected, you can add custom domain pattern rules to manually assign a consent category. This is useful for internal tools or niche vendors that aren't in the known tracker database yet.

What's Next [#whats-next]

* [Categories & Regions](/docs/concepts/categories-and-regions). Learn how consent categories and regional rules connect to tracker blocking.
* [Script Blocking](/docs/concepts/script-blocking). Understand how ConsentStack prevents scripts from running before consent is given.
* [Analytics & Logs feature overview](/features/analytics-logs). See what the analytics dashboard and consent logs look like in practice.


# Config Builder (/docs/dashboard/config-builder)



import { REGULATION_COUNT_DISPLAY, LANGUAGE_COUNT } from "@/lib/headline-numbers"
import { Callout } from "@/components/fumadocs/callout"

The Config Builder is where you design and customize your entire consent experience. Every change you make is reflected instantly in a live preview, so you always see exactly what your visitors will see. Changes save automatically as drafts, and nothing goes live on your site until you explicitly publish.

You'll find four tabs in the Config Builder sidebar: **Appearance**, **Content**, **Compliance**, and **Settings**. Integrations and Languages live within the Compliance tab.

Appearance [#appearance]

The Appearance tab controls the visual design of your consent banner and preferences panel. You can customize colors, fonts, banner layout, button styles, corner radius, shadows, and the position of the re-entry button that lets visitors change their preferences later.

A set of banner layouts are available out of the box. You can also choose how the preferences panel looks when a visitor wants to review individual consent categories. On the **Pro plan and above**, you can write custom CSS and custom JavaScript for pixel-perfect control over banner appearance and behavior. For fine-grained control over individual elements like toggle colors and focus rings, see the [theming override tokens](/docs/developers/theming-tokens).

Content [#content]

The Content tab is where you edit the text your visitors read: the banner headline, body copy, button labels, and the preferences panel copy. ConsentStack adapts text based on the consent model shown to each visitor, so you can write different copy for opt-in visitors (who need to actively accept) versus notice visitors (who just need to be informed).

Edit any text field in the inspector panel on the right, and watch the live preview update instantly on the left. To link your privacy policy from the banner text, click the link icon in the text toolbar, then the document icon in the link bar that opens, and choose a policy you've published with the [Policy Generator](/docs/dashboard/policy-generator). That link follows your policy wherever it lives. For a policy page of your own, click the link icon and type the page's address into the link bar.

Compliance [#compliance]

The Compliance tab is the control center for your consent rules. Here you manage your **consent categories** (like Analytics, Marketing, and Functional), add the **regulations** that apply to your site (GDPR, CCPA, and {REGULATION_COUNT_DISPLAY} others), and configure the **consent rules** that determine what each regulation requires for each category.

For example, you might set Analytics cookies to require opt-in consent for GDPR visitors, but only require notice for CCPA/CPRA visitors. The rules you set here drive everything: which banner your visitors see, what scripts are blocked, and what signals are sent to your ad platforms.

[Learn more about how categories and regions work.](/docs/concepts/categories-and-regions)

Integrations [#integrations]

Platform integrations let you automatically send consent signals to Google Consent Mode, Meta, TikTok, and other advertising and analytics platforms. When a visitor grants or denies consent, ConsentStack forwards that decision to each enabled platform so your tags and pixels respect the visitor's choices without any extra code.

Enable the integrations you need, and ConsentStack handles the signal format for each platform. Integrations are available on the **Pro plan and above**.

Languages [#languages]

ConsentStack supports multi-language consent banners in {LANGUAGE_COUNT} languages. Enable the languages your visitors speak, and ConsentStack automatically translates your banner text when you publish, no manual translation work required. If you've customized any text in the Content tab, those customizations are translated too.

Customizing translations per language [#customizing-translations-per-language]

Automatic translation is a starting point, not a limit. To fine-tune the wording for a specific language, open the **Content** tab and pick the language from the dropdown in the preview toolbar. The panel switches to that language: every field shows the text your visitors currently see, and any change you make applies to that language only.

Fields you customize this way are protected. Automatic translation never overwrites them, on this publish or any future one. Protection is per field: if you rewrite the Italian description but leave the Italian title alone, the title keeps updating automatically when your default text changes, while your description stays exactly as you wrote it.

A dot next to a language in the dropdown means that language has customized fields. Consent model tabs work per language too, so you can give Italian visitors different opt-in and opt-out wording without touching any other language. To discard a customization, use the reset control on the field and the automatic translation returns instantly.

Category names and descriptions can also be customized per language. Select a category on the **Compliance** tab and pick a language from the dropdown at the top of the category panel.

Multi-language support is available on the **Pro plan and above**. Language settings live within the Compliance tab.

Settings [#settings]

The Settings tab holds site-level behavior that isn't part of the banner's design or wording: how published changes roll out, how visitor location is resolved, how long consent stays valid, and a few developer options. Like everything else in the Config Builder, changes here save as drafts until you publish.

Banner & UI [#banner--ui]

**Instant config updates** makes published changes appear on your site immediately instead of within about five minutes. Turn it on while you're setting things up, and turn it off when you're done so your visitors get the speed benefit of caching.

**Test mode** hides the banner from real visitors so you can verify your setup before launch. Real visitors see no banner, no preferences panel, and no re-entry button, and nothing is blocked, so trackers run freely. Add `?cs-test-mode=true` to any page URL to load the site normally and see the banner yourself.

Test mode doesn't stop ConsentStack from reporting. Tracker detection keeps filling in your inventory and visitors still count toward your plan, which is what lets you validate an install before launch. It also keeps config updates instant on its own, so the Instant config updates toggle is paused while it's on. Your saved choice there is kept and resumes when you turn test mode off.

<Callout type="warn">
  While test mode is on, your site has no working consent banner for real visitors. Turn it off and publish before you launch.
</Callout>

**Show ConsentStack branding** controls whether "Powered by ConsentStack" appears in the banner.

Geo & compliance [#geo--compliance]

**Geo-detection** applies region-appropriate consent rules based on where each visitor is. With it off, every visitor sees your default region's banner.

**Strict mode** decides what happens when a visitor's location can't be determined. It applies the strictest consent model (opt-in) rather than your default, which is the recommended setting for GDPR.

**Global Privacy Control** sets how ConsentStack responds to GPC opt-out signals sent by visitors' browsers. *Honor everywhere* is the simplest compliant posture. *Only where legally required* limits it to the jurisdictions that mandate it, and *Off* ignores the signal. Twelve US states legally require honoring GPC.

Consent storage [#consent-storage]

**Share consent across subdomains** means a visitor who consents on one subdomain won't see the banner again on another subdomain of the same site.

**Recollect consent after** sets how many days a consent decision stays valid before the visitor is asked again.

Developer [#developer]

**Expose geo details via SDK** includes city, postal code, coordinates, and timezone in the config response, readable through [`getGeo()`](/docs/developers/javascript-api).

Draft & Publish Workflow [#draft--publish-workflow]

Every change you make in the Config Builder saves automatically as a draft. Drafts are private to your team. Your visitors never see them. When a tab has unpublished changes, a "Draft" indicator appears next to it in the sidebar so you always know what's pending.

When you're happy with your changes, hit **Publish** to push the new config live. The published version is what your visitors see. You can also discard a draft at any time to revert back to the currently published version. This workflow lets you experiment freely without worrying about breaking your live consent experience.

What's Next [#whats-next]

* [Add your site to ConsentStack](/docs/getting-started) to start building your config
* [Learn about consent categories and regions](/docs/concepts/categories-and-regions) to understand the compliance model


# Dashboard Guide (/docs/dashboard)



The ConsentStack dashboard is where you configure the banner, manage your sites, and review what visitors actually consented to. These pages walk through each area.

Overview [#overview]

Workspaces, sites, domains, and settings. Start here to understand how your account is structured and where each setting lives.

Config Builder [#config-builder]

The visual editor for your consent banner: appearance, content, compliance rules, integrations, and languages, with a live preview. Changes are staged until you publish, so you can work without affecting your live site.

Policy Generator [#policy-generator]

Generate your Privacy Policy, Cookie Policy, Terms of Service, Disclaimer and Accessibility Statement from a short business profile, your answers, and the services detected on your site. ConsentStack hosts every version, gives you an embed code for your own pages, keeps your banner's policy links pointing at them, and updates the Privacy Policy and Cookie Policy as your tools change.

Activity & Insights [#activity--insights]

Consent rates over time, audit-ready consent logs you can export, and the list of third-party scripts ConsentStack has detected on your sites.


# Overview (/docs/dashboard/overview)



The ConsentStack dashboard is where you manage everything about your consent setup, from the workspaces and sites you work with, to the domains you protect and the policies you publish. This page walks you through each section so you know exactly where to find things.

Workspaces [#workspaces]

A workspace is your account. It holds your sites, members, and billing subscription. When you sign up for ConsentStack, you create your first workspace as part of the onboarding flow.

You can invite other people to your workspace and assign them a role that controls what they can do:

| Role       | What they can do                                                                              |
| ---------- | --------------------------------------------------------------------------------------------- |
| **Owner**  | Full control. Manage members, billing, settings, and delete the workspace. One per workspace. |
| **Admin**  | Add and remove sites, edit consent configs, invite members.                                   |
| **Member** | View sites and consent logs. Read-only access.                                                |

Most workspaces only need one or two people. If you are working solo, the Owner role covers everything.

Sites [#sites]

A site represents one website you manage consent for. You can have multiple sites under a single workspace (for example, a marketing site and a product app).

When you create a site, ConsentStack generates a **Site Key**. This key is part of the script tag you add to your website. Once the script is installed, the consent banner appears for your visitors automatically.

Each site has its own:

* **Consent configuration:** the rules, appearance, and content of your banner.
* **Tracked scripts:** third-party scripts ConsentStack detects and manages.
* **Consent logs:** a record of every consent decision visitors make.

To create a site, click **Create Site** from your workspace dashboard and give it a name. You will land on the site's settings page where you can copy your script tag.

Domains [#domains]

Domains tell ConsentStack which websites are authorized to show your consent banner. The SDK checks the domain on every page load, so only registered domains will work.

You manage domains from the **Domains** page inside each site. Add a domain by entering it (for example, `example.com` or `app.example.com`), and ConsentStack will verify it once the script is detected on that domain.

Each plan includes a set number of domains. If you need more, you can purchase additional domain slots from the billing page.

<Callout type="info">
  Subdomains count as separate domains. Registering `example.com` automatically covers `www.example.com`, but other subdomains (like `blog.example.com` or `app.example.com`) need their own entries.
</Callout>

Policies [#policies]

The **Policies** page inside each site generates your Privacy Policy, Cookie Policy, Terms of Service, Disclaimer and Accessibility Statement from a short business profile, your answers, and the services ConsentStack has detected on your site. ConsentStack hosts every published version, gives you an embed code for your own pages, keeps your banner's policy links pointing at them, and updates the Privacy Policy and Cookie Policy as your tools change. See the [Policy Generator](/docs/dashboard/policy-generator) guide for the full walkthrough.

If you already have a privacy policy of your own, you don't need the Policies page. Link your page from the banner text in the [Config Builder](/docs/dashboard/config-builder) like any other link.

Settings [#settings]

Both workspaces and sites have their own settings pages.

**Workspace settings** let you update your workspace's name, icon, and accent color. These show up in the sidebar and workspace switcher, which is helpful when you belong to multiple workspaces.

**Site settings** let you update the site name, copy your script tag, and manage the site's status (active or paused).

Both settings pages include a **danger zone** at the bottom for irreversible actions like deleting a workspace or site. Only the workspace owner can delete a workspace. Deleting removes all associated sites, configurations, and consent logs permanently.

What's next [#whats-next]

Now that you know your way around the dashboard, dive into the tools you will use most:

* [Config Builder](/docs/dashboard/config-builder). Customize your consent banner's appearance, content, and compliance rules.
* [Policy Generator](/docs/dashboard/policy-generator). Generate, embed, and link your Privacy Policy, Cookie Policy, Terms of Service, Disclaimer and Accessibility Statement.
* [Activity & Insights](/docs/dashboard/activity-and-insights). View consent logs and analytics for your sites.


# Policy Generator (/docs/dashboard/policy-generator)



import { Step, Steps } from "fumadocs-ui/components/steps"
import { Callout } from "@/components/fumadocs/callout"

The Policy Generator writes five documents for your site: a Privacy Policy, a Cookie Policy, Terms of Service, a Disclaimer and an Accessibility Statement. All five start from a short business profile you fill in once. The Privacy Policy and Cookie Policy also start from the services ConsentStack has detected on your site, so they name your real analytics, advertising and security tools instead of a list you have to remember and keep up to date yourself. The Terms of Service and Disclaimer come from your answers alone, and the Accessibility Statement from your answers plus any accessibility menu detected on your site.

ConsentStack hosts every version you publish, gives you an embed code for your own pages, keeps your banner's policy links pointing at them, and updates the Privacy Policy and Cookie Policy as your tools change. The Policy Generator is included on every plan, including Basic.

For an overview of what the generator does, see the [Policy Generator page](/privacy-policy-generator).

<Callout type="info">
  ConsentStack generates the text from your answers and what it detects on your site. It isn't legal advice, so review your documents with your counsel.
</Callout>

You can also set up and publish policies with an AI agent through the [ConsentStack MCP server](/docs/developers/mcp).

Where to find it [#where-to-find-it]

Open a site and choose **Policies** in the sidebar. The page has one card per document. Each card shows its status (**Not started**, **Draft**, **Published** or **Needs review**) and, once the document is on your website, the page it was last seen on.

Workspace Owners and Admins can write and publish documents. Members can see the cards and open a published document, but can't edit it.

Set up your business profile [#set-up-your-business-profile]

Every document draws on the same business profile, so you answer these questions once per site. Until the profile is complete, the document cards can't be started. Click **Set up profile** on the Policies page to fill it in.

| Section                       | What it asks                                                                                                                                                                                                                                     |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Your business**             | Your legal business name, business type, where the business was formed, the website addresses your documents cover, and where you store and handle personal information. The first website address is the one named at the top of each document. |
| **Privacy contact**           | Who handles privacy requests from your visitors. Canadian law asks you to name the person accountable for your privacy practices; if that is someone else, switch on the second contact. Otherwise the policy names your privacy contact.        |
| **Policy behavior**           | Who your website is for (a general audience, or children), how you'll tell visitors when a document changes, and whether your site stops tracking when a browser sends a Do Not Track signal.                                                    |
| **United States**             | The states where you do business and whose residents' information you collect, plus your revenue, how many consumers' information you handle each year, whether you sell personal information, and whether you qualify as a small business.      |
| **Outside the United States** | Whether you serve or collect information from people in the EU or EEA, the United Kingdom, Canada (and Quebec), or Australia.                                                                                                                    |

ConsentStack uses the last two sections to work out which privacy laws apply to you. That decides which rights your Privacy Policy lists, which residents each right applies to, and how quickly you promise to respond to a request.

To change your answers later, use the **Business profile** button at the top of the Policies page. Each document uses the new profile from the next time it publishes, so publish your documents again to put a change live.

Write a document [#write-a-document]

<Steps>
  <Step>
    Open the editor [#open-the-editor]

    Click **Start** on a document's card. The questions are on the left, split into sections, and a live preview of the finished document is on the right.
  </Step>

  <Step>
    Answer each section [#answer-each-section]

    Some answers are already filled in for you, as described below for each document. The preview updates as you answer. If a required answer is missing, the preview names the question and gives you a button that takes you to it.
  </Step>

  <Step>
    Publish [#publish]

    Your changes save automatically as a draft, and nothing changes on your website until you click **Publish**. Use **Discard** to throw away a draft and go back to the published version.

    Answers you've changed since you last published have blue labels, and the preview marks the text they change with a blue bar. Click a blue label to put that answer back the way it was. To step through your edits, use the undo and redo buttons above the preview, or ⌘Z and ⇧⌘Z.

    To take a published document off your website, open the status menu next to the document's name and choose **Unpublish**. The hosted page and every embed stop showing it, and your banner stops linking to it. Your answers stay as a draft, so you can publish again at any time.
  </Step>
</Steps>

<Callout type="info">
  Your documents link to each other: the Privacy Policy links to your Cookie Policy, and the Cookie Policy and Terms of Service link to your Privacy Policy. A link is filled in when the document that carries it publishes, so start with the Privacy Policy. If you publish a document before the one it links to, the link is added on its own within the hour after the other document publishes. Links also follow your pages: once ConsentStack sees a document embedded on your own site, the documents that link to it point there.
</Callout>

Customize [#customize]

The last section of every document, **Customize**, goes beyond our questions:

* **Add a section** in your own words, such as a payment plan or membership policy. A new section starts just before the section about changes to the document, or at the end of the Accessibility Statement, which has none. The **×** on a section's card removes it.
* **Replace a section** to reword any of ours. Its box starts with our wording, so you can edit it instead of starting from nothing. Where a section lists your services or reflects your banner settings, that part stays under your text and keeps updating. While you use your own wording for a section, it stays as you wrote it. Our updates to its wording, and changes to your answers or business profile, don't reach it. The **×** on its card puts our wording back.
* **Change the order** of sections in **Section order**: drag a section, or use its move up and move down buttons. The first section always stays first. **Use our order** puts ours back.

You write your sections in a text editor with bold, italic, bulleted and numbered lists, and links (the same editor as the other text boxes in your policies). Select text and use the link button to link a web page, an email address, a phone number or one of your other policies.

The five documents [#the-five-documents]

Privacy Policy [#privacy-policy]

Explains what personal information you collect, where it comes from and why, who you share it with, and the rights your visitors have under the laws that apply to you. Its questions come in these sections:

| Section                | What it covers                                                                                                                                                                         |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **What you collect**   | The personal information you collect, where it comes from and why you use it, plus whether you combine it, use it for targeted advertising or profiling, or use it to train AI models. |
| **Who you share with** | Whether you share personal information with third parties, what you share with each kind of provider, and whether you sell it.                                                         |
| **Your practices**     | Whether your site sets cookies, how you protect personal information, how long you keep it, and whether you use it for direct marketing.                                               |
| **Text messaging**     | Your SMS program, if you have one: the number messages come from, how often you send them, and how to opt out.                                                                         |
| **Exercising rights**  | What you need from a visitor to verify a request, and what an authorized agent must provide on their behalf.                                                                           |
| **Named services**     | The analytics, advertising and security services the policy names one by one.                                                                                                          |

ConsentStack also adds:

* **Your rights**: each right, the residents it applies to and your response window, from the laws your business profile says apply.
* **Global Privacy Control**: if your banner honors [Global Privacy Control](/docs/compliance/global-privacy-control), the policy says so.
* **Last updated**: the date the policy was published.

Cookie Policy [#cookie-policy]

Lists the services on your site, grouped by your banner's consent categories, with what each one does, who provides it, which cookies it sets and for how long, and how to opt out. It also explains how visitors can change their choices, through your banner's preferences, their browser settings and, if your banner honors it, Global Privacy Control.

Its main section, **Services and cookies**, is the list of services (see [Detected services](#detected-services)). The only other question is an optional introduction of your own.

Terms of Service [#terms-of-service]

Sets the rules for using your website: what visitors may not do, who owns your content, the limits of your liability and the law that governs disputes. It doesn't read your detected services, so it comes from your answers alone.

| Section                   | What it covers                                                                                                                                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Offers**                | Whether you sell through your website, what you offer, and anything to note about pricing.                                                                                                                                                  |
| **Purchases**             | Whether visitors buy directly on your website, the payment methods you accept, and your cancellation, refund, advance payment and deposit terms.                                                                                            |
| **Accounts**              | Whether visitors can create an account, and the minimum age.                                                                                                                                                                                |
| **Conduct**               | Anything else visitors may not do. A standard list of prohibited uses is always included. You can also prohibit copying your content to train AI models.                                                                                    |
| **Text messaging**        | Your SMS program, the number messages come from and how often you send them.                                                                                                                                                                |
| **Intellectual property** | Who owns your website's content (your legal business name unless you enter another), and who receives copyright (DMCA) notices. That is your privacy contact unless you switch on a separate contact.                                       |
| **Disputes**              | The law that governs the Terms, filled in from where your business was formed; where disputes are brought; whether you require binding arbitration and individual claims instead of class actions; and an optional minimum liability limit. |

The Terms limit your liability to what the customer paid you in the 12 months before a claim, or to the minimum liability limit you enter in **Disputes** if that is greater. Offers, purchases, accounts and text messaging appear in the Terms only when you say they apply.

The text boxes for your offers, pricing, cancellation, refund, advance payment and deposit terms use the same text editor as Customize, with bold, italic, lists and links, so you can link another page such as your shop terms.

Disclaimer [#disclaimer]

Tells visitors the limits of what your website promises, for example that its content isn't professional advice or that you may earn from affiliate links. It doesn't read your detected services: you pick the disclaimers that apply.

The choices are advertising, affiliate links, sponsored content, professional advice, medical advice, legal advice, financial advice, fitness advice, testimonials and reviews, earnings and results, links to other websites, errors and omissions, use of copyrighted material (fair use), views of guest authors or contributors, and AI-assisted content. Errors and omissions and links to other websites are selected to start. Picking affiliate links lets you list the programs you belong to and say that you mark affiliate links, picking professional advice asks which field, and picking AI-assisted content lets you say that a person reviews it before you publish. You can also add a sentence or two of your own.

Accessibility Statement [#accessibility-statement]

Tells visitors that you want your website to be usable by people with disabilities, which standard you aim to meet, and how to contact you if something is hard to use. It never claims more than you tell it.

| Section                   | What it covers                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Introduction and goal** | The Web Content Accessibility Guidelines (WCAG) version and level you aim for, WCAG 2.2 at level AA to start, plus an optional sentence of your own. Switch on **State how well the site conforms today** only if an assessment backs it up: you then choose partially or fully conforms and say how the site was assessed, and you can't publish until you do. |
| **What we do**            | Steps you take, such as testing with screen readers. Nothing is checked to start, so check only what you actually do.                                                                                                                                                                                                                                           |
| **Accessibility tools**   | Any accessibility menu on your site, such as UserWay or accessiBe. ConsentStack fills this in from what it detected when you first open the statement. The statement describes a menu as an optional extra for visitors, never as what makes your site accessible.                                                                                              |
| **Known limitations**     | Parts of your site that aren't fully accessible yet. The statement offers to provide that content another way.                                                                                                                                                                                                                                                  |
| **Feedback**              | Who visitors contact: your business name with your privacy contact's email and phone, unless you switch on a separate accessibility contact. You can add how many business days you aim to reply within.                                                                                                                                                        |

With only your business profile filled in, the statement gives your goal and how to contact you, and you can publish it as it is.

Detected services [#detected-services]

The Privacy Policy and Cookie Policy are built from the services ConsentStack has detected on your site, the same list as your **Trackers** page. A tracker you ignore or block there stays out of your documents, and a tracker you move to another category there appears under that category.

Until the banner is installed and has seen visitors, your most recent [compliance scan](/docs/compliance/compliance-scanner) of one of the site's domains fills the list instead.

What's filled in for you [#whats-filled-in-for-you]

The first time you open the Privacy Policy editor, ConsentStack fills in what it already knows from your detected services:

* **What you collect** comes pre-checked with the information your detected services gather through cookies, such as IP address, device identifiers and how visitors interact with your website.
* **Who you share with** comes pre-filled with the kinds of providers you use, such as analytics providers and advertising networks.

Each pre-checked item names the services it came from (for example, *Detected: Google Analytics 4, Meta Pixel*).

This happens on the first open only. After that, your answers stay as you left them: automatic updates never change them, and applying a reviewed change about a new service only adds what that service collects and shares.

Named services [#named-services]

The Privacy Policy names each detected analytics, advertising and security service in a table with these columns: **Service**, **Provider**, **Purpose**, **Privacy policy** (a link to the provider's policy) and **Opt out** (a link to its opt-out page, where the provider offers one). Other kinds of service, such as a payment processor, aren't named one by one in the Privacy Policy. The Cookie Policy lists every service.

Edit the list [#edit-the-list]

The Privacy Policy's **Named services** section and the Cookie Policy's **Services and cookies** section list the services, grouped by your banner's consent categories. Each one is marked **Detected**, **From scan** or **Added by you**. Changes you make in one document's list don't affect the other. In each list you can:

* Switch a detected service off to leave it out of that document.
* Open a service's details to give it a different name in that document.
* Add a service ConsentStack can't detect by searching for it under **Add a service you use**.

The Privacy Policy's list holds only analytics, advertising and security services, so add other tools, like a payment processor, in the Cookie Policy.

<Callout type="warning">
  Detection only sees services that run in your visitors' browsers. Payment processors, email marketing platforms, CRMs and other tools you use behind the scenes won't be pre-filled. Add them to the Cookie Policy yourself, and add what they collect and who you share it with in the Privacy Policy's **What you collect** and **Who you share with** sections.
</Callout>

Add the policy to your website [#add-the-policy-to-your-website]

Open the menu on a document's card and choose **Get embed code**. Paste the snippet where the document should appear on your website. For the Privacy Policy it looks like this:

```html
<link rel="preconnect" href="https://policies.consentstack.io" crossorigin>
<style>[data-cs-policy]:not([data-cs-policy-state="filled"],[data-cs-policy-state="error"]){min-height:100vh}</style>
<div data-cs-policy="privacy-policy" data-cs-key="<YOUR_SITE_KEY>">
  <noscript><a href="https://policies.consentstack.io/<YOUR_SITE_KEY>/privacy-policy">Read our privacy policy</a></noscript>
</div>
<p class="cs-policy-attribution">Policy generated and kept current by <a href="https://www.consentstack.io/privacy-policy-generator">ConsentStack</a></p>
<script src="https://cdn.consentstack.io/policy.js" async></script>
```

Each document has its own snippet, so copy it from that document's card rather than from this page. The dashboard's copy already has your site key filled in.

| Platform      | Where to paste it                   |
| ------------- | ----------------------------------- |
| Squarespace   | A Code block on the document's page |
| WordPress     | A Custom HTML block                 |
| Webflow       | An Embed element                    |
| Anything else | Any place that accepts raw HTML     |

The embed works whether or not the ConsentStack banner is installed on that page. You only paste it once: every time the document publishes, the embed shows the new version, with no need to paste again.

Once the page loads on one of your site's domains, the card shows where the document is live, for example *Live on example.com/privacy, seen 2h ago*. Visitors with JavaScript turned off see a link to the hosted copy instead.

Choose a layout [#choose-a-layout]

The embed sheet has a **Layout** setting for each document:

* **Accordion** folds each detailed entry, such as a kind of information in the Privacy Policy or a service in the Cookie Policy, into a row visitors can expand.
* **Flat** shows every entry open, one after another.

Changing the layout updates every embed and the hosted page within a few minutes. The Terms of Service, Disclaimer and Accessibility Statement have no expandable rows, so they look the same either way.

Use the hosted page [#use-the-hosted-page]

Every published document is also hosted at its own address:

```
https://policies.consentstack.io/<YOUR_SITE_KEY>/privacy-policy
```

The other documents end in `cookie-policy`, `terms-of-service`, `disclaimer` and `accessibility-statement`. The embed sheet shows each link, and **View** on a published card opens it. Use it if you don't have a page to paste the embed into. The hosted copy asks search engines not to index it, so it never competes with the page on your own site.

Attribution [#attribution]

On the Basic plan, the embed code ends with a line crediting ConsentStack, and the hosted page shows the same line. While branding is on, the document carries the credit at its end even if you delete the line from your page.

On paid plans you can remove it with the **Remove branding** feature. In the Config Builder's **Settings** tab, turn off **Show ConsentStack branding** and publish. This removes the credit from your banner and all your documents together. If you pasted the embed code before turning branding off, delete the attribution paragraph from your page, or paste a fresh copy of the embed code.

Link the policy from your banner [#link-the-policy-from-your-banner]

Your banner should link to your Privacy Policy and Cookie Policy. You only need to add each link once:

<Steps>
  <Step>
    Open the banner text [#open-the-banner-text]

    In the [Config Builder](/docs/dashboard/config-builder), open the **Content** tab and click into the banner description where the link should go.
  </Step>

  <Step>
    Insert the policy link [#insert-the-policy-link]

    Click the link icon in the text toolbar, then the document icon in the link bar that opens, and choose the document. The menu lists the documents you've published. If no text is selected, the document's name becomes the link text.
  </Step>

  <Step>
    Publish your banner [#publish-your-banner]

    Publish the Config Builder as usual so the new text goes live.
  </Step>
</Steps>

From then on, the link follows your document. It points to the page where your embed is live, or to the hosted page until the embed has been seen on your site. Until your banner links to each published Privacy Policy and Cookie Policy, the Policies page reminds you and opens Content for you.

If you keep your own privacy policy instead of generating one, you don't need the Policies page at all. Click the link icon in the text toolbar and type your page's address into the link bar, like any other link.

Versions [#versions]

Every publish, yours or an automatic update, creates a new version, and every version stays available at its own address. Choose **Versions** in the card menu to see each one with its publish date and why it was published (*First version*, *Edited answers*, *Automatic update* or *Reviewed update*), and open any of them. The hosted address followed by `/versions` lists them all.

An older version opens with a notice giving the date it was published and the date it was replaced, so you can show exactly what your document said at any point.

Keeping your policies current [#keeping-your-policies-current]

ConsentStack checks your published Privacy Policy and Cookie Policy against your detected services once an hour. Facts update on their own. Anything that changes what a policy promises waits for you.

What updates on its own [#what-updates-on-its-own]

Each of these publishes as a new version marked *Automatic update*:

* A new tool in a category the policy already covers, such as a second analytics tool.
* Removing a tool that has been gone from your site for 48 hours. A tool that disappears for a day and comes back stays.
* Updated provider details and cookie durations, and cookies a tool starts or stops setting.
* Changes to your banner's consent categories (adding or removing one, or changing their names, descriptions or order) or its Global Privacy Control setting, once you publish them in the Config Builder.
* A link to another of your policies, when that policy is first published, moves to a page on your own site, or is unpublished.
* Template updates from ConsentStack that need nothing new from you. These reach every document.

Automatic updates never change your answers.

What waits for your review [#what-waits-for-your-review]

These change what a policy promises, so nothing goes live until you act:

* The first tool in a category the policy didn't cover before, such as your first advertising tool.
* A tool that ConsentStack's catalog lists as selling or sharing personal information (for example, for targeted advertising).
* A template update that needs a new answer from you.
* Live detections replacing the compliance scan the policy was first written from.
* A business profile that is missing or incomplete.

While a change waits, that policy's other automatic updates wait too.

Waiting changes appear in a **Needs review** list at the top of the Policies page, and the **Policies** item in the sidebar shows how many there are. Click **Open** to go to the document's editor, where each change is explained at the top:

* **Apply** publishes the change. For a template update, answer the new question right there first.
* **Leave out of policy** appears for a tool the policy doesn't name yet. It publishes a new version, marked *Reviewed update*, that leaves the tool out, and keeps it out so the same change doesn't come back.

Policy emails [#policy-emails]

Every Monday, ConsentStack emails your workspace's Owners and Admins a summary of its policies: the automatic updates published in the past week, and every change still waiting for review, with a button to review each site's changes. The weekly email only goes out when something new happened that week.

A change that needs your review doesn't wait for Monday. When one comes up, you get an email the next morning listing every change waiting for review.

Terms of Service, Disclaimer and Accessibility Statement [#terms-of-service-disclaimer-and-accessibility-statement]

The Terms of Service, Disclaimer and Accessibility Statement don't depend on your detected services. They change only when you publish new answers, when a template update reaches them, or, for the Terms of Service, when the link to your Privacy Policy changes. The Accessibility Statement looks at your detected services once, to fill in any accessibility menu when you first open it.

Copy answers from another site [#copy-answers-from-another-site]

Each site has its own business profile and its own documents, since different websites often collect different information and use different services. To start a site from another site's answers, open the site's **Settings** and click **Copy from another site** on the **Copy policy answers** card. Workspace Owners and Admins can copy between sites in the same workspace.

It replaces this site's business profile and each document's draft answers with the other site's. It doesn't copy published versions, so this site's live documents keep their text until they next publish.

Check the business profile straight after copying, especially the website addresses, which still belong to the other site. Every publish reads the profile, including automatic updates, so the copied profile reaches this site's live documents at the next one.


# Content Security Policy (/docs/developers/content-security-policy)



import { Callout } from '@/components/fumadocs/callout';

If your site sends a `Content-Security-Policy` header, you need to allowlist the ConsentStack endpoints. Without it, the browser blocks the SDK's network requests and the banner can't load its config, log consent, or render its logo. The script tag itself usually succeeds, which makes this a quiet failure: the SDK appears installed, but nothing actually works.

This page lists the directives the SDK touches, the minimum allowlist for each, and the most common console errors so you can match a symptom to a fix.

What the SDK calls [#what-the-sdk-calls]

Once the core script runs it makes three HTTPS requests:

| Request | Endpoint                                               | Purpose                                 |
| ------- | ------------------------------------------------------ | --------------------------------------- |
| `GET`   | `https://config.consentstack.io`                       | KV-cached config (primary fast path)    |
| `GET`   | `https://origins.consentstack.io/functions/v1/config`  | Origin config (fallback when KV misses) |
| `POST`  | `https://origins.consentstack.io/functions/v1/consent` | Consent and impression logging          |

It also fetches the "Powered by" logo from `https://cdn.consentstack.io/assets/` and injects a `<style>` tag with the banner's CSS.

Minimum directives [#minimum-directives]

If your CSP defines any of the following directives, add the listed origins.

connect-src [#connect-src]

Required. The SDK can't function without these.

```
connect-src 'self' https://config.consentstack.io https://origins.consentstack.io;
```

script-src [#script-src]

Required so the two install tags can execute.

```
script-src 'self' https://cdn.consentstack.io;
```

img-src [#img-src]

Required so the banner's "Powered by" logo renders (free plan only). If you're on a paid plan and have removed branding, this is optional.

```
img-src 'self' https://cdn.consentstack.io;
```

style-src [#style-src]

The banner CSS is injected as a single `<style>` tag at init. Dynamically inserted `<style>` elements count as inline styles under CSP, so you currently need `'unsafe-inline'`:

```
style-src 'self' 'unsafe-inline';
```

<Callout type="info">
  Nonce-based `style-src` is not yet supported. If your security review requires removing `'unsafe-inline'` from `style-src`, get in touch and we'll prioritise nonce propagation.
</Callout>

Full example [#full-example]

A complete, copy-paste-ready policy for a site whose own assets sit on the same origin:

```
Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://cdn.consentstack.io;
  connect-src 'self' https://config.consentstack.io https://origins.consentstack.io;
  img-src 'self' data: https://cdn.consentstack.io;
  style-src 'self' 'unsafe-inline';
  font-src 'self';
  frame-ancestors 'none';
  base-uri 'self';
  form-action 'self';
```

Merge each `*-src` line with whatever your site already needs (analytics, fonts, embeds, etc.). The directives above only show the ConsentStack-specific entries.

<Callout type="warn">
  If you set CSP via a `<meta http-equiv="Content-Security-Policy">` tag instead of an HTTP header, place it before the ConsentStack script tags. Meta-tag CSP only applies to elements parsed after it.
</Callout>

Verifying [#verifying]

Open DevTools, reload the page, and look at the Console and Network tabs.

* **Console clean, Network shows `200` for** `config.consentstack.io` **and** `origins.consentstack.io`: allowlist is correct.
* **Console shows `Refused to connect because it violates the document's Content Security Policy`**: `connect-src` is missing one of our origins.
* **Console shows `Refused to load the script`**: `script-src` is missing `cdn.consentstack.io`.
* **Console shows `Refused to apply inline style`**: `style-src` is missing `'unsafe-inline'`.

You can also enable `data-debug="true"` on the core script tag to see exactly which fetches the SDK is attempting. See [SDK Installation](/docs/developers/sdk-installation#data-attributes).

Common errors, decoded [#common-errors-decoded]

```
Refused to connect to 'https://config.consentstack.io/...' because it
violates the document's Content Security Policy directive:
"connect-src 'self' ..."
```

Add `https://config.consentstack.io` and `https://origins.consentstack.io` to `connect-src`. Both are needed: the first is the fast path, the second is the fallback the SDK retries on if KV misses or returns a non-2xx.

```
Refused to load the script 'https://cdn.consentstack.io/consent.js?...'
because it violates the document's Content Security Policy directive:
"script-src 'self' ..."
```

Add `https://cdn.consentstack.io` to `script-src`. The CDN is where both the stub and core bundles are served from.

```
Refused to apply inline style because it violates the document's
Content Security Policy directive: "style-src 'self' ..."
```

Add `'unsafe-inline'` to `style-src`, or scope it to a `style-src-elem` directive that allows inline. Without this, the banner renders unstyled.

CDN preconnect [#cdn-preconnect]

The recommended `<link rel="preconnect" href="https://cdn.consentstack.io" />` tag is not affected by CSP `connect-src`; preconnect hints are governed by the network layer, not CSP. You don't need any extra directive for it to work.


# Framework Guides (/docs/developers/framework-guides)



import { Callout } from '@/components/fumadocs/callout';

Framework-specific guides for integrating ConsentStack. Each section shows the recommended approach for your stack. Pick the one that matches and you'll be up and running in minutes.

For the full React SDK reference (hooks, props, headless mode), see the [React SDK docs](/docs/developers/react-sdk). For the vanilla JavaScript API, see the [JavaScript API reference](/docs/developers/javascript-api).

Next.js (App Router) [#nextjs-app-router]

Install the React SDK and wrap your root layout with `ConsentStackProvider`. This gives every page access to consent state via hooks.

```bash
npm install @consentstack/react
```

```tsx title="app/layout.tsx"
import { ConsentStackProvider } from '@consentstack/react'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <link rel="preconnect" href="https://cdn.consentstack.io" />
      </head>
      <body>
        <ConsentStackProvider siteKey="<YOUR_SITE_KEY>">
          {children}
        </ConsentStackProvider>
      </body>
    </html>
  )
}
```

For best performance, also add `<link rel="preconnect" href="https://cdn.consentstack.io" />` to the document `<head>` (shown above) so the TLS connection is warm when the React provider injects the script tags.

Use the `useConsent` hook in any client component to check consent state or conditionally load scripts:

```tsx title="components/analytics.tsx"
'use client'

import { useConsentValue } from '@consentstack/react'
import Script from 'next/script'

export function Analytics() {
  const hasAnalytics = useConsentValue('analytics')
  if (!hasAnalytics) return null

  return <Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" strategy="afterInteractive" />
}
```

Loading third-party trackers in your layout [#loading-third-party-trackers-in-your-layout]

<Callout type="warn">
  **Do not drop `<Script src="...">` or `<GoogleTagManager />` into your root layout for trackers without gating them.** Next.js renders an SSR'd `<link rel="preload" as="script">` for every `<Script>` and for `@next/third-parties` components. The browser's preload scanner fetches those URLs before any JavaScript runs, so the request reaches the third party (and sets cookies on its domain) before ConsentStack can intercept it. The script execution itself is still blocked, but the preload fetch leaks.
</Callout>

The simplest fix that works on every page without component-by-component gating is to inline the tracker's bootstrap snippet with `dangerouslySetInnerHTML`. The standard JS bootstrap pattern (used by Google Tag Manager, HubSpot, and most major trackers) creates a `<script>` element at runtime via `document.createElement('script')` and assigns `.src`. That assignment goes through the SDK's interceptor and is gated by consent. Because the inline `<script>` itself has no `src` attribute, Next.js never emits a preload for it.

```tsx title="app/layout.tsx"
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <link rel="preconnect" href="https://cdn.consentstack.io" />
        <script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>" />
        <script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>" />
      </head>
      <body>
        {children}

        {/* GTM bootstrap (the standard Google snippet) */}
        <script
          dangerouslySetInnerHTML={{
            __html: `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s);j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i;f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer','GTM-XXXXXXX');`,
          }}
        />

        {/* HubSpot bootstrap */}
        <script
          dangerouslySetInnerHTML={{
            __html: `(function(){var s=document.createElement('script');s.async=true;s.id='hs-script-loader';s.src='//js-na1.hs-scripts.com/<HUB_ID>.js';document.head.appendChild(s);})();`,
          }}
        />
      </body>
    </html>
  )
}
```

Place these inline scripts **after** the ConsentStack tags so the SDK's interceptor is installed before the bootstrap runs. When consent is denied, the SDK rewrites the dynamically-created `<script>` element's `src` to `about:blank` and tags it as blocked. When consent later grants, the SDK replays the blocked element and the tracker loads. No third-party request fires before consent.

If you prefer to use `<Script>` from `next/script`, gate it on `useConsentValue` as shown above. The component returning `null` on the server prevents Next.js from emitting the preload during SSR, and the `<Script>` only appears in the DOM after consent grants on the client.

Next.js (Pages Router) [#nextjs-pages-router]

Wrap your app in `_app.tsx`. The provider works the same way, it just lives in a different file.

```tsx title="pages/_app.tsx"
import type { AppProps } from 'next/app'
import { ConsentStackProvider } from '@consentstack/react'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <ConsentStackProvider siteKey="<YOUR_SITE_KEY>">
      <Component {...pageProps} />
    </ConsentStackProvider>
  )
}
```

If you don't need hooks, you can use the simpler `ConsentStack` component in `_document.tsx` instead:

```tsx title="pages/_document.tsx"
import { Html, Head, Main, NextScript } from 'next/document'
import { ConsentStack } from '@consentstack/react'

export default function Document() {
  return (
    <Html>
      <Head>
        <link rel="preconnect" href="https://cdn.consentstack.io" />
      </Head>
      <body>
        <Main />
        <NextScript />
        <ConsentStack siteKey="<YOUR_SITE_KEY>" />
      </body>
    </Html>
  )
}
```

For best performance, add `<link rel="preconnect" href="https://cdn.consentstack.io" />` to the document `<head>` (shown above) so the TLS connection is warm when the React component injects the script tags.

React (Vite / CRA) [#react-vite--cra]

Same React SDK, different entry point. Wrap your app at the root.

```bash
npm install @consentstack/react
```

```tsx title="src/main.tsx"
import React from 'react'
import ReactDOM from 'react-dom/client'
import { ConsentStackProvider } from '@consentstack/react'
import App from './App'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ConsentStackProvider siteKey="<YOUR_SITE_KEY>">
      <App />
    </ConsentStackProvider>
  </React.StrictMode>
)
```

For best performance, also add `<link rel="preconnect" href="https://cdn.consentstack.io" />` to your `index.html` `<head>` so the TLS connection is warm when the React provider injects the script tags.

All hooks (`useConsent`, `useConsentValue`) work exactly as documented in the [React SDK reference](/docs/developers/react-sdk).

Vue & Nuxt [#vue--nuxt]

Vue apps use the script tags directly. Add them via `useHead` in your root layout or app component.

Nuxt 3 [#nuxt-3]

Add the preconnect link and script tags globally in `nuxt.config.ts`:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
  app: {
    head: {
      link: [
        {
          rel: 'preconnect',
          href: 'https://cdn.consentstack.io',
        },
      ],
      script: [
        {
          src: 'https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>',
          tagPosition: 'head',
        },
        {
          src: 'https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>',
          tagPosition: 'head',
        },
      ],
    },
  },
})
```

Vue 3 (Vite) [#vue-3-vite]

Add the preconnect link and script tags to your `index.html`:

```html title="index.html"
<head>
  <link rel="preconnect" href="https://cdn.consentstack.io" />
  <script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
  <script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"></script>
</head>
```

Vue composable [#vue-composable]

Access consent state reactively by wrapping `window.consentstack` in a composable:

```ts title="composables/useConsent.ts"
import { ref, onMounted, onUnmounted } from 'vue'

export function useConsent() {
  const consent = ref<Record<string, boolean> | null>(null)
  let unsubscribe: (() => void) | undefined

  onMounted(() => {
    const sdk = window.consentstack
    if (!sdk) return

    consent.value = sdk.getConsent()
    unsubscribe = sdk.onConsentChange((updated) => {
      consent.value = updated
    })
  })

  onUnmounted(() => {
    unsubscribe?.()
  })

  const hasConsent = (category: string): boolean => {
    return consent.value?.[category] ?? false
  }

  return { consent, hasConsent }
}
```

```vue title="components/Analytics.vue"
<script setup lang="ts">
import { useConsent } from '@/composables/useConsent'

const { hasConsent } = useConsent()
</script>

<template>
  <div v-if="hasConsent('analytics')">
    <!-- Analytics scripts load here -->
  </div>
</template>
```

Vanilla JS & Static Sites [#vanilla-js--static-sites]

The simplest integration. Add the preconnect link and script tags to your HTML `<head>` and ConsentStack handles everything automatically, no framework, no build step.

```html
<head>
  <link rel="preconnect" href="https://cdn.consentstack.io" />
  <script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
  <script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"></script>
</head>
```

To let visitors re-open their preferences (e.g., from a "Cookie Settings" link in your footer), add an anchor that points to `#cs-preferences`:

```html
<footer>
  <a href="#cs-preferences">Cookie Settings</a>
</footer>
```

For programmatic access, use the global `window.consentstack` API:

```js
// Check consent before running a script
if (window.consentstack?.hasConsent('marketing')) {
  loadFacebookPixel()
}

// Listen for consent changes
window.consentstack?.onConsentChange((consent) => {
  console.log('Consent updated:', consent)
})
```

See the [JavaScript API reference](/docs/developers/javascript-api) for the full API surface.

WordPress [#wordpress]

Add the preconnect link and script tags to your site's `<head>` using the theme customizer or a header/footer plugin.

**Theme Customizer:** Go to Appearance > Customize > Additional Scripts (if your theme supports it) and paste:

```html
<link rel="preconnect" href="https://cdn.consentstack.io" />
<script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
<script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"></script>
```

**Header/footer plugin:** Install a plugin like [WPCode](https://wordpress.org/plugins/insert-headers-and-footers/) or Insert Headers and Footers. Add all three tags above to the header section.

**functions.php:** If you prefer code, add this to your theme's `functions.php`:

```php title="functions.php"
function consentstack_preconnect() {
  echo '<link rel="preconnect" href="https://cdn.consentstack.io" />';
}
add_action('wp_head', 'consentstack_preconnect', 0);

function consentstack_enqueue_script() {
  wp_enqueue_script(
    'consentstack-stub',
    'https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>',
    array(),
    null,
    false
  );
  wp_enqueue_script(
    'consentstack-core',
    'https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>',
    array('consentstack-stub'),
    null,
    false
  );
}
add_action('wp_enqueue_scripts', 'consentstack_enqueue_script');
```

<Callout type="info">
  Replace `<YOUR_SITE_KEY>` with your actual site key from the [ConsentStack dashboard](https://app.consentstack.io). You'll find it under Site Settings after creating your site.
</Callout>

What's next [#whats-next]

* [React SDK reference](/docs/developers/react-sdk): full hook and component documentation
* [JavaScript API](/docs/developers/javascript-api): the `window.consentstack` API for any framework
* [SDK installation](/docs/developers/sdk-installation): advanced options like self-hosting and debug mode


# Headless Mode (/docs/developers/headless-mode)



import { Callout } from '@/components/fumadocs/callout';

Headless mode gives you ConsentStack's full consent engine (config fetching, script blocking, consent storage, platform signaling, and compliance logging) without rendering any UI. You build the consent experience yourself.

When to use headless mode [#when-to-use-headless-mode]

Headless mode is the right choice when you need:

* **A fully custom-branded consent experience** that matches your app's design system
* **Consent in a mobile app webview** where native controls replace a web banner
* **Server-rendered consent flows** where you control the HTML and hydration
* **Embedded consent in existing UI** like a settings page or onboarding wizard

If the default banner works for you, stick with the standard mode. You get the same compliance engine either way.

How to enable it [#how-to-enable-it]

Add `data-mode="headless"` to the core script tag:

```html
<link rel="preconnect" href="https://cdn.consentstack.io" />
<script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
<script
  src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"
  data-mode="headless"
></script>
```

That's it. The SDK initializes normally: fetches your config, loads existing consent from storage, starts blocking scripts, but skips all banner, preferences panel, and re-entry button rendering.

What still works [#what-still-works]

Everything except the visual UI:

| Feature                                | Standard mode | Headless mode |
| -------------------------------------- | ------------- | ------------- |
| Config fetching & caching              | Yes           | Yes           |
| Geo-detection & region resolution      | Yes           | Yes           |
| Script blocking                        | Yes           | Yes           |
| Platform adapters (Google, Meta, etc.) | Yes           | Yes           |
| Consent storage                        | Yes           | Yes           |
| Consent logging to server              | Yes           | Yes           |
| Offline queue                          | Yes           | Yes           |
| Banner & preferences UI                | Yes           | **No**        |
| Re-entry button                        | Yes           | **No**        |

The full [JavaScript API](/docs/developers/javascript-api) is available on `window.consentstack`, so you can read state, set consent, and listen for events, exactly as you would in standard mode.

Building a custom UI [#building-a-custom-ui]

The workflow is straightforward: wait for the SDK to be ready, read the config to know which categories to display, render your UI, and call `setConsent()` when the visitor makes a choice.

Step 1: Listen for the "ready" event [#step-1-listen-for-the-ready-event]

The SDK emits a `ready` event once it has fetched the config and loaded any existing consent from storage:

```js
window.consentstack.on("ready", ({ config, consent }) => {
  // config: your consent configuration (categories, content, etc.)
  // consent: existing consent (null for first-time visitors)
  renderMyConsentUI(config, consent)
})
```

Step 2: Read categories from the config [#step-2-read-categories-from-the-config]

The config contains the consent categories you defined in the dashboard. Each category has an `id`, `name`, `description`, and `required` flag:

```js
const config = window.consentstack.getConfig()

for (const category of config.categories) {
  console.log(category.id)          // "analytics"
  console.log(category.name)        // "Analytics"
  console.log(category.description) // "Help us understand how visitors use our site"
  console.log(category.required)    // true for essential categories
}
```

Step 3: Render your UI [#step-3-render-your-ui]

Build whatever UI fits your product. A modal, a bottom sheet, an inline form, there are no constraints. Just display the categories and let the visitor toggle them.

Step 4: Save consent [#step-4-save-consent]

When the visitor makes a choice, pass a categories object to `setConsent()`. Each key is a category ID, each value is `true` (granted) or `false` (denied):

```js
await window.consentstack.setConsent({
  essential: true,
  analytics: true,
  marketing: false,
})
```

This single call does everything: saves consent to storage, logs it to the server, updates script blocking, and fires platform adapter signals (Google Consent Mode, Meta CAPI, etc.).

Full example [#full-example]

Here's a minimal custom banner using vanilla JavaScript:

```js
window.consentstack.on("ready", ({ config, consent }) => {
  // Returning visitor: consent already given
  if (consent) return

  const banner = document.createElement("div")
  banner.id = "my-consent-banner"
  banner.innerHTML = `
    <h3>${config.content.title}</h3>
    <p>${config.content.description}</p>
    <button id="my-accept">Accept all</button>
    <button id="my-reject">Reject all</button>
  `
  document.body.appendChild(banner)

  document.getElementById("my-accept").addEventListener("click", async () => {
    const categories = {}
    for (const cat of config.categories) categories[cat.id] = true
    await window.consentstack.setConsent(categories)
    banner.remove()
  })

  document.getElementById("my-reject").addEventListener("click", async () => {
    const categories = {}
    for (const cat of config.categories) {
      categories[cat.id] = cat.required // only essential stays true
    }
    await window.consentstack.setConsent(categories)
    banner.remove()
  })
})
```

React integration [#react-integration]

The `@consentstack/react` package supports headless mode natively. Set `mode="headless"` on the provider and use the `useConsent` hook to build your UI:

```tsx
import { ConsentStackProvider, useConsent } from "@consentstack/react"

function App() {
  return (
    <ConsentStackProvider siteKey="YOUR_SITE_KEY" mode="headless">
      <MyConsentBanner />
      <RestOfYourApp />
    </ConsentStackProvider>
  )
}

function MyConsentBanner() {
  const { consent, config, isReady, setConsent } = useConsent()

  // Not ready yet or consent already given
  if (!isReady || consent) return null

  const acceptAll = async () => {
    const categories: Record<string, boolean> = {}
    for (const cat of config!.categories) categories[cat.id] = true
    await setConsent(categories)
  }

  const rejectAll = async () => {
    const categories: Record<string, boolean> = {}
    for (const cat of config!.categories) {
      categories[cat.id] = cat.required
    }
    await setConsent(categories)
  }

  return (
    <div className="my-consent-banner">
      <h3>We value your privacy</h3>
      <div className="categories">
        {config!.categories.map((cat) => (
          <label key={cat.id}>
            <input
              type="checkbox"
              disabled={cat.required}
              defaultChecked={cat.required || cat.default}
            />
            {cat.name}
          </label>
        ))}
      </div>
      <button onClick={acceptAll}>Accept all</button>
      <button onClick={rejectAll}>Reject all</button>
    </div>
  )
}
```

The `useConsent` hook re-renders your component whenever consent state changes, so your UI stays in sync automatically.

<Callout type="info">
  You can also use `useConsentValue("analytics")` to check a single category. It only re-renders when that specific category changes.
</Callout>

Listening for changes [#listening-for-changes]

Whether you use vanilla JS or React, you can listen for consent changes anywhere in your app:

```js
const unsubscribe = window.consentstack.onConsentChange((consent) => {
  console.log("Consent updated:", consent)
})
```

This is useful for updating UI outside your consent banner, for example, showing a "preferences saved" confirmation or conditionally loading a component.

What's next [#whats-next]

* [JavaScript API](/docs/developers/javascript-api): full reference for `window.consentstack`
* [React SDK](/docs/developers/react-sdk): detailed guide for `@consentstack/react`
* [Platform Integrations](/docs/developers/platform-integrations): how consent flows to Google, Meta, and other platforms


# HubSpot Integration (/docs/developers/hubspot)



import { Callout } from '@/components/fumadocs/callout';

ConsentStack integrates with HubSpot in two layers. The ConsentStack app for HubSpot connects your portal to a site in your dashboard: it imports your website domains and keeps them in sync automatically. The SDK itself handles the consent behavior on your pages: it turns off HubSpot's built-in cookie banner, shows yours instead, and reports every consent decision to HubSpot's own consent API so HubSpot analytics, chat, and forms follow each visitor's choice.

This page covers the full setup. For the general install reference, see [SDK Installation](/docs/developers/sdk-installation).

Connect your HubSpot portal [#connect-your-hubspot-portal]

From your [dashboard](https://app.consentstack.io), open the site you want to connect, go to **Settings**, and click **Connect** on the HubSpot row under Integrations. HubSpot asks you to choose an account and approve the connection, then sends you back to ConsentStack.

The app requests one permission: read access to your portal's website domains (`cms.domains.read`). It cannot write to your HubSpot content, contacts, or settings.

On connect, ConsentStack imports the domains your portal serves pages on (site, landing page, and blog domains; mail and redirect domains are skipped) into the site's Domains list. After that, domains re-sync automatically once a day, and a **Sync now** button on the Integrations row runs the same sync on demand.

If you installed the app from the HubSpot marketplace instead, the order flips: after you approve the connection in HubSpot, ConsentStack asks you to sign in (or create an account) and pick which site the portal belongs to. Everything else works the same.

Install the consent script [#install-the-consent-script]

HubSpot loads ConsentStack the same way as any site: three tags at the top of every page. In HubSpot the right place is **Site Header HTML**:

1. On the site's Settings page, use **Copy script** on the Integrations row. The **HubSpot settings** button next to it takes you straight to your portal's page settings.
2. In HubSpot, go to **Settings** > **Website** > **Pages**, paste the snippet into **Site Header HTML**, and save.

The snippet looks like this, with your own site key filled in:

```html
<link rel="preconnect" href="https://cdn.consentstack.io" />
<script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
<script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"></script>
```

ConsentStack detects the install automatically on the first page load and the Integrations row flips to **Active**. Nothing else to verify.

<Callout type="info">
  The paste is a one-time manual step by design. HubSpot does not offer marketplace apps an API for writing Site Header HTML, so no third-party app can inject the tag for you. The app gets you as close as possible: the exact snippet on your clipboard and a deep link to the field it goes in.
</Callout>

What happens on a HubSpot page [#what-happens-on-a-hubspot-page]

With the script installed, the SDK detects HubSpot and activates its HubSpot adapter. Two things happen:

1. **HubSpot's banner is turned off.** The SDK sets `window.disableHubSpotCookieBanner` before HubSpot's tracking code boots (your script runs from the page head, HubSpot's tracker loads later), so HubSpot's native cookie banner never renders alongside yours. Visitors see one banner: yours.
2. **Every consent decision is reported to HubSpot.** The SDK pushes `setHubSpotConsent` onto HubSpot's `_hsp` queue on every consent change, using [HubSpot's Cookie Banner API](https://developers.hubspot.com/docs/api-reference/cookie-banner/cookie-banner-api). HubSpot's own tracking (the `__hstc` and `hubspotutk` analytics cookies, conversations chat, form tracking) then follows what the visitor chose in your banner.

Categories map to HubSpot's three consent fields:

| ConsentStack category | HubSpot consent field |
| --------------------- | --------------------- |
| Analytics             | `analytics`           |
| Marketing             | `advertisement`       |
| Functional            | `functionality`       |

What about scripts HubSpot does not control? [#what-about-scripts-hubspot-does-not-control]

They are handled by [script blocking](/docs/concepts/script-blocking), not by this integration. Tags you add to your HubSpot pages directly (the Meta Pixel, LinkedIn Insight, heatmap tools) do not read HubSpot's consent record, so ConsentStack blocks them in the browser until the visitor consents. The HubSpot adapter never bypasses that blocking; it adds the HubSpot side on top.

Platforms with native consent APIs of their own (Google, Meta, TikTok, Bing, and others) also get dedicated consent signaling, described in [Platform Integrations](/docs/developers/platform-integrations).

Does the banner need the app? [#does-the-banner-need-the-app]

No. The consent behavior on this page, banner takeover included, comes from the script and works on any HubSpot site where the snippet is installed. The app adds the portal connection on top: automatic domain import, the daily sync, and the guided install. Connecting it is recommended, not required.

Disconnecting [#disconnecting]

Click **Disconnect** on the Integrations row to uninstall the app from your portal. ConsentStack calls HubSpot's uninstall API, HubSpot revokes the connection and notifies your portal's admins, and domain sync stops. Your imported domains stay on the site, and the consent script on your pages keeps working exactly as before. You can reconnect at any time.

Uninstalling ConsentStack from your HubSpot account's Connected Apps page has the same effect; the dashboard notices within a day and shows the connection as disconnected.

What's next [#whats-next]

* [SDK Installation](/docs/developers/sdk-installation). The full install reference.
* [Script Blocking](/docs/concepts/script-blocking). How third-party tags are held until the visitor consents.
* [Platform Integrations](/docs/developers/platform-integrations). Native consent signaling for Google, Meta, TikTok, and more.


# Overview (/docs/developers)



import { Download, Code, Terminal, Plug, BookOpen, Bot } from "lucide-react"
import { FaReact } from "react-icons/fa"

<Cards>
  <Card icon={<Download />} title="SDK Installation" description="Add ConsentStack to your website with three tags (a preconnect hint plus stub plus core). Supports all frameworks and static sites." href="/docs/developers/sdk-installation" />

  <Card icon={<FaReact />} title="React SDK" description="Integrate ConsentStack into React and Next.js apps with hooks and components." href="/docs/developers/react-sdk" />

  <Card icon={<Code />} title="JavaScript API" description="Complete API reference for the ConsentStack JavaScript SDK." href="/docs/developers/javascript-api" />

  <Card icon={<Terminal />} title="Headless Mode" description="Use ConsentStack's consent engine without the default banner UI. Build your own consent experience." href="/docs/developers/headless-mode" />

  <Card icon={<Plug />} title="Platform Integrations" description="Natively signal consent to Google, Meta, TikTok, Microsoft, Pinterest, and LinkedIn." href="/docs/developers/platform-integrations" />

  <Card icon={<BookOpen />} title="Framework Guides" description="Step-by-step guides for adding ConsentStack to React, Next.js, Vue, Nuxt, and static sites." href="/docs/developers/framework-guides" />

  <Card icon={<Bot />} title="MCP Server" description="Connect Claude, Cursor, or any MCP client and let your agent create sites, publish banners, and run compliance scans." href="/docs/developers/mcp" />
</Cards>


# JavaScript API (/docs/developers/javascript-api)



import { Callout } from '@/components/fumadocs/callout';

Once the ConsentStack script loads, the full API is available at `window.consentstack`. Use it to read consent state, set consent programmatically, listen for changes, and control the banner and preferences UI.

TypeScript types [#typescript-types]

The key types you will work with:

```ts
// Consent state: a map of category ID to granted/denied
type ConsentCategories = Record<string, boolean>
// Example: { essential: true, analytics: false, marketing: false }

// SDK event names
type ConsentEventType =
  | "ready"
  | "consent"
  | "error"
  | "preferences:open"
  | "preferences:close"

// Event payloads
type ConsentEventData = {
  ready: {
    config: ConsentConfig | null
    consent: Record<string, boolean> | null
    effectiveConsent: Record<string, boolean> | null
    hasDecision: boolean
  }
  consent: Record<string, boolean>
  error: Error
  "preferences:open": undefined
  "preferences:close": undefined
}

// Full config object (returned by getConfig)
interface ConsentConfig {
  appearance: Appearance
  content: Content
  categories: ConsentCategory[]
  bannerVisibility: ConsentModel[]
  reentryVisibility: ConsentModel[]
}
```

Consent operations [#consent-operations]

These methods let you read and write consent state directly.

getConsent() [#getconsent]

Returns the visitor's effective consent: the per-category state the request blocker acts on right now. Precedence is explicit decision, then GPC forcing, then implicit grant by consent model. A fresh visitor in an opt-out region gets `{ analytics: true, ... }` before they touch the banner; the same visitor in an opt-in region gets `{ analytics: false, ... }`.

Returns `null` only before initialization when no edge-seeded state is available. With the standard two-tag CDN install, consent state is stamped into the first script at the edge, so `getConsent()` is correct from the moment the script parses.

```ts
getConsent(): Record<string, boolean> | null
```

```js
const consent = window.consentstack.getConsent()

if (consent?.analytics) {
  loadCustomAnalytics()
}
```

<Callout type="info">
  Because `getConsent()` returns effective consent, it is non-null even before the visitor has chosen. To check whether an explicit decision exists (for example, to decide whether to show a custom banner), use [`hasDecision()`](#hasdecision), not `getConsent() === null`.
</Callout>

hasDecision() [#hasdecision]

Returns whether an explicit consent decision exists, either stored from a prior visit or made this session. This replaces the old `getConsent() === null` idiom for custom-banner logic.

```ts
hasDecision(): boolean
```

```js
if (!window.consentstack.hasDecision()) {
  // No explicit choice yet: show your custom banner
  showMyCustomBanner()
}
```

setConsent() [#setconsent]

Sets consent programmatically. This saves the decision to local storage, logs it to the ConsentStack server, activates or blocks scripts accordingly, and hides the banner.

```ts
setConsent(categories: Record<string, boolean>): Promise<void>
```

| Parameter    | Type                      | Description                                                    |
| ------------ | ------------------------- | -------------------------------------------------------------- |
| `categories` | `Record<string, boolean>` | A map of category IDs to `true` (granted) or `false` (denied). |

```js
// Grant analytics, deny marketing
await window.consentstack.setConsent({
  essential: true,
  analytics: true,
  marketing: false,
})
```

<Callout type="info">
  If this is the visitor's first consent decision, it is logged as an `initial` event. Subsequent calls are logged as `update` events. If you revoke a previously granted category, the SDK shows a refresh prompt since already-executed scripts cannot be undone.
</Callout>

hasConsent() [#hasconsent]

Returns whether the category is effectively granted right now. Precedence: GPC-forced denial, then the stored decision, then implicit grant by consent model. In opt-in regions (e.g. GDPR), this is `false` until the visitor explicitly grants. In opt-out regions, it is `true` until the visitor explicitly rejects. This is the same state the request blocker and `data-cs-category` script blocking act on, and it is correct at parse time with the standard two-tag install.

```ts
hasConsent(category: string): boolean
```

```js
if (window.consentstack.hasConsent("analytics")) {
  loadCustomAnalytics()
}
```

onConsentChange() [#onconsentchange]

Subscribes to effective-consent changes. Your callback fires every time effective consent changes, whether from the banner, preferences panel, a `setConsent()` call, or init reconciliation (when initialization resolves a state that differs from what was known before). Returns an unsubscribe function.

```ts
onConsentChange(
  callback: (consent: Record<string, boolean>) => void
): () => void
```

```js
const unsubscribe = window.consentstack.onConsentChange((consent) => {
  if (consent.analytics) {
    initAnalytics()
  }
})

// Later, stop listening
unsubscribe()
```

UI operations [#ui-operations]

Control the consent banner and preferences panel from your own code.

showBanner() [#showbanner]

Displays the consent banner. In the default `banner` mode, the SDK shows the banner automatically for new visitors. Use this method to re-show it manually, for example, in `headless` mode where you handle the UI trigger yourself.

```ts
showBanner(): void
```

```js
document.getElementById("manage-cookies").addEventListener("click", () => {
  window.consentstack.showBanner()
})
```

showPreferences() [#showpreferences]

Opens the preferences panel where visitors can toggle individual consent categories.

```ts
showPreferences(): void
```

```js
// Open preferences from a footer link
document.getElementById("cookie-settings").addEventListener("click", () => {
  window.consentstack.showPreferences()
})
```

You can also open preferences by navigating to `#cs-preferences`. The SDK listens for this hash automatically.

hidePreferences() [#hidepreferences]

Closes the preferences panel programmatically. Emits a `preferences:close` event and re-shows the re-entry button if the visitor has already made a consent decision.

```ts
hidePreferences(): void
```

isPreferencesOpen() [#ispreferencesopen]

Returns whether the preferences panel is currently visible.

```ts
isPreferencesOpen(): boolean
```

```js
if (!window.consentstack.isPreferencesOpen()) {
  window.consentstack.showPreferences()
}
```

setLanguage() [#setlanguage]

Switches the banner and preferences panel to a different language at runtime. Useful when your site has its own language switcher and you want the consent UI to follow it.

```ts
setLanguage(language: string): Promise<void>
```

Accepts ISO language codes with or without a region subtag (`"ja"` and `"ja-JP"` are equivalent). Only languages you have enabled for the site in the dashboard take effect; requests for other languages are ignored. The choice persists across page loads.

```js
// Follow the page language (e.g. after a locale-prefixed navigation)
const pageLang = document.documentElement.lang || "en"
window.consentstack.setLanguage(pageLang)
```

Because `setLanguage()` runs after the banner has rendered, switching this way briefly shows the previous language. For localized sites, declare the page language before the SDK loads instead. The banner then renders in the page language from the first paint:

```html
<script src="https://cdn.consentstack.io/consent-core.js?k=YOUR_SITE_KEY" data-lang="auto"></script>
```

`data-lang="auto"` follows the page's `<html lang>` attribute; you can also pass a fixed code like `data-lang="ja"`, or set `window.consentstackLang = document.documentElement.lang` in an inline script above the consent tags if you cannot modify the script tag attributes.

Events [#events]

Subscribe to SDK lifecycle events for fine-grained control over your integration.

on() [#on]

Subscribes to a named SDK event. Returns an unsubscribe function.

```ts
on<T extends ConsentEventType>(
  event: T,
  callback: (data: ConsentEventData[T]) => void
): () => void
```

| Event                 | Payload                                              | Fires when                                                                                                                                                                                                                |
| --------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"ready"`             | `{ config, consent, effectiveConsent, hasDecision }` | SDK has initialized and consent state is known. `consent` is the stored explicit decision (or `null`), `effectiveConsent` is the state the request blocker acts on, `hasDecision` is whether an explicit decision exists. |
| `"consent"`           | `Record<string, boolean>`                            | Effective consent changes (same as `onConsentChange`), including init reconciliation when initialization resolves a state that differs from what was known before.                                                        |
| `"error"`             | `Error`                                              | An SDK error occurs, including init aborts (site not configured, domain not registered for the site key).                                                                                                                 |
| `"preferences:open"`  | `undefined`                                          | Preferences panel opens.                                                                                                                                                                                                  |
| `"preferences:close"` | `undefined`                                          | Preferences panel closes.                                                                                                                                                                                                 |

```js
// Wait for the SDK to be ready before reading state
const unsubscribe = window.consentstack.on("ready", ({ config, effectiveConsent, hasDecision }) => {
  console.log("SDK ready. Region categories:", config?.categories)
  console.log("Effective consent:", effectiveConsent)
  console.log("Explicit decision exists:", hasDecision)
  unsubscribe()
})

// Track when users open preferences
window.consentstack.on("preferences:open", () => {
  analytics.track("consent_preferences_opened")
})
```

Configuration [#configuration]

getConfig() [#getconfig]

Returns the loaded consent configuration object, or `null` if the SDK has not finished initializing. The config includes appearance settings, content strings, category definitions, and re-entry button settings.

```ts
getConfig(): ConsentConfig | null
```

```js
const config = window.consentstack.getConfig()

if (config) {
  console.log("Categories:", config.categories.map(c => c.name))
  console.log("Layout:", config.appearance.layout)
}
```

getRegion() [#getregion]

Returns the consent region that was applied to the current visitor. In global compliance mode this is the matched jurisdiction key (e.g. `"US-CA"`, `"FR"`, `"CA-QC"`). In manual region mode it is the id of the site-defined region that matched.

Returns `null` in two cases: before the SDK has finished resolving the config, and when no configured region or regulation matched the visitor's location. The second case is the common one: `null` means your default configuration applies. It is not a geolocation failure, and it is expected for visitors outside every jurisdiction you have rules for.

This method reports what config resolution did, so it always agrees with the banner behavior the visitor actually gets. For raw location independent of your consent setup, use [getGeo()](#getgeo).

```ts
getRegion(): string | null
```

```js
const region = window.consentstack.getRegion()
if (region === "US-CA") {
  // Show the California-specific privacy choices link
}
```

Source: `ConsentStackAPI` in `packages/sdk/src/types.ts`, wired through `core.getRegion()`.

getConsentModel() [#getconsentmodel]

Returns the dominant consent model resolved for the current visitor: the strictest model among non-exempt categories after region resolution (`opt_in` > `opt_out` > `notice` > `notice_required`). This is the same value the SDK uses to decide banner behavior, which makes it the right primitive for gating jurisdiction-dependent UI. Prefer it over matching `getRegion()` against a list of jurisdictions: it tracks what the applicable law requires rather than which jurisdiction happened to match.

Returns `null` before the config has resolved.

```ts
getConsentModel(): "opt_in" | "opt_out" | "notice" | "notice_required" | null
```

```js
const model = window.consentstack.getConsentModel()
if (model === "opt_out") {
  // Visitor is in an opt-out jurisdiction (CCPA-style):
  // render the "Your Privacy Choices" link
}
```

Source: `ConsentStackAPI` in `packages/sdk/src/types.ts`, wired through `core.getConsentModel()`.

getGpcStatus() [#getgpcstatus]

Returns the effective Global Privacy Control status for the current visitor, or `null` before initialization.

* `detected`: the signal is present on either surface (the `Sec-GPC: 1` request header read at our edge, or `navigator.globalPrivacyControl` read client-side). Prefer this over reading `navigator.globalPrivacyControl` yourself, which misses the header-only case.
* `honored`: the signal governs the current consent state. This is the effective outcome, not just policy: it is `false` when your site's GPC setting does not honor the signal for this jurisdiction, and also when the visitor has made an explicit consent choice on your site, which overrides the signal under CCPA section 7025(c)(3).

```ts
getGpcStatus(): { detected: boolean; honored: boolean } | null
```

Three UI states fall out, which is exactly what a privacy policy page needs:

```js
const gpc = window.consentstack.getGpcStatus()
if (gpc?.honored) {
  // "Opt-Out Preference Signal Honored"
} else if (gpc?.detected) {
  // "You have overridden your browser's opt-out signal with an explicit choice"
} else {
  // No signal: show nothing
}
```

Source: `ConsentStackAPI` in `packages/sdk/src/types.ts`, wired through `core.getGpcStatus()`.

getGeo() [#getgeo]

Returns a `GeoDetails` object with city, postal code, latitude, longitude, region (e.g. US state code), timezone, and continent, or `null` if geo-detail is not enabled or available. Each field is `string | null`.

```ts
getGeo(): GeoDetails | null
```

```js
const geo = window.consentstack.getGeo()
if (geo?.region === "CA") {
  // Likely California (when the resolved region is also US)
}
```

The method is declared at `packages/sdk/src/types.ts:400`; the `GeoDetails` shape is at `packages/sdk/src/types.ts:184-192`. Geo-detail availability is gated by plan. Wired at `packages/sdk/src/index.ts:183`.

clearCache() [#clearcache]

Clears the local config cache and re-fetches the config from origin, bypassing the edge cache. Returns a `Promise<void>`.

```ts
clearCache(): Promise<void>
```

```js
await window.consentstack.clearCache()
```

This is a developer tool. It is logged in `?cs-debug=true` output. Implementation at `packages/sdk/src/core.ts:1378-1411`.

debug() [#debug]

Prints SDK state to the browser console: site key, mode, current consent, and config version. Pass `{ verbose: true }` to include the full config and state objects.

```ts
debug(options?: { verbose?: boolean }): void
```

```js
// Quick overview
window.consentstack.debug()

// Full state dump
window.consentstack.debug({ verbose: true })
```

Debug query parameter [#debug-query-parameter]

Add `?cs-debug=true` (or `?cs-debug=1`) to any page URL to enable the init waterfall, a console-printed timing breakdown of every SDK initialization phase:

Example output:

```
[ConsentStack] Init waterfall — ~XXms total
Config fetch              ~Xms  ██████████████████  (fresh)
Inject styles              ~Xms  █
Consent reconciliation     ~Xms  █  (none)
Platform adapters          ~Xms  █
Script blocker             ~Xms  █  (N rules)
Banner/UI                  ~Xms  █  (banner shown)
```

This is useful for diagnosing slow init times or verifying that config caching is working. No code changes required; just append the parameter to your URL.

Test mode query parameter [#test-mode-query-parameter]

When a site has **Test mode** on (Config Builder, Settings tab), the SDK stays quiet for real visitors: no banner, no preferences panel, no re-entry button, and no request blocking. Add `?cs-test-mode=true` to any page URL to load the site normally instead, exactly as a visitor will see it once test mode is off.

The activation persists to `sessionStorage` for the rest of the tab, so you can click through the site without re-adding the parameter. `?cs-test-mode=false` clears it. This is the same pattern as `?cs-debug=1`.

Test mode never stops the SDK from reporting. The config request still runs, so page views still count toward your plan's visitor limit and your domain still verifies, and tracker detection still fills in your inventory. What test mode suppresses is the visitor-facing UI and enforcement, nothing else.

<Callout type="warn">
  A site in test mode has no working consent banner for real visitors. It's a pre-launch tool, not a way to quiet the banner on a live site.
</Callout>

Sites pinned to a legacy `cdn.consentstack.io/consent.vX.js` bundle don't honor test mode.

Command queue [#command-queue]

Before `consent-core.js` finishes loading, `window.consentstack` is an array. Push commands as tuples; the SDK replays them in order once initialized.

```js
window.consentstack = window.consentstack || []
window.consentstack.push(["on", "ready", (data) => {
  console.log("Consent ready:", data.consent)
}])
window.consentstack.push(["setConsent", { analytics: true }])
```

Each pushed call is a tuple of `[methodName, ...args]`. The queue type is `ConsentStackQueuedCall = [keyof ConsentStackAPI, ...unknown[]]` (`packages/sdk/src/types.ts:534`). After the core loads, `window.consentstack` is replaced with the live API object (`packages/sdk/src/index.ts:38-62`).

Waiting for the SDK [#waiting-for-the-sdk]

The SDK initializes asynchronously. If your code runs before the script has loaded, `window.consentstack` will be `undefined`. Use the `ready` event or a guard check:

```js
// Option 1: Guard check
if (window.consentstack) {
  const consent = window.consentstack.getConsent()
}

// Option 2: Wait for ready event
function onSdkReady() {
  window.consentstack.on("ready", ({ effectiveConsent }) => {
    console.log("Effective consent:", effectiveConsent)
  })
}

if (window.consentstack) {
  onSdkReady()
} else {
  // Poll until available
  const interval = setInterval(() => {
    if (window.consentstack) {
      clearInterval(interval)
      onSdkReady()
    }
  }, 50)
}
```

First-page analytics [#first-page-analytics]

To fire an analytics event on the landing page, gate it on `hasConsent()`:

```js
window.consentstack = window.consentstack || []
window.consentstack.push(["on", "ready", () => {
  if (window.consentstack.hasConsent("analytics")) {
    trackPageView()
  }
}])
```

With the standard two-tag install, consent state is seeded from the edge before your page scripts run, so `hasConsent()` reflects real effective consent on the very first page load. Landing page views from visitors whose consent model grants analytics (implicitly or from a stored decision) are no longer lost while the SDK initializes.

If effective consent changes later (the visitor accepts, rejects, or updates preferences), react with `onConsentChange()`:

```js
window.consentstack.push(["onConsentChange", (consent) => {
  if (consent.analytics) {
    trackPageView()
  }
}])
```

What's next [#whats-next]

* [Automatic script blocking](/docs/concepts/script-blocking): how the SDK manages third-party scripts based on consent state
* [Consent models](/docs/concepts/consent-models): understand opt-in, opt-out, notice, and notice-required behavior
* [Quickstart](/docs/getting-started): add ConsentStack to your site in under 5 minutes
* [MCP Server](/docs/developers/mcp): connect Claude, Cursor, or any MCP client and manage sites, banner config, and compliance scans by agent


# MCP Server (/docs/developers/mcp)



import { Callout } from '@/components/fumadocs/callout';

ConsentStack ships a hosted MCP server, so an AI agent can set up and run cookie consent for you. MCP (Model Context Protocol) is the open standard AI tools use to connect to outside services. Connect once and your agent gets 38 tools covering the whole job: create a site, set up the banner, get the install snippet, run a compliance scan, categorize the trackers it finds, and generate your policies.

If you built your site with an AI tool like Claude, Cursor, Lovable, or Replit, this is the shortest path to a working, compliant cookie banner: the same agent that built the site can install consent on it.

Connection details [#connection-details]

|                |                                                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| Server URL     | `https://app.consentstack.io/api/mcp`                                                                     |
| Transport      | Streamable HTTP                                                                                           |
| Authentication | OAuth 2.1 (sign in with your ConsentStack account)                                                        |
| API keys       | None. There is nothing to create or paste.                                                                |
| Registry name  | `io.consentstack/cookie-consent` (listed in the [MCP Registry](https://registry.modelcontextprotocol.io)) |

On first connect, your MCP client opens a browser window where you sign in with the same account you use for the [dashboard](https://app.consentstack.io). No ConsentStack account yet? [Sign up free](https://app.consentstack.io/signup) first; the Basic tier costs nothing.

Connect from Claude [#connect-from-claude]

For Claude Code, run:

```bash
claude mcp add --transport http consentstack https://app.consentstack.io/api/mcp
```

For claude.ai or the Claude desktop app, go to **Settings > Connectors > Add custom connector** and paste the server URL. Complete the sign-in when the browser window opens.

Connect from Cursor or another MCP client [#connect-from-cursor-or-another-mcp-client]

Add the server to your client's MCP configuration. For Cursor, that is `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "consentstack": {
      "url": "https://app.consentstack.io/api/mcp"
    }
  }
}
```

Any client that supports remote MCP servers over streamable HTTP with OAuth works the same way: give it the URL, sign in when prompted.

What your agent can do [#what-your-agent-can-do]

All 38 tools, grouped by job:

| Job                   | Tools                                                                                                                                                                                                                                                                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Sites and setup       | `list_sites`, `get_site_overview`, `create_site`, `manage_domains`, `get_setup_guide`                                                                                                                                                                                                                                                                        |
| Banner configuration  | `get_config`, `update_appearance`, `update_content`, `update_compliance`, `update_settings`, `publish_config`, `discard_draft`                                                                                                                                                                                                                               |
| Trackers and blocking | `list_detected_trackers`, `set_tracker_category`, `clear_tracker_override`, `set_hostname_policy`                                                                                                                                                                                                                                                            |
| Compliance scanning   | `start_scan`, `get_scan_result`                                                                                                                                                                                                                                                                                                                              |
| Analytics and logs    | `get_consent_analytics`, `get_consent_logs`                                                                                                                                                                                                                                                                                                                  |
| Policies              | `list_policies`, `get_policy_profile`, `update_policy_profile`, `get_policy_questions`, `get_policy`, `update_policy_answers`, `update_policy_services`, `search_service_catalog`, `preview_policy`, `publish_policies`, `unpublish_policy`, `discard_policy_draft`, `get_policy_embed`, `set_policy_layout`, `resolve_policy_review`, `copy_policy_answers` |
| Documentation         | `search_docs`, `get_doc`                                                                                                                                                                                                                                                                                                                                     |

`get_setup_guide` returns install snippets with your site's real key filled in, so the agent can paste working tags straight into your codebase.

What does an end-to-end setup look like? [#what-does-an-end-to-end-setup-look-like]

A typical run, from nothing to verified:

1. **Create.** `create_site` adds a site on the free Basic tier; `manage_domains` registers where it runs.
2. **Install.** `get_setup_guide` returns the three install tags with your real site key, and the agent adds them to your site's `<head>`.
3. **Configure.** The agent stages banner appearance, text, and compliance settings as drafts. Drafts never touch your live site.
4. **Publish.** After you approve the changes in conversation, `publish_config` makes them live.
5. **Verify.** `start_scan` runs the [compliance scanner](https://www.consentstack.io/compliance-scanner) against the live site: a real browser visits, declines the banner, and reports any tracker that fired anyway. The agent categorizes what the scan finds and rescans until it comes back clean.

<Callout type="info">
  Scan findings come back with remediation hints that name the exact tool that fixes them, so an agent can close the loop on its own: scan, categorize, publish, rescan.
</Callout>

Can my agent set up my policies? [#can-my-agent-set-up-my-policies]

Yes. The [policy generator](/docs/dashboard/policy-generator) works through the MCP server as well as the dashboard, so an agent can take a site from nothing to a published Privacy Policy, Cookie Policy, Terms of Service, Disclaimer and Accessibility Statement:

1. **Profile.** The agent fills in your business profile: legal name, contact, where you do business. It asks you for these facts rather than guessing them.
2. **Answers.** It answers each policy's questions. The Privacy and Cookie Policies start from the trackers ConsentStack detected on your site, and the agent can add services it cannot detect, such as your payment or email provider.
3. **Preview and publish.** It shows you the policy text, then publishes it. The server's own instructions direct agents to get your explicit go-ahead before publishing.
4. **Embed.** It gives you the snippet for your policy page and checks that your banner links to the policy.

The policy text always comes from our templates. Your agent supplies the answers, never the legal wording. Policies keep themselves current after that, and any change that affects what you disclose waits for your review, which the agent can walk you through.

<Callout type="info">
  Agencies and teams with many sites can ask for `list_policies` to see every site's policies in one place, and copy answers from one site to others in the same team with `copy_policy_answers`.
</Callout>

Does the MCP server cost anything? [#does-the-mcp-server-cost-anything]

No. MCP access is included on every plan, including the free Basic tier, and `create_site` creates Basic sites. Features that belong to paid plans (consent analytics and logs, for example) stay plan-gated exactly as they are in the dashboard; the tools tell your agent which plan unlocks them rather than working around the limit.

Who can make changes? [#who-can-make-changes]

The same people who can in the dashboard. Every request runs under your account with your team role. Read tools work for any team member. Writes (`update_*`, `publish_config`, `publish_policies`, `unpublish_policy`, tracker overrides, policy reviews) require the admin or owner role. And the server's own instructions direct agents to summarize pending changes and get your explicit go-ahead before publishing anything.

How is access secured? [#how-is-access-secured]

The server implements OAuth 2.1 with standard protected-resource discovery, so clients negotiate sign-in automatically. Tokens are issued to your account, never to a shared key, and every database query enforces the same row-level security the dashboard uses. There are no long-lived API keys to leak or rotate.

What's next [#whats-next]

* [SDK Installation](/docs/developers/sdk-installation). The install tags your agent will be pasting.
* [Compliance Scanner](https://www.consentstack.io/compliance-scanner). The free scan the `start_scan` tool drives.
* [Platform Integrations](/docs/developers/platform-integrations). Native consent signaling for Google, Meta, TikTok, and more.
* [JavaScript API](/docs/developers/javascript-api). Programmatic control of the banner and consent state.


# Platform Integrations (/docs/developers/platform-integrations)



ConsentStack automatically signals your visitors' consent choices to the advertising and analytics platforms you already use. Enable an integration in your dashboard, and the SDK handles the rest. No extra code, no manual wiring.

This is especially important for platforms like Google that require real-time consent signals to comply with regulations like the EU Digital Markets Act. Without proper signaling, your ad measurement and remarketing data degrades or stops entirely.

How integrations work [#how-integrations-work]

When a visitor makes a consent choice (or arrives with a saved preference), the SDK notifies every enabled platform using that platform's native consent API. Each platform adapter follows the same lifecycle:

1. **Initialize with deny-all defaults.** The adapter sets a privacy-safe default state before any tracking occurs.
2. **Wait for consent.** The platform's scripts can load, but they respect the denied state and do not collect data.
3. **Update on consent change.** When the visitor grants or revokes consent, the adapter calls the platform's consent API with the new state.

This means platforms with native consent APIs can load their scripts immediately. They handle consent natively and do not need to be blocked. Platforms without a native API (like LinkedIn) rely on [script blocking](/docs/concepts/script-blocking) instead.

Google Consent Mode v2 [#google-consent-mode-v2]

Google Consent Mode v2 (GCM) is the most important integration for most sites. It signals consent state to Google Tag Manager, Google Analytics 4, Google Ads, and all other Google tags.

For the conceptual background, including the June 15, 2026 change that made Consent Mode the single control over Google Ads data, see the [Consent Mode v2 setup guide](/blog/google-consent-mode-v2-setup).

How ConsentStack implements GCM [#how-consentstack-implements-gcm]

ConsentStack runs GCM in **Basic Mode** by default. Google tags stay blocked until the visitor consents to their category, so no request reaches Google before that. The adapter still sets the full Consent Mode v2 signal state up front, so when a tag does load it receives the correct consent state immediately instead of firing on stale defaults.

On initialization, the adapter sets deny-all defaults for all consent types:

| GCM consent type          | Default state | ConsentStack category |
| ------------------------- | ------------- | --------------------- |
| `ad_storage`              | Denied        | Marketing             |
| `ad_user_data`            | Denied        | Marketing             |
| `ad_personalization`      | Denied        | Marketing             |
| `analytics_storage`       | Denied        | Analytics             |
| `functionality_storage`   | Granted       | Essential (always on) |
| `security_storage`        | Granted       | Essential (always on) |
| `personalization_storage` | Granted       | Functional            |

The adapter also enables `ads_data_redaction` (strips ad click identifiers when consent is denied) and `url_passthrough` (preserves ad click info in URLs without cookies, improving conversion measurement in cookieless scenarios).

wait_for_update behavior [#wait_for_update-behavior]

The default consent state includes a `wait_for_update` window of 500 milliseconds. This tells Google tags: "Hold off, a consent update is coming." If the visitor has a saved consent preference, the SDK fires the update within this window. If no saved preference exists (first visit), the defaults remain until the visitor interacts with the banner.

This avoids a race condition where Google tags fire with denied defaults before the SDK has time to restore a returning visitor's granted state.

Script blocking [#script-blocking]

Google scripts are blocked until consent, exactly like any other tracker. Google Tag Manager, Analytics, and Ads are catalogued under their normal categories, and the request-blocking stub holds them at parse time until the visitor grants that category.

Consent Mode sits alongside that, it does not replace it. Running tags before consent means a request reaches Google before the visitor has agreed to anything. That request carries no identifiers, but it is still a request, and not every regulator treats it as equivalent to silence. Blocking first is the reading ConsentStack defaults to.

A per-platform opt-in that loads Google tags before the fence and lets Consent Mode govern them on its own is planned, but it is not available yet and it will never be on by default.

One exception exists today: a Google tag served from your own domain through Google Tag Gateway is a first-party request, so the fence lets it through and only the denied defaults govern it. Keep the ConsentStack snippet above that tag and turn off the CDN's automated tag setup, which Google's own gateway instructions require when you use Consent Mode. The [Consent Mode v2 setup guide](/blog/google-consent-mode-v2-setup) covers what the gateway changes and how to check whether it is on.

Meta (Facebook Pixel) [#meta-facebook-pixel]

The Meta adapter uses the `fbq('consent', ...)` API built into the Facebook Pixel.

On initialization, the adapter revokes consent by default:

```js
fbq('consent', 'revoke')
```

When a visitor grants marketing consent, it calls:

```js
fbq('consent', 'grant')
```

If the visitor later revokes consent (through the preferences panel), it switches back to `revoke`. The Facebook Pixel respects these signals and adjusts its data collection accordingly.

Meta scripts are blocked until marketing consent is granted. The `fbq` consent signal is layered on top of that, so the Pixel knows the visitor's choice once it is allowed to load.

TikTok Events API [#tiktok-events-api]

The TikTok adapter uses TikTok's built-in consent methods on the `ttq` object.

On initialization, the adapter holds consent:

```js
ttq.holdConsent()
```

When marketing consent is granted, it calls `ttq.grantConsent()`. If revoked, it calls `ttq.revokeConsent()`.

When GPC is honored, the adapter additionally calls `ttq("limited_data_use", true)`. See [Global Privacy Control](/docs/compliance/global-privacy-control) for details.

TikTok scripts are blocked until consent is granted. Even though TikTok has a consent API, the adapter does not allow the scripts to preload.

Bing UET [#bing-uet]

The Bing UET (Universal Event Tracking) adapter uses UET's consent signaling API, which follows a pattern similar to Google Consent Mode. On initialization, the adapter pushes a deny-all default:

```js
uetq.push('consent', 'default', { ad_storage: 'denied' })
```

When marketing consent is granted, it pushes an update:

```js
uetq.push('consent', 'update', { ad_storage: 'granted' })
```

Bing UET scripts (`bat.bing.com`) are blocked until marketing consent is granted, with the `uetq` consent signal layered on top. See `packages/sdk/src/platforms/microsoft.ts` for the adapter source.

Microsoft Clarity [#microsoft-clarity]

The Microsoft Clarity adapter uses Clarity's Consent API v2. The SDK calls `consentv2` once with the resolved state (granted or denied) every time consent updates, ensuring preference-center revocations after a prior accept are propagated to Clarity:

```js
clarity('consentv2', { ad_Storage: 'granted', analytics_Storage: 'granted' })
```

Publishers should configure their Clarity project dashboard with "cookies off by default." The dashboard default governs first-load behavior before the SDK runs; once `consentv2` is called, the explicit signal wins.

Clarity scripts (`clarity.ms`) are blocked until consent for their category is granted, with the `consentv2` signal layered on top. See `packages/sdk/src/platforms/clarity.ts` for the adapter source.

Pinterest Tag [#pinterest-tag]

The Pinterest adapter uses the `pintrk('setconsent', ...)` API:

```js
pintrk('setconsent', false)   // default: denied
pintrk('setconsent', true)    // on consent grant
```

Pinterest scripts are blocked until consent is granted.

LinkedIn Insight Tag [#linkedin-insight-tag]

LinkedIn does not offer a native consent API. The Insight Tag either tracks or it does not; there is no way to tell it "load but do not collect data."

Because of this, ConsentStack manages LinkedIn entirely through [script blocking](/docs/concepts/script-blocking). When marketing consent is denied, the Insight Tag script is blocked from loading. When consent is granted, the script is unblocked and loads normally.

Shopify Customer Privacy [#shopify-customer-privacy]

On Shopify storefronts, ConsentStack reports every explicit consent decision to Shopify's Customer Privacy API via `setTrackingConsent`, so Shopify Analytics and sandboxed web pixels follow the banner. The adapter writes only visitor decisions, never default states, and third-party scripts stay blocked until consent regardless. The full mechanics, including the category mapping and GPC handling, are in the [Shopify integration guide](/docs/developers/shopify).

Adapters and script blocking [#adapters-and-script-blocking]

Every platform script is blocked until consent. What differs is whether the platform also has a native consent API that ConsentStack signals on top of that:

| Platform          | Native consent API | Blocked until consent | Signal layered on top                          |
| ----------------- | ------------------ | --------------------- | ---------------------------------------------- |
| Google            | Yes                | Yes                   | Consent Mode v2 state via `gtag`               |
| Meta              | Yes                | Yes                   | `fbq` consent calls                            |
| Bing UET          | Yes                | Yes                   | `uetq` consent push commands                   |
| Microsoft Clarity | Yes                | Yes                   | `consentv2` calls                              |
| TikTok            | Yes                | Yes                   | None, blocking only                            |
| Pinterest         | Yes                | Yes                   | None, blocking only                            |
| LinkedIn          | No                 | Yes                   | None, blocking only                            |
| Shopify           | Yes                | Yes                   | Decisions recorded to the Customer Privacy API |

Blocking is the primary control, and it applies to every platform in the table. A native consent API is a second layer, not a substitute: it tells the platform what the visitor chose once its script is allowed to load, and it governs behavior the platform handles internally, such as Shopify Analytics and sandboxed web pixels.

<Callout type="info">
  You do not need to configure script blocking rules for integrated platforms. The SDK handles this automatically based on each adapter's capabilities.
</Callout>

What's next [#whats-next]

* [Script Blocking](/docs/concepts/script-blocking). How ConsentStack prevents unauthorized scripts from executing.
* [Shopify Cookie Consent Banner with Customer Privacy API](/docs/developers/shopify). How consent reaches Shopify's Customer Privacy API.
* [SDK Installation](/docs/developers/sdk-installation). Add the SDK to your site.
* [JavaScript API](/docs/developers/javascript-api). Programmatic access to consent state.


# React SDK (/docs/developers/react-sdk)



import { Callout } from '@/components/fumadocs/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

React bindings for ConsentStack. Use hooks to read consent state, conditionally render components, and build custom consent UIs, all with full TypeScript support.

This page is the API reference. For what a compliant React consent flow needs and how the common consent-bar libraries differ, start with [cookie consent for React](/platforms/react).

Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @consentstack/react
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @consentstack/react
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @consentstack/react
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Peer dependencies: `react` and `react-dom` ^18 or ^19.

For best performance, also add `<link rel="preconnect" href="https://cdn.consentstack.io" />` to the document `<head>` (e.g. via your framework's head/metadata API). The React loader injects the SDK script tags itself, but warming the TLS connection to the CDN first cuts time-to-banner.

Quick start [#quick-start]

Choose the approach that fits your needs:

| Approach               | When to use                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------- |
| `ConsentStack`         | You just need the banner. No hooks, no conditional rendering.                           |
| `ConsentStackProvider` | You need hooks to read consent state, conditionally load scripts, or build a custom UI. |

Simple integration [#simple-integration]

<Steps>
  <Step>
    Install the package [#install-the-package]

    ```bash
    pnpm add @consentstack/react
    ```
  </Step>

  <Step>
    Add to your layout [#add-to-your-layout]

    ```tsx title="app/layout.tsx"
    import { ConsentStack } from '@consentstack/react'

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <body>
            {children}
            <ConsentStack siteKey="<YOUR_SITE_KEY>" />
          </body>
        </html>
      )
    }
    ```

    That's it. The consent banner renders automatically.
  </Step>
</Steps>

With hooks [#with-hooks]

<Steps>
  <Step>
    Wrap your app with the provider [#wrap-your-app-with-the-provider]

    ```tsx title="app/layout.tsx"
    import { ConsentStackProvider } from '@consentstack/react'

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <body>
            <ConsentStackProvider siteKey="<YOUR_SITE_KEY>">
              {children}
            </ConsentStackProvider>
          </body>
        </html>
      )
    }
    ```
  </Step>

  <Step>
    Use consent in any component [#use-consent-in-any-component]

    ```tsx
    import { useConsent } from '@consentstack/react'

    function CookieStatus() {
      const { hasConsent, showPreferences, error } = useConsent()

      if (error) return <p>Failed to load consent: {error.message}</p>

      return (
        <div>
          <p>Analytics: {hasConsent('analytics') ? 'Allowed' : 'Denied'}</p>
          <button onClick={() => showPreferences()}>
            Manage preferences
          </button>
        </div>
      )
    }
    ```
  </Step>
</Steps>

Component props [#component-props]

ConsentStack [#consentstack]

| Prop      | Type      | Default                                    | Description                                               |
| --------- | --------- | ------------------------------------------ | --------------------------------------------------------- |
| `siteKey` | `string`  | *required*                                 | Your site's public key from the ConsentStack dashboard.   |
| `debug`   | `boolean` | `false`                                    | Log SDK initialization and consent events to the console. |
| `cdnUrl`  | `string`  | `"https://cdn.consentstack.io/consent.js"` | Override the SDK script URL (useful for self-hosting).    |
| `timeout` | `number`  | `15000`                                    | Timeout in milliseconds for SDK script loading.           |

ConsentStackProvider [#consentstackprovider]

Accepts all `ConsentStack` props plus:

| Prop       | Type                     | Default    | Description                                                                                     |
| ---------- | ------------------------ | ---------- | ----------------------------------------------------------------------------------------------- |
| `mode`     | `"banner" \| "headless"` | `"banner"` | `"banner"` shows the consent UI automatically. `"headless"` hides it so you can build your own. |
| `children` | `ReactNode`              | *required* | Your app tree.                                                                                  |

Hooks [#hooks]

useConsent [#useconsent]

Returns the full consent state and control methods. Must be used within a `ConsentStackProvider`.

```ts
interface UseConsentReturn {
  /**
   * Effective consent per category (explicit decision, GPC, or implicit
   * grant by consent model), or null if not yet known
   */
  consent: Record<string, boolean> | null

  /** The loaded consent config, or null if not loaded */
  config: ConsentConfig | null

  /**
   * The consent region applied to the current visitor: the matched
   * jurisdiction key (e.g. "US-CA", "FR") in global compliance mode, or the
   * site-defined region id in manual mode. Null when no configured region or
   * regulation matched (your default configuration applies) or before the
   * config has resolved.
   */
  region: string | null

  /**
   * The dominant consent model resolved for the current visitor. The right
   * primitive for gating jurisdiction-dependent UI, e.g. render a "Your
   * Privacy Choices" link when it is "opt_out". Null before the config has
   * resolved.
   */
  consentModel: "opt_in" | "opt_out" | "notice" | "notice_required" | null

  /**
   * Effective GPC status. detected: the opt-out signal is present (edge
   * header or client property). honored: the signal governs the current
   * consent state (no explicit user decision overrides it). Null before
   * initialization. Re-syncs when the visitor makes a consent decision.
   */
  gpc: { detected: boolean; honored: boolean } | null

  /** True while the SDK is initializing */
  isLoading: boolean

  /** True once consent state is known and no error occurred */
  isReady: boolean

  /**
   * Whether an explicit consent decision exists (stored from a prior visit
   * or made this session). Use this, not `consent === null`, to decide
   * whether to render a custom banner: `consent` is effective consent and
   * is non-null even before the user has chosen.
   */
  hasDecision: boolean

  /** Error if SDK failed to load, null otherwise */
  error: Error | null

  /** Update consent programmatically, logs to the server */
  setConsent: (categories: Record<string, boolean>) => Promise<void>

  /** Check if a specific category has consent */
  hasConsent: (category: string) => boolean

  /** Programmatically show the consent banner */
  showBanner: () => void

  /** Open the preferences panel */
  showPreferences: () => void

  /** Close the preferences panel */
  hidePreferences: () => void

  /** Whether the preferences panel is currently open */
  isPreferencesOpen: boolean
}
```

A few fields deserve a closer look:

* `consent` is effective consent: the same per-category state the SDK's request blocker acts on. In an opt-out region it is `true` for non-essential categories before the visitor touches the banner; in an opt-in region it is `false` until they grant. It is not "null until the user decides".
* `isReady` means consent state is known, not merely that the script loaded. With the standard install, consent state is seeded from the edge, so `isReady` is `true` as soon as the provider connects to the SDK, without waiting for a config fetch or a user decision. Gating on `isReady && hasConsent('analytics')` is the recommended pattern and works immediately on the landing page.
* `hasDecision` tells you whether an explicit choice exists. If you are building a custom banner, show it when `hasDecision` is `false`.

The `config` object uses the `ConsentConfig` type from the JS SDK. See the [JavaScript API reference](/docs/developers/javascript-api#typescript-types) for the full shape.

The `region` field is the consent region that config resolution applied to this visitor, not raw geolocation. `null` is a normal value: it means no configured region or regulation matched and your default configuration applies. `<PrivacyChoicesButton />` uses it to pick the California-specific label.

The `consentModel` field is usually the better primitive for conditional privacy UI. Rather than matching `region` against a list of jurisdictions, gate on what the applicable law requires:

```tsx
function Footer() {
  const { consentModel } = useConsent()
  return (
    <footer>
      {consentModel === "opt_out" && <PrivacyChoicesButton />}
    </footer>
  )
}
```

The `gpc` field powers signal-status UI, such as the confirmation language on a privacy policy page. It distinguishes an honored signal from one the visitor has overridden with their own explicit choice:

```tsx
function GpcStatusLine() {
  const { gpc } = useConsent()
  if (!gpc?.detected) return null
  return (
    <p>
      {gpc.honored
        ? "Opt-Out Preference Signal Honored"
        : "You have overridden your browser's opt-out signal with an explicit choice."}
    </p>
  )
}
```

useConsentValue [#useconsentvalue]

An optimized hook for checking a single consent category. Uses `useSyncExternalStore` under the hood, so your component only re-renders when that specific category value changes.

```ts
function useConsentValue(category: string): boolean
```

Returns `true` if the category has consent, `false` otherwise. Returns `false` during SSR and while the SDK is loading, a safe default that prevents scripts from firing before consent is confirmed.

```tsx
import { useConsentValue } from '@consentstack/react'

function AnalyticsLoader() {
  const hasAnalytics = useConsentValue('analytics')
  if (!hasAnalytics) return null
  return <script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" async />
}
```

useConsentEvent [#useconsentevent]

Subscribe to SDK lifecycle events. Automatically subscribes on mount and unsubscribes on unmount. You don't need to memoize the callback. The hook handles that internally via a ref.

```ts
function useConsentEvent<T extends ConsentEventType>(
  event: T,
  callback: (data: ConsentEventData[T]) => void
): void
```

| Event                 | Payload                                              | Fires when                                                                                                                                                          |
| --------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"ready"`             | `{ config, consent, effectiveConsent, hasDecision }` | SDK has initialized and consent state is known. `consent` is the stored explicit decision (or `null`), `effectiveConsent` is the state the request blocker acts on. |
| `"consent"`           | `Record<string, boolean>`                            | Effective consent changes, including init reconciliation when initialization resolves a state that differs from what was known before.                              |
| `"error"`             | `Error`                                              | An SDK error occurs, including init aborts (site not configured, domain not registered for the site key).                                                           |
| `"preferences:open"`  | `undefined`                                          | Preferences panel opens.                                                                                                                                            |
| `"preferences:close"` | `undefined`                                          | Preferences panel closes.                                                                                                                                           |

```tsx
import { useConsentEvent } from '@consentstack/react'

function PreferencesTracker() {
  useConsentEvent('preferences:open', () => {
    analytics.track('consent_preferences_opened')
  })

  useConsentEvent('error', (error) => {
    console.error('SDK error:', error)
  })

  return null
}
```

Error handling [#error-handling]

The provider exposes errors from SDK initialization. If the CDN is unreachable, the script fails to load, or the SDK aborts init (site not configured, domain not registered for the site key), `error` will contain the reason. When `error` is set, `isReady` stays `false`.

```tsx
function ConsentFallback() {
  const { error, isReady } = useConsent()

  if (error) {
    return <p>Consent system unavailable. Some features may be limited.</p>
  }

  if (!isReady) return null

  return <YourApp />
}
```

<Callout type="warn">
  The SDK times out after 15 seconds by default. If the CDN is slow or blocked, `isLoading` will become `false` and `error` will contain a descriptive timeout message. Customize the timeout with the `timeout` prop on `ConsentStackProvider` or `ConsentStack`.
</Callout>

Common patterns [#common-patterns]

First-page analytics [#first-page-analytics]

Gate landing page events on `isReady && hasConsent('analytics')`:

```tsx
import { useEffect } from 'react'
import { useConsent } from '@consentstack/react'

function PageViewTracker() {
  const { isReady, hasConsent } = useConsent()

  useEffect(() => {
    if (isReady && hasConsent('analytics')) {
      trackPageView()
    }
  }, [isReady, hasConsent])

  return null
}
```

With the standard install, consent state is seeded from the edge, so the gate passes as soon as the provider connects to the SDK, without waiting for a config fetch or a user decision. Landing page events from visitors whose consent model grants analytics (implicitly or from a stored decision) are no longer lost while the SDK initializes.

Conditional script loading [#conditional-script-loading]

Block third-party scripts until the visitor grants consent:

```tsx
import { useConsentValue } from '@consentstack/react'
import Script from 'next/script'

function ThirdPartyScripts() {
  const analyticsAllowed = useConsentValue('analytics')
  const marketingAllowed = useConsentValue('marketing')

  return (
    <>
      {analyticsAllowed && (
        <Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" strategy="afterInteractive" />
      )}
      {marketingAllowed && (
        <Script src="https://connect.facebook.net/en_US/fbevents.js" strategy="afterInteractive" />
      )}
    </>
  )
}
```

Custom preferences UI (headless mode) [#custom-preferences-ui-headless-mode]

Set `mode="headless"` on the provider to suppress the default banner entirely. Then build your own UI using the hook methods:

```tsx title="app/layout.tsx"
<ConsentStackProvider siteKey="<YOUR_SITE_KEY>" mode="headless">
  {children}
</ConsentStackProvider>
```

```tsx title="components/cookie-preferences.tsx"
import { useConsent } from '@consentstack/react'

function CookiePreferences() {
  const { consent, config, setConsent, isReady, showPreferences, hidePreferences } = useConsent()

  if (!isReady || !config) return null

  const handleToggle = (categoryId: string, enabled: boolean) => {
    setConsent({ ...consent, [categoryId]: enabled })
  }

  return (
    <div>
      <h2>Cookie Preferences</h2>
      {config.categories.map((cat) => (
        <label key={cat.id}>
          <input
            type="checkbox"
            checked={consent?.[cat.id] ?? cat.default}
            disabled={cat.required}
            onChange={(e) => handleToggle(cat.id, e.target.checked)}
          />
          <span>{cat.name}</span>
          <p>{cat.description}</p>
        </label>
      ))}
    </div>
  )
}
```

To decide when your custom banner should appear, use `hasDecision`. Checking `consent === null` no longer works: `consent` is effective consent and is populated even before the visitor makes a choice.

```tsx
function CustomBanner() {
  const { isReady, hasDecision, setConsent } = useConsent()

  // Only show the banner when no explicit decision exists yet
  if (!isReady || hasDecision) return null

  return (
    <div role="dialog">
      <p>We use cookies for analytics and marketing.</p>
      <button onClick={() => setConsent({ essential: true, analytics: true, marketing: true })}>
        Accept all
      </button>
      <button onClick={() => setConsent({ essential: true, analytics: false, marketing: false })}>
        Reject all
      </button>
    </div>
  )
}
```

<Callout type="info">
  In headless mode, you can call `showBanner()` to display the default ConsentStack banner on demand. This is useful as a fallback while you build your custom UI.
</Callout>

TypeScript [#typescript]

All exports are fully typed. The key types you can import:

```ts
import type {
  ConsentConfig,
  ConsentCategory,
  ConsentStackAPI,
  ConsentEventType,
  ConsentEventData,
  UseConsentReturn,
  ConsentStackProps,
  ConsentStackProviderProps,
} from '@consentstack/react'
```

`ConsentConfig`, `ConsentCategory`, `ConsentStackAPI`, `ConsentEventType`, and `ConsentEventData` are re-exported from the JS SDK. The React package is always in sync.

What's next [#whats-next]

* [Script blocking](/docs/concepts/script-blocking): how ConsentStack prevents scripts from firing before consent
* [Categories and regions](/docs/concepts/categories-and-regions): configuring which consent categories apply to which regions
* [JavaScript API](/docs/developers/javascript-api): full reference for the underlying SDK


# SDK Installation (/docs/developers/sdk-installation)



import { Callout } from '@/components/fumadocs/callout';

The ConsentStack SDK ships as three tags (a preconnect hint plus stub plus core) that you add to your site's `<head>`. It handles consent collection, script blocking, geo-detection, and banner rendering, no build step required.

This page covers every installation option. If you just want to get running fast, start with the [Quickstart](/docs/getting-started) and come back here when you need more control.

The install tags [#the-install-tags]

Add these three tags to your site's `<head>`, replacing `<YOUR_SITE_KEY>` with the key from your [dashboard](https://app.consentstack.io):

```html
<link rel="preconnect" href="https://cdn.consentstack.io" />
<script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
<script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"></script>
```

The preconnect link warms the TLS connection to the CDN while the browser parses the script tags. It is optional but recommended for fastest first paint.

<Callout type="warn">
  **Do not add `defer` or `async` to either ConsentStack script tag.** The SDK must execute synchronously before other scripts in the page. It installs a script observer at parse time that intercepts third-party scripts before they run. With `defer` or `async`, other scripts can execute before the observer is active, bypassing consent enforcement entirely.
</Callout>

<Callout type="info">
  Place both ConsentStack script tags as the **first scripts** in your `<head>`, with the stub before the core. Scripts that appear after ConsentStack are caught and blocked before they execute. Scripts that appear before it may run before the observer is active.
</Callout>

CDN and versioning [#cdn-and-versioning]

The SDK is served from `cdn.consentstack.io`, a global CDN backed by Cloudflare R2.

Two URL patterns are available:

```
https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>   (latest, 5 min cache)
https://cdn.consentstack.io/sdk/consent-body-v0.24.0.js    (versioned, immutable)
```

The latest URL always serves the most recent release. The versioned URL is immutable and cached for one year. Use it to pin a specific version. The canonical immutable URL pattern is `sdk/consent-body-v{version}.js`.

The current version is **0.24.0**, and the SDK ships as two scripts totaling roughly **48 KB** gzipped (stub 19 KB plus core 29 KB), plus a preconnect link tag for the CDN. It executes synchronously at parse time so it can intercept tracker requests before they fire, and has zero dependencies.

Data attributes [#data-attributes]

Configure the SDK's behavior using `data-` attributes on the core script tag. No JavaScript configuration file needed.

| Attribute          | Required             | Default    | Description                                                                                                                                                                                    |
| ------------------ | -------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-site-key`    | No (legacy fallback) | (none)     | The site key is read from the `?k=` URL param on both script tags. `data-site-key` is a legacy attribute used only by single-file React loader builds.                                         |
| `data-mode`        | No                   | `"banner"` | Set to `"headless"` to run consent logic without rendering any UI. Useful when you want to build a custom consent interface. [Learn more about headless mode.](/docs/developers/headless-mode) |
| `data-debug`       | No                   | `false`    | Set to `"true"` for verbose console logging. Logs config loading, consent decisions, script blocking, and API calls.                                                                           |
| `data-debug-panel` | No                   | `false`    | Set to `"true"` to load a visual debug overlay on the page. The panel is loaded automatically from CDN. Displays real-time consent state, blocked scripts, and detected region.                |

Example with all options [#example-with-all-options]

```html
<link rel="preconnect" href="https://cdn.consentstack.io" />
<script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
<script
  src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"
  data-mode="banner"
  data-debug="true"
  data-debug-panel="true"
></script>
```

<Callout type="warn">
  Only enable `data-debug` and `data-debug-panel` during development. Both add console output and UI overlays that your visitors should not see.
</Callout>

Hash trigger for preferences [#hash-trigger-for-preferences]

The SDK listens for the URL hash `#cs-preferences`. When a visitor navigates to any page with this hash, the preferences panel opens automatically.

This is useful for "Manage cookies" or "Privacy settings" links in your site footer:

```html
<a href="#cs-preferences">Manage cookie preferences</a>
```

The hash works from any page where the SDK is loaded. It also works as a direct link. If someone visits `https://yoursite.com/#cs-preferences`, the preferences panel opens on page load. The SDK cleans the hash from the URL after opening the panel, so it does not persist in the address bar.

Framework examples [#framework-examples]

Next.js (App Router) [#nextjs-app-router]

Add the tags to your root layout so they load on every page:

```tsx title="app/layout.tsx"
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        {/* ConsentStack must appear before third-party scripts */}
        <link rel="preconnect" href="https://cdn.consentstack.io" />
        <script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>" />
        <script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>" />
        {/* Third-party scripts go after ConsentStack */}
      </head>
      <body>{children}</body>
    </html>
  );
}
```

Plain HTML [#plain-html]

```html title="index.html"
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My Website</title>
    <!-- ConsentStack must appear before third-party scripts -->
    <link rel="preconnect" href="https://cdn.consentstack.io" />
    <script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
    <script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"></script>
    <!-- Third-party scripts go after ConsentStack -->
  </head>
  <body>
    <h1>Hello world</h1>
  </body>
</html>
```

Other frameworks [#other-frameworks]

The SDK works with any framework or static site generator (Astro, Gatsby, Nuxt, SvelteKit, WordPress, [Shopify](/docs/developers/shopify), and more). The pattern is always the same: add the preconnect link and both script tags to your site's `<head>`. On Shopify storefronts the SDK additionally reports consent to Shopify's Customer Privacy API; see the [Shopify integration guide](/docs/developers/shopify).

For framework-specific details and edge cases, see [Framework Guides](/docs/developers/framework-guides).

Verifying your installation [#verifying-your-installation]

After adding the install tags, open your site in a browser and check:

1. **Look for the banner.** A consent banner should appear based on your published configuration.
2. **Check the console.** Open your browser's developer tools and look for `[ConsentStack]` log messages. If you see an initialization success message, you are connected.
3. **Enable debug mode.** Add `data-debug="true"` to the core script tag to see detailed logs for config loading, region detection, and script blocking activity.

If the banner does not appear, verify that the `?k=` site key on both script tags matches the key shown in your dashboard and that you have published a consent configuration for your site.

What's next [#whats-next]

* [JavaScript API](/docs/developers/javascript-api). Programmatic access to consent state via `window.consentstack`.
* [Headless Mode](/docs/developers/headless-mode). Run consent logic without the built-in banner UI.
* [Framework Guides](/docs/developers/framework-guides). Detailed integration instructions for popular frameworks.
* [MCP Server](/docs/developers/mcp). Let an AI agent like Claude or Cursor run this whole install for you, from site creation to a clean compliance scan.


# Shopify Cookie Consent Banner with Customer Privacy API (/docs/developers/shopify)



import { Callout } from '@/components/fumadocs/callout';

ConsentStack is a third-party cookie consent banner for Shopify that integrates with Shopify's Customer Privacy API. It installs as three tags in your theme's `<head>`, with no app to add, detects Shopify automatically, and records every visitor decision through Shopify's `setTrackingConsent`, so Shopify Analytics and web pixels follow the same choice your banner showed. Tags Shopify does not control, such as the Meta Pixel, TikTok, Klaviyo, or a Google Tag Manager container added to the theme, are blocked in the browser until the visitor consents, and Google tags receive Consent Mode v2 signals from the same decision.

Shopify's own guidance is why the integration matters. Its Help Center says: "If you have manually installed third-party cookies or pixels or integrated them through apps on your store, then you may need to use a third-party cookie banner or add custom logic to ensure they are honoring customer consent." Shopify then points merchants at "a third-party cookie banner app properly integrated with the Customer Privacy API". This page covers the install, exactly how that integration behaves, and what Shopify asks of a third-party banner. Verified against Shopify's [Help Center](https://help.shopify.com/en/manual/privacy-and-security/privacy/customer-privacy-settings/privacy-settings) and [developer documentation](https://shopify.dev/docs/api/customer-privacy) on September 11, 2026.

For the general install reference, see [SDK Installation](/docs/developers/sdk-installation). For the product overview, see [Cookie consent for Shopify](/platforms/shopify).

Install on a Shopify theme [#install-on-a-shopify-theme]

Add the three ConsentStack tags to the `<head>` of your theme, before any other script tags. Replace `<YOUR_SITE_KEY>` with the key from your [dashboard](https://app.consentstack.io):

```html
<link rel="preconnect" href="https://cdn.consentstack.io" />
<script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
<script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"></script>
```

In the Shopify admin, go to **Online Store > Themes**, open your theme's menu, choose **Edit code**, and paste the tags into `layout/theme.liquid` just after the opening `<head>` tag. Save, and the banner is live on your storefront.

<Callout type="warn">
  Do not add `defer` or `async` to either script tag, and keep both tags ahead of any other scripts in the head. The SDK must install its script observer before third-party tags execute, or those tags can run before consent enforcement is active. Details in [SDK Installation](/docs/developers/sdk-installation).
</Callout>

What is Shopify's Customer Privacy API? [#what-is-shopifys-customer-privacy-api]

Shopify describes it as "a browser-based, JavaScript API that you can use to verify data processing permissions or build a cookie consent banner". It applies to Shopify-managed surfaces: pixels, audiences, and checkout. Shopify's [help center](https://help.shopify.com/en/manual/privacy-and-security/privacy/customer-privacy-settings/understanding-customer-privacy-settings) tells merchants who use a third-party banner to integrate it with these settings.

The record matters because Shopify gates its own tracking with it. If your banner never writes it, Shopify has no record of what the visitor chose: analytics sessions and web pixels either keep firing without consent, or stay silent for shoppers who said yes. Either way, what Shopify does no longer matches what your banner showed.

How ConsentStack reports consent to Shopify [#how-consentstack-reports-consent-to-shopify]

Automatically. On a Shopify storefront the SDK detects the `window.Shopify` global, loads Shopify's consent-tracking API ahead of time, and writes the visitor's choice with `setTrackingConsent` whenever an explicit decision exists. There is nothing to configure: install the tags and the bridge is active.

The mechanics, in order:

1. **Detection.** The bridge activates only when `window.Shopify` is present, so it costs nothing on non-Shopify pages.
2. **Warm-up.** If `Shopify.customerPrivacy` is not on the page yet, the SDK loads it through `Shopify.loadFeatures` (the `consent-tracking-api` feature, version 0.1) during initialization, so the API is ready before the visitor touches the banner. Nothing is written at this stage.
3. **Explicit decisions only.** Shopify's rule is that recording consent "should only be done on a visitor interaction" and "never done automatically on behalf of the visitor". The bridge follows it: regional default states are never written to Shopify. Only an actual decision is recorded, whether that is a fresh accept or reject, or a saved preference from an earlier visit.
4. **No redundant writes.** Before writing, the SDK reads Shopify's current record with `currentVisitorConsent` and skips the call when nothing has changed.

<Callout type="info">
  Shopify's API is a consent ledger, not a runtime switch. `setTrackingConsent` writes a durable first-party record (the `_tracking_consent` cookie plus a consent ID) that Shopify then applies to the tracking it controls.
</Callout>

How categories map to Shopify's signals [#how-categories-map-to-shopifys-signals]

Each explicit decision is translated from ConsentStack's consent categories into the four fields Shopify's API expects:

| ConsentStack category         | Shopify consent field |
| ----------------------------- | --------------------- |
| Analytics                     | `analytics`           |
| Marketing                     | `marketing`           |
| Functional                    | `preferences`         |
| Marketing, unless GPC applies | `sale_of_data`        |

`sale_of_data` is the one with a twist: it is granted only when the visitor consented to marketing and ConsentStack is not honoring a Global Privacy Control signal for them. When GPC applies, `sale_of_data` is recorded as denied even for a shopper who accepted marketing, which is what US state opt-out rules expect. See [Global Privacy Control](/docs/compliance/global-privacy-control) for how GPC is detected and honored.

What Shopify does with the record [#what-shopify-does-with-the-record]

Shopify applies it to everything it controls. The consent record gates Shopify Analytics, including the `_shopify_y` and `_shopify_s` session cookies and storefront page-view tracking, and every sandboxed web pixel, including pixels installed by apps. When the record says no, Shopify's own tracking holds back. When it says yes, it runs normally and your attribution stays intact.

Google Consent Mode v2 on Shopify [#google-consent-mode-v2-on-shopify]

Shopify's Customer Privacy API and Google Consent Mode v2 are two different signals, and a store that runs Google Ads or GA4 usually needs both. ConsentStack sends both from one decision:

* **Google tags loaded from your theme** (gtag.js or a Google Tag Manager container) receive Consent Mode v2 defaults before they load, with `ad_storage`, `ad_user_data`, `ad_personalization`, and `analytics_storage` denied until the visitor decides, then an update carrying the decision. Details in [Platform Integrations](/docs/developers/platform-integrations#google-consent-mode-v2).
* **Pixels installed through Shopify apps** run inside Shopify's web pixel sandbox and follow the Customer Privacy record described above rather than the browser-side Consent Mode signal.

What Shopify asks of a third-party banner [#what-shopify-asks-of-a-third-party-banner]

Shopify's Help Center lists three things to do when you replace its banner with a third-party one. All three take a few minutes:

1. **Remove Shopify's own banner** so shoppers do not see two. In the Shopify admin, go to **Settings > Customer privacy**, click **Cookie banner** in the Privacy settings section, then **More actions > Remove cookie banner**. Do this after the ConsentStack tags are live, since Shopify warns that removing its banner without a replacement can stop non-essential data from being collected.
2. **Name Shopify in your banner text.** Shopify's suggested wording is: "We and our partners, including Shopify, use cookies and other technologies to personalize your experience, show you ads, and perform analytics, and we will not use cookies or other technologies for these purposes unless you accept them. Learn more in our Privacy Policy." The banner title and description are editable in the [config builder](/docs/dashboard/config-builder).
3. **Link your privacy policy from the banner**, and make sure that policy itself links to the Shopify Consumer Privacy Policy. The banner's policy links are set in the config builder as well.

What about scripts Shopify does not control? [#what-about-scripts-shopify-does-not-control]

They are handled by [script blocking](/docs/concepts/script-blocking), not by this integration. Tags added to the theme directly (the Meta Pixel, TikTok, Klaviyo, heatmap tools) do not read Shopify's consent record, so ConsentStack blocks them in the browser until the visitor consents. The Shopify bridge never bypasses that blocking; it adds the Shopify side on top.

Platforms with native consent APIs of their own (Google, Meta, TikTok, Bing, and others) also get dedicated consent signaling, described in [Platform Integrations](/docs/developers/platform-integrations).

If you are not sure what actually fires on your store before consent, run it through the free [compliance scanner](https://www.consentstack.io/compliance-scanner). It loads your storefront in a real browser, declines the banner, and reports which trackers fired anyway, with the evidence attached.

FAQ [#faq]

Does ConsentStack integrate with Shopify's Customer Privacy API? [#does-consentstack-integrate-with-shopifys-customer-privacy-api]

Yes, automatically. On any Shopify storefront the SDK detects Shopify, loads the consent-tracking API, and records each explicit visitor decision with `setTrackingConsent`. There is no setting to turn on and no app to install.

Do I need a Shopify app to use ConsentStack? [#do-i-need-a-shopify-app-to-use-consentstack]

No. ConsentStack is a script install: three tags in `layout/theme.liquid`. The Customer Privacy integration, script blocking, and Consent Mode v2 all run from those tags.

Is Shopify's built-in cookie banner enough? [#is-shopifys-built-in-cookie-banner-enough]

Usually not on its own. Shopify's [help center](https://help.shopify.com/en/manual/privacy-and-security/privacy/customer-privacy-settings/privacy-settings) says its cookie banner "governs Shopify-specific tools, including cookies and Shopify Pixels", and a [Shopify Community answer](https://community.shopify.com/t/shopify-native-cookie-banner/355471) puts it plainly: the built-in banner controls the first-party cookies Shopify sets, not tags like Google Tag Manager or the Meta Pixel. For those, Shopify itself points merchants at a third-party banner integrated with the Customer Privacy API.

Does it work with Google Consent Mode v2 on a Shopify store? [#does-it-work-with-google-consent-mode-v2-on-a-shopify-store]

Yes. Google tags in your theme get Consent Mode v2 defaults and updates from ConsentStack, and Shopify's own pixels follow the Customer Privacy record. See [Google Consent Mode v2 on Shopify](#google-consent-mode-v2-on-shopify) above.

What happens when a shopper clicks Reject? [#what-happens-when-a-shopper-clicks-reject]

Shopify's record is written with `analytics`, `marketing`, `preferences`, and `sale_of_data` all denied, so Shopify Analytics and app pixels hold back. Tags in the theme stay blocked. The decision is stored in your [consent logs](/docs/dashboard/activity-and-insights), and the shopper can reopen the preferences panel later from the re-entry button.

What's next [#whats-next]

* [Cookie consent for Shopify](/platforms/shopify). The product overview for Shopify stores.
* [Script Blocking](/docs/concepts/script-blocking). How third-party tags are held until the visitor consents.
* [Platform Integrations](/docs/developers/platform-integrations). Native consent signaling for Google, Meta, TikTok, and more.
* [SDK Installation](/docs/developers/sdk-installation). The full install reference.


# Add a Cookie Banner to Squarespace (/docs/developers/squarespace)



import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Callout } from '@/components/fumadocs/callout';

Squarespace ships a cookie banner of its own, and it does a narrower job than most site owners expect. This page covers what the built-in banner actually controls, how to install ConsentStack alongside or instead of it, and how to check the result. For the product overview, see [Cookie consent for Squarespace](/platforms/squarespace).

What Squarespace's built-in banner covers [#what-squarespaces-built-in-banner-covers]

Squarespace's [cookie banner documentation](https://support.squarespace.com/hc/en-us/articles/206545727-Providing-cookie-consent-options-with-a-banner) describes the banner's purpose as preventing "Squarespace, and some third party integrations, from placing non-essential cookies on visitors' browsers until visitors accept them."

The scope is the part worth reading twice. Squarespace's [cookies reference](https://support.squarespace.com/hc/en-us/articles/360001264507-The-cookies-Squarespace-uses) states that the banner "disables or restricts cookies placed by some third-party services connected to your site, but not all."

Tags you add yourself sit outside that. Squarespace's own guidance is that if your site "has custom code injection that drops non-essential cookies, you may want to ensure your cookie banner can interact with the code," and it notes that custom code modifications fall outside the scope of Squarespace support.

In practice, Code Injection is exactly where tracking lives on a Squarespace site: Google Analytics, the Meta Pixel, TikTok, LinkedIn, heatmap tools. Those fire on page load unless something holds them back.

Install ConsentStack [#install-consentstack]

<Steps>
  <Step>
    Copy your install tags [#copy-your-install-tags]

    Get your site key from the [ConsentStack dashboard](https://app.consentstack.io), then take these three tags:

    ```html
    <link rel="preconnect" href="https://cdn.consentstack.io" />
    <script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
    <script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"></script>
    ```
  </Step>

  <Step>
    Open Code Injection [#open-code-injection]

    In your Squarespace site, go to **Website > Website Tools > Code Injection**. On older sites the same panel appears under **Settings > Advanced > Code Injection**.

    <Callout type="info">
      Code Injection is available on the Core, Plus, and Advanced plans, and on some legacy billing plans. If you do not see the panel, your plan does not include it.
    </Callout>
  </Step>

  <Step>
    Paste into the Header field [#paste-into-the-header-field]

    Paste all three tags into the **Header** field, at the very top, before anything already there. Squarespace injects this field into the `<head>` tag on every page of your site, which is what puts ConsentStack ahead of your other tags.

    <Callout type="warn">
      Do not add `defer` or `async` to either script tag, and keep both ahead of any other scripts in the Header field. The SDK installs its script observer at parse time. Anything that runs before the observer is active can fire before the visitor has consented.
    </Callout>
  </Step>

  <Step>
    Save and reload [#save-and-reload]

    Click **Save**, then open your site in a private window. The banner appears on first load. Trackers stay blocked until the visitor chooses.
  </Step>
</Steps>

Keep or turn off Squarespace's banner [#keep-or-turn-off-squarespaces-banner]

Running both banners shows visitors two consent prompts, which is confusing and makes your consent record ambiguous. Pick one.

**Turn Squarespace's banner off** if you want ConsentStack to be the single consent layer, which is the usual choice. Open **Settings > Website > Cookies & Data Privacy** and switch off the toggle beside **Cookie banner**, then click **Save**.

**Keep Squarespace's banner on** only if you specifically want Squarespace's own cookies governed by Squarespace's own toggle. Note that a visitor can then accept in one banner and decline in the other, and the two records will disagree.

Check what actually fires [#check-what-actually-fires]

Trust the network tab, not the banner. Open your site in a private window, decline consent, and watch for requests to domains like `google-analytics.com` or `connect.facebook.net`. Requests that appear after a decline mean tracking is running without consent.

The free [compliance scanner](https://www.consentstack.io/compliance-scanner) runs that check for you. It loads your Squarespace site in a real browser, interacts with the banner, and reports which trackers fired before and after consent with the evidence attached. The [testing and verification guide](/docs/guides/testing-and-verification) covers the manual version step by step.

Squarespace-specific notes [#squarespace-specific-notes]

**Tags added after the first page load are still caught.** Some Squarespace templates swap page content without a full browser refresh, and plenty of embeds inject their scripts late. ConsentStack watches the page for scripts added after parse time and holds them to the same consent rules as the ones that were there at load.

**The Header field is site-wide.** Squarespace injects it into the `<head>` tag on every page, so a single paste covers your whole site. There is no per-page install to repeat.

What's next [#whats-next]

* [Cookie consent for Squarespace](/platforms/squarespace). The product overview, including how the built-in banner compares.
* [Script Blocking](/docs/concepts/script-blocking). How third-party tags are held until the visitor consents.
* [Platform Integrations](/docs/developers/platform-integrations). Native consent signaling for Google, Meta, TikTok, and more.
* [SDK Installation](/docs/developers/sdk-installation). The full install reference.


# Theming Override Tokens (/docs/developers/theming-tokens)



The appearance settings in the dashboard set a small number of theme colors, and most banner elements inherit from them. The checked toggle track and focus ring inherit from your primary color, the unchecked track from your muted color, and the toggle thumb from your background color. For most themes that inheritance is exactly what you want.

Sometimes a design pins one of those parent colors. A common example: giving Accept and Reject buttons identical styling for equal prominence forces the primary color to a value that works poorly as a toggle accent or focus ring, especially on dark themes. For those cases, the SDK exposes override tokens that break the inheritance for one role at a time.

Available tokens [#available-tokens]

| Token                       | Inherits from        | Controls                                                       |
| --------------------------- | -------------------- | -------------------------------------------------------------- |
| `--cs-toggle-checked-color` | `--cs-color-primary` | Track color of a checked toggle                                |
| `--cs-toggle-track-color`   | `--cs-color-muted`   | Track color of an unchecked toggle                             |
| `--cs-toggle-thumb-color`   | `--cs-color-bg`      | The toggle thumb                                               |
| `--cs-focus-ring-color`     | `--cs-color-primary` | Keyboard focus rings on buttons, toggles, and the close button |
| `--cs-color-primary-border` | `transparent`        | Border of primary buttons (Accept All, Save Preferences)       |
| `--cs-prefs-max-width`      | `550px`              | Preferences modal width (modal layout only)                    |
| `--cs-prefs-max-height`     | `85vh`               | Preferences modal height (modal layout only)                   |

Every token falls back to its parent when unset, so you only declare the ones you want to change. On screens smaller than 768px, the preferences modal automatically fills the screen, so the width and height tokens don't apply.

Setting tokens [#setting-tokens]

Declare them on `#consentstack-root` in the Custom CSS field of the dashboard's Appearance tab (Pro plan and above), or in your own site stylesheet on any plan:

```css
#consentstack-root {
  --cs-toggle-checked-color: #ff5722;
  --cs-focus-ring-color: #ff5722;
  --cs-toggle-thumb-color: #ffffff;
  --cs-prefs-max-width: 800px;
}
```

That is the whole pattern. The SDK's stylesheet reads these variables directly, so there is no specificity to fight and no selectors to reverse-engineer.

A dark theme example [#a-dark-theme-example]

Suppose your banner background is dark and you style Accept and Reject identically for equal prominence, which pins your primary color to a dark value. Without overrides, the checked toggle track, thumb, and focus ring all inherit colors that vanish against the dark surface. With overrides:

```css
#consentstack-root {
  /* brand accent for state indicators */
  --cs-toggle-checked-color: #ff5722;
  --cs-focus-ring-color: #ff5722;
  /* keep the thumb visible on both track states */
  --cs-toggle-thumb-color: #ffffff;
  --cs-toggle-track-color: #3a3f47;
  /* give the primary button a visible boundary */
  --cs-color-primary-border: #3a3f47;
}
```

Disabled toggles need no override: the SDK blends the track toward your background color automatically, so the required Essential category stays legible on light and dark themes.


# Getting Started (/docs/getting-started)



import { Step, Steps } from 'fumadocs-ui/components/steps';

Go from zero to a fully working consent banner in four steps. No code required except pasting three tags (a preconnect hint plus stub plus core).

<Steps>
  <Step>
    Create your account [#create-your-account]

    Head to [app.consentstack.io/login](https://app.consentstack.io/login) and sign in with Google or your email address. If you use email, you'll get a one-time verification code to confirm your account.
  </Step>

  <Step>
    Create a workspace [#create-a-workspace]

    After signing in, you'll be prompted to create a workspace. Enter a name and ConsentStack generates a URL-friendly slug automatically.

    Workspaces organize your sites, members, and billing in one place. Even if you're working solo, you need one workspace to get started.
  </Step>

  <Step>
    Add a site [#add-a-site]

    Inside your workspace, click to create a new site. Give it a name like "Marketing Site" or "Blog." ConsentStack will:

    * Generate a unique **Site Key** for your site
    * Publish a default consent configuration so your banner works immediately

    You'll find your Site Key on the site's overview page. It looks like this: `<YOUR_SITE_KEY>`
  </Step>

  <Step>
    Embed the script tags [#embed-the-script-tags]

    Add these three tags to your website's `<head>`, replacing `<YOUR_SITE_KEY>` with the key from the previous step:

    ```html
    <link rel="preconnect" href="https://cdn.consentstack.io" />
    <script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
    <script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"></script>
    ```

    That's it. The SDK (\~48 KB total, stub + core) fetches your consent configuration, detects the visitor's location, and displays the right consent banner, all automatically.

    Using a website builder? There are step-by-step install walkthroughs for [Squarespace](/platforms/squarespace), [Webflow](/platforms/webflow), and [WordPress](/platforms/wordpress).
  </Step>
</Steps>

Verify it's working [#verify-its-working]

Open your site in a browser. You should see the consent banner appear. If something looks off, check our [Testing & Verification guide](/docs/guides/testing-and-verification).

What happens next [#what-happens-next]

* **Third-party scripts are blocked automatically.** ConsentStack detects trackers on your page and prevents them from running until your visitor consents. [Learn how script blocking works.](/docs/concepts/script-blocking)
* **The right rules apply to every visitor.** Visitors in the EU see GDPR opt-in banners, visitors in California see CCPA-style notices, and everyone else gets a simple acknowledgement, no configuration needed. [Explore consent models.](/docs/concepts/consent-models)
* **Every consent decision is logged.** Accepts, rejections, and preference changes are recorded with a privacy-first audit trail. No personal data is stored. [See how categories and regions work.](/docs/concepts/categories-and-regions)
* **Coming from another CMP? Your visitors may not need to choose again.** If you are migrating from Cookiebot, we can carry over the choices your visitors already made so they are not asked twice. [See how consent import works.](/docs/concepts/consent-import)


# Guides (/docs/guides)



Task-shaped walkthroughs for the two things people most often need help with: moving over from another consent platform, and proving the setup actually works before you rely on it.

For conceptual background, see [Core Concepts](/docs/concepts). For install steps, see [Getting Started](/docs/getting-started).

Migration from Other CMPs [#migration-from-other-cmps]

Switching from Cookiebot, OneTrust, CookieYes, Termly, or Osano. Each platform has its own leftovers: inert script tags that survive removal, global variables other tags still reference, plugins that re-inject the tag after you delete it. This guide covers what transfers, what does not, and the per-vendor steps.

Testing & Verification [#testing--verification]

Debug mode, testing geo-detection without a VPN, and the pre-launch checklist. Use this to confirm scripts really are blocked before consent, rather than assuming they are.


# Migration from Other CMPs (/docs/guides/migration)



import { TRACKER_PATTERN_COUNT_DISPLAY } from '@/lib/headline-numbers';

This guide is for site owners moving a website from one consent management platform to another. The actual swap is one script tag out, three tags in (a preconnect hint plus two script tags). The real work is a few minutes of preparation and one decision about your old consent records.

**Looking for something else?** To update billing details or hand your account to a colleague, use your current provider's admin area, not this guide. If you are a visitor who wants to change a cookie choice on a site you do not run, look for the privacy or cookie settings link in that site's footer.

**Jump to your current platform:** [Cookiebot](#migrating-from-cookiebot), [OneTrust](#migrating-from-onetrust), [CookieYes](#migrating-from-cookieyes), [Termly](#migrating-from-termly), [Osano](#migrating-from-osano).

Will I lose my consent records when I switch? [#will-i-lose-my-consent-records-when-i-switch]

We move your historical consent log across for you during onboarding, so your audit trail for the period before the switch ends up in the same place as everything after it. The one part only you can do is pull the export from your old provider before you cancel, because we cannot sign into their dashboard on your behalf. Tell us you want it and we will say exactly what to export.

Your visitors' current choices are a separate question, with a better answer. Whichever platform you are leaving, we can turn on [consent import](/docs/concepts/consent-import) for your site. It reads the decision your old platform already stored in each visitor's browser and honors it, so people who accepted stay accepted and people who declined stay declined. Cookiebot is built and running today; for any other platform we build the connector for you before your cutover, so tell us what you are migrating from during onboarding. Without import, ConsentStack starts a fresh log from the day you go live.

Those are two separate questions, and most platforms answer only one of them. We compared what every major CMP commits to on each, read from their own documentation, in [do you lose your visitors' consent when you switch CMPs?](/compare/consent-migration)

Either way, that export matters more than the platform you keep it in. If a regulator asks you to evidence consent for a visit that happened last year, what you need is the record of that visit, not the vendor who stored it.

From go-live, ConsentStack records every decision with a timestamp and the config version that produced it, viewable in your site dashboard and exportable as CSV. Log retention is 30 days on Pro and 1 year on Business.

<Callout type="warn">
  Export your consent records **before** you cancel your old subscription. Most providers cut off dashboard access at the end of the billing period, and some tiers never included consent logs in the first place. Check the notes in your platform's section below.
</Callout>

Before you start [#before-you-start]

Take a quick inventory of your current setup. You'll want this information handy when configuring ConsentStack.

* **Consent records**: Export them from your current provider and store the file somewhere durable. This is the one thing you cannot recreate later.
* **Consent categories**: List every cookie category your current CMP uses. Note which ones are essential and which are optional.
* **Custom integrations**: Do you have any scripts that listen for consent events from your current CMP? Note these so you can reconnect them using ConsentStack's JavaScript API.
* **Regulation settings**: Which regions are you covering? GDPR for Europe, CCPA for California, or others? Write down which consent model (opt-in, opt-out, notice) applies to each region.
* **Banner customizations**: Note any brand colors, custom text, or layout preferences you've set up. You'll recreate these in ConsentStack's config builder.

This inventory typically takes five to ten minutes and saves time during setup.

Set up ConsentStack [#set-up-consentstack]

If you haven't already, follow the [Quickstart guide](/docs/getting-started) to create your account, workspace, and site. Then configure your consent settings to match your current setup:

1. **Map your categories**: ConsentStack ships with three categories enabled by default: Essential, Analytics, and Marketing. Functional is a standard category too, but it is off until you add it, so switch it on if your current CMP separates preferences or personalization from analytics. Add custom categories if your current CMP uses non-standard groupings. The per-platform tables below give you the mapping.
2. **Set up your regions**: ConsentStack ships with built-in regions for GDPR, US State Privacy Laws, and a default for everyone else. Review the consent models assigned to each region and adjust if needed to match your current configuration.
3. **Customize your banner**: Use the config builder to match your brand colors, button styles, and banner text. This is also a good time to improve wording if your current banner language was unclear.
4. **Publish your config**: Once everything looks right, publish the configuration so it's ready to serve visitors.

The swap [#the-swap]

This is the easy part. You're replacing one line of code with another.

**Remove your old CMP script tag.** Find the script tag for your current provider in your site's `<head>` and delete it. It looks something like:

| Provider  | What to remove                                                              |
| --------- | --------------------------------------------------------------------------- |
| Cookiebot | `<script>` tag referencing `consent.cookiebot.com`                          |
| OneTrust  | `<script>` tag referencing `cdn.cookielaw.org` (or `eu1.cdn.cookielaw.org`) |
| CookieYes | `<script>` tag referencing `cdn-cookieyes.com` (or `cdn.cookieyes.com`)     |
| Termly    | `<script>` tag referencing `app.termly.io`                                  |
| Osano     | `<script>` tag referencing `cmp.osano.com`                                  |

**Add the ConsentStack tags.** Paste these in the same location, replacing `<YOUR_SITE_KEY>` with your site key from the dashboard:

```html
<link rel="preconnect" href="https://cdn.consentstack.io" />
<script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
<script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"></script>
```

Deploy your site. That's the entire swap.

If your old CMP was installed through a plugin or an app rather than pasted into your theme, removing the tag is not enough. Deactivate the plugin too, or it will keep injecting the old script on the next page build.

What to expect after switching [#what-to-expect-after-switching]

**By default, returning visitors will see the consent banner again.** ConsentStack uses its own consent storage, so unless consent import is switched on it does not read the cookie your old CMP set, and every visitor starts fresh.

That default is fine for compliance. Fresh consent means your visitors are making informed decisions based on your current banner, not a choice they made months ago under different wording or categories. Auditors and regulators view re-consent favorably, and after a few days the vast majority of your traffic will have provided fresh consent through ConsentStack.

**You can skip the re-prompt.** With [consent import](/docs/concepts/consent-import) enabled, returning visitors who made an explicit choice under your old platform keep it, the banner stays hidden for them, and the original decision is written into your ConsentStack log with the old consent ID and timestamp attached. Cookiebot is built and running today; for any other platform we build the connector before your cutover. Ask us to switch it on.

Verify your migration [#verify-your-migration]

Once the new script tags are live, confirm everything is working:

1. **Check the banner**: Open your site in a browser (or an incognito window). You should see the ConsentStack banner appear.
2. **Scan the live site**: Run your URL through the free [cookie checker](/tools/cookie-checker) to see which trackers fire before consent. This is the fastest way to catch a leftover tag from your old CMP.
3. **Review consent logs**: Head to your site dashboard and check that consent decisions are being recorded.
4. **Enable debug mode**: Add `data-debug="true"` to the core script tag temporarily to see detailed console output about category resolution, script blocking, and consent state.
5. **Test across regions**: If you have a VPN, test from different locations to verify the correct consent model appears for each region.

For a complete verification walkthrough, see the [Testing & Verification guide](/docs/guides/testing-and-verification).

Migrating from Cookiebot [#migrating-from-cookiebot]

**Remove:** the script referencing `consent.cookiebot.com`, plus the WordPress plugin if you installed it that way. Cookiebot also loads a hidden `consentcdn.cookiebot.com` frame, which disappears with the main tag.

**Map your categories:**

| Cookiebot category | ConsentStack equivalent                   |
| ------------------ | ----------------------------------------- |
| Necessary          | Essential                                 |
| Preferences        | Functional (add it, it is off by default) |
| Statistics         | Analytics                                 |
| Marketing          | Marketing                                 |

**Watch for inert script tags.** If you ran Cookiebot in auto-blocking mode, it rewrote your third-party tags in place, changing `src` to `data-cookieblock-src` and `type` to `text/plain` so the browser would skip them. Those rewrites can persist in cached pages, in templates a developer hand-edited to match, and in any tag you copied from a Cookiebot support article. A tag left in that state stays dead after Cookiebot is gone, so a script you expect to fire silently never does. Our teardown of [how script blocking works](/blog/how-script-blocking-works) decodes the full attribute set and its ConsentStack equivalent.

If you were relying on Cookiebot's auto-scan, ConsentStack's built-in script blocking with {TRACKER_PATTERN_COUNT_DISPLAY} known tracker patterns provides equivalent coverage, with no tag rewriting on your pages. Side-by-side detail is on the [Cookiebot comparison](/compare/cookiebot).

Migrating from OneTrust [#migrating-from-onetrust]

**Remove:** the script referencing `cdn.cookielaw.org` (EU accounts use `eu1.cdn.cookielaw.org`), and any `OptanonWrapper` function you defined in your own code.

**Map your categories:**

| OneTrust category          | ConsentStack equivalent                   |
| -------------------------- | ----------------------------------------- |
| Strictly Necessary (C0001) | Essential                                 |
| Performance (C0002)        | Analytics                                 |
| Functional (C0003)         | Functional (add it, it is off by default) |
| Targeting (C0004)          | Marketing                                 |
| Social Media (C0005)       | Marketing, or a custom category           |

**Rewire your custom code.** OneTrust integrations tend to accumulate references to `OnetrustActiveGroups`, the `OptanonConsent` cookie, and the `OptanonWrapper` callback. Search your codebase and your tag manager for those three names, then reconnect each one to ConsentStack's JavaScript API. Anything you miss will read a cookie that no longer exists and quietly behave as if consent was never given.

Category IDs are the other thing to check. OneTrust setups often carry custom groups beyond C0005, and those need a matching ConsentStack category before you publish. See the [OneTrust comparison](/compare/onetrust) for a feature-level view.

Migrating from CookieYes [#migrating-from-cookieyes]

**Remove:** the script referencing `cdn-cookieyes.com` or `cdn.cookieyes.com`. If you installed CookieYes as a WordPress plugin, deactivate the plugin as well. Deleting the tag alone leaves the plugin free to re-inject it.

**Map your categories:**

| CookieYes category | ConsentStack equivalent                   |
| ------------------ | ----------------------------------------- |
| Necessary          | Essential                                 |
| Functional         | Functional (add it, it is off by default) |
| Analytics          | Analytics                                 |
| Performance        | Analytics                                 |
| Advertisement      | Marketing                                 |

**Two categories collapse into one.** CookieYes splits Analytics and Performance, and most sites end up using them for the same class of tracker. Merging both into ConsentStack's Analytics is usually right. If you genuinely gave visitors a separate choice for each, create a custom category so nobody's earlier preference gets widened by the move.

Export your consent records before you cancel. CookieYes offers a CSV export of consent logs from the dashboard, and that file is your audit trail for the period before the switch. The [CookieYes comparison](/compare/cookieyes) covers the rest of the differences.

Migrating from Termly [#migrating-from-termly]

**Remove:** the script referencing `app.termly.io`, including the resource blocker tag if you use Termly's Auto Blocker.

**Map your categories:**

| Termly category             | ConsentStack equivalent                   |
| --------------------------- | ----------------------------------------- |
| Essential                   | Essential                                 |
| Performance & Functionality | Functional (add it, it is off by default) |
| Analytics & Customization   | Analytics                                 |
| Advertising                 | Marketing                                 |
| Social Networking           | Marketing, or a custom category           |
| Unclassified                | Review each cookie, then assign it        |

**Check whether you have records to export at all.** Termly gates consent logs to its Pro tier and above. On the Free and Starter plans there is no consent log to take with you, so your audit trail effectively begins the day you go live on ConsentStack. Worth knowing before you tell an auditor otherwise.

**Deal with Unclassified before you publish.** Termly's scanner leaves cookies it cannot identify in an Unclassified bucket, and sites often let that bucket sit for months. Do not carry it across. Assign each cookie to a real category, because an unassigned tracker on a GDPR page is the exact thing an enforcement action looks for. The [Termly comparison](/compare/termly) has more.

Migrating from Osano [#migrating-from-osano]

**Remove:** the script referencing `cmp.osano.com`.

**Map your categories:**

| Osano category  | ConsentStack equivalent                         |
| --------------- | ----------------------------------------------- |
| Essential       | Essential                                       |
| Analytics       | Analytics                                       |
| Marketing       | Marketing                                       |
| Personalization | Functional (add it, it is off by default)       |
| Opt-Out         | Handled by your US region rules, not a category |
| Storage         | IAB TCF specific, no direct equivalent          |

**Two of those are not really categories.** Osano's Opt-Out and Storage switches belong to IAB frameworks rather than to your cookie taxonomy. Opt-Out is the "Do Not Sell or Share" control that US state laws require, which ConsentStack expresses as the consent model on your US State Privacy Laws region. Storage only applies if you enabled TCF. Neither needs a ConsentStack category.

**You may have nothing to export.** Osano's free tier does not include consent storage, so if you were on it, there are no historical records to move. Paid plans do store consent, and you should pull that export before the subscription lapses. See the [Osano comparison](/compare/osano) for the wider picture.

<Callout type="info">
  No matter which CMP you're migrating from, ConsentStack detects your visitors' locations automatically and applies the right consent model. No manual geo-targeting rules to recreate.
</Callout>

What's next [#whats-next]

* [Testing & Verification guide](/docs/guides/testing-and-verification). Confirm your migration is working correctly.
* [Categories & Regions](/docs/concepts/categories-and-regions). Fine-tune your consent rules.
* [How script blocking works](/blog/how-script-blocking-works). Decode the blocking attributes your old CMP left behind.
* [Dashboard guide](/docs/dashboard/overview). Explore banner customization and consent logs.


# Testing & Verification (/docs/guides/testing-and-verification)



import { Callout } from '@/components/fumadocs/callout';

Before going live, you want to be confident that your consent banner works exactly as configured: scripts are blocked, consent signals reach your analytics platforms, and logs appear in your dashboard. This guide walks you through every step.

Enable debug mode [#enable-debug-mode]

ConsentStack includes two levels of debugging that you can activate on the core script tag.

**Console logging** adds `data-debug="true"` to your embed snippet. This prints every SDK event (config loaded, consent set, scripts blocked, platform signals) directly to your browser's developer console, prefixed with `[ConsentStack]`.

```html
<link rel="preconnect" href="https://cdn.consentstack.io" />
<script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
<script
  src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"
  data-debug="true"
></script>
```

**Visual debug panel** adds `data-debug-panel="true"` for a real-time overlay on your page. The panel shows your current config, detected region, consent state, blocked and activated scripts, platform adapters, and a live event log, all updating as you interact with the banner.

```html
<link rel="preconnect" href="https://cdn.consentstack.io" />
<script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
<script
  src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"
  data-debug="true"
  data-debug-panel="true"
></script>
```

Toggle the panel with **Ctrl+Shift+D** or click the collapse button on the panel header.

<Callout type="warn">
  Remove both debug attributes before going live. They are development tools and should not be present in production.
</Callout>

Test on a live site without showing the banner [#test-on-a-live-site-without-showing-the-banner]

If your site is already receiving traffic while you're still configuring consent, turn on **Test mode** in the Config Builder's [Settings tab](/docs/dashboard/config-builder). Real visitors see no banner and nothing is blocked, while you load any page with `?cs-test-mode=true` to see and test the banner exactly as it will ship. The activation sticks for the rest of your browser tab, so you can click through the whole site.

Tracker detection keeps running while test mode is on, so your inventory fills in from real traffic as you work. Everything below in this guide can be verified this way before a single visitor sees a banner.

<Callout type="warn">
  Test mode leaves real visitors with no working consent banner, so it's a pre-launch tool rather than a way to quiet the banner on a live site. Turn it off and publish before you launch.
</Callout>

Verify the banner [#verify-the-banner]

With debug mode on, load your page and confirm:

* **The banner appears** in the layout and position you configured (bottom bar, modal, etc.).
* **Text and buttons match your config**: check the headline, body copy, and button labels.
* **Buttons work**: click Accept All, Reject All, and open the preferences center. Each interaction should dismiss the banner and update consent state in the debug panel or console.

Verify script blocking [#verify-script-blocking]

Open your browser's developer tools and go to the **Elements** tab.

* **Before consent:** Third-party scripts that require consent should show `type="application/cs-blocked"` on their `<script>` tags. This means ConsentStack has intercepted and blocked them. (The legacy ScriptBlocker class still uses `text/plain` for the tracker-sync detection beacon; the request-blocking stub uses `application/cs-blocked`.)
* **After consent:** Accept all categories, then check the same scripts. They should now have their original `type` restored and be executing normally.

The debug panel's **Scripts** section gives you a quick count of detected, blocked, and activated scripts, so you can confirm the numbers match what you see in the DOM.

Verify Google Consent Mode [#verify-google-consent-mode]

If you use Google Analytics or Google Ads, ConsentStack automatically sends Google Consent Mode v2 signals. To verify:

1. Install the [Google Tag Assistant](https://tagassistant.google.com/) browser extension.
2. Load your page and open Tag Assistant.
3. **Before consent**, confirm that `analytics_storage`, `ad_storage`, `ad_user_data`, and `ad_personalization` show as `denied`.
4. **Accept consent**, then check that the relevant signals update to `granted`.

The debug panel's **Platforms** section also shows which adapters are active and whether native consent signals are being sent.

For what each signal controls, the difference between basic and advanced mode, and the June 15, 2026 change that made Consent Mode the single control over Google Ads data, see the [Consent Mode v2 setup guide](/blog/google-consent-mode-v2-setup).

Test geo-detection [#test-geo-detection]

ConsentStack detects visitor location automatically using Cloudflare's geo-detection headers. To verify the banner behaves correctly for different regions, use a VPN or your browser's location override to simulate visitors from different locations.

Test a few key scenarios:

| Visitor location   | Expected behavior                                            |
| ------------------ | ------------------------------------------------------------ |
| EU country         | Opt-in banner (GDPR); scripts blocked until consent          |
| California (US-CA) | Opt-out banner (CCPA/CPRA); scripts run, visitor can opt out |
| Other US states    | Notice-only or no banner, depending on your config           |

The debug panel's **Resolution** section shows the resolved region, consent model, and language for the current session; use it to confirm the SDK detected the correct location.

Check consent logs [#check-consent-logs]

After interacting with the banner, open your ConsentStack dashboard and navigate to the **Activity** page. You should see consent events appearing within a few seconds. Verify:

* The **consent categories** match what you selected.
* The **region** matches where you are testing from.
* The **event type** reflects the interaction (accepted, rejected, or custom preferences).

If logs are not appearing, check that your site's domain is registered in your dashboard settings and that your site key matches.

Pre-launch checklist [#pre-launch-checklist]

Run through this list before removing debug mode and going live:

* [ ] **Banner renders correctly**: appears on page load with the right layout, text, and branding
* [ ] **All buttons work**: Accept All, Reject All, preferences center, and Save Preferences all behave as expected
* [ ] **Scripts are blocked before consent**: third-party scripts show `type="application/cs-blocked"` in the Elements tab. (The legacy ScriptBlocker class still uses `text/plain` for the tracker-sync detection beacon; the request-blocking stub uses `application/cs-blocked`.)
* [ ] **Scripts activate after consent**: blocked scripts execute once the relevant category is accepted
* [ ] **Google Consent Mode signals fire**: Tag Assistant confirms `granted`/`denied` states update correctly
* [ ] **Consent logs appear in the dashboard**: events show up on the Activity page after interacting with the banner
* [ ] **Geo-detection works**: banner adapts correctly when testing from different locations (EU, US-CA, other US states)
* [ ] **Re-entry button visible**: after dismissing the banner, visitors can reopen preferences via the floating button
* [ ] **Domains registered**: your production domain is added in your dashboard site settings
* [ ] **Correct plan active**: your billing plan supports the traffic and features you need
* [ ] **Debug attributes removed**: `data-debug` and `data-debug-panel` are not in your production snippet
* [ ] **Test mode off**: if you used it while configuring, turn it off in the Settings tab and publish, or real visitors keep getting no banner

How do you verify any consent tool actually blocks before consent? [#how-do-you-verify-any-consent-tool-actually-blocks-before-consent]

Open the site in a fresh browser profile, open the network tab before the page loads, and answer nothing. Every request to a third-party analytics or advertising domain that appears while the banner is still sitting there is a request that happened without consent. The test takes about two minutes and works on any consent tool, including ones that are not ConsentStack.

This is worth doing yourself rather than reading it off a feature list. Vendor pages describe tag rewriting, request interception, and consent signalling with the same phrases ("prior blocking", "auto-blocking", "blocks third-party scripts"), and those mechanisms behave differently. See [script blocking](/docs/concepts/script-blocking#what-does-blocks-scripts-before-consent-actually-mean) for what separates them.

The test [#the-test]

1. **Start clean.** Open a private or fresh browser profile so no consent cookie from a previous visit is present. An existing consent record makes any tool look like it is behaving.
2. **Open devtools first, then load the page.** Go to the Network tab and make sure recording is on before you navigate. Requests fired during initial load are the ones that matter, and they are gone if you open devtools late.
3. **Answer nothing.** Leave the banner untouched and read the request list. Filter out your own domain and the consent tool's own SDK, which is allowed to load.
4. **Then click Reject and keep watching.** Some tools block cleanly on load and then fire anyway once a decision is recorded.

What the results mean [#what-the-results-mean]

| What you see                                                       | What it means                                                                                         |
| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| Requests to analytics or ad domains **before you answer**          | Not blocking. Whatever the tool is doing, those third parties already have your visitor's IP address. |
| Nothing before you answer, but requests **after you click Reject** | The tool is treating a rejection as permission to load anyway, or a tag escaped its blocking rules.   |
| Requests present, but carrying a "consent denied" parameter        | Consent signalling, not blocking. The connection was still made.                                      |
| No third-party requests until you opt in                           | Blocking. This is the behaviour to look for.                                                          |

<Callout type="info">
  The consent tool's own SDK loading before consent is normal and expected. It has to load in order to ask the question. Exclude it, and judge everything else.
</Callout>

Why this matters more than it sounds [#why-this-matters-more-than-it-sounds]

We scanned 912 sites running four major consent tools in July 2026. **829 of them, 91%, fired a genuine third-party request before the visitor answered the banner**, excluding the consent tool's own SDK. Of the sites where Reject was actually clickable, 24% kept firing an analytics or marketing tracker after the visitor clicked it.

The four tools clustered closely, so this is not one bad vendor. Blocking depends on how a tool is deployed and on how much of the request surface it covers, which is why the test above is worth running on your own site rather than assumed from a feature list. Full method and per-tool numbers are in the [cookie compliance by consent tool study](/research/cookie-compliance-by-cmp).

If you would rather not do it by hand, the [free cookie checker](/tools/cookie-checker) runs this same test automatically and reports what fired before consent.

What's next [#whats-next]

Once everything checks out, remove the debug attributes from the core script tag and deploy. Your consent banner is live.

If you run into issues, the [JavaScript API](/docs/developers/javascript-api) reference covers programmatic access to consent state, and the [SDK Installation](/docs/developers/sdk-installation) guide has troubleshooting tips for common setup problems.