@hmcts/cookie-manager is a JavaScript library for handling and managing a services cookies.
npm install @hmcts/cookie-managerCookie Manager ·



======
@hmcts/cookie-manager is a JavaScript library for dealing with cookie compliance.
It provides a streamline way to define essential and non-essential cookies on a service,
which then acts as a basis for user’s to provide consent for each different category of cookie.
The minified script is just under 4KB (after GZIP) and supports IE11 / ES5 by default.
This library is intended to be used with the GDS Cookie Banner component
though it can be configured to support a variety of multi-stage cookie banners of varying designs.
**In-depth documentation on all configuration options, emitted events, configuration with common analytics
libraries and more can be found on the project's documentation site.**
#### 1. Install with NPM (recommended)
We recommend installing cookie-manager through Node's package
manager (NPM) or Yarn.
#### 2. Install using compiled script
You can also install cookie-manager by serving our compiled JavaScript
file
(included on each release).
In short, the library works by binding event listeners to the buttons defined for each action, with these
actions being specified within the config.
Each action defines:
- How consent should be affected
- What confirmation message should be shown
#### An example action of an action and how it works:
``json`
{
"name": "accept",
"buttonClass": "cookie-banner-accept-button",
"confirmationClass": "cookie-banner-accept-message",
"consent": true
}cookie-banner-accept-button
This action specifies that upon an element with the class (within the cookie banner) being clicked:
1. We consent to all optional cookie categories.
2. Any elements with the class cookie-banner-accept-message (within the cookie banner) should be shown.CookieBannerAction
3. A event is then emitted with the activated action's name (in this case, 'accept') being passed to any listening callbacks.
More information about how the cookie banner functionality and how it can be configured
to support a variety of different action/message (stage-based) cookie banners can be found
within the docs.
In short, on the form submission event:
1. The radio groups within the form are parsed.
2. Each selected option is matched to a cookie category (based on the radio element's name attribute).value
3. The consent value for the selected option is derived from the radio element's attribute, which should be either on or off.
4. The selected options are then set as user's active cookie preferences.
The form layout needs to be configured for each different cookie category you are utilising within your service.
This requires you to add another set of radio inputs, with the name attribute set to that of your cookie category,on
using /off as their values for consent / reject respectively.
More information about the cookie preferences form functionality and how it can be configured can be found
within the docs.
and off functions from the library, you can easily add callbacks to each event which fires.
This could be used to disable a third party analytics package, conditionally change the DOM etc.`js
import cookieManager from '@hmcts/cookie-manager';const someEventCallback = function (eventData) { ... };
cookieManager.on('', someEventCallback);
`More information about the built-in event processor / emitter can be found
within the project's documentation.
A list of the events fired by the Cookie Manager library can also be found here.
You can also see an example of this used to enable / disable Google Analytics (through GTM) and
Dynatrace RUM based on user preferences here within the docs.
Configuration
Configuration of the library is done through a config provided to the exposed init function
used when initializing the library. The default configuration is:
`json
{
"userPreferences": {
"cookieName": "cookie-preferences",
"cookieExpiry": 365,
"cookieSecure": false
},
"preferencesForm": {
"class": "cookie-preferences-form"
},
"cookieBanner": {
"class": "cookie-banner",
"showWithPreferencesForm": false,
"actions": [
{
"name": "accept",
"buttonClass": "cookie-banner-accept-button",
"confirmationClass": "cookie-banner-accept-message",
"consent": true
},
{
"name": "reject",
"buttonClass": "cookie-banner-reject-button",
"confirmationClass": "cookie-banner-reject-message",
"consent": false
},
{
"name": "hide",
"buttonClass": "cookie-banner-hide-button"
}
]
},
"cookieManifest": [],
"additionalOptions": {
"defaultConsent": false,
"deleteUndefinedCookies": false,
"disableCookieBanner": false,
"disableCookiePreferencesForm": false
}
}
`See our documentation to learn more about configuring and initializing the library,
or to view the other configuration options available.
The provided templates/examples within the documentation are intended to require little extra
configuration to get a basic cookie compliance solution working on your service.
**Note: Cookie Manager will attempt to validate the config passed to it on initialization.
If any malformed, missing properties etc. are supplied, the library will be disabled until it is resolved.
A warning will be printed in the console alerting of the problematic property.**
Development
$3
There are currently 2 seperate build options for this library
-
build:package - builds the esm version of the module, intended to be used with NodeJS based applications.
Includes TS declarations / typings and JSDoc comments on exposed functions.
- build:browser - builds the umd version of this module, intended for use directly within browsers (script tag).
Builds a minified version of the library.Both builds use rollup.js and a number of plugins
to compile, minify, and create declarations for the library.
$3
This project currently only uses dependencies for linting and building the project.$3
Follow the setup guide on installing and initializing the module within NodeJS,
this project provides type declarations built in, so for projects using TypeScript,
you should see typings support.Testing
To run the tests run npm run test or to see the coverage, npm run test:coverage`.As of v1.0.0 of this library, there are over 110 unit tests with a coverage of around 95%.
Manual testing has also been performed across most major browsers, including IE11.
Note: The unit tests will fail if coverage is found to be below 90%.
Linus Norton - Additional support