This documentation provides detailed instructions on how to use Termly.getConsentState() to retrieve consent state at any time after initialization, and how to use the Termly Event API to be notified when the CMP is initialized and/or when the user sets or changes his consent settings.
Termly.getConsentState()
The getConsentState() method allows you to retrieve the current consent status at any time. This method is part of the window.Termly object and can be used to check the consent state immediately after Termly has loaded.
Usage
Example
document.addEventListener('DOMContentLoaded', (event) => {
if (window.Termly && typeof window.Termly.getConsentState === 'function') {
const consentState = window.Termly.getConsentState();
// Use consentState as needed
console.log(consentState);
}
});
Parameters
Termly.getConsentState() does not require any parameters.
Example return object
{
"unclassified": true,
"essential": true,
"performance": true,
"analytics": true,
"advertising": false,
"social_networking": true
}
Termly Event API
Note: The Termly Event API replaces and extends the previous getUpdatedWhitelistByTermly() callback.
The optional Termly Event API makes it easy for you to be notified in real time when the CMP is initialized and also when the end user sets or changes his consent settings. Using the Termly Event API is a simple, two-step process:
Add an
onload="onTermlyLoaded()"attribute to your Termly CMP embed script.Define an
onTermlyLoaded()function that sets up the event handlers you need.
Example
<script>
function onTermlyLoaded() {
Termly.on('initialized', (data) => {
// put your code here
})
Termly.on('consent', (data) => {
// put your code here
})
}
</script>
<script
type="text/javascript"
src="https://app.termly.io/resource-blocker/1234-5678-9999-9999-999999?autoBlock=on"
onload="onTermlyLoaded()"
></script>
onTermlyLoaded()
The onTermlyLoaded callback is invoked as soon as the CMP code is fully loaded. Any code you add inside this function is guaranteed to have access to the window.Termly object, so you don't have to worry about checking for its existence. While you can add whatever logic you want in this callback, the primary use is to set up event listeners that will be invoked in real time when:
The CMP has finished initializing, or
The user's Consent preferences are set or changed
Termly.on('initialized', (data) => { ...})
This callback will be invoked when initialization of the CMP is complete. It will be called with an Object containing the following data:
consents_count: The Number of consents obtained.consents_quota: the Number of consents. If no quota exists for your plan, this will be Infinity.has_cookie_report: A Boolean indicating if there is a cookie report available.is_over_consent_quota: A Boolean indicating if the consent quota has been exceeded.location: An Object containing geographical details of the requesting client:continent: a String (e.g., "NA")country: a String (e.g., "US")state: a String (e.g., "Washington")
region_settings: An Object containing the configuration used to tailor the behavior of the CMP in the current user's region (these settings can be adjusted in the Termly Dashboard under "Consent Management :: Consent Banner"theme: An Object containing theme settings for the consent prompt:website_last_modified_at: an ISO8601 timestamp indicating when the website was last modified in the Termly dashboard.
Termly.on('consent', (data) => {...})
Whenever a change in consent is detected, this callback function will be invoked with an Object containing the following data:
categories: An Array of consent categories.cookies: An Array of objects representing whitelisted cookies. Each object contains:name: The name of the cookie.provider: The provider of the cookie.type: The type of the cookie (e.g., html_session_storage, server_cookie).
uuid: The visitor's unique identifier.
Example data argument
{
"categories": [
"unclassified",
"essential",
"performance",
"analytics",
"social_networking"
],
"cookies": [
{
"name": "_ctk",
"provider": "example.io",
"type": "html_session_storage"
},
{
"name": "_csid",
"provider": ".form.com",
"type": "server_cookie"
}
],
"uuid": "447c594e-de23-4g9c-ac24-22f5b7e2b024"
}