Govuk-single-consent NPM

Single Consent client

The Single Consent client is a small Javascript which can be embedded in a website to enable easily sharing a user's consent or rejection of cookies across different websites.

See the Single Consent service README.

Quick start

See the CommonJS example.

Contact data-tools-team@digital.cabinet-office.gov.uk to get the URL of the API endpoint.

The library provides the following static methods for finding out which types of cookies a user has consented to.

hasConsentedToEssential
hasConsentedToUsage
hasConsentedToCampaigns
hasConsentedToSetting

The method GovSingleConsent.getConsents() provides the current state of the user's consents to all types of cookies.

1. Install with npm

In order to set first-party cookies, the client Javascript must be served with your application.

We recommend installing the Single Consent client using node package manager (npm).

npm i govuk-single-consent

https://www.npmjs.com/package/govuk-single-consent

2. Including the Javascript client

The javascript client can be included in different ways. Choose one below.

CommonJS

See the example.

Typescript

See the example.

HTML script tag (IIFE)

The javascript client makes available the object window.GovSingleConsent for interacting with the API. It needs to be loaded on any page that could be an entry point to your web application, that allows modifying cookie consent, or provides a link to another domain with which you want to share cookie consent status. It is probably easiest to add the script to a base template used for all pages.

On the same pages, you need to load your javascript for interacting with the window.GovSingleConsent object.

See the following examples.

It is common practice to add Javascript tags just before the end </body> tag, eg:

    ...

    <script src="{path_to_client_js}/singleconsent.js"></script>
    <script src="{path_to_cookie_banner_script}.js"></script>
    <script src="{path_to_cookies_page_script}.js"></script>
  </body>
</html>

3. Passing the base URL to the constructor

You can either pass an environment string, or a custom base URL.

If using an environment string, its value should be either staging or production.

e.g

const dummyCallback = () => {}

// With an environemnt string to the staging environment
new GovSingleConsent(dummyCallback, 'staging')

// With an environemnt string to the production environment
new GovSingleConsent(dummyCallback, 'production')

// With a custom base URL
new GovSingleConsent(dummyCallback, 'http://some-development-url.com')

4. Share the user's consent to cookies via the API

When the user interacts with your cookie banner or cookie settings page to consent to or reject cookies you can update the central database by invoking the following function:

exampleCookieConsentStatusObject: Consents = {
  essential: true,
  settings: false,
  usage: true,
  campaigns: false,
}

singleConsentObject.setConsents(exampleCookieConsentStatusObject)

Content Security Policy

If your website is served with a Content-Security-Policy HTTP header or <meta> element, you may need to modify it to allow the client to access the Single Consent service. The value of the header or meta element should contain the following:

connect-src 'self' https://consent-api-nw.a.run.app/api/v1/consent [... other site URLs separated by spaces];

What the library does

The library manages all read/write operations with a cookie that stores the state of a user's consent.

Callback

Websites using the Consent API must provide a callback function. This will be invoked each time the consent has been updated. It will be called with three parameters:

consents An object describing the new consent state.
consentsPreferencesSet Boolean, the cookie banner must be displayed if this value is false.
error An object describing any error, otherwise null. If there is an error, then the consents object will say that the consents have been revoked.

The structure of the consent data object is currently based on the GOV.UK cookies_policy cookie. If your website cookies do not fall into any of the four categories listed, please contact us.