Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dxw/govuk-cookie-consent
A solution for managing cookies on GOV.UK services. Based on NHS Cookie Consent.
https://github.com/dxw/govuk-cookie-consent
client delivery-plus
Last synced: 21 days ago
JSON representation
A solution for managing cookies on GOV.UK services. Based on NHS Cookie Consent.
- Host: GitHub
- URL: https://github.com/dxw/govuk-cookie-consent
- Owner: dxw
- License: mit
- Created: 2021-03-16T14:50:06.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-12-05T01:26:36.000Z (29 days ago)
- Last Synced: 2024-12-05T02:26:26.239Z (29 days ago)
- Topics: client, delivery-plus
- Language: JavaScript
- Homepage:
- Size: 2.07 MB
- Stars: 3
- Watchers: 10
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# cookie-consent
A solution for managing cookies on GOV.UK services. Based on [NHS Cookie Consent](https://github.com/nhsuk/cookie-consent).
## Quickstart
```sh
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
```html
```
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`.
```html
```
### Cookie Settings page
There is also an optional form for you to add to your [cookies page](https://design-system.service.gov.uk/patterns/cookies-page/).
To use this, add the following markup to your Cookies Page:
```html
Change your cookie settings
We cannot change your cookie settings at the moment because JavaScript is
not running in your browser. To fix this, try:
- turning on JavaScript in your browser settings
- reloading this page
```
You can alter the `data-analytics`, `data-marketing` or `data-preferences` data attributes, depending on what options you need to display. For example, the following only show options for analytics cookies:
```html
...
```
### Script Options
#### `data-service-name`
By default, the banner shows the service name as `GOV.UK`.
To set this to your service, add a `data-service-name` attribute to the
script tag:
```html
```
#### `data-no-banner`
If you want to prevent the cookie banner from showing automatically, add a
`data-nobanner` attribute to the script tag.
```html
```
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.
```html
```
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 GovUkCookieConsent global variable.
```js
// shows the current cookie consent library version
console.log(GovUkCookieConsent.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](https://webpack.js.org/) and [Babel](https://babeljs.io/)
To compile the javascript in development mode, run
```sh
npm run build
```
For production mode, run
```sh
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.
#### `SERVICE_NAME`
By default, the banner shows the service name as `GOV.UK`.
To set this to your service, you can set this variable
```sh
SERVICE_NAME="Check the MOT status of a vehicle" npm run build:production
```
#### `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.
```sh
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
```sh
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.
```sh
LOG_TO_SPLUNK=true npm run build:production
```
## Tests
To run the [Jest](https://jestjs.io/en/) tests
```sh
npm test
```
To run only unit tests
```sh
npm run test:unit
```
To run only integration tests
```sh
npm run test:integration
```
N.B. The integration tests rely on there being a test server available on localhost:8080.
## 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 comptible 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.