This article refers to the legacy version of the Cookie Solution. For existing implementations (before 11.03.2019), we strongly suggest upgrading your Cookie Solution by simply copying the new code here (Dashboard > [Your website/app] > Cookie Solution > Embed) to avoid any CSS related conflicts and to access all the new features. If you’ve already updated your code to the new version, please find the updated Guide here.
In order to enable the iubenda Cookie Solution you just need to insert the following code within the <head>
tag of your website’s HTML as the first element.
- <script type="text/javascript">
- var _iub = _iub || [];
- _iub.csConfiguration = {
- cookiePolicyId: XxX,
- siteId: YyY,
- lang: "en"
- };
- (function (w, d) {
- var loader = function () { var s = d.createElement("script"), tag = d.getElementsByTagName("script")[0]; s.src = "//cdn.iubenda.com/cookie_solution/iubenda_cs.js"; tag.parentNode.insertBefore(s, tag); };
- if (w.addEventListener) { w.addEventListener("load", loader, false); } else if (w.attachEvent) { w.attachEvent("onload", loader); } else { w.onload = loader; }
- })(window, document);
- </script>
The code shown above is an example. To generate your own code, just click on “Activate / Edit Cookie Solution” located on the edit page of each website in your iubenda dashboard.
If you are a WordPress user, you can configure the iubenda Cookie Solution by adding the code to the header.php file of the theme you are using. Place the code as the first element within the HTML <head>
tag.
Alternatively, we also offer a dedicated plugin that further simplifies the task. You can find more information about it in the dedicated WordPress guide.
In order to configure the iubenda Cookie Solution on a Joomla! website, you can either install a module like the Custom HTML advanced module. Here’s an article that explains how to use this module to integrate the privacy policy generated with iubenda. We remind you that, as always, the iubenda Cookie Solution code must be entered within the <head>
tag as the first element.
We’ve also released a dedicated Joomla! plugin. For more information, check the comprehensive guide to the iubenda plugin for Joomla!.
Available parameters _iub.csConfiguration {}
:
siteId:
– Your site’s ID code (notice: This ID is used to share the preference among multiple cookies policies in different languages that are attributable to the same website/app)
cookiePolicyId:
– Your cookie policy’s ID code
lang:
– This parameter defines the language in which to display the content of the cookie banner (for example, “it” for the Italian, “en” for English, “es” for Spanish, etc..). All the language localizations available within the generator are also available for the content of the banner.
priorConsent:
(boolean, default true) – Enables the blocking of scripts and their reactivation only after having collected the consent. If false, the blocked scripts are always reactivated regardless of whether or not consent has been provided (we strongly advise against setting priorConsent to false if you want to be complying with EU legislation and thus the Italian legislation except if you are using the Light Cookie Solution deliberately, which requires you to set priorConsent on false). Please note that if the “Prior consent” setting has been disabled directly in your Cookie Solution’s configuration panel on iubenda.com, this configuration parameter will be ineffective.
consentOnScroll:
(boolean, default true) – you can set this parameter to false to avoid the registration of the user’s consent when the page is scrolled.
consentOnButton:
(boolean, default true) – The user’s consent is normally recorded also after a click on a button (button
) on the page, as well as on the links (a
). The consentOnButton
parameter, set to false, changes the default behavior by ensuring that the consent results as “not given” in these cases.
consentOnElement:
(string, default “input, textarea, form”) – The user’s consent is recorded by clicking on one of the html elements listed in the parameter. Unlike consentOnButton
(see above), the option does not manage the tags a
and button
. Important: if new html elements are added and you need the default elements to be still active, you must declare them again.
consentOnDocument:
(boolean, default false) – If set to true, the user’s consent will be registered if you click anywhere on the page (excluding the banner area).
consentOnScrollHorizontal:
(boolean, default false) – By setting this parameter to true, the consent is given even in cases of horizontal scrolling.
consentOnScrollOnElement:
(DOMElement, default window.document) – The scrolling event is observed on the element passed as a parameter. The DOM element may not yet be available when the Cookie Solution is initialized. In this case, you can use the setConsentOnScrollOnElement
API method.
reloadOnConsent:
(boolean, false by default) – You can set this parameter to true if you want the page to be reloaded after the collection of the consent.
localConsentDomain:
(string, default null) – the domain on which you want to save the consent collected from the users. If not set, the consent will be saved in a cookie on the domain of the current page (for example, by visiting www.example.com, the consent will be saved in a cookie placed in the domain example.com). If the default behavior is not appropriate, for example, if the website is located on the domain www.paesaggiurbani.italia.it the consent must be provided for paesaggiurbani.italia.it (and not for italia.it), in that case, you are required to set the localConsentDomain to the value ‘paesaggiurbani.italia.it’.
Notice: in a similar scenario, if the parameter is not given, the banner could continue to appear to the same user at each subsequent visit/page view.
localConsentPath:
(string, default ‘/’) – The path in which you want to save, in the local domain, the consent provided by the user. By default, the consent given by the user is saved in the local domain in the cookie in the path ‘/’. In this way, the cookie is available regardless of the page of the domain being accessed. If you want, for example, that the preference cookie set for www.example.com/percorso1 will not be available by browsing on www.example.com/percorso2, and vice versa, it will be necessary to provide this parameter the value ‘/percorso1’ in the first case and ‘/percorso2’ value in the second case.
enableRemoteConsent:
(boolean, default false) – You can set this parameter to true to enable a cross-site registration of the consent (it can be useful when the script is implemented in more than one websites of the same network). In particular, if you set this parameter to true, our solution creates a technical cookie on iubenda.com (domain) which is used when the cookie on the local domain is not found.
skipSaveConsent:
(boolean, default false) – By setting this parameter to true, the consent is not saved in a preference cookie.
Here are additional optional parameters that call for the definition of one or more objects:
banner {}
(object) – Use this object to customize the look (or appearance) of the banner. The options are listed below and must be contained within the object banner {}
.
consentOnScrollDelay: (integer, milliseconds, default 500) – The delay with which the consent via scroll is detected, once the banner has been shown
slideDown (boolean, default true) – You can set this parameter to false in order to disable the animation of the banner
zIndex (number) – This is the zIndex of the banner’s div. The default value is 99999998
content (string) – This is the textual content inside the cookie banner. For example, for the Italian version the default value is:
Notice: This website or its third party tools use cookies, which are necessary to its functioning and required to achieve the purposes illustrated in the: If you want to learn more or opt out of all or some cookies, please refer to the %{cookie_policy_link}
Note: %{cookie_policy_link} is the placeholder where the link of the cookie policy is placed. Remember that by default, the cookie policy linked in the banner is the one hosted on our servers. In order to change the default behavior, you need to modify the cookiePolicyUrl
parameter (please refer to the related section of this guide for more information on this parameter).
The content of the cookie banner will be localized in all languages available in the generator (the language in which to display the banner content is defined through the parameter lang
).
Warning: in order to make sure that the cookie policy is correctly displayed, it’s necessary that the iubenda-cs-cookie-policy-lnk
class is not used elsewhere on the same page
cookiePolicyLinkCaption (string) – Anchor text of the link to the cookie policy (the default value is “cookie policy”)
backgroundColor (string, default “#000”) – The background color of the banner
textColor (string, default “#fff”) – The color of the banner’s text
fontSize (string, default null) – The dimension of the banner’s text (including the closing button). If this option is active If this option is enabled the possible values in the options banner.fontSizeCloseButton and banner.fontSizeBody (available in beta only) will not be taken into account
fontSizeCloseButton (string, default “20px”) – The dimension of the banner’s closing button
fontSizeBody (string, default “14px”) – The dimension of the banner’s text content
innerHtmlCloseBtn (string, default “x”) – The text of the banner’s close button
applyStyles (boolean, default true) – By setting this parameter to false, the default style/CSS is not applied to the banner; this parameter can be useful, for example when you want to give the banner a different style than the standard one. The starting point should always be our CSS, that you can find here. It reapplies the same style excluded from this option but has the advantage of being editable once inserted into the pages.
Here are some examples:
html (string, default null) – It is the default HTML of the banner, through this parameter it can be replaced with a customized one. Note: some elements are in any case necessary for the proper functioning of the banner, in particular:
div.iubenda-cs-content
(the main container)a.iubenda-cs-cookie-policy-lnk
(the href link set to link to the cookie policy, i.e. https://www.iubenda.com/privacy-policy/417383/cookie-policy?an=no&s_ck=false)a.iubenda-cs-close-btn
(the banner’s close button)prependOnBody (boolean, default false) – If this parameter is set on true, the HTML
code of the banner is injected into the site as the first element of the BODY
. By default “prependOnBody” is set to false and the banner is placed as the last element of the BODY
.
You must set the prependOnBody on true when you want, for example, to place the banner above the header. In this way, the banner will be the first element on the page, and in order to display it on top of the header, simply apply a “padding-top” to the next item: #iubenda-cs-banner + * { padding-top: 180px; }
footer {}
(object)
message (string) – This is the text message displayed below the window where the extended policy is displayed (cookie policy) when you click the cookie policy link within the banner (for example, the default value is “By continuing to browse or by closing this window, you accept the use of cookies“)
btnCaption (string) – This is the text displayed in the button (located at the bottom of the window in which the extended policy is displayed when you click the cookie policy link within the banner) used to confirm your consent to the installation of cookies; for example, the default value is “Continue to browse“
callback {}
(object) – This is the parameter through which you can define the callback that iubenda Cookie Solution can perform upon the occurrence of an event, namely:
onReady (function) – If the consent of the user has not yet been processed (for example, because it’s his first visit) the onReady callback is invoked as soon as the banner cookie is displayed; on the contrary, if the user has already given their consent to the installation of cookies, this callback is invoked as soon as the iubenda Cookie Solution is initialized. The consent given or not is passed as an argument, which can be true or false.
onBannerShown (function) – Using this feature you can run a script when the banner is shown
onCookiePolicyShown (function) – Called when the cookie policy is shown (either in modal window or on a separate page)
onConsentGiven (function) – This callback is invoked if the user has given the consent to the installation of cookies, both when consenting for the first time and in all subsequent visits
onConsentFirstGiven (function) – It is invoked only for the first time that the user gives their consent. One of the following strings is passed as an argument: documentScroll, documentMoved, bannerXClose, documentClicked or cookiePolicyClosed
onConsentRead (function) – It is invoked the first time the user gives consent and each subsequent loading when the consent is detected. The callback onConsentGiven becomes an alias for onConsentRead and it is not invoked if the latter is defined
onStartupFailed (function) – It is invoked in the case where the iubenda Cookie Solution fails the startup phase. An error message is passed as an argument
onError (function) -It is invoked in the case where the iubenda Cookie Solution is experiencing an error. An error message is passed as an argument
onFatalError (function) – It is invoked in the case where the iubenda Cookie Solution experiencing an error that does not allow it to continue. An error message is passed as an argument
onActivationDone (function) – It is invoked when the snippet activation is complete (available only on the Safemode version)
preferenceCookie {}
(object) – This is the parameter through which you can customize the lasting of the preference cookie iubenda installs in the user’s browser in order to record its consent. In particular, the object to be defined is:
cookiePolicyUrl:
(string) – This is the cookie policy’s URL linked within the banner. It is available in your privacy policy’s edit page in the “integration” tab. If you don’t define this parameter it will refer to the cookie policy generated by iubenda and hosted on our servers. You can alternatively choose to host the cookie policy on a page of your website and thus fill this field with the related URL. Remember that if you decide to host the cookie policy on your own page, this page should not use cookies, beyond the technical ones. Note: this parameter will be ineffective if you are using a custom HTML for the banner (see the configuration banner.html below)
cookiePolicyInOtherWindow:
(boolean, default false) – If you set this parameter to true the cookie policy will open in another window instead of the iubenda modal window
rebuildIframe
(boolean, default false) – Once the user’s consent has been recorded, the default behavior of the Cookie Solution is to restore the iframes previously modified in order to make them working again. By setting this parameter to true, the iframes previously blocked are fully regenerated (or reintegrated) after the collection of consent.
preserveOriginalClasses
(boolean, default false) – By default, the original classes of the snippets are deleted as a result of their reactivation. By setting this parameter to true, it makes sure that the original classes remain intact even after the activation.
preserveIubClasses
(boolean, default false) – By default, the “_iub_cs_activate” class is deleted as a result of the reactivation of the snippet. By setting this parameter on true you allow this class to remain defined after the reactivation. Note: to be effective, this parameter requires also the parameter preseveOriginalClasses
to be set to true (see above for further details). Moreover, this parameter has no effect on the snippets tagged with _iub_activate-inline
.
inlineDelay
(integer, milliseconds, default 800 (safemode 500)) – The maximum time between the activations of snippets tagged with the class _iub_cs_activate-inline
(the snippet tagged in this way are activated sequentially). By decreasing this value you will reduce the total time of activation. CAUTION: The default value is set in order for the snippets to work properly; reducing it may prevent the successful activation of some snippet. It is highly recommended to check the activation of the snippet shown on your page if this setting is changed.
startOnDomReady
(boolean, default false) – if true banner rendering and/or activation of blocked snippets will be performed as soon as the document status is ‘loaded’ (i.e. when the DOM reaches the ‘loaded’ status); This implies that banner rendering and/or snippet activation may occur while some resources are still being loaded (such as scripts, images, css, etc.). If the option is set to false, then the Cookie Solution will start when the page has been fully loaded (i.e. when the DOM status is ‘completed’ and all resources included in the page have been loaded) (available only on the Safemode version).
enableCMP
(boolean, default false) — if true, a “customize advertising tracking” link will appear in the bottom section of Cookie Policy modal window. When clicked, this link will open a window that allows users to manage their advertising tracking preferences according to the IAB Transparency and Consent Framework. Learn more.
askConsentIfCMPNotFound
(boolean, default true) — if set to true, and the IAB CMP Framework preference is not found, the Cookie Solution will, by default, request a new consent from users that had provided consent prior to the activation of the Framework. Set this option to false to disable this default behavior.
logLevel:
(string) – It defines the verbosity of the logger (available values: ‘debug’, ‘info’, ‘warn’, ‘error’, ‘fatal’; the default value is ‘nolog’)).
iubenda-cs-close-btn
– By adding this class to any element of the page, the click on the item closes the banner and assumes that the consent is provided (in an equivalent manner to the click on the X button of the banner).
iubenda-cs-cookie-policy-lnk
– By adding this class to any element of the page, the click on that element allows the displaying of the Cookie Policy (it’s equivalent to the click on the link to the Cookie Policy).
In order to ensure proper display of the cookie policy, the class iubenda-cs-cookie-policy-lnk
(assigned to the link to the cookie policy in the banner) must not be used elsewhere on the page.
Here is an example of configuration with the optional parameters:
- <script type="text/javascript">
- var _iub = _iub || [];
- _iub.csConfiguration = {
- siteId: 234578,
- cookiePolicyId: 340542,
- cookiePolicyUrl: 'http://www.site.com/cookie-policy',
- enableRemoteConsent: false,
- consentOnScroll: false,
- banner: {
- slideDown: false,
- zIndex: 99999998,
- content: "
- Informativa
- " +
- "
- Questo sito o gli strumenti terzi da questo utilizzati si avvalgono di cookie necessari al funzionamento ed utili alle finalità illustrate nella cookie policy. Se vuoi saperne di più o negare il consenso a tutti o ad alcuni cookie, consulta la %{cookie_policy_link}.
- Chiudendo questo banner, scorrendo questa pagina o cliccando qualunque suo elemento acconsenti all’uso dei cookie.
- ",
- cookiePolicyLinkCaption: "cookie policy",
- backgroundColor: "#CCC",
- textColor: "#000",
- fontSize: "12px",
- innerHtmlCloseBtn: "OK"
- },
- footer: {
- message: 'Proseguendo la navigazione o chiudendo la finestra presti il tuo consenso all\'installazione dei cookie.',
- btnCaption: 'Prosegui la navigazione'
- },
- callback: {
- onBannerShown: function(){doSomethingOnBannerShown()},
- onConsentGiven: function(){setCustomCookies()}
- },
- preferenceCookie: {
- expireAfter: 365
- },
- consentOnButton: true,
- };
- (function (w, d) {
- var loader = function () { var s = d.createElement("script"), tag = d.getElementsByTagName("script")[0]; s.src = "//cdn.iubenda.com/cookie_solution/iubenda_cs.js"; tag.parentNode.insertBefore(s, tag); };
- if (w.addEventListener) { w.addEventListener("load", loader, false); } else if (w.attachEvent) { w.attachEvent("onload", loader); } else { w.onload = loader; }
- })(window, document);
- </script>
Other examples of possible configurations:
The iubenda Cookie Solution features a JS API for easy interaction with some of its main functions.
Syntax: _iub.cs.api.METHOD_NAME
The available methods are:
printErrors()
: prints any errors in the iubenda Cookie Solution on the browser console.
showCP()
: shows the Cookie Policy (similarly to when you click on the link to the Cookie Policy in the banner or on another link with the iubenda-cs-cookie-policy-lnk
class, as described here)
consentGiven()
: provides consent. The method accepts the following as optional parameters:
Note: the call to this method assumes the consent provided is completely equivalent to when it is provided via UI, e.g. with page scrolling. Therefore, all actions downstream of the consent provided are performed, including the updating of the preference cookie, the activation of the previously blocked snippets and the invocation of the onConsentFirstGiven
and onConsentRead
callbacks.
To activate only the snippets there’s the activateSnippets()
method.
activateSnippets()
: activate the previously blocked snippets.
Note: this method can be invoked repeatedly – already-activated snippets will not be taken into account. It is therefore useful in those installations where, upon collection of consent, previously blocked content that now needs to be activated, is dynamically added to the page (e.g. lazy loading or infinite scrolling).
For the Safemode version only, this method has the option runOnActivationDoneCallback
(boolean, default false) which, if true, will execute the onActivationDone
callback upon completion of the activation of the snippet (see onActivationDone callback).
isConsentGiven()
(DOMElement, default window.document): returns true if the consent was given, otherwise it returns false.
setConsentOnScrollOnElement()
(boolean): the call to this method defines the element on which the scroll will be observed for the purpose of consent.
Note: this method is useful when you want to take advantage of the consentOnScrollOnElement
option, but the DOMelement is not yet available when the Cookie Solution is initialized. In this regard it’s possible to use the onBannerShow
callback (example) which occurs when the CS is initialized.
The consent provided by the user is saved in some cookies within the host page’s domain. By verifying the presence or the absence of these cookies you can determine whether the user has given their consent or not.
In particular, the consent is considered provided if there is the cookie _iub_cs-s[siteId]
or the cookie _iub_cs-[cookiePolicyId]
, where siteId
and cookiePolicyId
are the parameters provided in the embedding code (in the case shown above, the two cookies to look for will be _iub_cs-s234578
and _iub_cs-340542
). Below is an example of JavaScript code for reading out the client-side consent:
- function isConsentGiven (siteId,cookiePolicyId){
- var cs = document.cookie.split(';');
- for (var i = 0; i < cs.length; i++) {
- while (cs[i].charAt(0) == ' ') cs[i] = cs[i].substring(1);
- if(cs[i].indexOf('_iub_cs-s'+ siteId) == 0||cs[i].indexOf('_iub_cs-'+ cookiePolicyId) == 0) return true;}
- return false;
- }
By placing this code as high as possible within the page you can read the consent given and transmit this information to all other JavaScripts that follow.