catalog/readme.md

@consent.software_private/catalog

Webcomponents for consent.software widget.

Install

To install this module, you need to have Node.js and npm installed on your machine. You can then run the following command in your terminal to add the module to your project:

npm install @consent.software_private/catalog

Ensure you have ESM support enabled in your TypeScript configuration, as this package uses ES module syntax.

Usage

The @consent.software_private/catalog module offers a set of web components to integrate consent management capabilities into your web application. These components leverage modern browser APIs and employ a system for cookie management that aligns with regulatory requirements.

Initial Setup

First, import the necessary modules and set up your project to use the web components provided:

import '@consent.software_private/catalog';

Ensure this import statement is included in your main JavaScript/TypeScript file where you want to utilize the consent management web components. It is vital to transpile with TypeScript compiler settings that support ES modules.

Building a Consent Modal

A primary feature of this module is the consentsoftware-cookieconsent component. This component can be embedded into your application to allow users to select their preferred cookie levels.

Setting Up the Environment

Before creating instances of the components, make sure your project environment is ready. Setup the DOM tools and any associated dependencies:

import { domtools } from '@design.estate/dees-domtools';

domtools.elementBasic.setup();

Using the Consentsoftware-Cookieconsent Component

Here's how you can include the consentsoftware-cookieconsent component in your application:

import { html, render } from 'lit-html';

const template = html`
  <consentsoftware-cookieconsent></consentsoftware-cookieconsent>
`;

render(template, document.body);

This will add the consent banner to the bottom of the page, providing users options to set their preferences.

Customizing the Component

The consentsoftware-cookieconsent component allows you to customize its design via CSS properties. Leverage light and dark themes through the CSS manager used in styling attributes:

const styles = `
  :host {
    --cookieconsent-height: 70px;
    --cookieconsent-background: #222;
    --cookieconsent-text-color: #fff;
  }
`;

Apply these custom styles to modify the appearance to match your site's design language.

Handling User Interactions

The component is interactive, responding to user actions to set cookie levels. Here’s how the interaction flow works:

1. User Interaction: Users click one of the consent buttons (e.g., "Functional Cookies").
2. Handling Consent Levels: The component's setLevel method is invoked, updating the user's cookie preferences, e.g.:

private async setLevel(event: MouseEvent, levelsArg: Array<TCookieLevel>) {
  await this.csWebclientInstance.setCookieLevels(levelsArg);
  // Adjust styling and visibility
  this.setAttribute('gotIt', 'true');
  await delayFor(300);
  this.setAttribute('show', 'false');
  // Update other business logic based on consent levels
}

The system remembers user choices using a backend managed by the consent.software infrastructure.

Integrating with Your Backend

For full functionality, the component interacts with a backend to manage user consent states. Using @consent.software/webclient, you can query the user's current consent levels, perform updates, and verify whether consent has been previously granted:

const webclientInstance = new CsWebclient();
const cookieLevels = await webclientInstance.getCookieLevels();

if (!cookieLevels) {
  // Show consent dialog if no consent levels are set
  document.querySelector('consentsoftware-cookieconsent').show = true;
} else {
  // Apply the consent settings to your analytics, advertisements, etc.
  applyConsentSettings(cookieLevels);
}

Advanced Considerations

Responsive Design

The component is responsive, optimized for various screen sizes using a grid layout. Ensure your main HTML elements are responsive to accommodate the consent bar.

Accessibility and Compliance

Ensure your application properly adheres to legal and accessibility standards by aligning with the consent management system's features. This often involves using correct semantics, polyfills for custom elements, and thorough testing on different devices and browsers.

Managing State Across Sessions

Store user's consent preferences beyond the session using either localStorage, cookies, or server-side sessions. Adjust the component’s connectedCallback and updated lifecycle methods to fetch and apply these stored settings.

Proper handling ensures a seamless user experience, helping companies comply with international privacy laws like GDPR.

Integration and Testing

Test extensively in your development environment, ensure correct rendering, and simulate various user interactions to gain confidence in production-level functionality. Automated testing might include:

• Unit tests for lifecycle behavior using testing libraries such as Mocha or Jest.
• Integration trials ensuring the component plays well with surrounding UI elements.

Conclusion

With these guidelines, developers can integrate, customize, and extend the consent management capabilities within their applications using @consent.software_private/catalog. Adapt the styling, maximize UX, and ensure regulatory compliance for a robust implementation. Mastery of the component enables seamless user consent handling and enhances your app's governance credentials. undefined