@mikelgmh/cookie-manager
v1.2.8
Published
A cookies manager that can inject scripts dynamically.
Downloads
19
Readme
cookie-manager
This library allows to inject scripts dynamically according to the cookie preferences chosen in a modal. You can also set values for cookies automatically for each cookie category. GitHub repository.
Installation
npm install @mikelgmh/cookie-managerGet started
import { CookiesManager, ScriptType } from '@mikelgmh/cookie-manager';
import '@mikelgmh/cookie-manager/dist/index.css'; // Optional. Default styles.
const cookiesManager = new CookiesManager(options); // Check the options object below
cookiesManager.init(true, false); // The first value shows the banner on load, the second value shows the modal on load
// You can manually open or close both
// OPEN
cookiesManager.showBanner();
cookiesManager.showModal();
// CLOSE
cookiesManager.hideBanner();
cookiesManager.hideModal();Styling
You can optionally import the default styles.
import '@mikelgmh/cookie-manager/dist/index.css'; // Optional. Default styles.If you want to use your own styles you can customize the default template by importing this SCSS file to your project.
Options
Here’s an example of the options object. Every option has a default value, so the only required option is the cookieCategories array.
{
askOnce: true, // If the user already accepted the cookies, don't ask again on page reload
askOnChange: true, // Ask again if cookieCategories array is modified. This overrides the askOnce option
askAgainIfRejectedAfterDays: -1, // -1 to disable, set to 30 to ask after 30 days if the user rejected any cookie
delay: 0, // Sets a timeout to show the banner / modal using the init() method.
modalOptions: { // Options for the modal
inject: true, // Inject the HTML of the modal using Javascript. This might cause CSP issues if CSP is on
showModalClass: "show-modal", // The clas used to show the modal. Use it along with modal__container
title: "Cookie settings",
description: "Change the settings for your cookies here.",
acceptAllButton: {
text: 'Accept all',
show: true,
onClick: () => { },
},
rejectAllButton: {
text: 'Reject all',
show: true,
onClick: () => { },
},
saveButton: {
text: 'Save',
show: true,
onClick: () => { },
},
closeButton: {
text: 'Close', // Not implemented yet. This shows the X mark in the modal's corner
show: true,
},
},
bannerOptions: { // Options for the banner
inject: true, // Inject the HTML of the banner using Javascript. This might cause CSP issues if CSP is on
wall: true, // Block the background with a semi-transparent wall
injectWall: true, // Injects the HTML for the wall. This might cause CSP issues if CSP is on
wallScroll: true, // Allow the scroll.
wallBlur: false, //Blurs the background wall
bannerText: 'This website uses cookies to ensure you get the best experience on our website.',
acceptAllButton: {
text: 'Accept all',
show: true,
onClick: () => { },
},
rejectAllButton: {
text: 'Reject all',
show: true,
onClick: () => { },
},
settingsButton: {
text: 'Configure',
show: true,
onClick: () => { },
},
},
cookieCategories: [ // The cookie categories. These will appear in the cookie modal
{
id: "my-custom-id-1", // Custom id. Useful to identify the categories on the onCookieCategoryChange callback.
title: 'Analytics Cookies',
description: 'This is a test description. You can change this in the options object.',
required: false, // Set to true to disable the switch
checked: false, // Set to true to check the switch
boxedHeader: false, // Puts the category in a Box
boxedBody: false, // Adds margins to fit the body in the header's box
accordion: {
enable: false, // Enables an accordion for the description
active: false, // Sets the accordion to active by default
},
events: { // You can defined some callbacks or events easily.
onAccept: () => { }, // Callback function. This method is called when the user accepted this cookieCategory when the user presses the save button.
onReject: () => { }, // Callback function. This method is called when the user accepted this cookieCategory when the user presses the save button.
setCookiesOnChange: [ // This array can be empty []. If you want to change some cookie values, you can follow this example:
{
cookieName: "analyticsCookie",
valueOnAccept: true,
valueOnReject: false,
expirationDays: 365, // Be careful, the limit is 400 days!
},
{
cookieName: "adsCookie",
valueOnAccept: true,
valueOnReject: false,
expirationDays: 365, // Be careful, the limit is 400 days!
}
]
},
scripts: [ // The scripts array can have an empty value [] if you don't want to inject scripts
{
type: ScriptType.STANDARD, // Standart to inject a regular script. GTM if using GTM.
// gtmCode: '', // Set this value if using GTM
scriptSrc: 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.1/jquery.min.js',
async: true,
},
],
},
{
id: "my-custom-id-2", // Custom id. Useful to identify the categories on the onCookieCategoryChange callback.
title: 'Analytics Cookies',
description: 'This is a test description. You can change this in the options object.',
required: false,
scripts: [ // The scripts array can have an empty value [] if you don't want to inject scripts
{
type: ScriptType.STANDARD,
// gtmCode: '',
scriptSrc: 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.1/jquery.min.js',
async: true,
},
],
events: { // You can defined some callbacks or events easily.
onAccept: () => { }, // Callback function. This method is called when the user accepted this cookieCategory when the user presses the save button.
onReject: () => { }, // Callback function. This method is called when the user accepted this cookieCategory when the user presses the save button.
setCookiesOnChange: [ // This array can be empty []. If you want to change some cookie values, you can follow this example:
{
cookieName: "analyticsCookie",
valueOnAccept: true,
valueOnReject: false,
expirationDays: 365, // Be careful, the limit is 400 days!
},
{
cookieName: "adsCookie",
valueOnAccept: true,
valueOnReject: false,
expirationDays: 365, // Be careful, the limit is 400 days!
}
]
},
},
],
}Order of scripts
You can change the order of script injection by moving the objects in the scripts array up or down.
Using it together with CSP
This library injects HTML directly to the DOM, so if your CSP configuracion does not allow this, you can manually add the HTML to your project. To get it to work, you need to set the inject value to false in bannerOptions and modalOptions.
- Copy and paste the HTML elements to your projects:
<div class="c-cookies-config-wall"></div> <div class="c-cookies-config-banner">
<div class="banner-container">
<p>This website uses cookies to ensure you get the best experience on our website.</p>
<div class="banner-container__buttons">
<button class="banner-container__button banner-container__accept-all-btn cm-banner-accept-all-btn">Accept all</button>
<button class="banner-container__button banner-container__reject-all-btn cm-banner-reject-all-btn">Reject all</button>
<button class="banner-container__button-link banner-container__config-btn cm-banner-config-btn">Settings</button>
</div>
</div>
</div> <div class="c-cookies-config-modal">
<div class="modal__container" id="modal-container">
<div class="modal__content">
<div class="modal__close close-modal" title="Close">
<div class="close-modal-img"></div>
</div>
<h1 class="modal__title">Configuración de cookies</h1>
<p class="modal__description">Configura aquí tus cookies.</p>
<div class="modal__cookie-categories">
<div class="cookie-category">
<div class="cookie-category__header cc-header">
<h2 class="header__title">
Cookies funcionales
</h2>
<div class="header__switch">
<label class="switch disabled">
<input disabled="" checked="" class="cm-switch-0" type="checkbox">
<span class="slider round"></span>
</label>
</div>
</div>
<div class="cookie-category__body body">
<p>This is a test description. You can change this in the options object.</p>
</div>
</div>
<div class="cookie-category">
<div class="cookie-category__header cc-header">
<h2 class="header__title">
Cookies de analítica
</h2>
<div class="header__switch">
<label class="switch ">
<input checked="" class="cm-switch-1" type="checkbox">
<span class="slider round"></span>
</label>
</div>
</div>
<div class="cookie-category__body body">
<p>This is a test description. You can change this in the options object.</p>
</div>
</div>
</div>
<div class="modal__footer">
<button class="modal__button modal__button-width cm-modal-reject-all footer__button-reject-all">Reject all</button>
<button class="modal__button modal__button-width cm-modal-accept-all footer__button-accept-all">Accept all</button>
<button class="modal__button-link close-modal cm-modal-save footer__button-save-btn"> Save </button>
</div>
</div>
</div>
</div>- Call the init method:
// First, set the inject value to false in the banner and modal options
var options = {
cookieCategories: [...],
bannerOptions: {
inject: false,
},
modalOptions: {
inject: false
}
};
const cookiesManager = new CookiesManager(options);
cookiesManager.init(true, false); // This method will automatically add the event listenersCustom HTML
You can create you own banner or modal, you just need to add some classes to your inputs or buttons. Your components should respect these rules
Banner
- The banner's parent div must have the following class:
c-cookies-config-banner. This is used to show / hide the banner. - Inside the banner there must be an element with the following class:
banner-container. This is used to show / hide the banner. - The accept all button must have this class:
cm-banner-accept-all-btn. - The reject all button must have this class:
cm-banner-reject-all-btn. - The cookie config button must have this class:
cm-banner-config-btn.
Modal
- The modal's parent div must have the following class:
c-cookies-config-modal. This is used to show / hide the modal. - Inside the modal there must be an element with the following class:
modal__container. This is used to show / hide the modal. - The modal's close button must have the following class:
close-modal - The modal's save button must have the following class:
cm-modal-save - The modal's accept all button must have the following class:
cm-modal-accept-all - The modal's reject all button must have the following class:
cm-modal-reject-all - The checkbox inputs for each cookieCategory must use this syntax:
cm-switch-[index], where index is the switch number starting from 0. - Watch out! The cookie categories (inside the
cookieCategoriesarray in theoptionsobject) MUST be in the same order as they're printed on screen.
Wall
- The wall must have this class:
c-cookies-config-wall - The wall on its blurred variant also has this class:
c-cookies-config-wall--blurred
To start using the library set the inject values to false in both the banner and modal.
// First, set the inject value to false in the banner and modal options
var options = {
cookieCategories: [...],
bannerOptions: {
inject: false,
},
modalOptions: {
inject: false
}
};
const cookiesManager = new CookiesManager(options);
cookiesManager.init(true, false); // This method will automatically add the event listenersCallbacks
You can set a callback function by calling the on method.
⚠️ It is very important to define the callbacks before calling the init() method ⚠️ If you want to use more specific callbacks, refer to the events object in each cookieCategory.
Available callbacks
|callback| params | description
|--|--|--|
| onCookieCategoryChange() | cookieCategory | This function is called when the user accepted / rejected a cookie Category after pressing the save button or after initializing the library. If you want an specific callback for each category, check the events object in cookieCategory.
var options = {...};
const cookiesManager = new CookiesManager(options);
cookiesManager.on('onCookieCategoryChange', (cookieCategory) => {
console.log(cookieCategory);
});
cookiesManager.init(true, false);Working example
import '@mikelgmh/cookie-manager/dist/index.css';
import { CookiesManager, ScriptType } from '@mikelgmh/cookie-manager';
var options = {
cookieCategories: [
{
title: 'Cookies funcionales',
description: 'This is a test description. You can change this in the options object.',
required: true,
scripts: [
{
type: ScriptType.STANDARD,
// gtmCode: '',
scriptSrc: 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.1/jquery.min.js',
async: true,
},
],
},
{
title: 'Cookies de analítica',
description: 'This is a test description. You can change this in the options object.',
required: false,
scripts: [
{
type: ScriptType.GTM,
gtmCode: 'GTM-XXXXXXX',
async: true,
},
],
},
],
};
const cookiesManager = new CookiesManager(options);
cookiesManager.init(true, false);