Iubenda logo
Start generating

Documentation

Table of Contents

How to Configure Your Cookie Solution (Advanced Guide)

Here you’ll find an in-depth look at:

💡 Need an introduction? Learn configurator options, how to change banner style, position and more in our Cookie Solution introduction guide.

Quick recap:

  • It’s implemented by inserting a simple code / script in all pages of the site;
  • It shows a notice containing a standard text, it is fully customizable and contains a link to the cookie policy;
  • It has a completely responsive design – optimized for various resolutions and device sizes;
  • We ensure that the cookie policy can be viewed even before the user consent is provided;
  • We ensure a proper functioning of the blocking of scripts – see the introductory guide for the blocking of cookies for more information regarding this topic;
  • Registers preferences via the continued browsing of the user, for instance, through the scroll action;
  • After the consent has been collected, it asynchronously activates (namely without reloading the page) all the scripts that were previously blocked;
  • If the consent has previously been provided by the user, the cookie banner does not appear and the scripts are automatically executed;
  • Easily customize with our configurator. Edit the look, details, features of the solution, all within a few clicks.

Once you’ve generated your cookie banner (Cookie Solution > Activate/Edit), you’ll get a similar code snippet:

<script type="text/javascript">
    var _iub = _iub || [];
    _iub.csConfiguration = {
        "lang": "en",
        "siteId": XXXXXX, //use your siteId
        "cookiePolicyId": YYYYYY, //use your cookiePolicyId
        "banner": {
            "position": "float-top-center",
            "acceptButtonDisplay": true,
            "customizeButtonDisplay": true
        }
    };
</script>
<script type="text/javascript" src="//cdn.iubenda.com/cs/iubenda_cs.js" charset="UTF-8" async></script>

To display the cookie banner on your site, copy and paste the snippet above (remember to generate your own code on Cookie Solution > Activate/Edit) at the end of the HEAD tag of your pages, or use one of our plugins for:

We also have step-by-step integration guides for custom websites, Shopify, Webflow, Wix and Squarespace.

Drupal users, you can access the class via direct download or Packagist, and find full instructions in the PHP class guide.

In addition to displaying a cookie banner, you must also block cookies prior to consent:

 

Note: all of the following parameters need to be included within _iub.csConfiguration {}.

1. Required parameters

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.

2. Compliance settings

countryDetection (boolean, default false) – Allows you to autodetect and limit prior-blocking and cookie consent requests only to users from the EU – where this is a legal requirement – while running cookies scripts normally in regions where you are still legally allowed to do so.

Set this parameter to true if gdprAppliesGlobally is set to false and you want to automatically detect the user country. If you disable this option, remember to set gdprApplies:false on all page views where the consent is not being requested.

2.1 GDPR

enableGdpr (boolean, default true) – If true, you’ll enable/make available the GDPR functionality in the Cookie Solution (without actually applying it).

gdprAppliesGlobally (boolean, default true) – If true, you’ll apply GDPR protections to all users. Set this parameter to false and countryDetection:true to request consent to EU users only. Remember that if you’re based in the EU you must apply the GDPR also to users based outside of the EU.

gdprApplies (boolean, default true) – If false, you won’t apply GDPR protections to the current user and he will not be shown the cookie banner. If you’ve set countryDetection:false, you should set gdprApplies:false on all page views where the consent is not being requested.

Buttons (accept, customize, reject, close)

The options listed below must be contained within the banner {} object:

acceptButtonDisplay (boolean, default false) – Determines whether or not the “Accept” button is displayed.

customizeButtonDisplay (boolean, default false) – Determines whether or not the “Learn more and customize” button is displayed.

rejectButtonDisplay (boolean, default false) – Determines whether or not the “Reject” button is displayed. When true banner.closeButtonDisplay is forced to false. View the demo on CodePen.

closeButtonDisplay (boolean, default true) – If set to false, the banner’s close button won’t be displayed.

consentOnContinuedBrowsing (boolean, default true) – If set to false, consentOnScroll, consentOnDocument and consentOnLinkAndButton are set to false, and consentOnElement is set to no element. This way you only accept explicit consent, while consent on scroll and page interaction is not given.

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.

consentOnHorizontalScroll (boolean, default false) – By setting this parameter to true, the consent is given even in cases of horizontal scrolling.

consentOnScrollOnElement (string|DOMElement, default null) – The scrolling event is observed on the element passed as a parameter (including selectors like classes and ids). The DOM element may not yet be available when the Cookie Solution is initialized. In this case, you can use the setConsentOnScrollOnElement API method.

consentOnLinkAndButton (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). Set to false, the consentOnLinkAndButton parameter (formerly consentOnButton) changes the default behavior by ensuring that the consent results as “not given” in these cases.

consentOnElement (string|DOMElement, default “input, textarea, form”) – The user’s consent is recorded by clicking on one of the html elements (including selectors like classes and ids) listed in the parameter. Unlike consentOnLinkAndButton (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).

perPurposeConsent (boolean, default false) – Setting this parameter to true gives users granular control over which categories of cookies they consent to (see below). The categories are displayed along with a short description and toggle so that users can either grant or reject consent for the particular processing purpose.

The categories displayed in the modal are automatically detected and passed from your iubenda cookie policy to the Cookie Solution. However, the categories displayed can also be customized by using the purposes parameter below.

Examples:

Manual tagging and per-category consent

If you’ve enabled the per-category consent feature you’ll need to specify the categories of scripts that install cookies prior to consent with a special comma-separated data-iub-purposes attribute. Read this guide for further instructions and examples on using manual tagging and per-category consent.

purposes (string, default null) – Purposes are grouped into 5 categories (strictly necessary, basic interactions & functionalities, experience enhancement, measurement, targeting & advertising), each having an id (1, 2, 3, 4, 5). By default, we use the purposes from the iubenda cookie policy connected to your configuration, but you can customize which categories to display with purposes (for example, if you use your own cookie policy).

Here are the purposes included in each category:

  1. Strictly necessary (id 1). Purposes included:
    • Backup saving and management
    • Hosting and backend infrastructure
    • Managing landing and invitation pages
    • Platform services and hosting
    • SPAM protection
    • Traffic optimization and distribution
    • Infrastructure monitoring
    • Handling payments
  2. Basic interactions & functionalities (id 2). Purposes included:
    • Contacting the User
    • Interaction with live chat platforms
    • Managing web conferencing and online telephony
    • Managing support and contact requests
    • Interaction with support and feedback platforms
    • Tag Management
    • Registration and authentication
    • User database management
  3. Experience enhancement (id 3). Purposes included:
    • Content commenting
    • Interaction with data collection platforms and other third-parties
    • Displaying content from external platforms
    • Interaction with external social networks and platforms
    • Interaction with online survey platforms
    • RSS feed management
    • Social features
  4. Measurement (id 4). Purposes included:
    • Analytics
    • Beta testing
    • Content performance and feature testing (A/B testing)
    • Heat mapping and session recording
    • Managing data collection and online surveys
  5. Targeting & Advertising (id 5). Purposes included:
    • Advertising
    • Advertising service infrastructure
    • Commercial affiliation
    • Managing contacts and sending messages
    • Remarketing and behavioral targeting

So, for example, if you’re using all 5 categories, and you’re not using an iubenda cookie policy, you’ll need to specify "purposes": "1, 2, 3, 4, 5", if you don’t use Measurement (id 4) you can simply specify "purposes": "1, 2, 3, 5" and so on.

Note: to be effective, this parameter requires the parameter perPurposeConsent to be set to true (see above for further details).

listPurposes (boolean, default false) – If true, it displays purposes in the first layer of the cookie banner (to be effective, perPurposeConsent must be set to true). This option must be contained within the banner {} object.

2.2 CCPA

enableCcpa (boolean, default false) – If true, you’ll enable/make available the CCPA functionality in the Cookie Solution (without actually applying it).

ccpaApplies (boolean, default undefined) – If true, you’ll apply CCPA protections to the current user.

ccpaNoticeDisplay (boolean, default true) – If false, you won’t display an actual banner to notify users about CCPA (effective only if GDPR doesn’t apply).

ccpaAcknowledgeOnDisplay (boolean, default false) – If ccpaNoticeDisplay: true, allows you to specify what constitutes acknowledgment of the notice: the simple loading of the notice (true) or the explicit interaction after the notice has loaded (false).

ccpaLspa (boolean, default undefined) – Allows you to specify whether the transaction should be performed under the Limited Service Provider Agreement (LSPA) by IAB.

Classes

iubenda-ccpa-opt-out – By adding this class to any element of the page, the click on the item triggers the opening of a dialog where the user can confirm their intention to opt-out from the sale of their personal information (“Do Not Sell My Personal Information” link).

Major advertising networks now require publishers to gain consent before showing personalized ads. In this guide you’ll find out how you can meet this requirement with the IAB Transparency and Consent Framework and our Cookie Solution.

enableCMP or enableTcf (boolean, default false) – If true, users will be able to manage their advertising tracking preferences according to the IAB Transparency and Consent Framework.

googleAdditionalConsentMode (boolean, default false) – If set to true, you’ll be able to gather consent for Google ad partners that are not yet part of the Transparency and Consent Framework, but are on Google’s Ad Tech Providers (ATP) list.

tcfPurposes (object) – TCF v2.0 has 10 purposes, each having an id:

  1. Store and/or access information on a device
  2. Select basic ads
  3. Create a personalised ads profile
  4. Select personalised ads
  5. Create a personalised content profile
  6. Select personalised content
  7. Measure ad performance
  8. Measure content performance
  9. Apply market research to generate audience insights
  10. Develop and improve products

With TCF v2.0 you can:

  • limit the legal basis to consent only or to legitimate interest only, as well as both; and
  • choose which TCF purposes to prompt

Here’s how to do it. Thanks to tcfPurposes, in the following example we’ll:

  • disable the purpose number 1 (“Store and/or access information on a device”, set to consent_not_needed, possible only if our legislation does not require consent for this purpose) *,
  • disable the purpose number 2 (“Select basic ads”, set to false),
  • limit the legal basis to legitimate interest only (li_only) for purpose number 4 (“Select personalised ads”), and
  • limit the legal basis to consent only (consent_only) for purpose number 7 (“Measure ad performance”)
_iub.csConfiguration = {
    "lang": "en",
    "siteId": xxxxxx, //use your siteId
    "cookiePolicyId": yyyyyy, //use your cookiePolicyId
    "enableTcf": true,
    ...
    "tcfPurposes": {
        "1": "consent_not_needed",
        "2": false,
        "4": "li_only",
        "7": "consent_only"
    },
    "tcfPublisherCC": "DE",
    "banner": {
        ...
    }
}

* Note about PurposeOneTreatment: previously, in some countries it was not required get user consent for purpose number 1 (“Store and/or access information on a device”). In those cases, asking for consent for purpose one could be disabled by using "1": "consent_not_needed". However since this option should only be enabled if legally supported by the legislation that applies to you, and, at the time of writing, no EU country currently supports this legislatively – we strong advise against using it.

askConsentIfCMPNotFound (boolean, default true) – If set to true, and the IAB 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.

newConsentAtVendorListUpdate (number, default undefined) – Number of days to wait to trigger a new consent request after the vendorlist.json is updated. If set to undefined, users who have already given consent will not be shown the cookie banner again, and consent for new vendors will be set to off. If set to 0 users will get prompted with a new consent request whenever the vendor list is updated.

Classes

iubenda-advertising-preferences-link – By adding this class to any element of the page, the click on the item triggers the opening of the advertising tracking settings modal (allowing users to update their TCF preferences even after closing the cookie banner).

Please note that as an alternative to this specific TCF class, you can also use the “generic” iubenda-cs-preferences-link, the result will be the same.

iubenda-vendor-list-link – Add this class to any element of the page to allow users to reopen the TCF vendor list.

3. Style and text

3.1 Format and Position

position (string, default “float-top-center”) – It defines the position of the cookie banner. Available values: top, bottom, float-top-left, float-top-right, float-bottom-left, float-bottom-right, float-top-center, float-bottom-center and float-center.

backgroundOverlay (boolean, default false) – Set this parameter to true in order to add an opaque background overlay effect to the rest of the page when the cookie banner is shown.

3.2 Theme

logo (string) – URL (https recommended) or base64 equivalent of an image to be used as a logo for the header of the cookie banner. Use a white SVG on transparent background for best result.

brandTextColor (string, default “#000”) – Text color of the header of the modal/cookie banner.

brandBackgroundColor (string, default “#fff”) – Background color of the header of the cookie banner.

Banner colors

backgroundColor (string, default “#000”) – The background color of the banner.

textColor (string, default “#fff”) – The color of the banner’s text.

Buttons

acceptButtonColor (string, default “#0073ce”) – Background color of the “Accept” button.

acceptButtonCaptionColor (string, default “#fff”) – Text color of the “Accept” button.

customizeButtonColor (string, dark theme default “#212121”, light theme default “#dadada”) – Background color of the “Learn more and customize” button.

customizeButtonCaptionColor (string, dark theme default “#fff”, light theme default “#4d4d4d”) – Text color of the “Learn more and customize” button.

rejectButtonColor (string, default “#0073ce”) – Background color of the “Reject” button.

rejectButtonCaptionColor (string, default “#fff”) – Text color of the “Reject” button.

Advanced settings

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’s an example: Banner with custom CSS.

zIndex (number) – This is the zIndex of the banner’s div. The default value is 99999998.

3.3 Text

Font size

fontSize (string, default null) – The dimension of the banner’s text (including the closing button). If this option is active the possible values in the options banner.fontSizeCloseButton and banner.fontSizeBody 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.

Banner copy

content (string) – This is the textual content inside the cookie banner. For example, for the English version the default value is:

Notice
We and selected partners use cookies or similar technologies as specified in the %{cookie_policy_link}.

Shortcodes

Shortcodes are special words that can be used inside banner.content and banner.html as a placeholder for something else. You can use them when you want to customize the banner but still keep the UI elements that allow to have the standard Cookie Solution behaviour.

Shortcodes available for banner.content:

  • %{cookie_policy_link} is replaced with a link to cookiePolicyUrl and with the caption specified in banner.cookiePolicyLinkCaption
  • %{advertising_preferences_link} is replaced with a link to the Transparency and Consent Framework widget
  • %{vendor_list_link} is replaced with a link to the list of Transparency and Consent Framework vendors
  • %{privacy_policy} is replaced with a link to the privacy policy (needed for CCPA)
  • %{do_not_sell} is replaced with a link to opt out of CCPA selling

Here’s an example of a cookie banner with custom HTML and content.

Notes

  • %{cookie_policy_link} is the shortcode 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 cookiePolicyUrl).
  • 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).
  • If you’ve enabled the Transparency and Consent Framework, you may notice that the banner text is quite long – this is necessary to meet IAB’s minimum requirements. Therefore, please read IAB’s requirements carefully before editing the content of the banner.
  • 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.

acceptButtonCaption (string, default “Accept”) – The text of the banner’s “Accept” button.

customizeButtonCaption (string, default “Learn more and customize”) – The text of the banner’s “Learn more and customize” button.

rejectButtonCaption (string, default “Reject”) – The text of the banner’s “Reject” button.

Advanced settings

html (string, default null) – It is the default HTML of the banner, through this parameter it can be replaced with a customized one.

Notes: 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, ie https://www.iubenda.com/privacy-policy/123456/cookie-policy?an=no&s_ck=false)
Shortcodes

Shortcodes are special words that can be used inside banner.content and banner.html as a placeholder for something else. You can use them when you want to customize the banner but still keep the UI elements that allow to have the standard Cookie Solution behavior.

Shortcodes available for banner.html:

%{banner_content} is replaced with the value specified in banner.content (or the default banner content). Please note that %{banner_content} is mandatory in case of TCF v2 (unless we’ve approved your custom text).

Here’s an example of a cookie banner with custom HTML and content.

innerHtmlCloseBtn (string, default “x”) – The text of the banner’s close button.

footer {} (object) – The options listed below must be contained within the footer {} object.

btnCaption (string) – Text of the button (located at the bottom of the “Tracking preferences” window, see per-category consent) used to save the consent preferences. The default value is “Save and continue”.

i18next

i18n {} (object) – You can translate/edit the texts of any Cookie Solution component via the i18n JavaScript library. See this demo on CodePen for a list of all components/strings you can edit and/or localize.

Important: if you’ve enabled the Transparency and Consent Framework, in order to meet IAB’s minimum configuration requirements, you must necessarily use the official translations (see “List of translations for purpose descriptions v2.0”).

floatingPreferencesButtonDisplay (string, default false) – It defines the position of the privacy widget (a feature that allows your users to access and edit tracking preferences at any time after setting their initial preferences). Available values: false, true, top-left, top-right, bottom-left, bottom-right (default if set to true), anchored-center-left, anchored-center-right, anchored-top-left, anchored-top-right, anchored-bottom-left, anchored-bottom-right.

floatingPreferencesButtonCaption (string, default false) – Text of the privacy widget button.

floatingPreferencesButtonIcon (boolean, default true) – Icon of the privacy widget button.

floatingPreferencesButtonHover (boolean, default false) – Shows the privacy widget text on hover.

floatingPreferencesButtonRound (boolean, default false) – Adds the iubenda-tp-circle attribute to the privacy widget button.

floatingPreferencesButtonColor (string, default “#fff”) – Background color of the privacy widget button.

floatingPreferencesButtonCaptionColor (string, default “#000”) – Text color of the privacy widget button.

privacyPolicyUrl (string) – Allows you to customize the privacy policy link.

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 privacy policy and the cookie policy will open in another window instead of the iubenda modal window.

cookiePolicyLinkCaption (string) – Anchor text of the link to the cookie policy (the default value is “cookie policy”). This option must be contained within the banner {} object.

5. Advanced settings

The options listed below must be contained within the banner {} object:

slideDown (boolean, default true) – You can set this parameter to false in order to disable the animation of the banner.

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

Example with the banner placed over the header.

reloadOnConsent (boolean, default false) – You can set this parameter to true if you want the page to be reloaded after the collection of the consent.

askConsentAtCookiePolicyUpdate (boolean, default false) – You can set this parameter to true if you want to request new consent when the Cookie Policy is updated.

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.

priorConsent (boolean, default true) – Enables the blocking of scripts and their reactivation only after having collected user consent. If false, the blocked scripts are always reactivated regardless of whether or not consent has been provided (useful for testing purposes, or when you’re working on your project locally and don’t want pageviews to be counted).

We strongly advise against setting "priorConsent":false if you need to comply with EU legislation. Please note that if the prior blocking setting has been disabled server side (via the checkbox on the flow page), this parameter will be ineffective whether it’s set to true or false.

5.3 Development

inlineDelay (integer, milliseconds, default 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.

consentOnScrollDelay (integer, milliseconds, default 500) – The delay with which the consent via scroll is detected, once the banner has been shown. This option must be contained within the banner {} object.

rebuildIframe (boolean, default true) – Once the user’s consent has been recorded, the default behavior of the Cookie Solution is to fully regenerate (or reintegrate) the iframes previously modified. By setting this parameter to false, the iframes previously blocked are restored after the collection of consent.

Callbacks

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.

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.

onBannerClosed (function) – Using this feature you can run a script when the banner is closed.

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.

onConsentRejected (function) – This callback is invoked if the user has rejected the consent to the installation of cookies.

onConsentFirstRejected (function) – Invoked when the consent has been rejected, as soon as the user gives his preference (not on every page view, as onConsentRejected).

onPreferenceExpressed (function) – It is invoked whenever a preference is expressed, be it accept or reject.

onPreferenceFirstExpressed (function) – Invoked as soon as the user gives his preference (not on every page view, as onPreferenceExpressed).

onPreferenceExpressedOrNotNeeded (function) – It is invoked whenever a preference is expressed or not needed, for example when:

  • gdprApplies:true and the user has expressed his preference, or
  • gdprApplies:false, or
  • gdprAppliesGlobally:false, countryDetection:true and the user is based outside the EU

onPreferenceNotNeeded (function) – It is invoked whenever a preference is not needed, for example when:

  • gdprApplies:false, or
  • gdprAppliesGlobally:false, countryDetection:true and the user is based outside the EU

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.

onBeforePreload (function) – Invoked when the Cookie Solution preloads, that is before the cookies are loaded.

onCcpaAcknowledged (function) – Invoked when the CCPA notice has been acknowledged.

onCcpaFirstAcknowledged (function) – Invoked the first time the CCPA notice has been acknowledged.

onCcpaOptOut (function) – Invoked when the user has opted out from sale.

onCcpaFirstOptOut (function) – Invoked the first time the user has opted out from sale.

View a sample configuration ↓

Debugging

skipSaveConsent (boolean, default false) – By setting this parameter to true, the consent is not saved in a preference cookie.

logLevel (string) – It defines the verbosity of the logger (available values: ‘debug’, ‘info’, ‘warn’, ‘error’, ‘fatal’; the default value is ‘nolog’).

logViaAlert (boolean, default false) – By setting this parameter to true, the logging is shown via alert.

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

expireAfter (number, default 365) – It represents the number of days of validity of the consent given by the user on a given web site. Note: this value is updated at each subsequent visit by the user.

ccpaCookie {} (object) – Allows you to customize the expiration of the cookie that stores the acknowledgment of the notice. In particular, the object to be defined is expireAfter.

expireAfter (number, default 365) – Number of days of validity.

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 within the local domain, in which you want to save the consent provided by the user. By default, the user’s consent is saved in the local domain within the cookie in the path ‘/’. This way, the cookie is available regardless of the page of the domain being accessed.

If you, for example, don’t want the preference cookie set for www.example.com/percorso1 to also apply to www.example.com/percorso2 (by browsing), and vice versa, you will need to provide the value ‘/percorso1’ for this parameter in the first case, and ‘/percorso2’ in the second case.

Further parameters

whitelabel (boolean, default true) – Set this parameter to false to show the iubenda branding on the second layer.

invalidateConsentBefore (“YYYY-MM-DD”, milliseconds from epoch, default null) – All consents collected prior to this date will be invalidated. Consents collected on this date and in the future will not be invalidated.

maxCookieSize (number, default 4096) – To avoid browsers reject cookies longer than 4096 characters, the Cookie Solution allows to split cookies in multiple chunks. With maxCookieSize you can configure the maximum length of every chunk (see also maxCookieChunks).

maxCookieChunks:(number, default 5) – With this parameter you can configure the maximum number of chunks into which cookies can be split (see also maxCookieSize).

Note: if the cookie to be saved is longer than maxCookieSize * maxCookieChunks (20480 chars with default values), then the cookie is not saved.

timeoutLoadConfiguration (integer, milliseconds, default 30000) – The amount of time to wait for the remote configuration before stating that a timeout occurred. In case of a slow network, by increasing this value, you’ll make sure that the Cookie Solution gets the needed resources on time.

startOnDomReady (boolean, default true) – 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). 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).

Classes

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

iub-prevent-consent – Add this class to certain links/buttons to avoid automatically giving consent when pressed. To be effective, it requires the parameter consentOnLinkAndButton to be set to true.

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). Note: 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.

iubenda-cs-preferences-link – Add this class to any element of the page to allow users to update their cookie preferences even after closing the cookie banner.

5.4 Examples

Here is an example of configuration with the optional parameters:

<script type="text/javascript">
    var _iub = _iub || [];
    _iub.csConfiguration = {
        "lang": "en",
        "siteId": 896537, //use your siteId
        "cookiePolicyId": 8207462, //use your cookiePolicyId
        "enableRemoteConsent": "false",
        "consentOnScroll": "false",
        "banner": {
            "position": "top",
            "slideDown": "false",
            "content": "This website or its third-party tools use cookies. Please refer to the %{cookie_policy_link} if you want to learn more or withdraw your consent.",
            "cookiePolicyLinkCaption": "cookie policy",
            "backgroundColor": "#CCC",
            "textColor": "#000",
            "fontSize": "14px",
            "innerHtmlCloseBtn": "OK"
        },
        "callback": {
            "onPreferenceExpressed": function(preference) {
                console.log('onPreferenceExpressed', preference);
            }
        },
        "preferenceCookie": {
            "expireAfter": 180
        }
    };
</script>
<script type="text/javascript" src="//cdn.iubenda.com/cs/iubenda_cs.js" charset="UTF-8" async></script>

Other examples of possible configurations:

5.5 Inline activator

It’s possible to include the part of the code relative to the scripts, directly in-page (inline); this code is known as the inline activator. Scripts can be activated through the inline activator even if the iubenda_cs.js primary resource is generically unavailable or in error.

The inline activator only guaranties script activation but can also take on a provided permission (see the following forceSafeActivation option). It cannot be used to show the banner, the cookie policy or manage the obtaining of consent.

It serves only as another layer of protection in case of errors and does not at all act as a substitute for the main iubenda Cookie Solution code.

Note that the inline activator will only invoke the onActivationDone, while others will be ignored.

Two additional configuration options are available for the inline activator:

  • safeTimeout (milliseconds, default 0) – the time the inline activator waits before it’s starting to work.
  • forceSafeActivation (boolean, default false) – If set to true scripts are activated independently of the given consent. If set to false the inline activator activates the scripts only if consent has been given (as memorized in the preference cookie of the domain of the host page).

The inline activator is available at:

IAB Transparency and Consent Framework

If you’ve enabled IAB Transparency and Consent Framework (TCF) compatibility for the customization of advertising tracking preferences, you can use the inline activator both for safe.js and safe-tcf-v2.js

safe-tcf-v2.js is available at:

Examples

The content of safe.js(and safe-tcf-v2.js) has to be included in-page after the initial configurations and before the code that loads iubenda_cs.js.

CURRENT
<script type="text/javascript">
    var _iub = _iub || [];
    _iub.csConfiguration = {
        "lang": "en",
        "siteId": XXXXXX, //use your siteId
        "cookiePolicyId": YYYYYY, //use your cookiePolicyId
        "banner": {
            "position": "float-top-center",
            "acceptButtonDisplay": true,
            "customizeButtonDisplay": true
        }
    };
    _iub.csConfiguration.safeTimeout = 500; //custom option
    _iub.csConfiguration.forceSafeActivation = false; //custom option
</script>

<!-- inline activator - safe.js (current channel) -->
<script type="text/javascript">
    //<![CDATA[
    //copy content from cdn.iubenda.com/cs/safe.js and paste here
    //]]>
</script>

<script type="text/javascript" src="//cdn.iubenda.com/cs/iubenda_cs.js" charset="UTF-8" async></script>

Sample configuration with IAB TCF v2.0 enabled:

<script type="text/javascript">
    var _iub = _iub || [];
    _iub.csConfiguration = {
        "lang": "en",
        "enableCMP": true,
        "siteId": XXXXXX, //use your siteId
        "cookiePolicyId": YYYYYY, //use your cookiePolicyId
        "banner": {
            "position": "float-top-center",
            "acceptButtonDisplay": true,
            "customizeButtonDisplay": true
        }
    };
</script>

<script type="text/javascript" src="//cdn.iubenda.com/cs/tcf/stub-v2.js"></script>

<!-- inline activator - safe.js (current channel) -->
<script type="text/javascript">
    //<![CDATA[
    //copy content from cdn.iubenda.com/cs/safe.js and paste here
    //]]>
</script>

<!-- inline activator - safe-tcf-v2.js (current channel) -->
<script type="text/javascript">
    //<![CDATA[
    //copy content from cdn.iubenda.com/cs/tcf/safe-tcf-v2.js and paste here
    //]]>
</script>

<script type="text/javascript" src="//cdn.iubenda.com/cs/iubenda_cs.js" charset="UTF-8" async></script>
BETA
<script type="text/javascript">
    var _iub = _iub || [];
    _iub.csConfiguration = {
        "lang": "en",
        "siteId": XXXXXX, //use your siteId
        "cookiePolicyId": YYYYYY, //use your cookiePolicyId
        "banner": {
            "position": "float-top-center",
            "acceptButtonDisplay": true,
            "customizeButtonDisplay": true
        }
    };
    _iub.csConfiguration.safeTimeout = 500; //custom option
    _iub.csConfiguration.forceSafeActivation = false; //custom option
</script>

<!-- inline activator - safe.js (beta channel) -->
<script type="text/javascript">
    //<![CDATA[
    //copy content from cdn.iubenda.com/cs/beta/safe.js and paste here
    //]]>
</script>

<script type="text/javascript" src="//cdn.iubenda.com/cs/beta/iubenda_cs.js" charset="UTF-8" async></script>

Sample configuration with IAB TCF v2.0 enabled:

<script type="text/javascript">
    var _iub = _iub || [];
    _iub.csConfiguration = {
        "lang": "en",
        "enableCMP": true,
        "siteId": XXXXXX, //use your siteId
        "cookiePolicyId": YYYYYY, //use your cookiePolicyId
        "banner": {
            "position": "float-top-center",
            "acceptButtonDisplay": true,
            "customizeButtonDisplay": true
        }
    };
</script>

<script type="text/javascript" src="//cdn.iubenda.com/cs/tcf/beta/stub-v2.js"></script>

<!-- inline activator - safe.js (beta channel) -->
<script type="text/javascript">
    //<![CDATA[
    //copy content from cdn.iubenda.com/cs/beta/safe.js and paste here
    //]]>
</script>

<!-- inline activator - safe-tcf-v2.js (beta channel) -->
<script type="text/javascript">
    //<![CDATA[
    //copy content from cdn.iubenda.com/cs/tcf/beta/safe-tcf-v2.js and paste here
    //]]>
</script>

<script type="text/javascript" src="//cdn.iubenda.com/cs/beta/iubenda_cs.js" charset="UTF-8" async></script>
STABLE
<script type="text/javascript">
    var _iub = _iub || [];
    _iub.csConfiguration = {
        "lang": "en",
        "siteId": XXXXXX, //use your siteId
        "cookiePolicyId": YYYYYY, //use your cookiePolicyId
        "banner": {
            "position": "float-top-center",
            "acceptButtonDisplay": true,
            "customizeButtonDisplay": true
        }
    };
    _iub.csConfiguration.safeTimeout = 500; //custom option
    _iub.csConfiguration.forceSafeActivation = false; //custom option
</script>

<!-- inline activator - safe.js (stable channel) -->
<script type="text/javascript">
    //<![CDATA[
    //copy content from cdn.iubenda.com/cs/stable/safe.js and paste here
    //]]>
</script>

<script type="text/javascript" src="//cdn.iubenda.com/cs/stable/iubenda_cs.js" charset="UTF-8" async></script>

Sample configuration with IAB TCF v2.0 enabled:

<script type="text/javascript">
    var _iub = _iub || [];
    _iub.csConfiguration = {
        "lang": "en",
        "enableCMP": true,
        "siteId": XXXXXX, //use your siteId
        "cookiePolicyId": YYYYYY, //use your cookiePolicyId
        "banner": {
            "position": "float-top-center",
            "acceptButtonDisplay": true,
            "customizeButtonDisplay": true
        }
    };
</script>

<script type="text/javascript" src="//cdn.iubenda.com/cs/tcf/stable/stub-v2.js"></script>

<!-- inline activator - safe.js (stable channel) -->
<script type="text/javascript">
    //<![CDATA[
    //copy content from cdn.iubenda.com/cs/stable/safe.js and paste here
    //]]>
</script>

<!-- inline activator - safe-tcf-v2.js (stable channel) -->
<script type="text/javascript">
    //<![CDATA[
    //copy content from cdn.iubenda.com/cs/tcf/stable/safe-tcf-v2.js and paste here
    //]]>
</script>

<script type="text/javascript" src="//cdn.iubenda.com/cs/stable/iubenda_cs.js" charset="UTF-8" async></script>

The activator code is an integral part of the iubenda Cookie Solution and as such can be modified to include new features, upgrades and fixes.

To facilitate the management of the activator version in your page, the _iub.csSafeActivatorVersionvariable is available, which recalls the iubenda_cs.js version from which the activator was extracted.

5.6 API

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

openPreferences() – Allows users to update their cookie preferences even after closing the cookie banner (similarly to when they click on an element with the iubenda-cs-preferences-link class).

showTcfVendors() – Reopens the TCF vendor list (similarly to when users click on an element with the iubenda-vendor-list-link class).

consentGiven() – Provides consent. The method accepts the following as optional parameters:

  • eventName (string) – One of the following: documentClicked (default), documentScrolleddocumentMovedbannerXclose, cookiePolicyClosed. Indicates the type of action by which consent is provided.
  • force (boolean)true | false (default) – If false , iubenda CS ensures that the banner is shown before actually accepting the consent; instead, by providing this option to true, consent is received in any case. Note: the call to this method assumes the consent provided is completely equivalent to when it is provided via UI, eg 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 onConsentReadcallbacks. To activate only the snippets there’s the activateSnippets() method.

activateSnippets() – Activate the previously blocked snippets. 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 (eg lazy loading or infinite scrolling).

The option runOnActivationDoneCallback (boolean, default false), if true, will execute the onActivationDonecallback 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.

Note: you cannot use this function if you’ve set banner.rejectButtonDisplay: true or perPurposeConsent: true. Also, if you’ve enabled the Transparency and Consent Framework, you mandatorily need to add the synchronous activator (safe-tcf-v2.js).

setConsentOnScrollOnElement() (boolean) – The call to this method defines the element on which the scroll will be observed for the purpose of consent. 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 onBannerShowcallback (example) which occurs when the CS is initialized.

storeConsent() – Stores consent in cookies. If, for example, you want to migrate consents from a previous provider, you could call this method inside the onBeforePreload callback when consent is already given by another platform. Also, if you’re a vendor, you can take advantage of storeConsent() to test our solution (see this demo on CodePen).

gdprApplies() (boolean) – Returns true if the GDPR protections are applied to the current user, otherwise it returns false.

ccpaApplies() (boolean) – Returns true if the CCPA protections are applied to the current user, otherwise it returns false .

askCcpaOptOut() – Pops up the dialog to request confirmation for the opt-out from sale.

isCcpaAcknowledged() – Returns whether the CCPA notice has been acknowledged.

isCcpaOptedOut() – Returns whether the user has opted out from sale.

Notes: you can invoke Cookie Solution API methods also from an iframe.

See also