JavaScript API
Example
This example places an informational (default) black and white popup with a yellow button inside the body of a website. Location is switched on an so this example will send the users IP to Maxmind to get the country code as assess if the user needs to see the notice based on location.
<script src="js/gdprconsent.min.js"></script>
<script type="text/javascript">
var GDPR_VERSION = '25-May-2018';
window.addEventListener("load", function(){
window.gdprconsent.initialise({
container: document.getElementsByTagName("body"), //Change this to the element you wish
"GDPR_VERSION": GDPR_VERSION,
"cookie": {
"domain": "localhost",
"path": "/",
"expiryDays": 365,
},
"palette": {
"popup": {
"background": "#000"
},
"button": {
"background": "#f1d600"
}
},
"type": "info"
"location": true
});
});
</script>
Main options
These are the main options that can be passed to the Cookie Consent tool.
GDPR_VERSION
(string)
Default: ‘25-May-2018’
Please add your version or date of the privacy policy. This field is used to set a gdpr_version cookie and if the version in the code does not match the version in the cookie, the notice will be shown once more.
enabled
(boolean)
Default: true
This can be used to disable the popup. It is internally used to disable itself (if needed), but can be configured externally too.
container
(HTMLElement)
Default: null
The tool is automatically appended to the HTML body. Use this option to select the parent element. Use autoOpen: false to prevent the tool automatically appending itself to any container.
Cookie options
It is recommended to set these values to correspond with your server. You MUST set the ‘domain’ option, otherwise your cookies may not work.
cookie.name
(string)
Default: ‘gdprconsent_status’
Name of the cookie that keeps track of users choice
cookie.path
(string)
Default: ‘/’
URL path that the cookie ‘name’ belongs to. The cookie can only be read at this location
cookie.domain
(string)
Default: ‘‘
The domain that the cookie ‘name’ belongs to. The cookie can only be read on this domain. Guide to cookie domains
cookie.expiryDays
(integer)
Default: 365
The cookies expire date, specified in days (specify -1 for no expiry)
Content options
Text strings used for cookie consent window elements.
content
(object)
Defaults:
content: {
header: 'Privacy & Cookie notice!',
message: 'This website requires cookies, and the limited processing of your personal data in order to function. For more information please read our',
allow: 'OK',
deny: 'Decline',
link: 'Privacy policy',
href: 'http://cookiesandyou.com',
close: '❌',
},
Overwrite these default options to change the content within the tool
Custom HTML options
elements
(object)
Defaults:
elements: {
header: '<span class="gc-header"></span> ',
message: '<span id="gdprconsent:desc" class="gc-message"></span>',
messagelink: '<span id="gdprconsent:desc" class="gc-message"> <a aria-label="learn more about our privacy policy" role=button tabindex="0" class="gc-link" href="" rel="noopener noreferrer nofollow" target="_blank"></a></span>',
allow: '<a aria-label="allow cookies" role=button tabindex="0" class="gc-btn gc-allow"></a>',
deny: '<a aria-label="deny cookies" role=button tabindex="0" class="gc-btn gc-deny"></a>',
link: '<a aria-label="learn more about cookies" role=button tabindex="0" class="gc-link" href="" target="_blank"></a>',
close: '<span aria-label="deny cookie message" role=button tabindex="0" class="gc-close"></span>',
//compliance: compliance is also an element, but it is generated by the application, depending on `type` below
},
This is the HTML for the elements above. Any word surrounded by ‘’ will be automatically replaced. The string will be replaced with the equivalent text above. You can remove “” and write the content directly inside the HTML if you want.
window
(string)
Default:
<div role="dialog" aria-live="polite" aria-label="gdprconsent" aria-describedby="gdprconsent:desc" class="gc-window"><div class="gc-notice "><!--googleoff: all--><!--googleon: all--></div></div>
Window is the ‘container’ that houses the popup contents. It has the HTML class ‘gc-window’ The placeholders and both get replaced during initialisation. The gc-window places a shroud over the page so that the only interaction is with the popup. The popup itself will appear within gc-notice and will appear in the center of the page.
deathShroud
(string)
Default:
<div role="dialog" aria-live="polite" aria-label="gdprconsent denied" aria-describedby="gdprconsent:desc" class="gc-death-shroud"><div class="gc-notice "><!--googleoff: all--><p>You have chosen to decline the privacy policy and therefore we cannot provide this service to you.</p><p>If you have changed your mind, either refresh the page or click on the "Privacy Policy" tab.</p><!--googleon: all--></div></div>
This is shown when using opt-in and the user has declined. The user will only be able to interact with the revoke tab.
Position
position
(string)
Default: bottom
Position is used to describe where on the screen your revoke should display. The other option is top.
Palette options
Colours can be defined in additional stylesheets or using attributes.
palette (object) Default: null
If palette is set to null, colours have to be defined in CSS.
To pass the colours using attributes, use:
palette: {
popup: {background: '#000000', text: '#fff', link: '#fff'},
button: {background: 'transparent', border: '#f8e71c', text: '#f8e71c'},
highlight: {background: '#f8e71c', border: '#f8e71c', text: '#000000'},
}
Highlight is optional and extends button
. if it exists, it will apply to the rightmost button.
Only background needs to be defined for every element. If text or border colour is not set, it will be calculated from the background colour.
Revoke options
Some countries require consent to be revokable. Cookie Consent keeps track of these countries and adds a button to review the consent window.
revokable
(boolean)
Default: false
If set true, revoke button is displayed every time. If false, revoke button is only displayed for advanced compliance options (opt-in and opt-out) and in countries that require revokable consent. The latter can be disabled by regionalLaw below.
revokeBtn
(string)
Default: <div class=”gc-revoke ”>Privacy Policy</div>
This is the html for the revoke button. This only shows up after the user has selected their level of consent.
animateRevokable
(boolean)
Default: true
If true, the revocable button will translate in and out. Disabled by default for mobile devices.
Callback hooks
Called at certain points in the program execution
This is called when the popup is opened. It can be used to trigger an animation, or to attach extra handlers, etc.
onPopupOpen: function() {}
This is called when the popup is closed. It can be used to clean up commands from onPopupOpen
onPopupClose: function() {}
This is called on start up, with the current chosen compliance. It can be used to tell you if the user has already consented or not as soon as you initialise the tool.
onInitialise: function(status) {}
This is called any time the status is changed. This can be used to react to changes that are made to the compliance level. You can use the popup instance functions from within these callbacks too. I.E. ‘this.hasAnswered()’ and ‘this.hasConsented()’.
onStatusChange: function(status, chosenBefore) {}
This is called when the user clicks the ‘revoke’ button. This means that their current choice has been invalidated.
onRevokeChoice: function() {}
Hooks can be used to disable cookies when consent is not given, and the generally extend the tool.
Location options
The location services are disabled by default. You are encouraged to implement a handler to your own service, rather than using the free ones provided.
To enable the basic location services, set ‘location’ to ‘true’. To add you own services or configure the order or execution, pass an object with configuration properties.
location.timeout
(array)
Default: 5000 (milliseconds)
We can’t react to errors from script tag resources, so we set a timeout. If we don’t have the answer after 5000ms, try the next service.
location.services
(array)
Default: [‘maxmind’, ‘ipstack’]
This array defines the services that you want to use. We attempt to get the country code from the first service, and only if the service fails do we move onto the next service. If all services fail, the popup is opened without modification.
If a service succeeds, then the two letter country code is passed to the ‘Law’ module, with changes your popup options depending on the cookie laws in the country code.
location.serviceDefinitions
(object)
This can be used to define new services via a key, but new services they can also go straight into the ‘services’ array in an ad-hoc fashion. It is recommended that you define services in ‘serviceDefinitions’ and use ‘services’ to configure priority between services