gdprconsent

A free solution to the GDPR and EU Cookie Laws

View project on GitHub

JavaScript API

Example

This example places an informational (default) black and white popup with a yellow button inside the body of a website. Location is switched on an so this example will send the users IP to Maxmind to get the country code as assess if the user needs to see the notice based on location.

  <script src="js/gdprconsent.min.js"></script>
  <script type="text/javascript">
      var GDPR_VERSION = '25-May-2018';
      window.addEventListener("load", function(){
        window.gdprconsent.initialise({
          container: document.getElementsByTagName("body"),		//Change this to the element you wish
          "GDPR_VERSION": GDPR_VERSION,
          "cookie": {
            "domain": "localhost",
            "path": "/",
            "expiryDays": 365,
          },
          "palette": {
            "popup": {
              "background": "#000"
            },
            "button": {
              "background": "#f1d600"
            }
          },
          "type": "info"
          "location": true
        });
      });
  </script>

Main options

These are the main options that can be passed to the Cookie Consent tool.

GDPR_VERSION (string) Default: ‘25-May-2018’

Please add your version or date of the privacy policy. This field is used to set a gdpr_version cookie and if the version in the code does not match the version in the cookie, the notice will be shown once more.

enabled (boolean) Default: true

This can be used to disable the popup. It is internally used to disable itself (if needed), but can be configured externally too.

container (HTMLElement) Default: null

The tool is automatically appended to the HTML body. Use this option to select the parent element. Use autoOpen: false to prevent the tool automatically appending itself to any container.

It is recommended to set these values to correspond with your server. You MUST set the ‘domain’ option, otherwise your cookies may not work.

cookie.name (string) Default: ‘gdprconsent_status’

Name of the cookie that keeps track of users choice

cookie.path (string) Default: ‘/’

URL path that the cookie ‘name’ belongs to. The cookie can only be read at this location

cookie.domain (string) Default: ‘‘

The domain that the cookie ‘name’ belongs to. The cookie can only be read on this domain. Guide to cookie domains

cookie.expiryDays (integer) Default: 365

The cookies expire date, specified in days (specify -1 for no expiry)

Content options

Text strings used for cookie consent window elements.

content (object) Defaults:

content: {
  header: 'Privacy &amp; Cookie notice!',
  message: 'This website requires cookies, and the limited processing of your personal data in order to function. For more information please read our',
  allow: 'OK',
  deny: 'Decline',
  link: 'Privacy policy',
  href: 'http://cookiesandyou.com',
  close: '&#x274c;',
},

Overwrite these default options to change the content within the tool

Custom HTML options

elements (object) Defaults:

elements: {
        header: '<span class="gc-header"></span>&nbsp;',
        message: '<span id="gdprconsent:desc" class="gc-message"></span>',
        messagelink: '<span id="gdprconsent:desc" class="gc-message"> <a aria-label="learn more about our privacy policy" role=button tabindex="0" class="gc-link" href="" rel="noopener noreferrer nofollow" target="_blank"></a></span>',
        allow: '<a aria-label="allow cookies" role=button tabindex="0"  class="gc-btn gc-allow"></a>',
        deny: '<a aria-label="deny cookies" role=button tabindex="0" class="gc-btn gc-deny"></a>',
        link: '<a aria-label="learn more about cookies" role=button tabindex="0" class="gc-link" href="" target="_blank"></a>',
        close: '<span aria-label="deny cookie message" role=button tabindex="0" class="gc-close"></span>',

        //compliance: compliance is also an element, but it is generated by the application, depending on `type` below
      },

This is the HTML for the elements above. Any word surrounded by ‘’ will be automatically replaced. The string will be replaced with the equivalent text above. You can remove “” and write the content directly inside the HTML if you want.

window (string) Default:

<div role="dialog" aria-live="polite" aria-label="gdprconsent" aria-describedby="gdprconsent:desc" class="gc-window"><div class="gc-notice "><!--googleoff: all--><!--googleon: all--></div></div>

Window is the ‘container’ that houses the popup contents. It has the HTML class ‘gc-window’ The placeholders and both get replaced during initialisation. The gc-window places a shroud over the page so that the only interaction is with the popup. The popup itself will appear within gc-notice and will appear in the center of the page.

deathShroud (string) Default:

<div role="dialog" aria-live="polite" aria-label="gdprconsent denied" aria-describedby="gdprconsent:desc" class="gc-death-shroud"><div class="gc-notice "><!--googleoff: all--><p>You have chosen to decline the privacy policy and therefore we cannot provide this service to you.</p><p>If you have changed your mind, either refresh the page or click on the "Privacy Policy" tab.</p><!--googleon: all--></div></div>

This is shown when using opt-in and the user has declined. The user will only be able to interact with the revoke tab.

Position

position (string) Default: bottom

Position is used to describe where on the screen your revoke should display. The other option is top.

Palette options

Colours can be defined in additional stylesheets or using attributes.

palette (object) Default: null

If palette is set to null, colours have to be defined in CSS.

To pass the colours using attributes, use:

palette: {
  popup: {background: '#000000', text: '#fff', link: '#fff'},
  button: {background: 'transparent', border: '#f8e71c', text: '#f8e71c'},
  highlight: {background: '#f8e71c', border: '#f8e71c', text: '#000000'},
}

Highlight is optional and extends button. if it exists, it will apply to the rightmost button. Only background needs to be defined for every element. If text or border colour is not set, it will be calculated from the background colour.

Revoke options

Some countries require consent to be revokable. Cookie Consent keeps track of these countries and adds a button to review the consent window.

revokable (boolean) Default: false

If set true, revoke button is displayed every time. If false, revoke button is only displayed for advanced compliance options (opt-in and opt-out) and in countries that require revokable consent. The latter can be disabled by regionalLaw below.

revokeBtn (string) Default: <div class=”gc-revoke ”>Privacy Policy</div>

This is the html for the revoke button. This only shows up after the user has selected their level of consent.

animateRevokable (boolean) Default: true

If true, the revocable button will translate in and out. Disabled by default for mobile devices.

Callback hooks

Called at certain points in the program execution

This is called when the popup is opened. It can be used to trigger an animation, or to attach extra handlers, etc.

onPopupOpen: function() {}

This is called when the popup is closed. It can be used to clean up commands from onPopupOpen

onPopupClose: function() {}

This is called on start up, with the current chosen compliance. It can be used to tell you if the user has already consented or not as soon as you initialise the tool.

onInitialise: function(status) {}

This is called any time the status is changed. This can be used to react to changes that are made to the compliance level. You can use the popup instance functions from within these callbacks too. I.E. ‘this.hasAnswered()’ and ‘this.hasConsented()’.

onStatusChange: function(status, chosenBefore) {}

This is called when the user clicks the ‘revoke’ button. This means that their current choice has been invalidated.

onRevokeChoice: function() {}

Hooks can be used to disable cookies when consent is not given, and the generally extend the tool.

Location options

The location services are disabled by default. You are encouraged to implement a handler to your own service, rather than using the free ones provided.

To enable the basic location services, set ‘location’ to ‘true’. To add you own services or configure the order or execution, pass an object with configuration properties.

location.timeout (array) Default: 5000 (milliseconds)

We can’t react to errors from script tag resources, so we set a timeout. If we don’t have the answer after 5000ms, try the next service.

location.services (array) Default: [‘maxmind’, ‘ipstack’]

This array defines the services that you want to use. We attempt to get the country code from the first service, and only if the service fails do we move onto the next service. If all services fail, the popup is opened without modification.

If a service succeeds, then the two letter country code is passed to the ‘Law’ module, with changes your popup options depending on the cookie laws in the country code.

location.serviceDefinitions (object)

This can be used to define new services via a key, but new services they can also go straight into the ‘services’ array in an ad-hoc fashion. It is recommended that you define services in ‘serviceDefinitions’ and use ‘services’ to configure priority between services