Documentation index

Introduzione ›

Technical documentation for the iubenda Cookie Solution: banner, cookie policy and consent management


Our consent request banner has the following characteristics:

  • It’s implemented by inserting a simple code/script in all pages of the site
  • It shows a banner with a predefined and modifiable text which holds a link to the actual cookie policy
  • It’s optimized for various resolutions and device sizes
  • Makes sure the cookie policy can be consulted without prior consent
  • Makes sure the script blocking works correctly – please consult the introductive guide to cookie blocking configuration for a more in depth understanding.
  • Registers preferences via the continued browsing of the user e.g. scrolling down the page
  • Scrolling or further browsing triggers the activation of all scripts that were previously blocked and this is done asynchronously (without page-reload)
  • The banner does not appear and all scripts are automatically executed If the user’s preference has already been registered.

1. Installation

Generic installation

Insert the following code before closing the closing of the HEAD tag.

<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 above is an example. To generate your own code, just click “Activate/Configure cookie policy” which you will find located on the right inside the management page of each privacy policy within your own iubenda account.

WordPress installation

Open the header.php file of the theme you are using and insert the base code above the closing of the HEAD tag.

For WordPress we’ve also published a plugin that further simplifies the tasks at hand. See the following post on how to utilize the WordPress plugin by iubenda to automate the blocking of scripts.

Joomla! installation

To configure the iubenda Cookie Solution for Joomla! you can install an aid such as the custom HTML advanced module. Here’s an article that explains how to use this module to install the privacy policy generated with iubenda on the site; although the example provided therein does not pertain to the iubenda Cookie Solution, the integration process is identical. We remind you that, as always, the iubenda Cookie Solution code must be entered before the closing HEAD tag.

For Joomla! we’ve also published a plugin to simply the process. Please consult the post on how to utilize the Joomla! plugin by iubenda to automate the blocking of scripts.

Note:

  • The iubenda Cookie Solution requires at least jQuery 1.4.4 at the moment (if the site has an older version, you’ll need to update jQuery. If jQuery isn’t on the site, iubenda installs it automatically for you)

2. Configuration

Available parameters _iub.csConfiguration {}:

Required parameters

siteId: – ID of the site (note: this ID is used to share the preferences of various cookie policies in multiple languages that are however connected to the same site/app)

cookiePolicyId: – ID of your cookie policy

lang: – This parameter defines the language in which to display the content contained within the cookie banner (eg. “en” for English, “it” for Italian, “es” for Spanish etc.). All languages that can be used with the iubenda privacy/cookie policy, will also work for the cookie banner

Optional parameters

cookiePolicyUrl: (string) – The URL of your cookie policy, available in your iubenda dashboard, or from any page that hosts the policy. This configuration value isn’t working if you’re using a custom HTML for the banner (see the banner.html configuration below). Please note: if you decide to host the cookie policy on one of your own pages, that page cannnot make use of cookies outside of technical, strictly necessary cookies

cookiePolicyInOtherWindow: (boolean, false by default) – Set to true if you want the cookie policy to open in another window and not in the lightbox/iubenda modal

enableRemoteConsent: (boolean, false by default) – You can set this parameter to true to enable the registration of cross-site consent (e.g. if the script is implemented on more of the same network sites). In particular, with this parameter set to true our solution creates a cookie (technical) on the iubenda.com domain that is read when the cookie on the local domain is not found

consentOnScroll: (boolean, true by default) – Set to false to avoid the registration of consent at the scrolling of the page

reloadOnConsent: (boolean, false by default) – Set to true if you want to reload the page when the user gives his consent

localConsentDomain: (string, null by default) – The domain on which you want the consent given by the user saved. If this parameter isn’t given, the consent gets saved by default in a cookie for the domain on a second level of the current page (for example: visiting www.example.com, the consent gets saved in a cookie on the domain example.com). In the case in which the default behavior isn’t suitable, for example if the site were www.store.example.com and the consent needs to be saved for store.example.com, you need to fill that parameter with ‘store.example.com’

Note: if in a similar scenario to the one described by example www.store.example.com the parameter localConsentDomain should not be supplied, the banner could continue to appear to the same user at each subsequent visit/page view

localConsentPath: (string, ‘/’ by default) – The path at which you’ll want, on the local domain, the consent by the user saved. By default, the consent given by the user gets saved on the local domain in a cookie on the path ‘/’. In this way, the cookie is available at whichever page of the domain that a user accesses. If on the other hand one would like to not make the preference cookie set for www.example.com/user1 available on www.example.com/user2, and vice versa, you’ll need to set this parameter to the value ‘/user1’ in the first case and to the value ‘/user2’ in the second

consentOnScrollDelay: (integer, default 1000 milliseconds) – The delay with which consent gets recognized via scroll once the informative banner has been shown [Available in BETA]

priorConsent: (boolean, default true) – enable script blocking and their reactivation only after consent has been collected. If false, the scripts subjected to blocking are always activated regardless of whether or not consent has been provided (it is strongly advised against settting priorConsent to false if you want to be in strict accordance with EU cookie legislation and in particular with the Italian law, except that you do not consciously use the Cookie Light Solution, which requires you to set priorConsent: false)

rebuildIframe: (boolean, false by default) – By default the Cookie Solution, once the user’s consent was recorded, restores iframes previously modified so as to make them functional again. Setting this parameter to true, however, after the consent iframes that were previously blocked are fully regenerated (or reintegrated)

preserveOriginalClasses: (boolean, false by default) – By default the original classes of the snippets are deleted as a result of their reactivation. Instead, when setting this parameter to true, it makes sure that the original classes remain intact even after activation

preserveIubClasses: (boolean, false by default) – By default the class “_iub_cs_activate” is canceled as a result of the reactivation of the snippet. Instead, setting this parameter to true will result in this class remaining defined in the snippet, even after activation. Note: to be effective, this parameter requires that preserveOriginalClasses is set to true (see above for details). Also, this parameter has no effect on snippets tagged with class “_iub_cs_activate-inline”

Here are additional optional parameters that call for the definition of one or more objects

banner {} (object) – Use this object to customize various aspects of the cookie banner. The options are listed below and must be children of the banner {} tree.

View application example below →

  • slideDown (boolean, true by default) – Set to false to remove the initial banner animation
  • zIndex (number) – zIndex of the div of the banner of the cookie policy (default value: 99999998)
  • content (string) – Content (text) with the notice of the cookie policy, current default (e.g. in English):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 %{cookie_policy_link}. If you want to know more or withdraw your consent to all or some of the cookies, please refer to the cookie policy.
    By closing this banner, scrolling this page, clicking a link or continuing to browse otherwise, you agree to the use of cookies
    Please note: %{cookie_policy_link} is the placeholder for the cookie policy link. Remember that by default the cookie policy linked in the banner is hosted on our site. To change the default behavior, customize the parameter cookiePolicyUrl (please refer to the section of this guide for more information on cookiePolicyUrl parameter). The content of the cookie banner will be localized in all languages available in the generator (the language in which to display the cookie banner content is defined through the parameter lang)

    Warning

    In order to make sure that the cookie policy visualizes properly, the class “iubenda-cs-cookie-policy-lnk” (assigned to the link in the cookie policy in the banner) can’t be used anywhere else on the page.

  • cookiePolicyLinkCaption (string) – Anchor text of the link to the cookie policy (default value: “cookie policy”)
  • backgroundColor (string, “#000” by default) – Background color of the banner
  • textColor (string, “#FFF” by default) – Text color of the banner
  • fontSize (string, “14px” by default) – Text size of the banner
  • innerHtmlCloseBtn (string, “x” by default) – Closing button text for the banner
  • applyStyles (boolean, true by default) – If set to false, then banner doesn’t have any style applied/CSS; as the base for your own design, we suggest you use the CSS available here for you, which reapplies the same styles excluded by this option, which however has the upside to be modifiable once added to your own pages. Examples for you to check out:
  • html (string, null by default) – HTML of the banner to substitute the default version. Please note, the following elements are necessary for the correct functioning of the banner:
    • div.iubenda-cs-content (main content)
    • a.iubenda-cs-cookie-policy-lnk (link with href set 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 (close button for the banner)
  • prependOnBody (boolean, false by default) – Setting prependOnBody to true, the HTML code of the banner is injected into the site as the first element of the BODY. By default, however, prependOnBody is set to false and the banner is placed as the last element of BODYSet to true in order to place the banner above the header. This way the banner will be the first element of the page and, to show it above the header, you’ll just have to add a padding-top to the next element:#iubenda-cs-banner + * { padding-top: 180px; }

footer {} (object)

  • message (string) – Text message visualized below the details of the cookie policy (default value, e.g. in English: “By continuing to browse or by closing this window, you accept the use of cookies”)
  • btnCaption (string) – Text message inserted in the button to confirm and consent to the cookie policy (default value, e.g. in English: “Continue to browse”)

See application example below →

callback {} (object) – Contains all the various possible callbacks:

  • onReady (function) – If your consent has not yet been processed (for example, because it is your user’s first visit), the onReady callback is invoked as soon as the banner cookie will be displayed; but if you have already received their consent to the installation of cookies, this callback is invoked as soon as the iubenda Cookie Solution is initialized
  • onBannerShown (function) – Through this function you can run a script when the banner is shown
  • onCookiePolicyShown (function) – Invoked when the cookie policy is shown
  • onConsentGiven (function) – Called at the moment when the user consents to the cookie policy and therefore to the use of cookies
  • onConsentFirstGiven (function) – Invoked the first time the user gives consent. One of the following strings is passed as an argument: ‘documentScroll’, ‘documentMoved’, ‘bannerXClose’, ‘documentClicked’ or ‘cookiePolicyClosed’
  • onConsentRead (function) – Invoked the first time the user gives consent and each subsequent execution when the consent is detected. The onConsentGiven callback becomes an onConsentRead alias and is not invoked if the latter is defined
  • onStartupFailed (function) – Invoked when the iubenda Cookie Solution fails the startup phase. An error message is passed as an argument
  • onError (function) – Invoked when an error occurs. An error message is passed as an argument
  • onFatalError (function) – Invoked when an error occurs and the iubenda Cookie Solution cannot be executed. An error message is passed as an argument

See application example below →

preferenceCookie {} (object) – It is the parameter by which to customize the duration of the preference cookie installed by iubenda into the user’s browser when consent is being recorded. In particular, the object to be defined is:

  • expireAfter (number, 365 by default) – Number of days that the consent will remain valid for this website

See application example below →

Parameters for developers

logLevel: (string) – Logging depth (available: ‘debug’, ‘info’, ‘warn’,’error’,’fatal’. Default value is ‘noLog’)

skipSaveConsent: (boolean, true by default) – If the consent doesn’t need to be saved in the preference cookies

logViaAlert: (boolean, false by default)True if the logging needs to be shown via alert

consentOnButton: (boolean, true by default) – Allows to activate the cookie policy also via clicking on the buttons (button) present in the page, other than the links

Available classes

  • iubenda-cs-close-btn – If you add this class to any element of the page, a click on the item closes the banner and assumes consent was provided (in a manner equivalent to clicking the default X button on the banner)
  • iubenda-cs-cookie-policy-lnk – If you add this class to any element of the page, a click on the item allows the visualization of the cookie policy (in a manner equivalent to clicking the cookie policy link on the banner)

Warning

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.

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&agrave; illustrate nella cookie policy. Se vuoi saperne di pi&ugrave; 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>

Below you’ll find examples to demonstrate the different options and how they are expressed in code:

Interpreting the preference cookie

The consent provided by the user is registered into some cookies on the host domain. Verifying the presence (or absence) of these cookies makes it possible to deduce if the users have provided their consent. In particular, the consent has been provided if the cookie _iub_cs-s[siteId] or else _iub_cs-[cookiePolicyId] are present where siteId and cookiePolicyId are the parameters given to the embedding code (in the case of the embedding code illustrated before, the two cookies to look for are _iub_cs-s234578 and _iub_cs-340542). Below, an example Javascript code to interpret consent on the client-side:

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;
}

Placing this code as high on the page as possible allows you to read the consent given and provide this information to all other subsequent Javascript.


Still have questions?

Visit our support forum Email us