Quick Start Tutorial

Relevant source files

The following files were used as context for generating this wiki page:

• src/index.ts
• src/modules/ConsentManager.ts
• src/modules/GrantsInterface.ts
• src/modules/DOMConnector.ts
• README.md
• package.json
• src/styles.scss
• src/bundle.ts

This tutorial provides a guide to getting started with consent-manager, a flexible and privacy-friendly cookie consent management solution. It covers installation, core setup, and the use of its main modules: ConsentManager for logic, GrantsInterface for UI, and DOMConnector for dynamic content rendering based on user consent. The library is designed to be modular, allowing developers to use only the components they need.

Sources: README.md:5-10, package.json:2

Installation

You can add consent-manager to your project using a package manager or by including it directly in your HTML.

Package Manager:

# pnpm
pnpm i consent-manager

# yarn
yarn add consent-manager

# npm
npm i consent-manager

CDN or Direct File:

For direct browser usage, you can use a CDN like unpkg. This makes the core classes (ConsentManager, DOMConnector, GrantsInterface) available on the global window object.

<!-- Main script -->
<script src="https://unpkg.com/consent-manager@1/dist/consent-manager.min.js"></script>

<!-- Stylesheet for GrantsInterface -->
<link rel="stylesheet" href="https://unpkg.com/consent-manager@1/dist/consent-manager.min.css">

Sources: README.md:14-32, src/bundle.ts:2-8

Core: ConsentManager Setup

The ConsentManager class is the heart of the library, managing the state of user consent.

Initialization

To begin, create a new ConsentManager instance, passing a configuration object. The version and categories properties are required.

import ConsentManager from 'consent-manager';

const consentManager = new ConsentManager({
  version: '2023-10-27',
  categories: [
    {
      id: 'essential',
      label: 'Essential Cookies',
      description: 'Required for basic functionality',
      required: true,
    },
    {
      id: 'analytics',
      label: 'Analytics Cookies',
      description: 'Visitor statistics used to improve content',
      required: false,
      default: true,
    }
  ]
});

Sources: src/modules/ConsentManager.ts:70-73, README.md:37-77

Configuration

The ConsentManager is configured via the ConsentManagerConfig object passed to its constructor.

Option	Type	Default	Description
version	string	'1'	The version of your configuration. If this changes, all existing user consents are disregarded.
cookieName	string	'consent-manager'	The name of the cookie used to store consent preferences.
expires	number | Date | 'session'	365	Cookie expiration in days, a specific Date, or 'session'.
categories	array	[]	An array of consent categories. Each category is an object with id, label, description, required, and an optional default status.

Sources: src/modules/ConsentManager.ts:56-68

Key Properties and Methods

The ConsentManager class provides properties to access its state and methods to modify it.

This diagram shows the main components of the ConsentManager class.

Properties

• config: The full configuration object.
• grants: A key-value object where keys are category IDs and values are booleans indicating if consent is granted.

  // Example:
  // { "essential": true, "analytics": true }
  

• isCustomized: A boolean that is true if the user has actively made a choice, or if a valid cookie matching the current version is found.

Sources: src/modules/ConsentManager.ts:69-71, README.md:83-97

Methods

• setGrant(id, status): Sets the grant status for one or all categories. Use '*' as the id to target all non-required categories. This action marks the consent as customized and writes the cookie.
• on(eventName, callback): Registers an event listener. Available events are grant, revoke, and update.
• off(eventName, callback): Removes a previously registered event listener.

The following diagram shows the sequence of events when setGrant is called.

UI: GrantsInterface

The GrantsInterface module provides ready-to-use UI components, including a consent banner and a preferences modal.

Initialization

Instantiate GrantsInterface with your ConsentManager instance. By default, it will automatically show a banner if the user has not yet customized their consent.

import { GrantsInterface } from 'consent-manager';
import 'consent-manager/dist/consent-manager.css'; // Import styles

const gi = new GrantsInterface(consentManager);

You can disable the automatic banner and control it manually:

const gi = new GrantsInterface(consentManager, { autoShow: false });

// Manually show/hide UI elements
gi.showBanner();
gi.showModal();

Sources: src/modules/GrantsInterface.ts:42-46, 19-22, README.md:167-187

UI Flow

The diagram below illustrates the logic for displaying the consent banner.

Customization

You can customize the text strings used in the UI by passing a languageStrings object in the configuration.

Option	Type	Description
autoShow	boolean	If true, shows the banner automatically. Defaults to true.
languageStrings	object	An object to override default text for the banner and modal.

Sources: src/modules/GrantsInterface.ts:19-36, README.md:191-209

Dynamic Content: DOMConnector

The DOMConnector module links the consent state to the DOM, allowing you to conditionally modify elements using data- attributes.

Initialization

Instantiate DOMConnector with your ConsentManager instance. It will automatically scan the DOM and listen for consent updates.

import { DOMConnector } from 'consent-manager';

new DOMConnector(consentManager);

Sources: src/modules/DOMConnector.ts:4-7, README.md:143-145

data- Attributes

To make an element responsive to consent changes, add the following attributes:

Attribute	Description	Required
data-consent-manager	Marks the element for processing by DOMConnector.	Yes
data-cm-categories	A comma-separated list of category IDs. The element is considered "granted" if consent is given for any of these categories.	Yes
data-cm-attribute	The name of the HTML attribute to set when granted.	Yes
data-cm-value	The value to set for the specified attribute.	Yes
data-cm-inverted	Inverts the logic. The attribute is set when consent is not granted.	No

Sources: src/modules/DOMConnector.ts:9-29, README.md:149-157

Usage Example: Conditional Script Loading

This example shows how to load an analytics script only if the analytics category is granted.

<script
  data-consent-manager
  data-cm-categories="analytics"
  data-cm-attribute="src"
  data-cm-value="https://analytics-provider.com/script.js"
></script>

Sources: README.md:161-167

DOMConnector Logic Flow

This diagram shows how DOMConnector processes a single element.