Introduction to Cookie Control V8

Cookie Control is a JavaScript module that can help make a website compliant with EU cookie legislation; and specifically in version 8 with the General Data Protection Regulation's (GDPR) guidelines on the use of cookies.

The GDPR has a global reach, meaning all EU states and sites receiving EU visitors should seek user consent with an explicit opt in. With this in mind, Cookie Control v8 has been redesigned to run exclusively in what was previously known as "explicit mode".

As long as you have the ability to add JavaScript, the module will work on any platform and may be integrated with any JS library. This includes popular Google products such as Tag Manager and Universal Analytics; advertising aids such as the Facebook Pixel, and sharing tools such as AddThis. See how some of these may be integrated using the Optional Cookies Example.

Loading the module

You will need to include both the Cookie Control module, and your own configuration at an appropriate place in your document. The easiest way to load the Cookie Control module is from our CDN:

                              
                                  <!--  Latest Version  -->
                                  <script src="https://cc.cdn.civiccomputing.com/8/cookieControl-8.x.min.js" type="text/javascript"></script>

                                  <!--  SRI HASH of Specific Version  -->

                                  <!--  8.1  -->
                                  <script src="https://cc.cdn.civiccomputing.com/8/cookieControl-8.1.min.js" integrity="sha384-IxNAc6VrSYlLpEtwbpn1msykm1vI7qz2tFIop4jpqao0JuugIBqryEStDNP9rfIQ" crossorigin="anonymous"></script>

                                  <!--  8.0  -->
                                  <script src="https://cc.cdn.civiccomputing.com/8/cookieControl-8.0.min.js" integrity="sha384-aBljEElVtGPm5e/VQJaBZApqKrZGqXacpn6h6B39QzZQ+3yXd83NMD0YT1v60pxz" crossorigin="anonymous"></script>

                                  <!-- For a list of all available versions, please see the CookieControl Changelog -->
                              
                            

This is done for you automatically if you are using a CMS module - available for Drupal 8.x, Joomla 3.x, and Wordpress 4.x.

Beginning your configuration

You define (and create) your own configuration as a JavaScript Object, containing as many properties as you deem necessary.

To get started, detail both the apiKey and product type you have registered for; and then run Cookie Control's load() function to invoke them.

Limitations

Before exploring the configuration options further and outlining what Cookie Control can do; we feel it is important to go through the limitations so that you can assess whether or not the module is right for you.

First, no JavaScript module can remove all cookies that your site may set; and that's for good reason. It helps to safeguard your site and its users from potential security vulnerabilities. Cookie Control is no different, and in certain scenarios the most we can do is inform the user of the action they need to take.

Second, we cannot know all the ways that your site may set cookies, and require you to accurately set your own configuration. Should you do this, Cookie Control will provide users with an accessible means of explicitly granting, and revoking consent.

Configuration Options

Cookie Control allows you to control nearly every aspect of what it does - from informing your users of the types of cookies used, through to customising the appearance and text. Sensible defaults will exist for a lot of these properties, so you generally only need to include those that you'd like to overwrite.

The exceptions to this are apiKey, product and optionalCookies. While the first two may strictly speaking be the only required properties for Cookie Control to load (discussed in the Getting Started section), the end user will ultimately receive little value if you do not accurately set how your site uses cookies. With this in mind, we have grouped the configuration options into two groups: those related to controlling cookies, and customisation options that may be thought of as entirely option.

Controlling the use of Cookies

Option Description Type
necessaryCookies

This is a list of cookies names necessary for your website's core functionality, that you wish to protect from the module's deleteAll() function. In most cases you won't have to set this option, as typically these cookies will be issued by the server as Secure and HttpOnly, which are automatically protected.

Note - it is possible to use the * wildcard at the end of a cookie name, if you want all cookies that start with this prefix to be protected.

array of strings No Default
optionalCookies

This is a list of purposes that your website may use. The module's core behaviour will be dependent on you accurately setting this option, as it informs the user of the different cookies the website may set, and offers them controls for opting in or out.

Each purpose will be defined as its own object, so please refer to the Purpose Object section below for a description of all the properties available.

array of objects No Default
consentCookieExpiry

Determines how many days the consent of the user will be remembered for. This setting will apply globally to all categories.

number 90
statement

Cookie Control will respect user given consent until either the cookie expires, or there is a change in your privacy statement.

Please refer to the Statement Object section below for a description of all the properties available.

object No Default
logConsent

Determines whether or not Cookie Control should record the user's granting or revoking of consent.

Please note, this is also dependent on you having agreed with CIVIC's data processor agreement. Please sign in to update your settings.

boolean true

Purpose Object (Cookie Category)

The optionalCookies property may contain as many Purpose Objects as you require, though we recommend either using a couple of simple categories such as Analytics, Social Networks, and Marketing; or the broader terms recognised by the IAB: Information storage and access, Personalisation, Ad selection, delivery, reporting, Content selection, delivery, reporting, and Measurement. Find out more about the IAB here.

Each Purpose Object may consist of:

Option Description Type
name

A unique identifier for the category, that the module will use to set an acceptance cookie for when user's opt in.

string None
label

The descriptive title assigned to the category and displayed by the module. This value may be overwritten depending on your locale property and user's preferences.

string Purpose {index}
description

The full description assigned to the category and displayed by the module. This value may be overwritten depending on your locale property and user's preferences.

array of objects A description for {label} has not been provided.
cookies

The name of the cookies that you wish to protect after a user opts in.

Note that you can use the * wildcard at the end of the name, if want to define more than one cookies that share the same prefix.

array of strings None
thirdPartyCookies

Only applicable if the category will set third party cookies on acceptance. Each object will consist of the following key-value pairs:

  • name : string
  • optOutLink : url string
array of objects None
onAccept

Callback function that will fire on user's opting into this cookie category.

function None
onRevoke

Callback function that will fire on user's opting out of this cookie category. Should the thirdPartyCookies be set for this Purpose, the module will automatically display a warning that manual user action is needed.

function None
recommendedState

Defines whether or not this category should be accepted (opted in) as part of the user granting consent to the site's recommended settings.

If true, the UI will update to show the category toggled 'on' and the user's consent will be recorded if logConsent is enabled.

boolean false
lawfulBasis

Defines whether this category requires explicit user consent, or if the category can be toggled on prior to any user interaction and justified under the more flexible lawful basis for processing: legitimate interest.

Possible values are either consent or legitimate interest. If the latter, the UI will show the category toggled 'on', though no record of consent will exist.

If you choose to rely on legitimate interest, you are taking on extra responsibility for considering and protecting people’s rights and interests; and must include details of your legitimate interests in your privacy statement. Read more from the ICO

string consent

Example

Below is an example of how you might set optionalCookies to define three categories (Analytics, Marketing and Social Sharing), that uses the onAccept to add Google Analytics, Facebook Pixel, and AddThis respectively.

Statement Object

If the statement property exists, a description and link to your privacy policy is added after the module's introductory text. Cookie Control will check this property on each load to ensure the user's record of consent coincides with the same privacy policy. Should the Statement Object change, the module will revert to its initial state as though it is the first time the user is accessing the site, and will seek their consent again.

The Statement Object must consist of:

Option Description Type
description

The text description that introduces your privacy statement.

string
name

The text that you wish to call your terms by, for example Privacy Statement.

string
url

The URL where your terms may be accessed. This link will try to open in a new tab, so it may point to a PDF document without closing the user's access to your site.

string
updated

The date that your privacy statement was last issued, in the format of dd/mm/yyyy.

string

Example

Customising appearance and behaviour

All of the following properties may be considered entirely optional, as Cookie Control will use sensible defaults for any property not present in your configuration - this means you only need to include those you wish to overwrite.

Option Description Type
initialState

Determines the initial display state of Cookie Control.

Possible values are either open, closed, or notify (pro licenses only).

string closed
notifyOnce

Determines whether the module only shows its initialState once, or if it continues to replay on subsequent page loads until the user has directly interacted with it - by either toggling on / off a category, accepting the recommended settings, or dismissing the module.

boolean false
layout

Determines the display type and behaviour of Cookie Control.

Possible values are either slideout or popup (pro licenses only).

string slideout PRO
position

Determines the side of the display Cookie Control will occupy.

Possible values are either left or right.

string right
theme

Determines the appearance of Cookie Control.

Possible values are either light or dark.

string right
toggleType

Determines the control toggle for each item within optionalCookies

Possible values are either slider or checkbox.

string slider
closeStyle

Determines the closing behaviour of the module.

Possible values are either icon, labelled or button.

string icon
text

Determines the text used by Cookie Control. Please refer to the Text Object section below for a description of all the properties available.

object
branding

With pro and pro_multisite licenses, you are able to set all aspects of the module's styling, and remove any back links to CIVIC. Please refer to the Branding Object section below for a description of all the properties available.

objectPRO
excludedCountries

With pro and pro_multisite licenses, you are able to disable the module entirely for visitors outside of the EU. Either add the value all, or a list of 2 letter ISO codes for the countries you wish to disable the module for. Using the value all will mean the widget will be shown to users coming from IPs that belong to EU countries only.

array of stringsPRO
locales

With pro and pro_multisite licenses, you are able to offer alternative text depending on your user's preferences. Please refer to the Locale Object section below for a description of all the properties available.

array of objectsPRO
onLoad

Defines a function to be triggered after the module initiates the defined configuration.

function none
accessibility

Determines the accessibility helpers available, such as the accesskey and keyboard focus style. Please refer to the Accessibility Object for more information.

function

Example

Text Object

The text object consists of various string properties, and is entirely optional. Cookie Control will use sensible defaults for any property not present in your configuration - this means you only need to include those you wish to overwrite.

All properties may in turn be overwritten by your locale property, should the user's preferences coincide.

Option Default
title

This site uses cookies to store information on your computer.

intro

Some of these cookies are essential, while others help us to improve your experience by providing insights into how the site is being used.

acceptRecommended

Accept Recommended Settings

necessaryTitle

Necessary Cookies

necessaryDescription

Necessary cookies enable core functionality such as page navigation and access to secure areas. The website cannot function properly without these cookies, and can only be disabled by changing your browser preferences.

thirdPartyTitle

Some cookies require your attention

thirdPartyDescription

Consent for the following cookies could not be automatically revoked. Please follow the link(s) below to opt out manually.

on

On

off

Off

notifyTitle

Your choice regarding cookies on this site

notifyDescription

We use cookies to optimise site functionality and give you the best possible experience.

accept

Accept

settings

Cookie Preferences

closeLabel

Close

accessibilityAlert

This site uses cookies to store information. Press accesskey C to learn more about your options.

Example

Branding Object PRO

The branding object consists of various properties, and is entirely optional. Cookie Control will use sensible defaults for any property not present in your configuration - this means you only need to include those you wish to overwrite.

Option Description
fontFamily

The CSS font-family that you'd like to use for the entire module.

string default: Arial, sans-serif

fontSizeTitle

The CSS font-size that you'd like to use for the main (h2) title when the module is opened.

string 1.2em

fontSizeHeaders

The CSS font-size that you'd like to use for the sub (h3) titles when the module is opened.

string 1em

fontSize

The CSS font-size that you'd like to use throughout the module for body text.

string 0.8em

fontColor

The CSS color that you'd like to use for all text and icons within the module.

string dark theme default: #FFF light theme default: #333

backgroundColor

The CSS background-color that you'd like to use throughout the module.

string dark theme default: #313147 light theme default: #f4f4f4

acceptText

The CSS color that you'd like to use for the text within the module's primary 'accept' buttons.

string dark theme default: #fff; light theme default: #111125

acceptBackground

The CSS background-color that you'd like to use for the module's primary 'accept' buttons.

string dark theme default: #313147; light theme default: #fff

toggleText

The CSS color that you'd like to apply to the toggle button's text.

string dark theme default: #FFF light theme default: #333

toggleColor

The CSS background-color that you'd like to use for the movable part of the toggle slider.

string dark theme default: #2f2f5f light theme default: #000

toggleBackground

The CSS background-color that you'd like to use for the toggle background.

string dark theme default: #111125 light theme default: #555

alertText

The CSS color that you'd like to use within the alert areas, such as to announce manual user actions for third party cookies.

string dark theme default: #fff; light theme default: #000

alertBackground

The CSS background-color that you'd like to use to highlight the alert areas, such as to announce manual user actions for third party cookies.

string dark theme default: #111125 light theme default: #eaeaea

buttonIcon

The URL address of an image you'd like to use instead of the CIVIC C icon in the bottom corner.

string

buttonIconWidth

If buttonIcon exists, the css width that you'd like this image to be sized to.

string default: 64px

buttonIconHeight

If buttonIcon exists, the css height that you'd like this image to be sized to.

string default: 64px

removeIcon

Whether or not to remove the button icon entirely. Please note, if you do this, you will need to present an alternative trigger to run the module's open() function.

boolean default: false

removeAbout

Whether or not to remove the 'About this tool' link to CIVIC at the bottom of the module.

boolean default: false

Example

Locale Object PRO

The locales property may contain as many Locale Objects as you require. Each Object may consist of:

Option Description type
locale

Defines who the contained language settings would be appropriate for. Accepts either a full locales (en_US), or two letter language code (en). Where both are present and matched with the current user's preference, the more specific locale will be used.

string
text

The text object mirrors that of the default text object, and allows you to localise all values to this particular locale / language. Please refer to the Text object section for more information.

object
optionalCookies

The optionalCookies array mirrors that of the default optionalCookies array, though only expects each object to contain a localised value for label and description. Please refer to the Text object section for more information.

object

Example

Accessibility Object

Option Description type
accessKey

Remaps the accesskey that the module is assigned to.

string C
highlightFocus

Determines if the module should use more accentuated styling to highlight elements in focus, or use the browser's outline default.

If enabled, this property uses CSS filters to invert the module's colours. This should hopefully mean that a higher visual contrast is achieved, even with a custom branding.

boolean false

Public Methods

Cookie Control offers various public methods to help make interacting with the module, and generally managing Cookies easier.

Please note, that by using some of these methods to set your own custom behaviour, you are taking on extra responsibility for considering and protecting people’s rights and interests.

Method Description
load

Initiates the module based on the defined configuration object, passed in as a parameter.

function CookieControl.load( { ... config } )

update

Updates the module with a new configuration object, passed in as a parameter.

function CookieControl.update( { ... config } )

open

Triggers the module's open state. Useful if you wish to add your access points within privacy pages, etc.

function CookieControl.open()

hide

Triggers the module's closed state. Useful if you have opened it with your own access points.

function CookieControl.hide()

notifyAccept

Programmatically sets the notification bar as accepted, which in turn activates the configuration's recommended purposes. Useful if you wish to add your own behaviour, such as accepting after scroll.

If you choose to use this method, you are taking on extra responsibility for considering and protecting people’s rights and interests. Should you simply wish to hide the notification bar use notifyDismiss()

function CookieControl.notifyAccept()

notifyDismiss

Programmatically sets the notification bar as dismissed. Useful if you wish to add your own behaviour, such as dismissing after scroll.

function CookieControl.notifyDismiss()

config

Returns the configuration object currently used by the module.

function CookieControl.config()

geoInfo

Returns the geoLocation object used by the module, describing a user's location by name, ISO code and EU status.

function CookieControl.geoInfo()

getCookie

Retrieve a cookie, by passing its name as a string parameter.

Returns the value of the cookie if it exists, or 'false' otherwise.

function CookieControl.getCookie('CookieControl')

getAllCookies

Retrieves all cookies set on the current page.

Returns an object with key value pairs of the cookies and their respective values.

function CookieControl.getAllCookies()

saveCookie

Saves a cookie, by passing its name, value, and expiryLength as a parameters.

function CookieControl.saveCookie( 'name', 'value', 90 )

delete

Deletes a cookie, by passing its name as a string parameter.

function CookieControl.delete('CookieControl')

deleteAll

Deletes all cookies set on the current page.

function CookieControl.deleteAll()

toggleCategory

Toggles consent to a given purpose (cookie category), passed as a number parameter describing its index within the optionalCookies array.

If the user has previously given consent to this category, consent is revoked, otherwise consent is granted.

Please note, this method does not issue a record of consent in our database. Only consent given by the user is recorded.

function CookieControl.toggleCategory( 0 )

Cookies Set By Cookie Control

When a user interacts with the module, their consent is recorded by as a first party cookie to remember that decision.

In version 8.0, the name of that cookie will be dependent on the name set in the configuration for that category; and only added after the user opts in.

In version 8.1, the introduction of lawfulBasis has meant that the module needs to remember when a user revoke's consent as well, so we have simplified the cookies the module may set to a single one, named CookieControl. This is still a first party cookie, used only to remember the user's preferences on your domain, and lasts for as long the consentCookieExpiry defined in your configuration (defaults to 90 days if not set).

API Validation and domains

Cookie Control will attempt to verify your apiKey and product automatically against the current domain that its being run on to ensure your license is being used as intended.

For community editions, only the single domain that you registered will pass; for example https://mydomain.com or https://www.mydomain.com

For pro editions, the single domain that you registered will pass, along with any subdomains; for example https://mydomain.com or https://sub.mydomain.com

For pro multisite editions, all domains that you have registered will pass, along with any subdomains.


If you have already registered, you can check what domain(s) we hold against your license, and add more by signing in to your user account. Should you wish to upgrade your license to enable subdomain or multiple domain support, the cost of your current license will be refunded from the amount due.

Update Settings

Issues

If you have a technical issue don't worry, help is on hand.

All members can access our Community Support help pages, while those with an active paid subscription can open a ticket with our support team and we'll give you a unique ticket number to track the solution's progress.

Community Support Open a support ticket

Changelog

v8.1

14/08/2018
  • Added alternative closing and toggle styles for the module.
  • Improved accessibility support.
  • Added support for more flexible lawful basis processing: legitimate interest.
  • Renamed initialConsentState to recommendedState so that it was intuitive.
  • Extended the branding options available.
  • Simplified the module's Cookie Footprint, and removed need for localStorage.
  • Automatically convert invalid cookie name's from user settings to valid alternatives.
  • Added onLoad property.
  • Extended public methods with saveCookie() and geoInfo().
  • Original GDPR Compliant Release
  • Simplified UI options
  • No dependencies
  • Polyfills for anything below IE11 removed.

v8.x

  • Latest stable release of Cookie Control.

* Please note, Subresource integrity is available on all versions, though we may update beta versions without warning to resolve certain user feedback. The latest URL will be updated periodically to incorporate the latest stable release.