invalidateConsentWithoutLog parameterPlease note that starting from 15-01-2023, the value of invalidateConsentWithoutLog has changed and is now set to true. This means that, if you have enabled the Cookie and Consent Preference Log, by default a new consent is requested each time a user’s consent is not found recorded in the logs.
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 Privacy Controls and Cookie Solution introduction guide.
Quick recap:
Once you’ve generated your cookie banner/consent banner (Privacy Controls and Cookie Solution > Activate/Edit), you’ll get a similar code snippet:
<script type="text/javascript">
var _iub = _iub || [];
_iub.csConfiguration = {
"siteId": XXXXXX, // your siteId,
"cookiePolicyId": YYYYYY, // your cookiePolicyId,
"lang": "en"
};
</script>
<script type="text/javascript" src="https://cs.iubenda.com/autoblocking/3095420.js"></script>
<script type="text/javascript" src="///cdn.iubenda.com/cs/iubenda_cs.js" charset="UTF-8" async></script>
<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>Please note that the remote configuration feature simplifies the implementation process. Most changes made in the Privacy Controls and Cookie Solution configurator will apply directly to your website without needing to re-embed the code. This makes it easier to keep your site up-to-date.
However, certain changes, such as using a custom CSS, the TCF tile, and US laws support, will still require you to re-embed the code. In any case, when you save your configuration, you will be notified whether the changes will apply directly or if re-embedding the code is necessary.
To display the cookie banner/consent banner on your site, copy and paste the snippet above (remember to generate your own code on Privacy Controls and 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/consent banner, you must also block cookies prior to consent:
Many Data Protection Authorities across the EU have strengthened their requirements and aligned their rules on cookies and trackers with the requirements of the GDPR, in particular it’s required that you record and store proofs of your users’ preferences.
Click here for more info on how to activate Cookie and Consent Preference Log within your Privacy Controls and Cookie Solution.
Note: all of the following parameters need to be included within _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/consent 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.
countryDetection (boolean, default false) -Allows you to automatically detect the user country.
For the GDPR
To 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.
If you disable this option, remember to set gdprApplies:false on all page views where the consent is not being requested.
For the US State Laws
To satisfy the US requirements only to users from the US while running cookies scripts normally in regions where you are still legally allowed to do so, set this parameter to true if usprApplies is set to false.
If you disable this option, you can set usprApplies:false on all page views where the US requirements are not relevant.
For the CCPA
To activate CCPA protections only for users to whom the CCPA applies, set this parameter to true if ccpaApplies is set to false.
For the LGPD
To satisfy the LGPD requirements only to users from Brazil while running cookies scripts normally in regions where you are still legally allowed to do so set this parameter to true if lgpdAppliesGlobally is set to false.
If you disable this option, you can set lgpdApplies:false on all page views where the LGPD requirements are not relevant.
enableGdpr (boolean, default true) – If true, you’ll enable/make available the GDPR functionality in the Privacy Controls and 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/consent banner. If you’ve set countryDetection:false, you should set gdprApplies:false on all page views where the consent is not being requested.
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.
closeButtonRejects (boolean, default false) – If set to true, when the banner’s close button is clicked, user’s consent is considered as denied.
explicitWithdrawal (boolean, default false) – If set to true, the sentence: “You can freely give, deny, or withdraw your consent at any time” will be added to the banner copy.
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 Privacy Controls and Cookie Solution. However, the categories displayed can also be customized by using the purposes parameter below.
Examples:
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 (Necessary, Functionality, Experience, Measurement, Marketing), 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). Purposes included:2). Purposes included:
3). Purposes included:
4). Purposes included:
5). Purposes included:
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/consent banner (to be effective, perPurposeConsent must be set to true). This option must be contained within the banner {} object.
banner.showPurposesToggles (true/false, default false) – Setting this parameter to true, gives users granular control in the first layer of the cookie banner over which categories of cookies they consent to. The categories (Necessary, Functionality, Experience, Measurement, Marketing) are displayed along with a toggle so that users can quickly either grant or reject consent for the particular processing purpose.
Consider that the categories displayed in the toggles are automatically detected and passed from your iubenda Cookie Policy to the Privacy Controls and Cookie Solution or, if you’ve customized them, from the categories listed in the purposes parameter.
We’ve added a new compliance setting: US State Laws, to help you meet the requirements of the following US state privacy laws: CCPA/CPRA and VCDPA. It offers broader support to the new US legislation and replaces the CCPA option.
enableUspr (boolean, default false) – If true, you’ll enable/make available the US functionality in the Privacy Controls and Cookie Solution (without actually applying it).
usprApplies (undefined/boolean, default undefined) – If enableUspr is true, countrydetection is true, upsrApplies is undefined, the US regulations are applied to US users only. If set to true US legislation is always applied.
usprPurposes (string, default undefined) comma separated Ids: e.g. usprPurposes:s,sh,sd5
this is the list of purposes handled by the CS:
s → selling of personal info (same as CCPA s)sh → sharing of personal infoadv → targeted advertisingSensitive data:
sd5 → Sensitive Data, Citizenship or Immigration Statussd8 → Sensitive Data, Precise Geolocation Datasd9 → Sensitive Data, Consumer’s Social Security, Driver’s License, State Identification Card, or Passport NumbershowBannerForUS (true/false, default false) if set to true a banner will be served to the users. If there’s a sensitive data in usprPurposes, showBannerForUSis forced to true.
privacyPolicyNoticeAtCollectionUrl (string, default undefined) the URL to the notice at collection, section of the privacy policy.
iubenda-cs-uspr-link – Add this class to any element of the page to allow users to open the notice at collection.
iubenda-cs-preferences-link – Add this class to any element of the page to allow users to update their preferences and open the 2nd layer.
enableCcpa (boolean, default false) – If true, you’ll enable/make available the CCPA functionality in the Privacy Controls and 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).
ccpaAcknowledgeOnLoad (boolean, default false) – If set to true and ccpaAcknowledgeOnDisplay: false, the notice is intended acknowledged at the page loading.
ccpaLspa (boolean, default undefined) – Allows you to specify whether the transaction should be performed under the Limited Service Provider Agreement (LSPA) by IAB.
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).
enableLgpd (boolean, default false) – If true, you’ll enable/make available the LGPD functionality in the Privacy Controls and Cookie Solution (without actually applying it).
lgpdAppliesGlobally (boolean, default true) – If true, you’ll apply LGPD protections to all users. Set this parameter to false and countryDetection:true to request LGPD consent to Brazilian users only.
lgpdApplies (boolean, default undefined) – If false, you won’t apply LGPD protections to the current user and he will not be shown the cookie banner/consent banner. This behavior applies regardless of the value of lgpdAppliesGlobally (whether it is true or lgpdAppliesGlobally is false with countryDetection : true )
Please note that all the parameters available for the GDPR can also be used for LGPD configuration.
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 Privacy Controls and Cookie Solution.
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:
With TCF v2.0 you can:
Here’s how to do it. Thanks to tcfPurposes, in the following example we’ll:
consent_not_needed, possible only if our legislation does not require consent for this purpose) *,false),li_only) for purpose number 4 (“Select personalised ads”), andconsent_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 Privacy Controls and 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/consent 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.
tcfPublisherCC (string, default null) – Two-letter country code expressed in ISO 3166-1 standard that determines the country legislation of reference . Normally corresponds to the country code of the country in which the publisher’s business entity is established. You can use this parameter to set the publisher’s country code in the TCF preference string when the TCF purpose “1” is set to “consent_not_needed“
acceptTcfSpecialFeaturesWithAcceptBtn (string, default true) – If false and the user clicks the Accept button, the TCF Special Features are not enabled and saved in the TCF consent string.
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/consent 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.
position (string, default “float-top-center”) – It defines the position of the cookie banner/consent 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/consent banner is shown.
logo (string) – URL (https recommended) or base64 equivalent of an image to be used as a logo for the header of the cookie banner/consent 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/consent banner.
brandBackgroundColor (string, default “#fff”) – Background color of the header of the cookie banner/consent banner.
backgroundColor (string, default “#000”) – The background color of the banner.
textColor (string, default “#fff”) – The color of the banner’s text.
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.
continueWithoutAcceptingButtonColor (string, default “#fff”) – Background color of the “Continue without accepting” button.
continueWithoutAcceptingButtonCaptionColor (string, default “#000”) – Text color of the “Continue without accepting” 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 recommended starting point for custom styling is to use our CSS as a base. This allows for the reapplication of styles excluded by the applyStyles option, with the benefit of being modifiable when implemented on your pages. For an illustration of a banner with custom CSS, refer to our example: “Banner with Custom CSS“.
Our system now automatically updates and serves custom styles via a CDN, optimizing the distribution and loading times of your custom styles.
Here are the endpoints for the custom CSS:
https://cdn.iubenda.com/cs/custom_banner_style.csshttps://cdn.iubenda.com/cs/beta/custom_banner_style.csshttps://cdn.iubenda.com/cs/stable/custom_banner_style.csshttps://cdn.iubenda.com/cookie_solution/iubenda_cs/1.50.0/custom_banner_style.csszIndex (number) – This is the zIndex of the banner’s div. The default value is 99999998.
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.
content (string) – This is the textual content inside the cookie banner/consent banner. For example, for the English version the default value is:
Notice
We and selected third parties use cookies or similar technologies for technical purposes and, with your consent, for other purposes as specified in the %{cookie_policy_link}.
Please note that banner.content can be used only to customize the text of the notice, and it allows you to specify special formatting to the text with HTML tags, but if you want to modify the structure of the notice (e.g., adding buttons or special layouts), then you should use banner.html.
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 Privacy Controls and 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 sellingHere’s an example of a cookie banner/consent 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).lang).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.
closeButtonCaption (string, default “x”) – The text of the banner’s close button (formerly innerHtmlCloseBtn).
continueWithoutAcceptingButtonCaption (string, default “false”) – The text of the Continue without accepting button.
useThirdParties (boolean, default true) – If set to false, any mention of third parties and the use of related third-party cookies and trackers is excluded from the banner text.
showTotalNumberOfProviders (boolean, default false) – If set to true, the total number of providers specified in totalNumberOfProviders will be displayed,
totalNumberOfProviders (number, default undefined) when undefined and showTotalNumberOfProviders is true, it will show in the banner text the number of third parties involved in data processing added in the Privacy and Cookie Policy Generator. If set manually, it will show in the banner text the value specified.
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 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 Privacy Controls and 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/consent banner with custom HTML and content.
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”.
i18n {} (object) – You can translate/edit the texts of any Privacy Controls and Cookie Solution component via the i18n JavaScript library. To handle this, we have created a list of all components/strings that you can edit and/or localize, please see the following JSON files to find them:
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.
floatingPreferencesButtonZIndex (default 2147483647) – Add this option to apply a custom zIndex to the floating preference button. This could be useful if some overlapping issues occur.
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.
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.
invalidateConsentWithoutLog (boolean, string, date, default true). When true, new consent will be requested whenever a user’s consent has not been found recorded within the Cookie and Consent Preference Log.
If a date is set (format: “yyyy-mm-dd”) when consent collected prior to this date is not found within the Cookie and Consent Preference Log a new consent will be requested(e.g. invalidateConsentWithoutLog: "2022-01-10“)
googleConsentMode (boolean, string, default null). When null the CS automatically detects whether enabling Google Consent Mode (if a global window.dataLayer variable or a global gtag function is found).
If set to true the Privacy Controls and Cookie Solution always enables Google Consent Mode and defines a global window.dataLayer if not already defined.
If set to false the CS always disables Consent Mode.
Set this parameter to template if you are using the iubenda Google Tag Manager template and you want to embed the Privacy Controls and Cookie Solution code manually (as explained in this section).
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.
rebuildIframe (boolean, default true) – Once the user’s consent has been recorded, the default behavior of the Privacy Controls and 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.
callback {} (object) – This is the parameter through which you can define the callback that iubenda Privacy Controls and 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 Privacy Controls and 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 the first time that the user gives their consent and each time the user updates their preferences (for example by clicking on iubenda-cs-preferences-link and saving their new preferences). 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, the first time the user gives their preference (not on every page view, as onConsentRejected) and each time the user updates their preferences (for example by clicking on iubenda-cs-preferences-link and saving their new preferences).
onPreferenceExpressed (function) – It is invoked whenever a preference is expressed, be it accept or reject.
onPreferenceFirstExpressed (function) – Invoked the first time the user gives their preference (not on every page view, as onPreferenceExpressediubenda-cs-preferences-link and saving their new preferences).
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, orgdprApplies:false, orgdprAppliesGlobally:false, countryDetection:true and the user is based outside the EUonPreferenceNotNeeded (function) – It is invoked whenever a preference is not needed, for example when:
gdprApplies:false, orgdprAppliesGlobally:false, countryDetection:true and the user is based outside the EUonConsentRead (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 Privacy Controls and 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 Privacy Controls and 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 Privacy Controls and 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 Privacy Controls and 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, and each time the user updates their preferences (for example by clicking on iubenda-ccpa-opt-out and saving their new preferences).
on2ndLayerShown (function) – Invoke when the second layer of the banner is shown.
onCookiePolicyShown (function) – Invoke when the cookie policy is shown (either in modal window or on a separate page).
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’).
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.
localConsentDomainExact (boolean, default null) – This allows you to specify the exact domain, in which you want to save the consent provided by the user.
Note: if both options (localConsentDomain and localConsentDomainExact) are configured, only the localConsentDomainExact option is considered.
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.
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 Privacy Controls and 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 Privacy Controls and 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 Privacy Controls and 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).
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).
Caution: Some national DPAs in Europe will NOT consider such a consent mechanism as allowed, therefore, you should carefully evaluate such an addition according to your applicable law.
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/consent banner.
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": true,
"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:
You may want to show a custom notice that replaces content that you can’t show until consent is given, or because consent has been rejected for that purpose and is therefore blocked by the Privacy Controls and Cookie Solution.
To do this, you can create a <div> element, with the custom notice you want to show in place of the unavailable content, and a priorly blocked script that removes the <div>, once the consent is granted.
<div id="content-before-consent">This will be removed as
soon as the user gives consent to purpose X</div>
// Where X is the purpose for which consent needs to be given to
run that script
<script type="text/plain" class="_iub_cs_activate" data-iub-purposes="X">
// Where X is the purpose for which consent needs to be given to
run that script
;(function() {
var divToRemove = document.getElementById('content-before-consent');
if (divToRemove && divToRemove.parentNode) {
divToRemove.parentNode.removeChild(divToRemove);
}
})();
</script>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 Privacy Controls and 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:
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:
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.
<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",
"enableTcf": 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><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",
"enableTcf": 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><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",
"enableTcf": 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 Privacy Controls and 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.csSafeActivatorVersion variable is available, which recalls the iubenda_cs.js version from which the activator was extracted.
The iubenda Privacy Controls and 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 Privacy Controls and 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/consent banner (similarly to when they click on an element with the iubenda-cs-preferences-link class).openPreferences({ acceptPurposes [purposes] }) Allows users to update their cookie preferences, opening the second layer of the banner with pre-selected purposes.
❗️Please note that the use of this parameter is available only to Ultimate plan users
getPreferences() – Retrieves the stored user’s cookie preferences at that moment in time. The return object varies based on applicable legislation and selected purposes. Additionally, it can return properties for CCPA (ccpa), TCF v2 (tcfv2), and Google Additional Consent Mode (gac). It is important to note that this method does not return the GPP (Global Privacy Platform) string.
{
"id": "xxxxx",
"purposes": {
"1": true,
"2": false,
"3": false,
"4": false,
"5": false
},
"ccpa": "1YN-",
"uspr": {
"s": true,
"sh": true,
"adv": true
}
}isPreferenceExpressed() – Returns the status of the preference expressed by the user.
true if a preference has been expressed
false if a preference has not been expressed
resetCookies() – Use this method to reset preference cookies.
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), documentScrolled, documentMoved, bannerXclose, 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 Privacy Controls and 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.
acceptAll() – Accepts everything (purposes or binary consent, all TCF entities, all Google Additional Consent vendors, activates scripts) as soon as it is invoked regardless of user’s preferences.
❗️Please note that the use of this parameter is available only to Ultimate plan users
rejectAll() – Rejects all cookies.
Notes: you can invoke Privacy Controls and Cookie Solution API methods also from an iframe.