Recipe: Handling Configuration Versioning

The consent-manager provides a robust mechanism for versioning consent configurations. This is crucial for scenarios where the defined consent categories or their purposes change over time. By updating a version string in the configuration, developers can ensure that all users are prompted to re-evaluate their consent choices against the new configuration, effectively invalidating any previously stored preferences.

This system guarantees that user consent is always aligned with the latest policies and cookie definitions. When the ConsentManager is initialized, it compares the version stored in the user's cookie with the version in the application's current configuration. A mismatch results in the old consent being disregarded, and the UI, such as the GrantsInterface banner, will be displayed to capture new consent.

Configuration

The versioning feature is controlled by a single property within the ConsentManager configuration object.

Sources: src/modules/ConsentManager.ts:57, README.md

The version Property

This property is a mandatory string that uniquely identifies the consent configuration. When this value is changed, all existing user consent preferences stored in cookies will be disregarded on their next visit.

Sources: src/modules/ConsentManager.ts:57, README.md

Example configuration:

import ConsentManager from 'consent-manager';

const consentManager = new ConsentManager({
  // When this changes all current consent preferences will be disregarded
  version: '2023-10-27',
  categories: [
    // ...
  ]
});

Sources: README.md

Cookie Data Structure

The user's consent preferences are stored in a browser cookie. This cookie contains both the grants (the status of each category) and the configuration version under which the consent was given.

Sources: src/modules/ConsentManager.ts:49-52

The structure of the data stored in the cookie is defined by the CookieData interface.

This diagram shows the CookieData object containing a version string and a grants object.

Sources: src/modules/ConsentManager.ts:49-52

The writeCookie method in ConsentManager is responsible for serializing this data and storing it.

// src/modules/ConsentManager.ts:117-124
private writeCookie(): void {
  const cookieData: CookieData = {
    version: this.config.version,
    grants: this.grants,
  };
  Cookie.set(this.config.cookieName, JSON.stringify(cookieData), {
    expires: this.config.expires !== 'session' ? this.config.expires : null,
  });
}

Initialization and Version Check

The core versioning logic is executed within the ConsentManager constructor, which calls the private parseCookie method. This method is responsible for reading the cookie, validating its contents, and checking the version.

Sources: src/modules/ConsentManager.ts:91-93, src/modules/ConsentManager.ts:95-115

The following flowchart illustrates the version check process during initialization:

This diagram shows the logic flow for parsing the consent cookie and checking its version.

Sources: src/modules/ConsentManager.ts:95-115, src/modules/ConsentManager.test.ts:28-48

1. Parse Cookie: The parseCookie method attempts to read and parse the JSON data from the cookie specified by config.cookieName.
2. Validate Cookie: The validateCookie helper function checks if the parsed data is a valid object with version (string) and grants (object of booleans) keys. If not, the cookie is ignored.
3. Compare Versions: If the cookie is valid, its version property is compared to the version in the ConsentManager's current configuration.
4. Apply Grants:
   • Match: If the versions match, the grants from the cookie are loaded, and the isCustomized property is set to true.
   • Mismatch: If the versions do not match (or if the cookie was invalid/missing), the grants are reset to the default values defined in the current configuration, and isCustomized is set to false.

Sources: src/modules/ConsentManager.ts:6-43, src/modules/ConsentManager.ts:104-106

Impact on UI and Application Logic

The isCustomized property, which is set by the versioning logic, is a key flag that other parts of the application can use to react to the user's consent state. A primary example is the GrantsInterface, which displays the consent banner.

The following sequence diagram shows how a version mismatch leads to the consent banner being displayed.

This diagram illustrates the initialization flow where a version mismatch in ConsentManager causes GrantsInterface to show the consent banner.

Sources: src/modules/GrantsInterface.ts:51-53, src/modules/ConsentManager.ts:86, 105-106

The GrantsInterface constructor explicitly checks this flag to decide whether to automatically show the banner.

// src/modules/GrantsInterface.ts:51-53
constructor(private client: ConsentManager, config?: GrantsInterfaceConfig) {
  // ...
  if (this.config.autoShow && !client.isCustomized) {
    this.showBanner();
  }
}

This direct dependency on isCustomized makes the versioning mechanism a powerful tool for forcing re-consent without any complex application-level logic.

Summary

The configuration versioning system in consent-manager is a fundamental feature for maintaining compliance and managing consent over the lifecycle of a project. By associating a version with each consent configuration, the library provides a simple and automated way to invalidate outdated user preferences when cookie policies or categories are updated. This process is centered around the version property in the configuration, the parseCookie logic on initialization, and the resulting isCustomized flag, which signals to UI components like GrantsInterface whether new consent is required.