Skip to content

Latest commit

 

History

History
201 lines (137 loc) · 6.05 KB

README.md

File metadata and controls

201 lines (137 loc) · 6.05 KB
Raw

cookie-consent

In-house solution for managing cookies on nhs.uk

Quickstart

npm install
npm start

Go to http://localhost:8080/tests/example/ for an example site using the cookie javascript.

Usage

Include the cookie javascript in your page

<script src="/path/to/javascript.js" type="text/javascript"></script>

Any scripts that use cookies must be given a type="text/plain" attribute to stop the javascript from running, and a data-cookieconsent attribute so that cookie-consent knows which scripts to enable based on the user's consent settings.

Possible data-cookieconsent values are preferences, statistics and marketing.

<script src="/path/to/js-that-uses-cookies.js" data-cookieconsent="marketing" type="text/plain"></script>

Script Options

data-nobanner

If you want to prevent the cookie banner from showing automatically, add a data-nobanner attribute to the script tag.

<script src="./cookie-consent.js" data-nobanner type="text/javascript"></script>

If you disable the banner, you will have to write your own logic and interact with the javascript API to set user cookie consent.

data-policy-url

By default, the cookie policy link takes users to /our-policies/cookies-policy/. If you need the link to use a different url, you can set the data-policy-url attribute.

<script src="./cookie-consent.js" data-policy-url="/custom/policy/url" type="text/javascript"></script>

The cookie banner will not show on the policy page, even if you have embedded the cookie-consent.js script. This is because the user does not need to be presented with a cookie banner if they are on the page which can manage cookies.

Javascript API

The javascript API is exposed on a NHSCookieConsent global variable.

// shows the current cookie consent library version
console.log(NHSCookieConsent.VERSION)

Methods

  • getPreferences()
  • getStatistics()
  • getMarketing()

These methods get the status of the cookie consent for that type of cookie.
Returns a boolean.

  • getConsented()

This method gets the status of whether the user has positively interacted with the banner. It is primarily used to hide the banner once consent has been given.

  • setPreferences(value)
  • setStatistics(value)
  • setMarketing(value)

These methods set the status of the cookie consent for that type of cookie.
set methods should only be used in response to a user interaction accepting that type of cookie.
Expects a boolean value argument.

  • setConsented(value)

This method is used to set the consent that the user has given. It should be set to true when the user has taken an action which gives their consent. It should not be used to make the banner appear again for a user, as that is handled by the expiry date of the cookie.

Properties

  • VERSION the current version as defined in package.json

Compiling

This project uses Webpack and Babel

To compile the javascript in development mode, run

npm run build

For production mode, run

npm run build:production

Compiled javascript will be saved to dist/main.js.

Environment variables

Environment variables can be used at compile-time to change the cookie script behaviour.

NO_BANNER

Set to true to produce a javascript file that doesn't show the cookie banner. Instead consent will be implied for all cookie types.

NO_BANNER=true npm run build:production

POLICY_URL

By default, the cookie policy link takes users to /our-policies/cookies-policy/. If you need the link to use a different url, you can set this variable

POLICY_URL=/custom/policy/url/ npm run build:production

LOG TO SPLUNK

Set to true a logging URL will be hit when the banner shown, analytics are accepted or analytics are not accepted.

LOG_TO_SPLUNK=true npm run build:production

Tests

The tests require the javascript to be compiled. See the Compiling section above.

To run the Jest tests

npm test

To run only unit tests

npm run test:unit

To run only integration tests

npm run test:integration

N.B. The integration tests rely on there being a test server available on localhost:8080.

Deployment

When code is merged into the main branch an Azure build pipeline will be triggered. If the pipeline runs successfully it will produce a build artifact containing the compiled javascript.

To deploy the artifact simply create a release referencing the appropriate build artifact and run the release pipeline in Azure DevOps, selecting the required environments. The compiled javascript will be uploaded to the following Azure Storage Account:

Environment Storage Account Container Blob path
Integration nhsukassetsstaging dev nhsuk / js / cookie-consent.js
Staging nhsukassetsstaging staging scripts / cookie-consent.js
Production nhsukassets scripts cookie-consent.js

NOTE: When deploying to the Staging and Production environments, the Akamai cache should be flushed using the full URL of the javascript resource. The resource content can then be verified by accessing the URL in a browser.

Contributing to a release.

A new Tag must be made for the release following the versioning format. We use Semantic Versioning. IE. x.y.z where: x = Major version that causes incompatibilities, y = Minor change that adds a backwards compatible feature, z = Patch version for backwards compatible fixes. more information can be found at https://semver.org/

The release also must contain changes to the package version number to match the new tag.

If the release contains a change that will require the banner to be redisplayed to users, then the COOKIE_VERSION variable in cookieconsent.js must be increased by 1.

Notes

Currently, in-house development for this solution is primarily done on UNIX systems. There may be some difficulties when developing this solution on a windows machine.