Introduction to Cookie Control

Cookie Control is a JavaScript module that can help make a website compliant with EU cookie legislation; and specifically since 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 has been redesigned to run by default in what was previously known as "explicit mode".

Since version 9 we have also added support for the California Consumer Privacy Act (CCPA). When using Cookie Control in CCPA mode, all cookie purposes will be enabled by default and users will see a "Do Not Sell My Personal Information" button giving them the option to opt out of the use cookies. Please note that this mode is incompatible with IAB TCF's v2.0 which requires the mode to be GDPR.

Version 9.3 have also adds support for the Brazilian General Data Protection Act (LGPD). LGPD greatly resembles GDPR, but requires users to explicitly explain the vendors that place cookies (when GDPR focuses on the "purposes" for which cookies are used).

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:

You load the module in exactly the same way for all Cookie Control editions, though the features available differ. Compare the features and prices of Cookie Control editions here.

                              
                                  <!--  Latest Release with support for IAB TCF v2.0 -->
                                  <script src="https://cc.cdn.civiccomputing.com/9/cookieControl-9.3.1.min.js"></script>

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

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

CMS modules are available for Drupal 8.x/Drupal 9.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
apikey

The apikey of your license.

string No Default
product

The product corresponding to your license's plan. It can be either 'COMMUNITY', 'PRO', or 'PRO_MULTISITE'.

string No Default
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 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
mode

Determines the mode in which Cookie Control runs. Possible values are either 'GDPR' or 'CCPA'.

When in GDPR mode, cookies will default to being off, allowing the user to opt in, while when in CCPA mode cookies will default to on and users will be allowed to opt out. In CCPA mode users can also click on a "Do Not Sell My Personal Information" button to opt out from optional cookies in bulk, as required by the legislation.

For Pro users where geolocation is available, Cookie Control will always run in "gdpr" if the website visitor is inside the EU or inside Brazil.

Furthermore, Pro users will be able to override this property for specific locations, for example use CCPA inside the USA or in California only. See the Locale object for more details.

Finally please note that when using CCPA mode you need to configure the CCPA Configuration Object property with a link to your Personal Information Policy (see below).

string gdpr
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
ccpaConfig

When using Cookie Control in CCPA mode, use this object to customise the CCPA required link name and description. Similarly to the statement object Cookie Control will respect user given consent until there is a change in the CCPA Personal Information Policy.

Please refer to the CCPA Configuration 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
encodeCookie

Determines whether or not the value of Cookie Control's own cookie should be encoded as a Uniform Resource Identifier (URI) component.

boolean false
subDomains

Determines whether Cookie Control's own cookie is saved to the top level domain, and therefore accessible on all sub domains, or disabled and saved only to the request host.

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.

string 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
vendors

The vendors that place the cookies.

You can use this if you want to explicitly display the vendors that place the cookies that you use. This is particularly useful if you are targeting users in Brazil and want to comply with LGPD.

Each vendor object consists of the following properties:

  • name : string
  • description : string
  • url : URL string
  • thirdPartyCookies : boolean
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.

Alternatively, if you use Google Tag Manager (GTM) you may configure categories to run specific events depending on the user's preference. For example, within GTM you can create an event "analytics_consent_given" to run your choice of analytics software and associate it with a user action via the onAccept proerty.

More information on custom events can be found here.

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

CCPA Configuration Object

This object is nearly identical to the statement object, but should be used when Cookie Control runs in CCPA mode, in which case a description and link to your Personal Information 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.

The CCPA Configuration Object must consist of:

Option Description Type
description

The text description that introduces your Personal Information Policy.

string
name

The text that you wish to call your terms by, for example Personal Information Policy.

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 Personal Information Policy was last issued, in the format of dd/mm/yyyy.

string

Example

Please note that in order to see the example below working on JSFiddle, you will need to be outside EU, otherwise Cookie Control defaults to using GDPR.

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, notify (pro licenses only), top (pro licenses only) or box (pro licenses only).

notify will display a summary of the use of cookies in a horizontal bar at the bottom of the page, with controls to accept/reject cookies, or read more information.

top is similar to notify and it will display a summary of the use of cookies in a horizontal bar, which will be at the top of the page.

box is also similar to notify though it will display a summary of the use of cookies in a modal in the centre of the page.

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
rejectButton

Determines whether the module shows a reject button alongside the accept button on the notification bar, or alongside the 'accept recommended settings' button when the panel is open.

Should the user click this, consent to all optionalCookies will be revoked.

boolean true
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 dark
toggleType

Determines the control toggle for each item within optionalCookies

Possible values are either slider or checkbox.

string slider
acceptBehaviour

This property is used to control what will happen when the user clicks on either of the 'Accept' or 'Accept recommended settings' buttons. By default all cookie purposes will be accepted.

Possible values are either all or recommended.

stringall
closeOnGlobalChange

If set to false the Cookie Control main window will remain open when the user clicks on either of the accept or reject buttons, and the user will have to explicitly close it using the X close icon at the top right, or the close button.

booleantrue
closeStyle

Determines the closing behaviour of the module.

Possible values are either icon, labelled or button.

string icon
notifyDismissButton

Set this to false if you are using the notify interface and don't wish to show the (X) close icon on it.

boolean true
settingsStyle

Determines the appearance of the settings button on the notification bar.

Possible values are either button or link.

string link
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
setInnerHTML

By default, only plain text is accepted within Text Object properties. If this property is set to true, HTML content will also be accepted.

boolean false
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
locale

The ISO language code for the locale out of the locales array that should be used for the current visitor. It defaults to the user's window.navigator.language , i.e. the user's browser language.

stringPRO
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.

object
sameSiteCookie

If set to true the CookieControl cookie will be marked with the SameSite:Strict flag. Otherwise it will be flagged with SameSite:None, which however will mean that in some browsers Cookie Control will not work unless your site is served over HTTPS.

boolean true
sameSiteValue

Used in conjuction with the sameSiteCookie property, it controls the value of the SameSite flag for the CookieControl cookie. It can be one of "Strict", "Lax" or "None".

string "Strict"

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
accept
(used on the notify bar)

I Accept

reject
(used on the notify bar)

I Do Not Accept

settings

Settings

title
(used on the main panel)

This site uses cookies to store information on your computer.

intro
(used on the main panel)

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

acceptSettings
(used on the main panel)

I Accept

acceptRecommended

Accept Recommended Settings

rejectSettings
(used on the main panel)

I Do Not Accept

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.

closeLabel

Close Cookie Control

cornerButton
(used by screen readers)

Set cookie preferences.

landmark
(used by screen readers)

Cookie preferences.

showVendors

Show vendors within this category

thirdPartyCookies
(used with vendors)

This vendor may set third party cookies.

readMore
(used with vendors)

Read more

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

notifyFontColor

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

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

notifyBackgroundColor

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

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: #000

acceptBackground

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

string dark theme default: transparent; light theme default: transparent

rejectText

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

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

rejectBackground

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

string dark theme default: transparent; light theme default: transparent

closeText

The CSS color that you'd like to use for the text within the module's "Close" button, if you have set the closeStyle property to "button".

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

closeBackground

The CSS background-color that you'd like to use for the module's "Close" button, if you have set the closeStyle property to "button".

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

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

The css pixel width that you'd like this image to be sized to.

number default: 80

buttonIconHeight

The css pixel height that you'd like this image to be sized to.

number default: 80

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
mode

Either gdpr, ccpa, or hidden. Similar to the global mode property, determines the mode Cookie Control will run in for a certain locale. Using the hidden option means Cookie Control will be hidden, and all onAccept functions will run immediately.

string
location

An array holding the ISO 3166 two letter country codes, for which this locale is valid. For United States in particular, you can also pass the ISO code of a particular state.

An example of a location setting targetting California and Canada to use CCPA mode is: ['US-CA', 'CA'].

array of strings
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
outline

Determines if the module should show the browser's default outline styling on elements. It can be combined with highlightFocus to add both a highlight and an outline to focused elements.

boolean false
overlay

Determines if the module should use an overlay to accentuate the presence of an open notification bar or panel and discourage use of the main site while these elements are open.

This property is recommended for accessibility purposes and enabled by default. Even if disabled, interaction with the site behind is not possible if the popup layout is enabled.

boolean true

IAB Transparency and Consent Framework PRO

IAB Transparency and Consent Framework

Cookie Control offers support for the IAB Transparency and Consent Framework (TCF v2.0), should the property iabCMP be enabled.

This effectively turns Cookie Control into an IAB registered Consent Management Provider (CMP), where the panels in Cookie Control's settings allow users to access information about IAB registered vendors and control the purposes and features that a vendor wishes to leverage. You don't need to set optionalCookies when in iab mode since IAB purposes will be the settings displayed on the first panel of Cookie Control.

Please note that when using Cookie Control as an IAB CMP, you cannot use any of the more subtle interfaces like notify or box. IAB requires certain view and text so Cookie Control will render in open state.

Should you enable iabCMP, we recommend including the Cookie Control module as early as possible in your document so that the stub functionality becomes available to queue commands from vendors. This typically means adding the Cookie Control <script> tag within the document's <head>. Alternatively, you may add your own stub functionality to queue commands from vendors, which Cookie Control will then process when after it loads.

Option Description type
iabCMP

Determines whether or not Cookie Control runs as and the IAB TCF v2.0 compliant CMP.

boolean false

Currently, Cookie Control only supports the global list of vendors and purposes that are centrally managed by IAB Europe; though some additional configuration options, such as how Cookie Control's recommended settings should influence the IAB purposes, are available via the iabConfig object.

Option Description
dropDowns

If set to true, Purposes, Special Purposes, Features and Special Features will be hidden by default so that the interface is more concise. The user will be able to see them after expanding the corresponding drop down.

boolean false

fullLegalDescriptions

If set to true, the full legal description for each Purpose or Feature will be shown, otherwise it will be hidden and the user can see them after expanding the corresponding drop down.

boolean true

saveOnlyOnClose

Cookie Control will wait until the user closes the widget before saving the consent, rather than doing so every time the user toggles a purpose on or off.

boolean false

publisherCC

The country code of the country that determines legislation of reference. Commonly, this corresponds to the country in which the publisher’s business entity is established.

string GB

You may also configure the text used to introduce the IAB category / panels via the iabCMP object, within the main text object.

As with the other text string properties, these are entirely optional. Cookie Control will use sensible defaults for any property not present in your configuration; and all properties may in turn be overwritten by your locale property, should the user's preferences coincide.

Option Default
panelTitle

This site uses cookies to store information on your computer.

panelIntro1

We and select companies use cookies to store and retrieve information from your browser. This information may be about you, your preferences or your device and is mostly used to make the site work as you expect. While the information does not usually directly identify you, details such as the device, operating system and type of browser may be considered personal data as it helps to create a more personalised web experience.

panelIntro2

You can review how this information is used and customise your consent preferences for cookies or for any other identifying technology below by either purpose, feature or third party vendor.

panelIntro3

Certain vendors may process personal data on the basis of legitimate interests to offer certain services. You have the right to object to the processing of data in this manner and can do so on an individual basis or globally by clicking "Reject All". Please refer to the vendor tab for more details. You may freely change your preferences at any time by clicking the Cookie Control icon.

aboutIab

The aforementioned personalised advertising services adhere to the

iabName

IAB Transparency and Consent Framework (TCF)

iabLink

https://iabeurope.eu/iab-europe-transparency-consent-framework-policies/

dataUse

How data is used

vendors

Third party vendors

purposes

Purposes

specialPurposes

Special Purposes

features

Features

specialFeatures

Special Features

purposeLegitimateInterest

I accept the processing of personal data on the grounds of Legitimate Interest for the purpose:

vendorLegitimateInterest

I accept the processing of personal data on the grounds of Legitimate Interest by:

relyConsent

Relying on consent for:

relyLegitimateInterest

Relying on legitimate interests for:

acceptAll

Accept All

rejectAll

Reject All

savePreferences

Save Preferences and Exit

legalDescription

Read full legal description

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 (deprecated)

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()

notifyReject (deprecated)

Programmatically sets the notification bar as rejected, which in turn disables the configuration's recommended purposes.

function CookieControl.notifyReject()

notifyDismiss (deprecated)

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

function CookieControl.notifyDismiss()

acceptAll

Programmatically accepts all cookie purposes.

If you choose to use this method, you are taking on extra responsibility for considering and protecting people’s rights and interests.

function CookieControl.acceptAll()

rejectAll

Programmatically rejects all cookie purposes.

function CookieControl.rejectAll()

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()

geoTest

Similar to geoInfo, but it can be used prior to loading the module. You can use it to load different config objects for different locations. Please note that this will send a request to our server in order to determine the location. This request can be either sync (blocking) or async (non blocking), depending on whether you supply a callback parameter or not (see below).

It accepts three parameters:

  • product: The product of your license
  • apikey: The apikey of your license
  • callback (OPTIONAL): A callback to run when the request returns. If this option is missing, the request will be synchronous.

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

function CookieControl.geoTest(product, apikey, callback)

Example using a callback (recommended):


var product = 'PRO_MULTISITE';
var apikey = '592b99ebdf88c091dad9b556b6d8de236ac97687';
CookieControl.geoTest(product,
    apikey,
    function(response){
        var config;
        if (response.withinEU()) {
            config = {
                // ...
            }
        } else {
            config = {
                // ...
            }
        }
        
        CookieControl.load( config );
    }
)

Example without using a callback:


var product = 'PRO_MULTISITE';
var apikey = '592b99ebdf88c091dad9b556b6d8de236ac97687';
var config;
if (CookieControl.geoTest(product, apikey)["withinEU"]) {
    config = {
        // ...
    }
} else {
    config = {
        // ...
    }
}

CookieControl.load( config );

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()

changeCategory

Changes consent to a given purpose (cookie category), passed as a number parameter describing its index within the optionalCookies array, according to the value of the second argument (true or false)

If the second argument passed is true, consent is granted, otherwise consent is revoked.

function CookieControl.changeCategory( 0, true )

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.

function CookieControl.toggleCategory( 0 )

getCategoryConsent

Gets the consent state of a particular category, passed as a number parameter describing its index within the optionalCookies array. Returns a boolean.

function CookieControl.getCategoryConsent( 0 )

Cookies Set By Cookie Control

When a user interacts with the module, their consent is recorded 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).

In version 9.0 onwards, if you are using the IAB TCF v2.0 version of Cookie Control, a cookie named CookieControlTC will be placed.

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

Support

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

v9.3

01/09/2020
  • Added support for LGPD legislation, by adding the vendors property to list vendors individually for each category.
  • Added new text properties for vendors: showVendors, thirdPartyCookies and readMore.
  • Added outline property in the Accessibility Object to allow users to use the default browser outline.
  • Added closeText and closeBackground options within the Branding Object to allow changing the styling of the "Close" button (if used).
  • Added notifyFontColor and notifyBackgroundColor options within the Branding Object to allow changing the styling of notify interface (if used).
  • Added fullLegalDescriptions and dropDowns properties in the iabConfig object to make the IAB view more concise.
  • Added legalDescription text property for the updated IAB interface.
  • Added saveOnlyOnClose property in the iabConfig object.
  • Added the ability to localise the statement and CCPA URLs.
  • The styling of the "Accept recommended settings" button is now consistent with the styling of the "Accept" button.
  • Removed deprecation notice from the geoTest function.
  • Bug fixes.

v9.2.1

29/06/2020
  • Added setInnerHTML option to allow HTML content within text properties.
  • Added overlay option within Accessibility Object.
  • Corrected the eventStatus of TCData to be ‘cmpuishown’ only when the settings panel is open. This change only applies to those who have enabled iabCMP.

v9.1

28/04/2020
  • Added notifyDismissButton option to hide the X close icon on the notify bar.
  • Added sameSiteValue property to control the value of the SameSite flag for the CookieControl cookie.
  • Added some legal texts required by IAB TCFv2.0

v9.0

20/03/2020
  • Support for IAB TCF v2.0. Support for v1.1 has been dropped since it is to be depreciated by IAB at the end of March 2020; certain IAB related public methods have been removed and the iabCMP text object has been updated accordingly.
  • It is no longer necessary to set optionalCookies when in iab mode since IAB purposes will be the first panel settings.
  • Support for California Consumer Privacy Act (CCPA).
  • Cookie Control can work in either GDPR or CCPA mode based on the user's location.
  • Added new box option for the initialState property.
  • Added sameSiteCookie property, to control whether SameSite:Strict is set to the CookieControl cookie. Setting this to false would mean Cookie Control can only work over HTTPS.
  • Added acceptBehaviour property to control the behaviour of "Accept" buttons. They now default to accepting all cookies. Please note that this is different from the behaviour of v8 where only recommended cookies were accepted
  • Added locale property so that the selected locale is customisable. It still defaults to the user's browser language.
  • Added closeOnGlobalChange property so that the there is control on whether the window should close or remain open when the user accepts/rejects cookies.
  • Added branding sub-properties that control the styling of the reject buttons.
  • Added acceptAll, rejectAll functions. deprecated notifyAccept, notifyReject and notifyDismiss functions.
  • Deprecated geoTest function, as the locales can now be used for locale specific settings.
  • Removed postConsentRecord function.
  • Added changeCategory function, to change consent of a cookie category to a particular state.
  • Accessibility improvements and bug fixes.
  • All apikeys now work under the following local adresses: localhost, 127.0.0.0/8, 10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12.

v8.3

13/01/2020
  • Added accessibility markup to the IAB TCF v1.1. iframe.
  • Resolved occasional RangeError issue.
  • Added SameSite=Strict flag to the CookieControl cookie.
  • Accessibility improvements for screen readers.
  • Accessibilty improvement preventing users to "tab" out of the popup when it's open
  • Fix bug with purging consent state due to the updated date of the statement object.
  • The onLoad callback will now run even when the widget is hidden due to geolocation.
  • Added getCategoryConsent function to get the consent state of a particular category.
  • Added geoTest function to get geolocation information prior to loading the module.
  • Added top option for the initialState property, which is similar to notify but will display a bar at the top of the page.

v8.2.1

08/07/2019
  • Added support for IAB TCF v1.1.
  • Added new behaviour to 'Reject All' cookie categories.
  • Added alternative appearance styles for the notify bar's settings button.
  • Added encodeCookie property to better support RFC standards and certain types of server processing.
  • Added subDomains property to offer more flexibility on how user consent is recorded.
  • Extended public methods with notifyReject() and postConsentRecord().

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.

  • 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.