138 lines
5.7 KiB
Markdown
138 lines
5.7 KiB
Markdown
# @consent.software_private/catalog
|
||
|
||
Webcomponents for consent.software widget.
|
||
|
||
## Install
|
||
|
||
To install this module, you need to have [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your machine. You can then run the following command in your terminal to add the module to your project:
|
||
|
||
```shell
|
||
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:
|
||
|
||
```typescript
|
||
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:
|
||
|
||
```typescript
|
||
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:
|
||
|
||
```typescript
|
||
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:
|
||
|
||
```typescript
|
||
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.:
|
||
|
||
```typescript
|
||
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:
|
||
|
||
```typescript
|
||
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 |