Troubleshooting

Relevant source files

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

• src/modules/ConsentManager.ts
• src/modules/DOMConnector.ts
• src/modules/GrantsInterface.ts
• src/modules/ConsentManager.test.ts
• src/styles.scss
• package.json

This document provides guidance for diagnosing and resolving common issues encountered when using the consent-manager library. It covers problems related to configuration, cookie management, DOM manipulation, and the user interface components. The solutions and explanations are derived directly from the library's source code.

The consent-manager is composed of three main modules: the core ConsentManager, the DOMConnector, and the GrantsInterface. Understanding their interaction is key to troubleshooting.

The diagram below illustrates the high-level architecture and dependencies between the main classes.

Sources: src/modules/DOMConnector.ts:4, src/modules/GrantsInterface.ts:48

Cookie and Configuration Issues

Problems often originate from an invalid or outdated cookie, or a misconfiguration of the ConsentManager instance.

Invalid Cookie Format

The ConsentManager will ignore a cookie if it doesn't pass a strict validation check. If user preferences are not being saved across sessions, check the browser's developer tools to inspect the cookie's value. A console warning Cookie "..." is not a valid object. will be logged if the cookie is invalid.

The cookie validation logic is as follows:

Sources: src/modules/ConsentManager.ts:4-40, src/modules/ConsentManager.ts:119-121

A valid cookie must conform to the CookieData interface structure.

Key	Type	Description
version	string	The configuration version string. Must match the one in the ConsentManager.
grants	Record<string, boolean>	An object where keys are category IDs and values are their boolean status.
Sources: src/modules/ConsentManager.ts:43-46

Preferences Not Loading (Version Mismatch)

If a user's previously saved consent preferences are ignored and reset to default, it's likely due to a version mismatch. When the version string in the ConsentManager configuration changes, all existing cookies with a different version are considered outdated. This forces the user to provide consent again. The isCustomized flag will be false in this case.

// src/modules/ConsentManager.ts:113-116
if (cookieValue.version === this.config.version) {
  this.isCustomized = true;
  // ... grant override logic
}

Sources: src/modules/ConsentManager.ts:113-120

Grants Not Changing

If calling setGrant() does not change a category's status, check if the category is marked as required: true in the configuration. Required categories cannot have their grant revoked, and any attempt to set their status to false will be ignored.

// src/modules/ConsentManager.ts:149-154
const isRequired = this.config.categories.find(
  (el) => el.id === id
)?.required;
if (isRequired) {
  return;
}

Sources: src/modules/ConsentManager.ts:149-154, src/modules/ConsentManager.test.ts:49-61

DOMConnector Not Updating Elements

The DOMConnector is responsible for dynamically altering HTML attributes based on consent grants. If elements are not updating, it's usually due to missing or incorrect data-* attributes.

Common data-* Attribute Issues

The DOMConnector looks for elements with the data-consent-manager attribute and then uses other data-cm-* attributes to perform its actions.

Attribute	Required	Description	Console Warning if Missing
data-consent-manager	Yes	Registers the element with the DOMConnector.	(No warning, element is simply ignored)
data-cm-categories	Yes	A comma-separated list of category IDs that enable the element.	Element ... is missing cookie category!
data-cm-attribute	Yes	The name of the HTML attribute to set when consent is granted.	Element ... is missing data-cm-attribute attribute!
data-cm-value	Yes	The value to be assigned to the attribute specified by data-cm-attribute.	Element ... is missing data-cm-value attribute!
data-cm-inverted	No	Inverts the logic, applying the attribute when consent is not granted.	N/A
Sources: src/modules/DOMConnector.ts:1-50, README.md:141-151

Element Grant Logic Flow

The following diagram explains how DOMConnector decides whether to apply an attribute to an element.

Sources: src/modules/DOMConnector.ts:7-50

GrantsInterface UI Issues

The GrantsInterface provides a pre-built banner and modal. Issues here are typically related to visibility or styling.

Banner or Modal Not Appearing

• autoShow: false: If the GrantsInterface is initialized with { autoShow: false }, the banner will not appear automatically. You must call gi.showBanner() or gi.showModal() manually.
• isCustomized is true: The banner is only shown automatically if the user has not already customized their preferences (i.e., client.isCustomized is false). If a valid cookie exists, the banner will not be shown.

Sources: src/modules/GrantsInterface.ts:48-52, README.md:188-196

Banner Not Hiding After Choice

The banner is designed to hide itself automatically once consent is customized. It does this by listening for the update event from the ConsentManager instance. If the banner persists, ensure that the setGrant method is being called correctly to trigger this event.

// src/modules/GrantsInterface.ts:114-118
this.client.on('update', () => {
  if (this.client.isCustomized) {
    this.hideBanner();
  }
});

Sources: src/modules/GrantsInterface.ts:114-118

Styling Conflicts

The UI elements use specific CSS classes. If the banner or modal looks incorrect, it may be due to conflicts with your site's existing stylesheets. You can debug by inspecting these elements in the browser and checking the applied styles.

Key CSS classes include:

• .consent-manager--banner-wrapper
• .consent-manager--modal-backdrop
• .consent-manager--modal-container
• .consent-manager--table

Sources: src/styles.scss:1-125

Event Listener Problems

Event listeners (on, off) are used to react to changes in consent.

Listeners Not Firing

The setGrant method is responsible for dispatching update, grant, and revoke events. If your listener is not being called, ensure:

1. The grant status is actually changing (e.g., not for a required category).
2. The setGrant method is being executed.

The diagram below shows the event dispatch sequence.

Sources: src/modules/ConsentManager.ts:136-168

Listeners Not Being Removed

To successfully remove a listener with off(), you must pass the exact same function reference that was used with on(). Anonymous functions or different function instances will not work.

Incorrect:

// This will NOT work
consentManager.on('update', (id) => { console.log(id); });
consentManager.off('update', (id) => { console.log(id); });

Correct:

const myCallback = (id) => { console.log(id); };
consentManager.on('update', myCallback);
consentManager.off('update', myCallback); // This works

Sources: src/modules/ConsentManager.ts:179-189, src/modules/ConsentManager.test.ts:98-102