Civic Cookie Control Technical Guide


Thank you for using Civic Cookie Control! This is a brief guide on integrating the Cookie Control widget into your site, and getting the most out of the widget. While it by no means covers all uses cases, it should provide enough information to make the widget cover some fairly unusual requirements.

Conventions

  This is code.

This is a tip. It may help you improve your deployment.

This is a warning. If you do not heed it, things may break.

This is a cautionary note. Pay attention or things will break!

The Basics

Cookie Control is a Javascript program that can help make a website compliant with EU legislation concerning the use of cookies. If your company is based in one of the European countries that implement the cookie law, and your visitors are from the EU, you have to be compliant. Different countries implement the law in different ways, so Cookie Control was designed with flexibility in mind. Cookie Control uses a widget for two purposes: it lets users know the site uses cookies, and optionally allows them to disable or enable cookies explicitly. The program works in three modes of ‘consent models’:
Information-only
Many countries (such as the UK) make it perfectly acceptable to simply notify the user that the site uses cookies, and to link them to the cookie and privacy policy. In this mode, Cookie Control simply provides information to the user. It does not affect whether or not cookies are allowed or blocked.
Implied Consent
This is an opt-out method. Cookies are allowed by default. Cookie Control lets the user know (optionally providing links to the cookie and privacy policy documents). The user may block cookies using the Cookie Control widget.
Explicit Consent
This is an opt-in method, and the most restrictive of the three. Cookies are blocked by default. Cookie Control lets the user know (providing links to the cookie and privacy policy documents). The user may allow cookies using the Cookie Control widget. Cookie Control behaves slightly different in this mode, attracting the user's attention more proactively.

Cookie Control, like all Javascript software, is unable to block all cookie generation. This is done either on the server side (for HTTP cookies, which Cookie Control cannot easily affect), or by other Javascript programs operating on the same page (Javascript cookies, which Cookie Control may be able to affect). The program thus takes a reactive approach: if cookie consent is not present, it deletes cookies (with some user-defined exceptions) on startup, and can be instructed, via Javascript, to delete cookies during the lifetime of a page.

Ironically, Cookie Control itself needs to store the user's preference, and this has to be be done with another cookie — the alternative would be to store the preference on a remote server, which would have an even more ironic and profound effect on user privacy. Cookie Control generally excludes its own cookie from deletion, but it may still be deleted using Javascript. For privacy information concerning this cookie, please read below.

Dependencies

Cookie Control uses jQuery 1.7.1. If your site doesn't use it, Cookie Control will detect this and automatically reference the official jQuery from its official location:

http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js

Cookie Control does its very best not to interfere with another version of jQuery, if one is found, but some installations have faced minor deployment issues due to version mismatches. If Cookie Control fails to appear, check your console for error messages and contact Civic for help.

Compression

If your site uses HTTP compression (e.g. mod_deflate in Apache), it is safe, convenient and recommended to allow the Cookie Control Javascript file to be compressed. Compression reduces the overall file to about 50–35% of its original size.

For a solution for pre-compressing files (to save CPU cycles and time, and to produce smaller results without the delay of on-line compression on every request), please read this article:

http://feeding.cloud.geek.nz/2011/01/serving-pre-compressed-files-using.html

Embedding the Widget

To add the widget to your page, two to three modifications are needed, depending on your cookie policy:

  1. Include the JavaScript source at an appropriate place in the document. It does not need to be in the <head>, and the exact src may be different depending on your version of Cookie Control and where it is on your site:
    <script src="cookieControl-6.2.min.js" type="text/javascript"></script>
    
  2. Instantiate Cookie Control. The simplest possible instanatiation will look like this:
    <script type="text/javascript">//<![CDATA[
    
        cookieControl({
              apiKey: '93a4b2dfe0c2d0b8c2b91ccb25f23c879f14c204',
              product: CookieControl.PROD_PAID,
              consentModel: CookieControl.MODEL_INFO
        });
    
    //]]></script>  
    
  3. Optionally, add callback Javascript functions that CookieControl will execute depending on whether or not cookies are acceptable to the user.

The last two steps can get arbitrarily complex to meet your demands. They are discussed below.

Initialisation and Customisation

The behaviour of Cookie Control may be influenced quite a lot, using initialisation-time options. The vast majority of these have sane defaults, but may be overridden to provide custom behaviour or adapt to unusual requirements.

Coookie Control

is initialised by including the following in your HTML page:

<script src="cookieControl-6.2.min.js" type="text/javascript"></script>
<script type="text/javascript">//<![CDATA[

    cookieControl({
          apiKey: '93a4b2dfe0c2d0b8c2b91ccb25f23c879f14c204',
          product: CookieControl.PROD_PAID,
          consentModel: CookieControl.MODEL_INFO
    });

//]]></script>  

Avoid putting this in the document head, as it will increase page loading times.

Microsoft Internet Explorer is especially sensitive to Javascript syntax errors — do not leave a trailing comma in the options!

Please note the syntax: a single argument is provided, and it is a Javascript object with a number of key-value pairs, separated by commas.

Once Cookie Control has initialised, it will create a global variable CookieControl for itself (please note the initial upper case ‘C’). You may use this to control Cookie Control after initialisation.

Mandatory Keys

There are three options you absolutely must provide for Cookie Control to initialise:
apiKey
The API Key you have received for your deployment of Cookie Control. If in doubt, or if you have lost your key, please contact the Civic helpdesk at helpdesk@civicuk.com.
product
This must be one of the following: The product code is tied to the API Key, and both must be correct for Cookie Control to initialise successfully.
consentModel
The consent model you wish to use for your deployment of Cookie Control. This must be one of the following:

Styling Options

These initialisation-time options control the appearance of Cookie Control.

style
The widget's style, which must be one of the following:

The CookieControl.STYLE_BAR is only available for Cookie Control premium.

theme
The widget's theme, which must be one of the following: The theme modifies the widget's style in a number of ways.
position
The widget's position. For button-style widgets, this must be one of the following: For the premium bar-style (CookieControl.STYLE_BAR) widget, on one of the following must be specified:

Cookie Settings

These initialisation-time options control how Cookie Control deals with its own cookies.

cookieName
The name of the Cookie Control cookie. Defaults to ‘civicCookieControl’.
cookieExpiry
The length of time the Cookie Control cookie will be valid for. Specified in days. Decimal (float) values may be specified too. This defaults to 90 days.
blockedCookieExpiry
The point of Cookie Control is to let users know about cookies, but the aim is for your site to work. If a user declines cookies, your cookie policy may make it appropriate to time this decision out earlier. If blockedCookieExpiry is specified, and cookies are not allowed either because the user has not opted in yet, or because they have explicitly opted out, this decision will be remembered for as many days as specified in blockedCookieExpiry. Making this a relatively small number, (e.g. 1) will make the Cookie Control widget reappear often to give the user another chance of changing their mind.

This may be seen as ‘nagware’ by the user, and may reduce the quality of your site's user experience. Use carefully.

cookiePath
The path part of the site's URL for which the Cookie Control cookie will be valid. This defaults to /, signifying ‘every path’. It may be necessary to change it if you are running multiple sites on the same domain name, each with its own Cookie Control. In that case, set the path to the root path of the site in question to limit the cookie to part of the domain.
cookieDomain
The domain for which the cookie is valid. This defaults to the current domain in use, but may be necessary to set it explicitly for special installations.
protectedCookies
A Javascript Array containing the names (as strings) of cookies exempt from deletion. Cookie Control will refuse to delete these cookies, even when a user declines cookies on the site. This feature is for excluding cookies used to alter the site's display, as outlined in your cookie policy. Cookie Control internally adds its own cookie to this list, and your cookie policy should reflect that.
subdomains
If set to true (the default), Cookie Control assumes it is deployed on a subdomain. Deleting cookies will attempt to delete them for the subdomain, but also try all super-domains. Leaving this option set will work fine in the vast majority of cases.

Policy Options

These initialisation-time options reflect your Cookie Policy in greated detail than just the consent model.
policyVersion
This is an optional setting that contains the version of your cookie/privacy policy. The version string may be anything: a date, serial number, major.minor version, or even a digest of the entire policy. The value may be generated automatically by a CMS, or set manually by a human. It is only important that this value changes whenever the policy changes. When a user makes an explicit choice about cookies (or acquiesces, in the case of the implicit consent model), the version of theprivacy/cookie policy they (presumably) read to do so is recorded in their Cookie Control cookie.

When this version differs from the value of policyVersion, the policy is assumed to have changed, and the user must re-examine the policy and perhaps provide consent. The widget is thus reset, and re-appears to the user anew.

The same happens when the consent model changes.

countries
A Javascript string (or Array) containing a list of countries Cookie Control will display its widget for. If using a string, it should be comma separated (spaces are ignored). If using an Array, one country per entry should be specified. Countries may be specified using their full names (e.g. "United Kingdom, Germany") or their ISO 3166-1-alpha-2 codes (e.g. "GB, DE").

This feature is only available on Cookie Control premium.

Behaviour Options

These initialisation-time options control the behaviour of the widget.

startOpen
If set to true, start the widget in the ‘open’ state. Button-style widgets will start with the window showing in the selected corner (bottom left or right). Bad-style widgets will start with the information pane extended. An appropriate animation will take place when this happens.
autoHide
If startOpen is true, the widget will revert to the ‘closed’ state after as many milliseconds as are specified in the value of autoHide. This timeout only applies until the widget is interacted with, and is temporarily suspended while the mouse pointer hovers over the widget.

There are 1,000 milliseconds to a second. To set the widget to auto-hide after seven seconds, you would specify autoHide:7000.

autoDelete
If set to true, Cookie Control will automatically delete all cookies if consent is declined. It will do this on startup, and whenever the user clicks on the widget button blocking cookies. The CookieControl.delAllCookies() method is called to perform the deletion. Cookies nominated in option protectedCookies are not deleted.
initialFadeSpeed
The duration (in milliseconds) of the initial fade-in animation.
autoFadeSpeed
The duration (in milliseconds) of the fade-out animation when the widget is hidden automatically.
clickFadeSpeed
The duration (in milliseconds) of the fade-out animation when the user explicitly hides the widget.
expandSpeed
The duration (in milliseconds) of expanding (or contracting) the information pane.
onlyHideIfConsented (introduced in CookieControl 6.2)
This option controls the behaviour of the ‘X’ button (for corner pop-up widgets) and ‘Close’ button (for bar widgets). Normally, pressing these buttons will hide the widget and not show it again on the next page load. Set this option to true to keep showing the widget until the user provides (or explicitly denies) consent.

onlyHideIfConsented:true was the default (and only) behaviour for CookieControl versions prior to 6. In versions 6.0 and 6.1, the default (and only) behaviour was onlyHideIfConsented:false. Versions 6.2 allow this to be configurable, but the default is still false.

Event Callbacks

Cookie Control can call user-supplied functions in response to various events. Functions can be registered at initialisation time and specified as anonymous functions or as function references. All events are fired off with a single parameter, the value of the CookieControl object. Here is an example using an anonymous function:
    <script type="text/javascript">//<![CDATA[
    cookieControl({
          apiKey: '93a4b2dfe0c2d0b8c2b91ccb25f23c879f14c204',
          product: CookieControl.PROD_PAID,
          consentModel: CookieControl.MODEL_INFO,
          onReady: function(cc) {
              alert('Cooke Control is ready and available as cc=' + cc);
          }
    });
    //]]></script>
onReady
Called immediately after Cookie Control initialises, after the DOM is ready (as a result of the jQuery .ready event). This event is fired exactly once per page.
onCookiesAllowed
Called immediately after initialisation (and after a potential onReady event) if cookies are allowed. This is an ideal place to add DOM elements such as <script>…</script> tags to include tracking functionality.
onCookiesNotAllowed
Like onCookiesAllowed, but called if cookies are not allowed. Fallback functionality may be added to the DOM by attaching a function to this event.
onAccept
Called whenever the user clicks a button explicitly accepting cookies. Can be used to generate tracking code (if the code is not on the page already) when the user enables cookies.
onReject
Called whenever the user clicks a button explicitly blocking cookies. Can be used to delete Javascript cookies set for the page as soon as the user rejects cookies.

Customising Text Messages

Most of the text messages presented by Cookie Control can be customised using the t object:

<script src="cookieControl-6.2.min.js" type="text/javascript"></script>
<script type="text/javascript">//<![CDATA[

    cookieControl({
          apiKey: '93a4b2dfe0c2d0b8c2b91ccb25f23c879f14c204',
          product: CookieControl.PROD_PAID,
          consentModel: CookieControl.MODEL_INFO,
          t: {
              ias: 'Information and Settings',
              title: 'A customised title',
              // ...
              c: 'Close'
          }
    });

//]]></script>  

The t object is a Javascript object containing a number of key-value pairs, as follows:

ias
Used to decorate buttons to expand the widget, providing more information. Defaults to ‘Information and Settings’.
title
Used for the widget's title. On window-style widgets, this text appears as the first sentence of the window. On bar-style widgets, this is the only text visible on the bar before it is expanded. Defaults to ‘This site uses cookies to store information on your computer.’.
intro
On window-style widgets, this text is contacenated to t.title and appears together. On bar-style widgets, this is the first text displayed in the widget when the information pane is visible. Defaults to ‘Some of these cookies are essential to make our site work and others help us to improve by giving us some insight into how the site is being used.’.
full
This long text appears in all types of widgets when the ‘read more’ or ‘information and settings’ panes are fully extended. The exact default text is omitted here for brevity.
on
This is the text that appears in buttons to enable cookies. It defaults to ‘Turn cookies on’.
off
This is the text that appears in buttons to disable cookies. It defaults to ‘Turn cookies off’.
bs
This is the text that takes the user to a page (on Civic's website) describing how to configure their particular browser's cookie support for privacy. It defaults to ‘Browser settings’.
rm
This appears in buttons and controls prompting the user to read more text by expanding a hidden panel. It defaults to ‘Read more’.
rl
This appears in buttons and controls allowing the user to contract panels to hide the full text of the widget. It defaults to ‘Read less’.
ab
Text used to take the user to the description of Civic Cookie Control on Civic's servers. Defaults to ‘About this tool’.
c
Text used for buttons that close the widget. Defaults to ‘I'm fine with this’.

Please note that some of this text may not appear on every configuration of widget, and some (for instance the t.c message) are used for accessibility reasons and may not ordinarily be visible on a browser as used by the general public.

Not all keys need be specified. Cookie Control will use sane defaults in UK/International English for missing values.

Cookie Control requires text to be present for many of these messages and will stop initialisation with an on-screen error alert if a message is left out.

Post-Initialisation Access and Use

Once Cookie Control has initialised, it will create a global variable CookieControl for itself (please note the initial upper case ‘C’). You may use this to control Cookie Control after initialisation.

A number of methods are available for convenience. Please regard all other methods as protected and avoid using them. They are likely to go away in the next version.

CookieControl.cookieLawApplies()
Returns true or false, depending on whether or not the Cookie Law applies in this case and jurisdiction.
CookieControl.maySendCookies()
Returns true if the page may set cookies, false otherwise. Handles implicit and explicit consent and various other cases. If the Cookie Law does not apply at all, always returns true.
CookieControl.consented()
Returns true if the user has explicitly consented to cookies, false if the user has explicitly blocked cookies. To check if cookies may be send regardless of user choice, CookieControl.maySendCookies() is a much better choice.
CookieControl.hidden()
Returns true if the widget has been hidden by the user, false otherwise.
CookieControl.reset()
Resets Cookie Control by deleting its ticket. The widget will appear the next time a page is loaded.
CookieControl.setTheme(newTheme)
Set the theme of the widget. The argument newTheme must be either CookieControl.THEME_LIGHT or CookieControl.THEME_DARK. Please avoid using this method. Instead, specify the theme at initialisation time.
CookieControl.setStyle(newStyle)
Set the style of the widget. The argument newStyle must be one of the CookieControl.STYLE_X values. Please avoid using this method. Instead, specify the style at initialisation time.
CookieControl.setPosition(newPosition)
Set the position of the widget. The argument newPosition must be one of the CookieControl.POS_X values appropriate to the current style. Please avoid using this method. Instead, specify the position at initialisation time.
CookieControl.popUp()
Pops up the widget, even if previously hidden by the user. Does nothing if the widget is already visible.
CookieControl.popDown()
Fades out the widget if it is visible.
CookieControl.popUpWithAutohide()
Pops up the widget, even if previously hidden by the user. If autoHide has been specified and is not disabled, the widget will be automatically hidden if not interacted with for the length of time specified in the autoHide initialisation option.
CookieControl.disableAutohide()
Disables the autohide feature. This has no effect if autoHide has not been specifie.d
CookieControl.enableAutohide()
Re-enables the autohide feature. This has no effect if autoHide has not been specified.
CookieControl.closeAndHide()
CookieControl.setCookie(name, value, options)
Convenience method to set a Javascript cookie. The name and value of the cookie are specified in name and value respectively. The options argument is an optional Javascript Object with the following key-value pairs:
expiry
The expiry of the cookie. It may be specified as an integer or float (specifying the number of days in the future the cookie will expire; decimal values specify day fractions), a string which must be properly formatted and is used as-is with no checking, or a Javascript Date object. Defaults to never expiring.
domain
The domain name the cookie will be valid on. Defaults to the current domain.

The path of the cookie will always be set to the value of the cookiePath option, whatever it may be.

CookieControl.hasCookie(name)
Returns true if the specified cookie exists and is available to the Javascript engine in the browser.
CookieControl.getCookie(name)
Returns the value of the specified cookie, or false if the cookie could not be found.
CookieControl.getAllCookies()
Returns all cookies accessible to the browser's Javascript engine as a Javascript Object (or associative array) where each cookie names and values are stored as key-value pairs. This is a convenient way to retrieve all cookie values parsed from the (string) document.cookie magic variable.
CookieControl.delCookie(name)
Deletes the named cookie. Attempts a number of workarounds and trickery to delete cookies set for this page by other entities (such as Google Analytics).
CookieControl.delAllCookies(exceptions)
Deletes all cookies except except the ones named in exceptions, which must be a Javascript Array. Repeatedly calls CookieControl.delCookie() to achieve this.
CookieControl.setConsent(consented)
Programmatically set the user's consent to the provided value. true signifies the user would like to allow cookies, and false denotes cookies are to be blocked.

This method updates Cookie Control's internal state but does not modify the widget itself. After calling this method, it may be prudent to call CookieControl.popDown() to also hide the widget. This is left to the programmer to allow for maximal flexibility.

Please do not call any methods other than the above. There is no guarantee they will remain in future versions, or that they will behave the same way.

When Things Go Wrong

There are two classes of problems you may encounter with Cookie Control.

The first class is trivial: a misconfiguration caught by the widget. In this case, a Javascript alert() will be invoked, Cookie Control will clearly identify itself, and it will present an error message. These error messages are always configuration problems, which is why an alert() is not inappropriate. They are not expected to appear in production, but are meant to let the site developer know about a simple problem.

The second class of problem is less than trivial: nothing happens. In fact, all Javascript-enabled functionality on your page appears to not work either. This is almost always down to a syntax error while initialising or using Cookie Control. Please check your browser's developer console. You are likely to find a Javascript exception. More often than not, the problem is actually something trivial, like a missing or superfluous comma in an option list.

A Javascript exception will often halt the entire Javascript engine for the page, which is why it may appear as if all functionality is broken. Once the error has been corrected and all code on the page parses correctly, all functionality will be restored.

However, should you encounter an unusual issue, please do not hesitate to contact the Civic helpdesk at helpdesk@civicuk.com. Our Javascript and jQuery experts will do their best to help you!

Privacy

In the interest of privacy, here is some information on Cookie Control's external requests and stored data.

External Accesses

Cookie Control will perform one to three external requests as part of initialising: Cookie Control does its best not to impact your page loading times. The above requests are all made after the page has fully loaded, parsed and rendered (using the onReady event).

Contents of the API Key Request

In the interest of privacy, here are the contents of the API Key request made to Civic's apikeys.civicuk.com server. The following parameters are submitted:

k
The API Key, as specified to Cookie Control during initialisation to Civic's apikeys.civicuk.com server (the apiKeyoption).
p
The product name for which an AIP Key is being submitted. This will depend on which product you are initialising, based on the value of the product option).
v
The major version of the product being initialised. This is used by the API Key server to account for future needs (by providing slightly different response fields), and so the API key can be matched to the product and version.
d
The domain for which the request is made. This is gleaned from the browser using Javascript's window.location.host and is used to retrieve the correct license key for the product.
Civic may log these requests for IP protection and statistics purposes.

Contents Of the civicCookieControl cookie

Cookie Control stores exactly one cookie, the name, domain and expiry of which may be set at initialisation time (see above).

The civicCookieControl cookie is a simple JSON object with the following keys and values. All values are URI-encoded. There is no identifying information in the cookie, only information on the user's cookie preferences and some information used to improve user experience, for instance by remembering if Cookie Control has been hidden by the user.

pv
The value of the cookie Policy Version you set using the policyVersion configuration option. Remember, this value is URI-encoded. To get the value you must decode it (in Javascript, using the decodeURI() function).
cm
Represents the consent model you selected at initialisation time, using the consentModel configuration option. Current, possible values are info (informational, MODEL_INFO), impl (implicit, MODEL_IMPLICIT) and expl (explicit, MODEL_EXPLICIT).
open
If set to yes, the widget was open when last shown. For button-style widgets, this means that the information/consent window was shown. For bar-style widgets, this means that the information box was expanded. If set to no (or any other value, including no value), the widget was not open.
hidden
If set to yes, the widget has been hidden by the user and will not be shown next time (unless the policy version or consent model have changed, or explicitly reset). Any other value means the widget has not been hidden.
consented
If set to yes, the user has consented to cookies. This is not recorded for the implicit consent model. Do not use this to tell if cookies are allowed! Use CookieControl.maySendCookies(), which returns an appropriate boolean value.
explicitly
Set to yes whenever the user explicitly disables or enables cookies by clicking on the appropriate button.

For more information, please contact helpdesk@civicuk.com.