Developer Documentation - Consent JavaScript API

Developer Documentation - Consent Manager JavaScript API#

About this documentation

The Consent Manager JavaScript API documentation details Osano’s publicly available features.

The Osano Consent Manager (CM) makes functions, properties and events available to developers so that you can easily implement additional functionality based on the visitor’s consent status (e.g., load scripts upon visitor consent being granted).

Important Notes

  • Utilizing this API to modify or disrupt Osano’s intended functionality is strongly discouraged. It may cause your site to not be compliant with privacy laws and regulations; while you have the ability to make such a change, it is not sanctioned by or approved by Osano and proceeding with the change will automatically terminate Section 4.7 of our Terms of Service which is our “No Fines Pledge”. It may also cause defective behavior in future revisions.
  • Osano.js must be the very first script in the document. Loading or injecting any other script prior to Osano may result in Osano being unable to ensure compliance with regional consent laws. See Installing Osano for more details.

Contents

API

The Osano CM API is available after initialization on the browser’s window object: window.Osano.cm.

Use of deprecated features is not recommended as they may be removed in a future revision.

Functions

Each of these functions are accessible via window.Osano.cm. For example, window.osano.cm.showDrawer().

function addEventListener(eventType /* string */, callback /* function */)

Adds an event listener. See the Events section for events, callback arguments and examples.

deprecated function emit(eventName)

Calling this function with a supported event will trigger an associated behavior in the Consent Manager. This function has been superseded by other functions and may be removed in a future revision.

Supported events:

  • osano-cm-dom-info-dialog-open: equivalent to window.Osano.cm.showDrawer()

function getConsent()

Returns the Consent object.

function hideDialog()

Hides the Dialog.

function hideDrawer()

Hides the Drawer.

function hideWidget()

Hides the Widget.

function off(eventType /* string */, callback /* function */)

Equivalent to window.Osano.cm.removeEventListener(eventType, callback).

function on(eventType /* string */, callback /* function */)

Equivalent to window.Osano.cm.addEventListener(eventType, callback).

function ready(readyApi /* string */, options /* object */)

This function allows the CM to integrate with third-party APIs. The customer is responsible for calling it with the correct parameters when the other API is ready.

Supported APIs

  1. Shopify

    Parameters:

    • readyApi: "shopify"
    • options: undefined

    Example:

    window.Shopify.loadFeatures([{
    name: 'consent-tracking-api',
    version: '0.1',
    }], function(error) {
    if (!error) {
    try {
    window.Osano.cm.ready('shopify');
    } catch (error) {
    console.error('Osano must be loaded before initializing the Shopify API.');
    }
    }
    });

function render()

Forces the DOM components of the Consent Manager to re-render.

function removeEventListener(eventType /* string */, callback /* function */)

Removes the callback from the list of listeners for the eventType. The callback argument must be the same object that was passed to addEventListener. See the Events and Using Events sections for more details.

function showDialog()

Shows the Dialog.

function showDrawer()

Shows the Drawer.

function showWidget()

Shows the Widget.

Properties

Each of these functions are accessible via window.Osano.cm. For example, window.osano.cm.analytics.

read-only analytics ⇒ boolean

Returns true if the ANALYTICS property of the Consent Object is ACCEPT. Returns false otherwise.

read-only drawerOpen ⇒ boolean

Returns true if the Drawer is visible or false if it is not.

read-only dialogOpen ⇒ boolean

Returns true if the Dialog is visible or false if it is not.

locale ⇒ string

Gets or sets the Consent Manager’s current locale in IETF language-tag format. Supports two-character primary language and optional two-character region sub-tag.

Setting to an available language will fetch the localization from Osano and update the CM’s visual components.

Setting this property to an unavailable or invalid language will throw an Error.

read-only marketing ⇒ boolean

Returns true if the MARKETING property of the Consent Object is ACCEPT. Returns false otherwise.

read-only mode ⇒ string

Returns a value corresponding to one of the Compliance modes:

  • debug ⇒ Discovery/Listener
  • permissive ⇒ Permissive
  • production ⇒ Strict

personalization ⇒ boolean

Returns true if the PERSONALIZATION property of the Consent Object is ACCEPT. Returns false otherwise.

read-only optOut ⇒ boolean

Returns true if the OPT-OUT property of the Consent Object is ACCEPT. Returns false otherwise.

deprecated | read-only storage ⇒ object

Returns an object wrapping the getConsent() function. This property has been superseded by the fuller API and may be removed in a future revision.

userData ⇒ string

Arbitrary data that you may set for a visitor that will be saved along with consent. Must be no greater than 128 characters.

⚠️ Caution: do not use this capability in a way that will take you out of compliance with privacy laws and regulations.

Events

osano-cm-analytics

This is a one-time event, meaning the callback will be called at most once. The event will dispatch when the ANALYTICS consent is given (the value becomes ACCEPT). If it is never given, the event will not be dispatched. A new listener added when consent has already been given (i.e. Osano.cm.getConsent()['ANALYTICS'] === 'ACCEPT') will be called immediately.

The callback does not receive any arguments.

Example:

Osano.cm.addEventListener('osano-cm-analytics', () => console.log('Consent granted for analytics.'));

osano-cm-cookie-blocked

This event will dispatch when a cookie is blocked from being set in the visitor’s browser.

The callback function receives a string that indicates the name of the cookie that was blocked.

Example:

Osano.cm.addEventListener('osano-cm-cookie-blocked', (cookie) => console.log('Cookie blocked:', cookie));
document.cookie = "marketing-cookie=John Doe; path=/";

// Assuming no consent for marketing and the "marketing-cookie" is classified as such, the console will output:
// Cookie blocked: marketing-cookie

osano-cm-consent-changed

This event will dispatch when the visitor toggles a consent category. It only indicates that the visitor has changed this option and does not reflect the consent being saved.

The callback function receives an object with a single key-value pair {"CATEGORY_NAME": "ALLOW_OR_DENY"} indicating the category the visitor toggled and its new value.

Example:

Osano.cm.addEventListener('osano-cm-consent-changed', (change) => console.log('Category toggled:', JSON.stringify(change)));

// When a visitor changes ANALYTICS from ACCEPT to DENY, the console will show:
// Category toggled: {"ANALYTICS":"DENY"}

osano-cm-consent-new

This event will dispatch immediately after osano-cm-consent-saved if the visitor is registering a new consent (i.e. they have never consented before or their consent was expired).

The callback function receives a full Consent Object representing the visitor’s consent.

osano-cm-consent-saved

This event will dispatch when the visitor saves their consent preferences.

The callback function receives a full Consent Object representing the visitor’s consent.

osano-cm-iframe-blocked

This event will dispatch when an iframe is blocked from being loaded in the visitor’s browser.

The callback function receives a string that indicates the src value of the iframe that was blocked.

Example:

Osano.cm.addEventListener('osano-cm-iframe-blocked', (src) => console.log('Iframe blocked:', src));

// Example console output:
// Iframe blocked: https://analytics-tracking-frames.example/

osano-cm-initialized

This event will dispatch when the CM is initialized. If the CM has already initialized when a listener is added for this event, the callback will be called immediately.

The callback function receives a Consent Object that indicates the current visitor’s provided consent or undefined when the visitor has not yet given consent.

osano-cm-locale-updated

This event will dispatch when the locale is updated even if the new locale is the same.

The callback function receives a string with the updated locale value.

Note: the callback will not be called if the locale is invalid or unavailable.

Example:

Osano.cm.addEventListener('osano-cm-locale-updated', (locale) => console.log('Locale updated:', locale));
Osano.cm.locale = 'en';

// Example console output:
// Locale updated: en

osano-cm-marketing

This is a one-time event, meaning the callback will be called at most once. The event is dispatched when the MARKETING consent is given (the value becomes ACCEPT). If it is never given, the event will not be dispatched.

The callback does not receive any arguments.

A new listener added when consent has already been given (i.e. Osano.cm.getConsent()['MARKETING'] === 'ACCEPT') will be called immediately.

Example:

Osano.cm.addEventListener('osano-cm-marketing', () => console.log('Consent granted for marketing.'));

osano-cm-opt-out

This is a one-time event, meaning the callback will be called at most once. The event is dispatched when the OPT_OUT value becomes ACCEPT (indicating that the visitor is opting out). If the value never becomes ACCEPT, the event will not be dispatched. See IAB CCPA Framework && Do Not Sell for more information on opting out.

The callback does not receive any arguments.

A new listener added when consent has already been given (i.e. Osano.cm.getConsent()['OPT_OUT'] === 'ACCEPT') will be called immediately.

Example:

Osano.cm.addEventListener('osano-cm-opt-out', () => console.log('Visitor has opted out.'));

osano-cm-personalization

This is a one-time event, meaning the callback will be called at most once. The event is dispatched when the PERSONALIZATION consent is given (the value becomes ACCEPT). If it is never given, the event will not be dispatched.

The callback does not receive any arguments.

A new listener added when consent has already been given (i.e. Osano.cm.getConsent()['PERSONALIZATION'] === 'ACCEPT') will be called immediately.

Example:

Osano.cm.addEventListener('osano-cm-personalization', () => console.log('Consent granted for personalization.'));

osano-cm-script-blocked

This event will dispatch when a script is blocked from being run in the visitor’s browser.

The callback function receives a string that indicates the src value of the script that was blocked.

Example:

Osano.cm.addEventListener('osano-cm-script-blocked', (src) => console.log('Script blocked:', src));

// Example console output:
// Script blocked: https://analytics-tracking-scripts.example/tracker.js

osano-cm-storage

This is a one-time event, meaning the callback will be called at most once. The event is dispatched when the STORAGE consent is given (the value becomes ACCEPT). If it is never given, the event will not be dispatched. See Osano and the IAB Framework (TCF 2.0) for more information on the Storage category.

The callback does not receive any arguments.

A new listener added when consent has already been given (i.e. Osano.cm.getConsent()['STORAGE'] === 'ACCEPT') will be called immediately.

Example:

Osano.cm.addEventListener('osano-cm-storage', () => console.log('Consent granted for storage.'));

osano-cm-ui-changed

This event will dispatch when a UI component is shown or hidden. It receives two arguments: component and stateChange.

Values for component:

  • dialog
  • drawer
  • widget

Values for stateChange:

  • hide
  • show

Example:

Osano.cm.addEventListener('osano-ui-changed', (component, stateChange) => {
if (component === 'drawer' && stateChange === 'show') {
console.log('Preferences drawer has been opened.');
}
});

Using Events

Osano automatically prevents scripts with a src attribute from loading until those scripts have been approved and categorized by the Osano administrator. Although the CM does prevent inline scripts from creating new scripts and iframes based on consent status and object categorization, it does not prevent inline scripts from executing. Therefore it is generally recommended that developers do not implement event listening unless code within inline scripts depends on consent status.

Some scenarios that might require event listening are:

  • Your inline script writes a script or iframe to the document and expects that object to be immediately available.
  • Your inline script depends upon the availability of a script that might be blocked by the CM in certain regions until the consent has been granted by the visitor.
  • Your organization loads content asynchronously or makes other content decisions that depend on visitor consent (e.g. the text of the article cannot be loaded until the visitor has accepts or denies a category).

The Osano.cm object is available immediately after the CM script in the document. You do not need to wait for the Osano.cm object to become available.

The Consent Object

Format

{ 
ANALYTICS: "ACCEPT",
MARKETING: "DENY",
PERSONALIZATION: "DENY",
ESSENTIAL: "ACCEPT",

/*special IAB categories*/
OPT-OUT: "ACCEPT",
STORAGE: "DENY"
}

Categories and Values

The consent object has the following categories: Analytics, Marketing, Personalization, Essential, Opt-Out, and Storage.

Each of these categories will have a value of either ACCEPT or DENY.

The Opt-Out and Storage categories are both connected to the Interactive Advertising Bureau (IAB). Opt-Out is related to the IAB CCPA framework. This corresponds to the “Do Not Sell” switch seen in the US version of the preferences Drawer.

The “Storage” category is related to the IAB TCF 2.0 framework. This corresponds to the storage option seen in the EU when TCF 2.0 is enabled.

Note: both of these values are present on the Consent Object (e.g. when calling window.Osano.cm.getConsent() or in the callback of a relevant event) even if you are not utilizing the TCF 2.0 feature. If you are not utilizing TCF 2.0, the “Storage” category will default to DENY.