consent-manager
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    npm

    consent-manager

    consent-manager aims to provide a comprehensive, flexible, accessible and privacy friendly cookie consent management solution for every project. Most cookie consent management solutions are either super basic or are proprietary. Additionally they may only offer you their pre-designed UI which doesn't fit every design. consent-manager allows you to only use the components you need. Anything from just the core consent management feature to the entire suite of bundled add-ons including ready-to-use UI components, integration with the DOM or blocking of cookies for any script (coming soon!) works!

    Getting started

    Add the script to your project through a package manager:

    $ npm i consent-manager

    or

    $ yarn add consent-manager

    Alternatively you can also import the script found in the releases section on GitHub directly. If you choose this option you won't need to import the individual classes going forward - they will all be available to you automatically.

    <script src="consent-manager.min.js"></script>

    Or include through a public CDN:

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

    Core

    First create a new ConsentManager object by passing a config:

    import ConsentManager from 'consent-manager';
    
    const consentManager = new ConsentManager({
      // Version of the current configuration
      // When this changes all current consent preferences will be disregarded
      // string - required
      version: '2021-01-01',
    
      // Name of the cookie containing preferences
      // string - optional - defaults to "consent-manager"
      cookieName: 'consent-manager',
    
      // How long until cookie containing preferences expires
      // number (days), Date object or "session" (until end of session) - optional - defaults to 365 days
      expires: 365,
    
      // Array of all toggleable categories by which cookies will be sorted; adjust to according to your needs
      categories: [
        {
          // Unique identifier
          // string - required
          id: 'essential',
    
          // Human understandable label
          // string - required
          label: 'Essential Cookies',
    
          // Explanation of category's purpose
          // string - required
          description: 'Required for basic functionality',
    
          // If required a category cannot be disabled
          // boolean - required
          required: true,
        },
        {
          // Unique identifier
          // string - required
          id: 'analytics',
    
          // Human understandable label
          // string - required
          label: 'Analytics Cookies',
          description: 'Visitor statistics used to improve content',
    
          // If required a category cannot be disabled
          // boolean - required
          required: false,
    
          // Default value of category
          // boolean - optional - defaults to false
          default: true,
        }
      ]
    });

    Properties

    config

    consentManager.config
    
    // Example: see object initialization above

    grants

    Key-value pairs of category ids and their current status indicated as boolean.

    consentManager.grants
    
    // Example:
    // {
    //   "essential": true
    //   "analytics": false
    // }

    isCustomized

    Boolean indicating whether the preferences were customized by the user.

    consentManager.isCustomized

    Methods

    setGrant

    Modify current status of one or multiple categories.

    consentManager.setGrant(categoryId, status);
    
    // Example - single category:
    consentManager.setGrant('analytics', true);
    
    // Example - all not required categories:
    consentManager.setGrant('*', false);

    on

    Listen for events. Available events:

    • grant (category was granted)
    • revoke (category was revoked)
    • update (category was either granted or revoked)
    consentManager.on(eventType, callback);
    
    // Example
    consentManager.on('update', (id) => {
      console.log(`Category ${id} was changed!`);
    });

    off

    Remove event listener. Make sure to pass the exact same function reference as when creating the listener.

    consentManager.off(eventType, callback);
    
    // Example
    consentManager.off('update', updateListener);

    DOMConnector

    DOMConnector allows you to modify the DOM based on user preferences without writing any custom logic by providing a set of data- attributes.

    Initialization

    import { DOMConnector } from 'consent-manager';
    
    new DOMConnector(consentManager);

    Attributes

    data-consent-manager - Required to make DOMConnector aware of element

    data-cm-categories="category1, category2" - Comma separated list of enabling categories

    data-cm-inverted - Inverts granted status

    data-cm-attribute="name" - Attribute which will be set when enabled

    data-cm-value="value" - Value of the attribute

    Usage Examples

    Load script conditionally

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

    Show info text if consent not given

    <style>
      p {
        display: none;
      }
    </style>
    
    <p
      data-consent-manager
      data-cm-categories="experience"
      data-cm-inverted
      data-cm-attribute="style"
      data-cm-value="display: block;"
    >
      Please consent to the use of cookies to use this feature!
    </p>

    GrantsInterface

    GrantsInterface provides ready-made UI elements for your users to set their preferences.

    Usage

    You already get the entire functionality just by creating a GrantsInterface object including a cookie banner that only shows up until users set their preferences and a modal where users can customize their preferences in detail. Make sure to also include the stylesheet or create your own one.

    import { GrantsInterface } from 'consent-manager';
    import 'consent-manager/dist/consent-manager.css';
    
    new GrantsInterface(consentManager);

    Include the stylesheet through a public CDN:

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

    If you want more control over the behavior of the UI elements you can disable them being shown automatically and use the following methods to control them manually instead:

    const gi = new GrantsInterface(consentManager, { autoShow: false });
    
    // Show cookie banner
    gi.showBanner();
    
    // Hide cookie banner
    gi.hideBanner();
    
    // Show preferences modal
    gi.showModal();
    
    // Hide preferences modal
    gi.hideModal();

    Additionally you may want to customize the text values shown in interface. You can change as many or as few as you'd like and simply leave the others unspecified:

    new GrantsInterface(consentManager, {
      languageStrings: {
        banner: {
          infoText: 'This website uses cookies to ensure you get the best experience on our website.',
          accept: 'Accept All',
          reject: 'Only required',
          options: 'More options'
        },
        modal: {
          title: 'Consent options',
          accept: 'Accept All',
          reject: 'Only required'
        }
      }
    });

    If you want to use the consent table used in the modal you can generate one yourself using generateConsentTable:

    // Generate table element linked to ConsentManager
    const table = gi.generateConsentTable();
    
    // Generate table element linked to ConsentManager that updates when preferences change elsewhere
    const table = gi.generateConsentTable(true);

    Install

    npm i consent-manager

    DownloadsWeekly Downloads

    6

    Version

    1.1.0

    License

    AGPL-3.0-only

    Unpacked Size

    415 kB

    Total Files

    27

    Last publish

    Collaborators

    • feliskio