Developer Documentation - Consent JavaScript API

The Consent JavaScript API documentation details Osano's publically available functions and events.

The Osano consent management platform makes events available to developers so that you can easily implement additional logic based on the visitor's consent status (e.g., programmatically load scripts or 3rd parties once consent is received). 

Please note that utilizing these functions and events to modify or disrupt Osano's intended functionality could result in breaking changes in future iterations. 

Important: 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.

Available Functions

  • // true or false 
  • // true or false 
  • // true or false 
  • // true or false
  • // { ESSENTIAL: ACCEPT ... etc. }
  • // {debug, permissive, production}
    Note: These modes map to one of three "Compliance Modes".
    Debug = Listener/Discovery | Permissive = Permissive | Production = Strict

Events for the addEventListener function

  • osano-cm-initialized 
    • This event will dispatch when the CMP is initialized. The callback function receives a ConsentObject that indicates the current user's provided consent or undefined when a user has not yet given consent. If the CMP has already initialized by the time a listener is added for this event, the callback is immediately fired with the appropriate argument.
  • osano-cm-consent-changed 
    • This event will dispatch when a user toggles a consent category. The callback function receives a ConsentObject with a single {key: value} pair indicating the category the user toggled. This event only indicates that a user has changed this option and does not reflect the consent being saved. 
  • osano-cm-consent-saved 
    • This event will dispatch when the user saves their consent preferences. The callback function receives a ConsentObject that indicates the current user's provided consent.
  • osano-cm-consent-new
    • This event will dispatch immediately after 'osano-cm-consent-saved' if the user is registering a new consent i.e. they have never consented before, or their consent was expired.

  • osano-cm-analytics, osano-cm-marketing, osano-cm-personalization, osano-cm-storage, osano-cm-opt-out
    • These events are one-time events. They will only fire if the newly saved consent will change the previous value to ACCEPT and will only fire once if the listener has already been added. Note: any listeners added AFTER the event will fire on the subsequent change to ACCEPT.

  • osano-cm-script-blocked 
    • This event will dispatch when the CMP has blocked a script from being run in the user's browser. The callback function receives a string that indicates src of the script file that was blocked.
  • osano-cm-cookie-blocked 
    • This event will dispatch when the CMP has blocked a cookie from being set on the user's browser. The callback function receives a string that indicates the name of the cookie that was blocked.

Using Events

Osano automatically prevents scripts with an src tag from loading until those scripts have been approved and categorized by the Osano administrator. Although Osano does prevent inline code from creating new scripts and iframes based on consent status and object categorization, Osano does not prevent inline code from executing, therefore it is generally recommended that developers do not implement event listening unless inline code needs to be triggered depending upon consent status.

Examples of situations that might require event listening are:

  • Your inline code writes an object such as a script or iframe to the document and expects that object to be immediately available.
  • Your inline code depends upon the availability of a script that might be blocked by Osano in certain regions until the consent has been granted by the visitor.
  • Your company loads content via AJAX/XHR or makes other content decisions dependent upon whether the user has granted consent (e.g., the text of the article should not be loaded until the visitors has accepted or denied)

The object is available immediately after the script in the document, you do not need to wait for the object to become available.

Example event after Osano has initialized"osano-cm-initialized", function (consentObject) {
if (consentObject.MARKETING === "ACCEPT") {
//run marketing scripts

Example event after a visitor changes their consent"osano-cm-consent-saved", function (consentObject) {
if (consentObject.PERSONALIZATION === "ACCEPT") {
//run personalization scripts

Consent object format


/*special IAB categories*/

Consent object values:

When requesting the consent object values, you will receive the following: 

Analytics, Marketing, Personalization, Essential, Opt-Out, and Storage. 

Each of these values will read either "Accept" or "Deny"

There are 2 *special* categories: Opt-Out and Storage. Both values are connected to the Interactive Advertising Bureau (IAB). 

The "Opt_out" category is related to the IAB CCPA framework. This coincides with the "Do Not Sell" switch seen in the US version of the "Storage Preferences" drawer.

The "Storage" category is related to the IAB TCF 2.0 framework This coincides with the "storage" option seen in the EU when TCF 2.0 is enabled.

NOTE: Both of these values are present when the  call is made even if you are not utilizing the TCF 2.0 feature. If you are not utilizing TCF 2.0, the "Storage" value will default to "deny".