Publishing and Implementing Cookie Consent Scripts
UUID-7478d3b4-18eb-3ac0-a6fd-fb7ebff9f8dc
Article Content
Once the design of the template is completed and the geolocation rule group is applied to a domain, the domain scripts have to be published to reflect the changes on a website. Every website scanned in the Cookie Consent tool will generate two sets of scripts: testing and production CDNs. The testing and production script tags are the snippets of code that you use to implement the Banner and Preference Center you have configured in Cookie Consent on your website. Once the script tag is implemented on your site and republished in the application, any changes to your associated template, geolocation rules, or categorizations will be pushed to your site automatically.
Note
Whenever there is a change made to any domain in the Cookie Consent application, including adding or deleting cookies, modifying templates, or reconfiguring geolocation rules, the respective domain scripts must be re-published to view the changes on the website where the scripts are hosted.
When implementing cookie consent scripts, there are four different tabs available.
Instructions: This screen provides detailed instructions on implementing the Banner scripts (testing and production CDN), the Cookie Settings button script, and the Cookie List script.
Test Scripts: This screen provides the Testing CDN script. The testing CDN is not domain specific and can be placed on any site for testing purposes.
For example, the testing CDN for onetrust.com can work correctly on testonetrust.com as well as staging.onetrust.com.
Production Scripts: This screen provides Production CDN script, which should be used on the production website. The production CDN is domain-specific and should only be placed on the website the scripts are generated for.
For example, the production script for onetrust.com will not work correctly on testonetrust.com. It is only meant to be placed on pages, paths and subdomains of onetrust.com.
History: This screen shows the publication history for a test or production script including the following:
Published Version: The version of the script chosen when publishing the script.
Script Type: The script type (test or production) published.
Geolocation Rule: The geo-location rule assigned to the domain.
Auto Blocking: Indicates whether auto-blocking feature is enabled.
Re-consent Required: Indicates if the Re-consent Required setting is checked when publishing.
Published Date: The date and time of the script publication.
Published By: The name of the usr who published the script.
Testing and Production CDNs
The Testing CDN or Production CDN should be implemented as close to the top of the <head> section of your site HTML on all pages. The CDNs contain a unique identifier that is specific to the domain for which it was generated. This is in the data-domain-script. The Testing CDN data-domain-script with be appended with"-test".
The CDN script needs to be loaded on each page of your domain in order to ensure site visitors are immediately presented with a banner and preference center when visiting your site if they have not yet interacted with OneTrust. Once the user has consented or interacted with the Banner and/or Preference Center, the OneTrust cookie OptanonAlertBoxClosed will be dropped on the page to prevent the Banner from re-appearing on subsequent pages for the user. The Banner/Preference Center will then only reappear for the user once OptanonAlertBoxClosed expires or is deleted from the users browser for any reason. For more information, see OneTrust Cookies.
If you use a site builder or content management system (CMS) to manage your domains, you may be able to customize the deployment of script loading on each page in your site template or through a code injector feature.
Caution
The CDN script must be placed before any other script on your site in order to ensure the Banner is loaded before any other scripts load or set cookies. This allows the script tag to communicate the site visitor's consent preferences downstream
Tip
You can define language codes using underscores or hyphens.
Example: en-US or en_US.
The Testing CDN matches the Production CDN script except:
The testing CDN is not domain-specific, so it will work on a site regardless of whether the root domain that the script was generated for matches the root domain where you test. The production CDN is domain-specific, so it will only work on the domain the script was generated for as well as any subdomains and paths of that root domain.
When a OneTrust cookie (OptanonConsent, OptanonAlertBoxClosed) is written using a Production CDN, it is written to a specific domain, such as .example.com or www.staging-example.com, because the production CDN is domain specific.
For example, if you scan onetrust.com and www.onetrust.com, the OneTrust cookies for onetrust.com will function as expected on www.onetrust.com as it will be considered a subdomain of the root onetrust.com. But the OneTrust cookies for www.onetrust.com will not function as expected on onetrust.com.
When OneTrust cookies are written using the testing CDN, they are written to the domain the script is currently hosted on. For example, the testing CDN for onetrust.com will function as expected on stageonetrust.com, but the production CDN for onetrust.com would not function as expected on stageonetrust.com.
The Testing CDN script writes cookies to the domain it is currently on, allowing users to test without impacting a live domain. When testing using the testing CDN, the user consent preferences will not carry over from page to page as they would when you implement the production CDN on your live site.
The Production CDN script references an SDK hosted by OneTrust. If you want to host the SDK on your own servers, you can download the full SDK and host it locally. For more information, see Downloading and Deploying Scripts from Local Hosting.
Use Distinct Script Src URL
When the Use Distinct Script Src URL settng is disabled, any changes to otSDKStub.js (hot fixes/bug fixes) are automatically pushed to the script without the need for republishing.
Enable this toggle to use the version-controlled copy of the otSDKStub and to avoid any changes pushed automatically to the stub.
Note
This is recommended if you would like to create a hash/ integrity key for the CDN scripts.
After enabling Use Distinct Script Src URL the testing/production CDN will be updated to include the data domain script in the source (src) as part of the otSDKStub.js. Make sure to add this new script to the site when deploying OneTrust.
Viewing the Change Log and Choosing a Script Version
When publishing a script for the first time, the version selected by default is the latest script version available.
Important
The end-of-support date for the selected version will be displayed when selecting your script version. After the support end date, the script version is no longer available for publishing. Any changes to templates, categorizations, or geolocation rules require publishing a later script version.
Although OneTrust scripts will function properly after a version's support end date, any subsequent hot fixes or bug fixes will not be accessible.
To ensure compatibility with new features, OneTrust recommends publishing to the latest version of the script.
When publishing a script after a change in geolocation rules:
The first screen you will notice is the Change Log. This screen will show the Critical Changes in the script that are ready to be published. Review the changes before clicking the Confirm button.
When publishing a different version of the script than the current OneTrust version:
If an older version of the script is selected, the screen will display any features that are incompatible with the version of the script you are attempting to publish.You can still configure these features in the Admin tool, but the script will not be able to use those features if published to an older version.
When publishing a script to a version of OneTrust older than the latest version in your tenant (e.g., OneTrust is currently on 202301.2.0, but you want to publish your script to the 202301.1.0 version), you will not be able to use of any new features or bug fixes released in the most recent version of OneTrust.
Click the Copy Scripts button for the Testing CDN script.
Paste the copied script in the <head> section of your testing environment. The script must be placed before any other script in your <head> section.
Testing CDN Screen Reference
Field
Description
Publish Individual Languages.
Enable this setting to publish the script for a specific language or languages. If not enabled, all languages will be published. By default this setting is disabled.
Note
If language detection is not enabled for the script, you will have to publish the languages individually.
If the script has previously been published for all languages existing on templates, these languages will still exist when the script is loaded. Only the changes applied to the selected languages will be published.
Do you require users to re-consent?
Enabling this setting will require your website users to re-consent. This will expire the OptanonAlertBoxClosed cookie and add a value of AwaitingReconsent=true to the OptanonConsent cookie. The users previous value of consent will still be present upon the re-consent, so the cookie category values are not reset based on the default configuration. When the script files are loaded with the new configuration (not loaded from cache), the banner will be re-presented if configured as so for the geolocation rule.
Note
Please allow 24-48 hours for this change to reflect on your CMP.
Prevent Fetching Banner
If Prevent Fetch of Banner or Preference Center is turned on, when your page loads we will not load the HTML or CSS. These elements will only be called when the site visitor takes an explicit action to call them. This is used to help optimize site performance.
Prevent Fetching Preference Center
When enabled, the Preference Center template HTML and CSS will only be loaded when needed.
Google Analytics Tracking for the Banner and Preference Center
When the setting is enabled, Google Analytics events will be created and passed based on user interaction with the Banner or Preference Center. You can also choose for gaEvent tracking on the Banner to be associated with the acceptance of a category. The data-ignore-ga='true' attribute will override this configuration. Google Analytics integration is also required.
Select a cookie category to send events data specifically when user interacts with this category.
Note
Only applicable if the Google Analytics Tracking for the Banner and Preference Center setting is enabled.
Enable Automatic Blocking of Cookies
The setting will enable the OneTrust AutoBlocking feature. Cookies will automatically be blocked or allowed to drop based on the configured consent model in the geolocation rule. When the user provides consent or interacts with Banner or Preference Center, the respective cookies are blocked or allowed to drop accordingly. Review OneTrust Cookie Auto-Blocking™ if you want to enable this feature.
When auto-blocking is enabled, publishing changes will take longer than expected.
Enabling this feature adds an additional script to the CDN. If you have already implemented, make sure to include the additional script on your page. The script will be found in the same place in the CDN.
When publishing scripts with auto-blocking enabled for the first time, a warning message appears indicating that the script tag has been modified. Ensure to copy and paste the new scripts to your website.
Automatically Block Known Tracking Technologies
Note
Only applicable if the Enable Automatic Blocking of Cookies setting is enabled.
If enabled, cookies, pixels, and web beacons that are known to be used in targeting will automatically be blocked.
This feature will be enabled and set to Determine the language from site visitor's browser settings by default. This means that the user will be presented with the Banner and Preference Center in the language they have configured for their browser if the language is configured in your template.
Note
Please select all languages that are required to be displayed are available for the Banner or Preference Center in the Manage Languages section of your templates.
If you choose to change the setting to Determine the language from HTML page, the language will be controlled by the HTML declared language. The language code in the HTML must match the language code from the template.
For example, I have a German site where I want to show the Cookie banner to my users in German and I want to do this based on my HTML declared language. The language code for German in my OneTrust template is "de". I can see this under Manage Languages. My HTML declared language code would need to also be "de".
<html lang="de">
Selecting this configuration adds data-document-language="true" to the script. If you have already implemented your script and decide to change this configuration, you will need to make this addition to the script. This will be reflected in the CDN after configuring.
Note
When enabling/disabling any features in the review section that result in an update to the CDN script, a modal displays reminding you that the CDN script has been updated and that the new scripts should be added to your site.
Warning
By default, implementing the OneTrust scripts on a site will not block cookies when user consent is not provided, unless the auto-blocking setting is enabled. If auto-blocking is not enabled, it is mandatory to manually block the cookies based on origin of the script tag. For additional information on manual blocking, refer to Third-Party Integrations & Cookie Blocking.
Live Preview
Once the test scripts are published, the Live Preview modal appears. This feature allows you to preview the changes made after your initial production publish but before publishing new changes to your production site.
Note
For Live Preview to work, the production script must be deployed on the domain, and should have been published at least once before.
If you have made configuration changes and not yet published the test script, make sure to publish the test first before publishing production scripts.
Once the test scripts of published, you can review the Test Scripts tab for the Last Tested Date, Last Tested Published Version, Last Test Published Status.
Status
Description
Draft
Script is not published.
Note
Any updates to the template or geolocation rules will not be displayed on a website when the status is Draft.
Publishing
Script is in the process of publishing
Published
Script is now published with all changes made within the OneTrust tool and is ready to use.
To implement the Production CDN script
Important
Production scripts can only be published within 30 minutes of publishing test scripts. You must first publish the test script to publish your production script.
Use this script for your production website. Published changes for this script may take up to 24 hours to cache but display immediately due to auto-enabled cache busting.
Note
To prevent events from being sent to Google Analytics, add the the following attribute to the Cookie Banner script.
data-ignore-ga='true'
On the Cookie Consent menu, select Scripts. The Scripts screen appears.
Select the the domain where script will be implemented.
Click the Publish Production button. The Publish pane appears.
Select the version of the script to publish and review the incompatible features.
Note
The end of support date for the selected version will be displayed.
Click the Confirm button.
Customize your settings for the Production CDN script. If you would like to host your the script locally, you can click Download to download the script to run locally. See the Production CDN Screen Reference.
Navigate to the Production Scripts tab.
Paste the copied script in the <head> of your site. The script must be placed before any other script in your <head> section.
Click the Publish button to publish your settings.
Production CDN Screen Reference
Field
Description
Publish Individual Languages.
Enable this setting to publish the script for a specific language or languages. If not enabled, all languages will be published. By default this setting is disabled.
Note
If language detection is not enabled for the script, you will have to publish the languages individually.
If the script has previously been published for all languages existing on templates, these languages will still exist when the script is loaded. Only the changes applied to the selected languages will be published.
Do you require users to re-consent?
Enabling this setting will require your website users to re-consent. This will expire the OptanonAlertBoxClosed cookie and add a value of AwaitingReconsent=true to the OptanonConsent cookie. The users previous value of consent will still be present upon the re-consent, so the cookie category values are not reset based on the default configuration. When the script files are loaded with the new configuration (not loaded from cache), the banner will be re-presented if configured as so for the geolocation rule.
Note
Please allow 24-48 hours for this change to reflect on your CMP.
Prevent Fetching Banner
If Prevent Fetch of Banner or Preference Center is turned on, when your page loads we will not load the HTML or CSS. These elements will only be called when the site visitor takes an explicit action to call them. This is used to help optimize site performance.
Prevent Fetching Preference Center
When enabled, the Preference Center template HTML and CSS will only be loaded when needed.
Google Analytics Tracking for the Banner and Preference Center
When the setting is enabled, Google Analytics events will be created and passed based on user interaction with the Banner or Preference Center. You can also choose for gaEvent tracking on the Banner to be associated with the acceptance of a category. The data-ignore-ga='true' attribute will override this configuration. Google Analytics integration is also required.
Select a cookie category to send events data specifically when user interacts with this category.
Note
Only applicable if the Google Analytics Tracking for the Banner and Preference Center setting is enabled.
Enable Automatic Blocking of Cookies
The setting will enable the OneTrust AutoBlocking feature. Cookies will automatically be blocked or allowed to drop based on the configured consent model in the geolocation rule. When the user provides consent or interacts with Banner or Preference Center, the respective cookies are blocked or allowed to drop accordingly. Review OneTrust Cookie Auto-Blocking™ if you want to enable this feature.
When auto-blocking is enabled, publishing changes will take longer than expected.
Enabling this feature adds an additional script to the CDN. If you have already implemented, make sure to include the additional script on your page. The script will be found in the same place in the CDN.
When publishing scripts with auto-blocking enabled for the first time, a warning message appears indicating that the script tag has been modified. Ensure to copy and paste the new scripts to your website.
Automatically Block Known Tracking Technologies
Note
Only applicable if the Enable Automatic Blocking of Cookies setting is enabled.
If enabled, cookies, pixels, and web beacons that are known to be used in targeting will automatically be blocked.
This feature will be enabled and set to Determine the language from site visitor's browser settings by default. This means that the user will be presented with the Banner and Preference Center in the language they have configured for their browser if the language is configured in your template.
Note
Please select all languages that are required to be displayed are available for the Banner or Preference Center in the Manage Languages section of your templates.
If you choose to change the setting to Determine the language from HTML page, the language will be controlled by the HTML declared language. The language code in the HTML must match the language code from the template.
For example, I have a German site where I want to show the Cookie banner to my users in German and I want to do this based on my HTML declared language. The language code for German in my OneTrust template is "de". I can see this under Manage Languages. My HTML declared language code would need to also be "de".
<html lang="de">
Selecting this configuration adds data-document-language="true" to the script. If you have already implemented your script and decide to change this configuration, you will need to make this addition to the script. This will be reflected in the CDN after configuring.
Note
When enabling/disabling any features in the review section that result in an update to the CDN script, a popup notice will be displayed reminding you that the CDN script has been updated and that the new scripts should be added to your site.
Publication Status of Production Scripts
Once the test scripts of published, you can review the Test Scripts tab for the Last Tested Date, Last Tested Published Version, Last Test Published Status.
Status
Description
Draft
Script is not published.
Note
Any updates to the template or geolocation rules will not be displayed on a website when the status is Draft.
Publishing
Script is in the process of publishing
Published
Script is now published with all changes made within the OneTrust tool and is ready to use.
Cookie Settings Button
This is the second set of scripts available on the Scripts screen. The Cookie Settings Button is a way for you to allow your website users to re-surface the Preference Center and change their consent. The Testing CDN/Production CDN script must also be included on the page for this script to function as expected. Though this script is available for both testing and production, it is identical for both and for all domains. It relies on the Banner CDN script to determine what to display.
The button text can be configured in your Banner template. For more information, see the Show Other Text section of Customizing the Banner Template.
On the Cookie Consent menu, select Scripts. The Scripts screen appears.
Click on the name of the domain you want to implement. The Scripts Details screen appears.
Navigate to the Production Scripts or Testing Scripts tab
Click the Copy Script button for the Cookie Settings Button script.
Paste the copied script in the code for your site. The Cookie Settings Button references the script that is placed in the <head> of the site.
Cookie List
This is the third set of scripts available on the Scripts screen and is an optional script. This snippet will insert a detailed Cookie List that includes a list of cookies based on the current cookie categorization within the OneTrust tool and their descriptions. You can embed the script in a privacy policy or a standalone cookie list page. The Testing CDN/Production CDN script must also be included on the page. Though this script is available for both testing and production it is identical for both and for all domains. It relies on the banner CDN script to determine what to display.
On the Cookie Consent menu, select Scripts. The Scripts screen appears.
Click on the name of the domain you want to implement. The Scripts Details screen appears.
Navigate to the Production Scripts or Testing Scripts tab.
Click the Copy Script button for the Cookie List script.
Paste the copied script in the code for the page where you want to display the list. The Cookie List references the script that is placed in the <head> of the site.
Embedded Web Form Script Integration
Note
This setting is only available to users leveraging both Cookie Consent and Consent & Preference Management Products.
This setting is enabled by default when a OneTrust Embedded Web Form from the Consent & Preference Management module is added to a registered cookie domain. When enabled, the OneTrust CMP script will be used to automatically deploy the embedded web form scripts. If disabled, all embedded web forms will be removed from this domain.
I am unable to publish the test scripts and notice an error that says ‘Sorry, there was an error while publishing script tags’. What should I do?
Re-publish the scripts. If the error persists, generate a HAR file for additional troubleshooting. If you have an active implementation, reach out to your consultant; if not contact OneTrust Support after generating a HAR file.
When does the OneTrust script change and what are the changes?
The OneTrust Testing/Production CDN remains the same in all scenarios except:
When the auto-blocking settng is enabled/disabled.
When auto-blocking is enabled, the source (src) of the script tag is modified to add OtAutoBlock.js. Make sure to copy and paste the new scripts on your website.
Similarly, when auto-blocking is disabled, source (src) OtAutoBlock.js is removed from the script. Ensure you update the correct scripts on the website.
When ‘Enable language detection of scripts’ is updated from corresponding to the visitor’s browser settings to corresponding to the language from the HTML page and vice-versa
If Determine the language from HTML page is chosen, a new attribute, data-document-language="true" is added to the script tag. Make sure to copy and paste the new scripts on the website when enabling this option
Similarly, when the language determination is chosen from Visitor’s browser settings, the attribute data-document-language is removed. Be sure to update to the correct scripts on your website.
3.
Why does the status of a template and its geolocation rule group remain in Draft even after publishing test scripts?
The status of a template and geolocation rule group changes from Draft to Active when production scripts are published.
4.
What is preventing the production scripts from publishing?
When there is an update to a template or geolocation rule, the best practice is to test the changes on a staging site before publishing production scripts. You must publish the test scripts before publishing the production scripts.
When the geolocation rule group is updated, a warning modal indicates the changes, which allows you to publish test scripts and perform testing before publishing the production scripts.
When the template is updated, a warning modal indicates that there are configuration changes made since the last production script publish. It is required to publish test scripts and perform testing before publishing the production scripts.
5.
Can I test the consent carrying forward from root domain to sub-domain using test scripts?
The testing CDN is meant for testing purposes, and it is not domain-specific to the website scanned within the OneTrust tool. The testing CDN writes OneTrust cookies to the domain it is currently on, allowing it to behave like a Production CDN script in a testing environment. While using the testing CDN, it is not possible to test consent carrying forward from root domain to sub-domain and vice-versa.
6.
When should we publish the testing CDN or production CDN?
When there is any change within OneTrust tool across categorizations, templates, geolocation rule groups, etc. you are required to publish the testing CDN or production CDN to view the changes on test or production site, respectively.
Without publishing the scripts, the changes will not reflect on test or production website.
7.
Can we publish multiple domains at once?
Yes, you can bulk publish domain scripts. This functionality is currently available for preview. To enable this feature, contact OneTrust support.
