Integration Guides

Cookie Consent Modal

Embed and configure the Neostra cookie consent modal (CPMP Modal) built with Svelte 5.

The Neostra Cookie Consent Modal (CPMP Modal) is a lightweight, customizable consent banner built with Svelte 5. It handles cookie categorization, user preferences, Global Privacy Control (GPC) detection, and consent writeback to the Neostra platform.

Quick Start

Add a single script tag to your website to load and initialize the consent modal.

<script
  src="https://cdn.neostra.io/cpmp/modal.umd.latest.js"
  data-cp-id="your-consent-profile-id"
></script>

The script auto-initializes a CPMPModal singleton that:

Loads configuration from the Neostra API
Checks for existing consent cookies
Detects Global Privacy Control signals
Displays the consent banner if consent has not been recorded

The data-cp-id attribute is required. It maps to your consent profile configuration in the Neostra platform, which defines categories, cookie lists, UI text, and behavior.

Installation Options

Add the script tag before the closing </body> tag:

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <!-- Your page content -->

  <script
    src="https://cdn.neostra.io/cpmp/modal.umd.latest.js"
    data-cp-id="your-consent-profile-id"
  ></script>
</body>
</html>

Import the ES module build for bundler-based projects:

import { CPMPModal } from "https://cdn.neostra.io/cpmp/modal.es.js";

const modal = new CPMPModal({
  cpId: "your-consent-profile-id",
});

modal.init();

Download the build artifacts and host them on your own CDN:

File	Description
`modal.umd.js`	UMD build with versioned filename
`modal.umd.latest.js`	UMD build, always points to latest version
`modal.es.js`	ES module build
`autoblocker.js`	Automatic script blocker (see Auto-Blocker section)

How It Works

Configuration

The modal loads its configuration from the Neostra API based on the data-cp-id. The configuration is managed through the Neostra platform UI but follows this structure:

Each cookie category has an ID, display name, description, and a required flag. The "necessary" category is always required and cannot be declined.

{
  "categories": [
    {
      "id": "necessary",
      "name": "Strictly Necessary",
      "description": "Essential for the website to function properly.",
      "required": true
    },
    {
      "id": "analytics",
      "name": "Analytics",
      "description": "Help us understand how visitors interact with the site.",
      "required": false
    },
    {
      "id": "marketing",
      "name": "Marketing",
      "description": "Used to deliver relevant advertisements.",
      "required": false
    },
    {
      "id": "functional",
      "name": "Functional",
      "description": "Enable enhanced functionality and personalization.",
      "required": false
    }
  ]
}

Each category lists the specific cookies it covers, including name, provider, purpose, and expiry.

{
  "cookies": {
    "necessary": [
      {
        "name": "session_id",
        "provider": "example.com",
        "purpose": "Maintains user session state",
        "expiry": "Session"
      }
    ],
    "analytics": [
      {
        "name": "_ga",
        "provider": "Google Analytics",
        "purpose": "Distinguishes unique users",
        "expiry": "2 years"
      },
      {
        "name": "_gid",
        "provider": "Google Analytics",
        "purpose": "Distinguishes unique users",
        "expiry": "24 hours"
      }
    ]
  }
}

All UI text is multilingual. The modal selects the appropriate language based on the user's browser locale and the configured supported locales.

{
  "text": {
    "en": {
      "bannerTitle": "We use cookies",
      "bannerDescription": "We use cookies to improve your experience...",
      "acceptAll": "Accept All",
      "rejectAll": "Reject All",
      "customize": "Customize",
      "save": "Save Preferences",
      "privacyPolicyLink": "Privacy Policy"
    },
    "de": {
      "bannerTitle": "Wir verwenden Cookies",
      "bannerDescription": "Wir verwenden Cookies, um Ihre Erfahrung...",
      "acceptAll": "Alle akzeptieren",
      "rejectAll": "Alle ablehnen",
      "customize": "Anpassen",
      "save": "Einstellungen speichern",
      "privacyPolicyLink": "Datenschutzrichtlinie"
    }
  }
}

Customize the modal appearance with theme colors.

{
  "theme": {
    "primaryColor": "#2563eb",
    "backgroundColor": "#ffffff",
    "textColor": "#1f2937",
    "buttonTextColor": "#ffffff",
    "borderRadius": "8px",
    "position": "bottom"
  }
}

Components

The modal consists of two main components:

Modal (Banner)

The initial consent banner shown to users. Provides Accept All, Reject All, and Customize buttons. Appears at the configured position (top or bottom of the viewport).

CustomizeModal

A detailed preferences panel where users can toggle individual cookie categories. Shows cookie details (name, provider, purpose, expiry) for each category.

The ConsentManager handles reading and writing consent state.

Consent is stored as a browser cookie with configurable expiry. The consent cookie contains:

Field	Description
`uuid`	Unique subject identifier for consent tracking
`categories`	Object mapping category IDs to boolean consent values
`timestamp`	ISO 8601 timestamp of when consent was given or updated
`version`	Configuration version to detect when re-consent is needed

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "categories": {
    "necessary": true,
    "analytics": true,
    "marketing": false,
    "functional": true
  },
  "timestamp": "2026-03-15T10:30:00Z",
  "version": "1.2"
}

API Writeback

When a user updates their consent, the modal submits the consent record to the Neostra API:

POST https://api.neostra.io/v1/consents

{
  "cpId": "your-consent-profile-id",
  "subjectId": "550e8400-e29b-41d4-a716-446655440000",
  "categories": {
    "necessary": true,
    "analytics": true,
    "marketing": false,
    "functional": true
  },
  "gpcDetected": false,
  "userAgent": "Mozilla/5.0 ...",
  "url": "https://www.example.com/page"
}

Event Handling

The modal fires a custom DOM event whenever consent is updated. Listen for this event to conditionally load scripts or activate features based on consent.

document.addEventListener("cpmp-consent-change", (event) => {
  const { categories, uuid } = event.detail;

  if (categories.analytics) {
    // Load analytics scripts
    loadGoogleAnalytics();
  }

  if (categories.marketing) {
    // Enable marketing pixels
    enableMarketingPixels();
  }

  console.log(`Consent updated for subject: ${uuid}`);
});

// Access the modal instance to check current consent state
const consent = window.CPMPModal.getConsent();

if (consent && consent.categories.analytics) {
  // Analytics consent was previously given
  loadGoogleAnalytics();
}

Global Privacy Control (GPC)

The modal automatically detects the Global Privacy Control signal (navigator.globalPrivacyControl). When GPC is enabled:

Non-essential cookie categories default to declined
The consent banner still appears but with non-essential categories pre-set to off
The GPC detection status is included in the consent writeback to the API

GPC detection respects the user's browser-level privacy preference as specified by the GPC specification. It does not prevent the user from manually opting in to categories.

Auto-Blocker

The auto-blocker script prevents third-party scripts from executing before consent is obtained. Add it before any other scripts on the page.

<head>
  <!-- Must be the first script -->
  <script src="https://cdn.neostra.io/cpmp/autoblocker.js"></script>

  <!-- These scripts will be blocked until consent is given -->
  <script src="https://www.googletagmanager.com/gtag/js?id=GA_ID"></script>
</head>
<body>
  <!-- Consent modal loads and manages script activation -->
  <script
    src="https://cdn.neostra.io/cpmp/modal.umd.latest.js"
    data-cp-id="your-consent-profile-id"
  ></script>
</body>

The auto-blocker works by:

Intercepting script tags before they execute
Matching scripts against known third-party domains in the configuration
Holding blocked scripts until consent is obtained for the relevant category
Releasing and executing scripts when the user grants consent

Modes

The default mode. Consent is persisted, writeback is enabled, and the modal respects existing consent cookies.

<script
  src="https://cdn.neostra.io/cpmp/modal.umd.latest.js"
  data-cp-id="your-consent-profile-id"
></script>

Used for testing the modal appearance and behavior without persisting consent or calling the API. The banner always appears regardless of existing consent.

<script
  src="https://cdn.neostra.io/cpmp/modal.umd.latest.js"
  data-cp-id="your-consent-profile-id"
  data-cp-preview="true"
></script>

Do not use preview mode in production. It disables consent persistence and API writeback, meaning user preferences will not be saved.

Build Artifacts

File	Format	Description
`modal.umd.js`	UMD	Versioned build, suitable for production pinning
`modal.umd.latest.js`	UMD	Always resolves to the latest version
`modal.es.js`	ES Module	For use with JavaScript bundlers
`autoblocker.js`	IIFE	Script blocking, must load before other scripts

Was this page helpful?

Last updated 1 week ago

Built with Documentation.AI