Consent

Overview

Anchor link for Overview

Cookie Control manages consent through three complementary mechanisms:

• Integrations — declare which third-party scripts or integrations should be blocked until a category is accepted. Cookie Control manages their lifecycle automatically.
• Script attributes — annotate existing inline scripts with data attributes so Cookie Control can gate them without any configuration object.
• Window Event API — subscribe to consent change events in your own scripts when you need custom behaviour on accept or revoke.

Categories

Anchor link for Categories

Categories group related cookies and scripts under a single consent decision presented to the user. Each category has a name used internally, a label shown in the banner, and a description.

"categories": [
  {
    "name": "analytics",
    "label": "Analytics",
    "description": "Analytical cookies help us to improve our website by collecting and reporting information on its usage."
  },
  {
    "name": "marketing",
    "label": "Marketing",
    "description": "We use marketing cookies to help us improve the relevancy of suggested content and advertising campaigns."
  }
]

The name value is used throughout — in integration definitions, script attributes, and the event API. Keep it lowercase and consistent.

Services

Anchor link for Services

Integrations are the primary way to declare which third-party scripts Cookie Control should block and manage. Each service is tied to one or more categories and is only activated once the user has consented.

"services": [
  {
    "id": "example-tracker",
    "category": "marketing",
    "type": "script",
    "src": "https://www.example.com/js?id=UA-XXX"
  },
  {
    "id": "google-consent-mode-v2",
    "type": "integration",
    "category": ["analytics", "marketing"],
    "initialRun": true,
    "options": {
      "containerId": "GTM-MR5K6VGJ"
    }
  }
]

type: script

A generic catch-all for any third-party tracking script. When consent to the specified category is granted, Cookie Control creates the script element and appends it to the page. The src field is the URL of the script to load.

type: integration

Integrations are predefined, platform-specific handlers shipped with Cookie Control itself. They work like prepared statements in database queries — the logic is fixed and vetted, so there is no opportunity for arbitrary code injection. Integrations accept platform-specific options (such as a GTM container ID) rather than a raw script URL.

Responding to consent changes

Anchor link for Responding to consent changes

If you need to run custom javascript when a user accepts or revokes consent to a category — you can subscribe to consent change events using window.CookieControl.onConsentChange().

Mark the script as necessary so it is never blocked by Cookie Control itself:

<script data-consent-necessary>
    window.CookieControl.onConsentChange('analytics', {
        onAccept: () => {console.log('User Handler - analytics accepted')},
        onRevoke: () => {console.log('User Handler - analytics revoked')}
    })
</script>

Pass the category name as the first argument and an object with onAccept and/or onRevoke callbacks as the second. Either callback is optional — you can supply just one if you only need to respond to one direction of consent change.

Consent Exception

Anchor link for Consent Exception

You can automatically enable the category of cookies via implied consent before any user interaction. By default, all optional categories require explicit user consent before they are enabled.

When active, this option creates an exception and enables the category prior to any user action. This should only be done if the category falls within a recognised consent exception such as statistical purposes, appearance settings, or emergency assistance.