API Methods
The Utiq API offers methods for on-demand access to various Utiq functionalities and data objects with a single call. The API is available as part of the Utiq loader script (utiqLoader.js
) and can be accessed via the window.Utiq.API
object. Specific methods are described below:
addEventListener
Register events to Utiq SDK, ensuring you can interact with it, regardless of which script gets loaded first, avoiding race conditioning issues.
Parameters:
eventName
eventHandler
Returns:
none
Example usage:
window.Utiq ||= {};
window.Utiq.queue ||= [];
// Store event handlers as variables
const eventHandler1 = ({ params } /*IF NEEDED*/) => {
// Callback action for eventName1
};
const eventHandler2 = ({ params } /*IF NEEDED*/) => {
// Callback action for eventName2
};
window.Utiq.queue.push(() => {
// Add event listeners
window.Utiq.API.addEventListener('eventName1', eventHandler1);
window.Utiq.API.addEventListener('eventName2', eventHandler2);
});
removeEventListener
Un-register events to Utiq SDK.
Parameters:
eventName
eventHandler
Returns:
none
Example usage:
window.Utiq.queue.push(() => {
// Remove event listener eventName2
window.Utiq.API.removeEventListener('eventName2', eventHandler2);
});
showConsentManager
Displays the Utiq Consent Manager overlay popup. This method operates with the default Utiq consent management setup. Find more details on the Utiq dedicated consent popup page.
Parameters:
none
Returns:
none
Example usage:
window.Utiq ||= {};
window.Utiq.queue ||= [];
window.Utiq.queue.push(() => {
window.Utiq.API.showConsentManager()
});
handleConsentChange
Method used for handling custom CMP consent change by managing the consent cookie and dispatching proper events handled by the Utiq service. It should be used when there’s a need to change the consent status.
Parameters:
isConsentGranted
: boolean - when consent is granted set totrue
. Otherwise, if consent is rejected set tofalse
.
Returns:
none
Example usage:
window.Utiq ||= {};
window.Utiq.queue ||= [];
window.Utiq.queue.push(() => {
window.Utiq.API.handleConsentChange(true)
});
revokeConsentWithPopup
Method used to revoke consent. The user sees a confirmation popup upon revocation completion. It should be used instead of the handleConsentChange
method when the user should see a confirmation of the consent revocation.
If we cannot verify if a user has previously given consent on the website (i.e. user visiting from new browser, no Utiq cookies set on this browser, or user cleared browser history), the user will see a respective notification message, with a suggesting to visit consenthub, to view and withdraw any Utiq consent.
Parameters:
none
Returns:
none
Example usage:
window.Utiq ||= {};
window.Utiq.queue ||= [];
window.Utiq.queue.push(() => {
window.Utiq.API.revokeConsentWithPopup()
});
handleDataClear
Method used to handle clear of all Utiq-related data from the browser cache and memory. Data clear is done automatically when window.Utiq.API.handleConsentChange(false)
is called, so this method does not have to be called manually within the Utiq flow.
Parameters:
none
Returns:
none
Example usage:
window.Utiq ||= {};
window.Utiq.queue ||= [];
window.Utiq.queue.push(() => {
window.Utiq.API.handleDataClear()
});
getUtiqConsentStatus
Method used to get current Utiq consent status.
Parameters:
none
Returns:
boolean:
true
/false
undefined
- only if the Utiq service has not yet been initialized
Example usage:
window.Utiq ||= {};
window.Utiq.queue ||= [];
window.Utiq.queue.push(() => {
const status = window.Utiq.API.getUtiqConsentStatus()
// Do something with the status
});
getIdGraphEntry
Method used to get current Utiq consent status.
Parameters:
entryName
: string - Name of the entry that should be extracted from the ID graph. Accepted values are:mtid
,atid
,attrid
,category
,ttl
,domain
category
will return ‘mobile’ or ‘fixed’, to differentiate if Utiq IDs are generated based the mobile connection, or the fixed (household) connection.
Returns:
string type value
value of a data entry
“Entry key (string) parameter is missing”
“No Utiq configuration set up”
“No required IDC data present. Cannot extract the ID graph entry”
“Could not find an entry for provided entry name: {entryKey}”
Example usage:
window.Utiq ||= {};
window.Utiq.queue ||= [];
window.Utiq.queue.push(() => {
const value = window.Utiq.API.getIdGraphEntry('entryName')
// Do something with the value
});
setLogLevel
This methods allows you to define desired logging level. The logging level, stored in utiq_logging_level
cookie, remains enabled until reset using the resetLoggingLevel
method, detailed below.
Parameters:
logLevel
: string - Level of desired logging. Accepted values are:silent
,error
(default),warn
,info
,verbose
(includingDEBUG
andTRACK
messages)
Returns:
none
This method logs
"[INFO] Logging level (<logLevel>) has been set"
message, that indicates the logging level has been set successfully.
Example usage:
window.Utiq ||= {};
window.Utiq.queue ||= [];
window.Utiq.queue.push(() => {
window.Utiq.API.setLogLevel('logLevel')
});
You can also use query ?utiq_log_level=<logLevel> to set desired log level.
Make sure you don’t forget logging enabled on production, as it creates utiq_logging_level
cookie to keep track of your choice.
resetLoggingLevel
This method reverts to default error
logging level and deletes utiq_logging_level
cookie.
Parameters:
none
Returns:
none
This method logs
"[INFO] Logging level has been reset to error level"
message, that indicates the logging level has been set back to the default successfully.
Example usage:
window.Utiq ||= {};
window.Utiq.queue ||= [];
window.Utiq.queue.push(() => {
window.Utiq.API.resetLoggingLevel()
});