Documentation

Everything you need to know about configuring and deploying a cookie banner

Getting Started

ConsentBadge is a visual cookie consent banner builder with full support for Google Consent Mode v2. The output is standalone HTML/CSS/JS code that you can add to your website via Google Tag Manager or directly into HTML.

Quick start in 3 steps

  1. Open the builder — navigate to /builder and pick a template you like, or start from scratch.
  2. Customize design and texts — set colors, fonts, cookie categories, banner texts, and advanced options like Consent Mode or multilingual support.
  3. Export and deploy — copy the generated code and paste it into GTM as a Custom HTML tag, or directly into your HTML page.

Requirements

The builder itself only requires a modern browser (Chrome, Firefox, Safari, Edge). To deploy the banner on your website, you need either access to Google Tag Manager or the ability to edit the HTML code of your website.

Tip

The generated banner has no external dependencies. It is pure HTML/CSS/JS under 30 KB in size.

Builder Overview

The builder is divided into five tabs. Each tab focuses on a different aspect of the banner configuration.

Presets

Choose from 12 pre-configured designs. A preset fills in colors, fonts, and layout — you can customize everything further.

Design

Set background colors, text, buttons, corner radius, shadows, font, and other visual properties of the banner.

Categories

Define cookie categories (analytical, preferences, marketing). Add descriptions and set default states.

Texts

Edit banner texts for each language — heading, description, button labels, and cookie policy.

Advanced

Configure Google Consent Mode v2, regional settings, multilingual support, API key for server-side consent, and more.

Tip

Use presets for a quick start. A preset sets sensible default values and you only adjust what you need.

GTM Deployment

Google Tag Manager is the recommended deployment method. The banner loads before other tags thanks to the Consent Initialization trigger, which ensures correct functioning of Google Consent Mode.

Step 1: Open Google Tag Manager

Log in to tagmanager.google.com and select the container for your website.

Step 2: Create a new tag

Click Tags → New → Tag Configuration → Custom HTML.

Step 3: Paste the code from the builder

In the builder, click the Export code button and copy the entire generated HTML code. Paste it into the Custom HTML field in GTM.

Step 4: Set the trigger

In the Triggering section, select Consent Initialization - All Pages. This trigger ensures the banner loads first — before all other tags are initialized.

Step 5: Publish the container

Save the tag, click Submit, and publish the new container version. The banner will immediately start appearing on your website.

Why Consent Initialization?

The Consent Initialization trigger fires first — even before All Pages. This allows the banner to set the default consent state (consent default) before GA4, Facebook Pixel, or other tags run. Without this trigger, tags could send data before the user has given consent.

Direct Embed

If you are not using Google Tag Manager, you can embed the banner directly in the HTML code of your page. Insert the exported code just before the closing </body> tag.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My website</title>
</head>
<body>

  <!-- Page content -->
  <h1>Welcome to my website</h1>

  <!-- ConsentBadge banner — insert before </body> -->
  <script>
    // Paste the code from the builder here
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag("consent", "default", {
      ad_storage: "denied",
      ad_user_data: "denied",
      ad_personalization: "denied",
      analytics_storage: "denied",
      functionality_storage: "denied",
      personalization_storage: "denied",
      security_storage: "granted",
      wait_for_update: 500
    });
  </script>

</body>
</html>

Important

When embedding directly, make sure the banner code loads before Google Analytics, Facebook Pixel, and other scripts. Place the consent default block as high as possible in the <head> and the banner itself before </body>.

Google Consent Mode v2

Google Consent Mode v2 allows Google tags (GA4, Google Ads, Floodlight) to adapt their behavior based on the user's consent state. ConsentBadge implements both required commands: consent default (default state on page load) and consent update (update after user interaction with the banner).

Mapping categories to consent types

ConsentBadge uses 4 cookie categories that map to 7 Google consent types:

Google Consent TypeBanner categoryDefault state
ad_storageMarketingdenied
ad_user_dataMarketingdenied
ad_personalizationMarketingdenied
analytics_storageAnalyticaldenied
functionality_storagePreferencesdenied
personalization_storagePreferencesdenied
security_storageStrictly necessarygranted

Region configuration

In the builder's advanced settings, you can restrict the default consent state to specific regions (e.g. EU/EEA). Outside the selected regions, consent is automatically set to granted. This corresponds to the consentModeRegions parameter in the configuration.

// Example: consent default for EU only
gtag("consent", "default", {
  ad_storage: "denied",
  analytics_storage: "denied",
  // ... other consent types
  region: ["CZ", "SK", "DE", "AT", "PL"]
});
Google recommends setting wait_for_update to 500 ms. ConsentBadge sets this value automatically so that tags wait for the user to interact with the banner.

JavaScript API

ConsentBadge exposes a JavaScript API via the global window.OSCBR object. Using the API, you can programmatically work with consents, reopen the banner, or clean up the instance for SPAs.

Banner instance

// Access the instance
const banner = window.OSCBR.instance;

// Reference to the modal DOM element
const modalEl = window.OSCBR.modal;

Getting current categories

The getCategories() method returns an array of categories the user has currently consented to.

const categories = window.OSCBR.instance.getCategories();
// Example output: ["strictly-necessary", "analytical"]

if (categories.includes("marketing")) {
  // Load Facebook Pixel, LinkedIn Insight Tag, etc.
}

Reopen the banner

Use showModal() to display the banner again at any time — for example, after clicking a “Cookie settings” link in the website footer.

// Button in the website footer
document.getElementById("cookie-settings").addEventListener("click", () => {
  window.OSCBR.instance.showModal();
});

SPA cleanup

For single-page applications (React, Vue, Angular) or GTM preview mode, use cleanup() to remove the banner and release event listeners.

// Cleanup when unmounting an SPA component
window.OSCBR.cleanup();

dataLayer events

The banner automatically sends two events to dataLayer:

cookiebarConsentInit

Sent when the banner first loads (default consent state).

cookiebarConsentUpdate

Sent after any consent change by the user (clicking "Accept all", "Save settings", etc.).

// Example: Reacting to consent update in GTM
// Create a Custom Event trigger with name "cookiebarConsentUpdate"
// and use it to fire tags that require consent.

// Or in JavaScript:
window.addEventListener("message", (e) => {
  // dataLayer push is automatic, but you can
  // also listen directly:
  if (e.data?.event === "cookiebarConsentUpdate") {
    console.log("Consent updated:", e.data);
  }
});

JSON Import/Export

The builder allows you to save and load the entire banner configuration in JSON format. This is useful for sharing settings between team members, versioning configuration in Git, or quickly switching between different banner variants.

Saving configuration

In the builder, use the keyboard shortcut Ctrl+S (or Cmd+S on Mac), or click the export button. The configuration will be downloaded as a .json file.

Loading from file

Click the import button in the builder and select a previously saved JSON file. The builder will load all settings and update the preview.

Drag & drop import

You can also drag and drop a JSON file directly into the builder window. The file will be automatically loaded.

File format

The JSON file contains three main keys:

{
  "_schema": "consentbadge-config-v1",
  "_savedAt": "2025-01-15T10:30:00.000Z",
  "config": {
    "host": "example.com",
    "version": "1.0.0",
    "multilingual": true,
    "langAutoSelect": true,
    "defaultLang": "en",
    "dismissible": false,
    "consentModeRegions": ["CZ", "SK"],
    "categoryConfig": {
      "analytical": { "defaultState": false },
      "preferences": { "defaultState": false },
      "marketing": { "defaultState": false }
    },
    "texts": [
      {
        "lang": "en",
        "title": "We use cookies",
        "description": "...",
        "acceptAll": "Accept all",
        "rejectAll": "Reject all",
        "save": "Save settings",
        "settings": "Settings"
      }
    ]
    // ... more settings
  }
}
The _schema key is used to identify the format version. The builder checks compatibility on import and warns you if the file is in an older or unknown version.

CLI

The ConsentBadge CLI lets you generate cookie consent banners directly from the command line — no need to open the builder.

Installation

No global installation required. Run it directly via npx:

npx consentbadge generate --preset dark-elegant --output banner.html

Available Commands

consentbadge generate

Generate an HTML banner file from a preset or JSON config file.

consentbadge init

Interactive wizard — creates a consentbadge.json configuration file.

consentbadge validate

Check configuration against GDPR rules and report issues.

consentbadge preview

Open the generated banner in the browser for preview.

consentbadge list-presets

List all available design presets.

Example: Generate from Preset

# Generate banner with preset and Czech + English texts
npx consentbadge generate \
  --preset glassmorphism \
  --lang cs,en \
  --domain .example.cz \
  --output cookie-banner.html

Example: Working with Config

# 1. Create config with wizard
npx consentbadge init

# 2. Validate config
npx consentbadge validate --config consentbadge.json

# 3. Generate banner
npx consentbadge generate --config consentbadge.json

Tip

The CLI is ideal for CI/CD pipelines — generate your banner automatically on every build.

MCP Server

The MCP (Model Context Protocol) server enables AI agents (Claude Code, Cursor, and others) to configure banners conversationally. Tell the agent what you need and it configures the banner for you.

Installation for Claude Code

claude mcp add consentbadge -- npx tsx packages/mcp/src/index.ts

Installation for Cursor / Other Clients

// claude_desktop_config.json or .cursor/mcp.json
{
  "mcpServers": {
    "consentbadge": {
      "command": "npx",
      "args": ["tsx", "packages/mcp/src/index.ts"]
    }
  }
}

Available Tools (27)

The MCP server provides 27 tools organized into 6 groups:

Configuration

get_config, apply_preset, reset_config

Design

set_colors, set_typography, set_layout, set_effects, set_button_styles, reorder_buttons, set_dark_mode

Texts

add_language, remove_language, update_texts, list_available_languages

Categories

add_category, remove_category, update_category, reorder_categories

Settings

update_consent_mode, update_behavior, update_cookie

Output

validate_config, generate_banner, preview_banner, list_presets, export_config, import_config

How It Works

The server maintains banner configuration in memory for the duration of the session. Each tool reads or modifies the config. At the end, call generate_banner to get the final HTML.

# Example conversation with AI agent:
# "Create a dark banner for my e-shop at .example.cz, in Czech and English"

# The agent calls:
# → apply_preset("dark-elegant")
# → set_colors({ theme: "#1E40AF" })
# → add_language("cs")
# → update_cookie({ host: ".example.cz" })
# → validate_config()
# → generate_banner({ outputPath: "banner.html" })

Tip

The MCP server requires no database or API keys. It runs locally as a subprocess of your AI editor.