1 of 11

OnSite API

Getting Started

Overview on the Commanders Act Consent OnSite API.

The Commanders Act Consent API is used to interact with Commanders Act Consent with JavaScript. It currently only offers methods to receive and update consent, but it will be improved with additional methods in the future.

API Stub

It is necessary to install a JavaScript stub before any of the OnSite API methods can be used. The stub is used to buffer all methods in a JavaScript array until Commanders Act consent banner JavaScript is loaded and ready to process the methods. This allows to use the OnSite API before Commanders Act Consent Banner (JavaScript file) was loaded.

window.caReady = window.caReady || []; 
window.cact = function() { window.caReady.push(arguments); };

window.caReady is a JavaScript array that buffers the interactions with the API. window.cact is a JavaScript function used to interact with the OnSite API.

In case you work in a big team and are unsure the stub was already installed it is ok to install the JavaScript stub multiple times.

Methods

After installing the stub it is then possible to use any of the OnSite API methods via the window.cact function.

The available methods are listed in the documentation under ONSITE API.

Each method follows a strict signature:

cact(command, [options,] [callback])

Below you will find an example method that is used to receive the Commanders Act consent status with the OnSite API. This example only provides a callback to receive the consent without providing any options.

cact('consent.get', function (result) {
    
    if (result.consent.status === "all-on") {
        
        // Consent available for all categories.
        
    }
    
});

The OnSite API methods are called asynchronously. In case e.g. you need information synchronous in the <head> of the document it is recommended to cache and retrieve the result of the API in localStorage.

consent.get

Method to receive Commanders Act consent and consent metadata OnSite via JavaScript.

The Commanders Act OnSite API stub has to be installed before using any of the OnSite API functions.

cact('consent.get', function (result) { ... });

The consent.get method takes one callback JavaScript function as an argument that gets called with the Consent Object that is currently stored on the browser. The callback is called once after Commanders Act CMP JavaScript loaded and validated the stored consent.

The OnSite API works asynchronous. In case you need the consent synchronous (e.g. in the <head> of a document for AB Testing or personalisation solutions) it is recommended to cache the object in the localStorage of the browser. In this case it is crucial to implement the consent.onUpdate method to keep the cached consent in sync.

Examples

In this example the Analytics category was configured with the consent category id 2 in Commanders Act banner.

cact('consent.get', function (result) {

   var ANALYTICS_ID = 2;
   var analyticsCategory = result.consent.categories[ANALYTICS_ID] || {};
   
   if (analyticsCategory.status === 'on') {
         
      // Consent was provided for the category. 
      
   } else {
      
      // Consent was not provided for the category.
   
   }
        
});

In this example the Analytics category was configured with the consent category id 2 and the vendor Google with vendor id 5 in Commanders Act CMP.

cact('consent.get', function (result) {
   
   var ANALYTICS_ID = 2;
   var analyticsCategory = result.consent.categories[ANALYTICS_ID] || {};

   var GOOGLE_ID = 5;
   var googleVendor = result.consent.vendors[GOOGLE_ID] || {};
   
   if (analyticsCategory.status === 'on' && googleVendor.status === 'on') {
         
      // Consent was provided for the category. 
      
   } else {
      
      // Consent was not provided for the category.
   
   }
        
});

cact('consent.get', function (result) {
   
   if (result.consent.status === 'unset') {
         
      // Consent was not yet provided.
      
   } else {
      
      // Consent was accepted or refused.
   
   }
        
});

cact('consent.get', function (result) {

    var dateExpires = result.meta.dateExpires;
                
});

consent.update

Method to update Commanders Act consent status OnSite via JavaScript.

The Commanders Act OnSite API stub has to be installed before using any of the OnSite API functions.

cact('consent.update', consentObject)

The consent.update method allows to update the consent with JavaScript. It has to be called with a Consent Object that includes the updated settings. Commanders Act will deep merge the status fields of the current Consent Object with the provided object and automatically update all meta properties and the consent.status property automatically. In case a consent.status field is provided with value all-on, all-off or unset all other updates are ignored and all categories and vendor settings will be set to on, off or unset accordingly.

All not configured categories and vendors are ignored when deep-merging the consent objects.

Examples

Update categories and vendors

cact('consent.update', {
    categories: {
        '2': { status: 'on' }
    },
    vendors: {
        '1': { status: 'on' }
    }
});

Below you can see how the Consent Object is affected by this update.

/* Consent Object Before Update
{
    meta: { ... },
    consent: {
        status: "mixed",
        categories: {
            "1": { status: "on" },
            "2": { status: "off" }
        },
        vendors: {
            "1": { status: "off" },
            "2": { status: "on"}
        }     
    }
}
*/

// Update
cact('consent.update', {
    categories: {
        '2': { status: 'on' }
    },
    vendors: {
        '1': { status: 'on' }
    }
});

/* Consent Object After Update
{
    meta: { ... }, // automatically updated
    consent: {
        status: "all-on", // automatically updated
        categories: {
            "1": { status: "on" },
            "2": { status: "on" } // updated
        },
        vendors: {
            "1": { status: "on" }, // updated
            "2": { status: "on"}
        }     
    }
}
*/

Update IAB TCF/ACM categories and vendors

cact('consent.update', {
    categories: {
        '1': { // non-IAB category
            status: 'on' 
        },
        'tcf2_1': { // TCF purpose 1
            status: 'on' // no legintStatus for purpose 1
        },
        'tcf2_2': { // TCF purpose 2
            status: 'off',
            legIntStatus: 'on'
        },
        'tcf2_sf_1': { // TCF special feature 1
            status: 'on'
        }
    },
    vendors: {
        'tcf2_1': { // TCF vendor 1
            status: 'on',
            legIntStatus: 'off'
        },
        'tcf2_2': { // TCF vendor 2
            status: 'on',
            legIntStatus: 'on'
        },
        'acm_1': { // ACM vendor 1
            status: 'on'
        }
    }
});

Accept all categories and vendors

cact('consent.update', { 
    status: 'all-on'
});

Specifying a category or vendor will not have any effect.

cact('consent.update', { 
    status: 'all-on', 
    categories: {
        '2': { status: 'unset' } // ignored as global status is specified
    }
});

Below you can see how the Consent Object is affected by this update.

/* Consent Object Before Update
{
    meta: { ... },
    consent: {
        status: "unset",
        categories: {
            "1": { status: "unset" },
            "2": { status: "unset" }
        },
        vendors: {
            "1": { status: "unset" },
            "2": { status: "unset"}
        }     
    }
}
*/

// Update Method
cact('consent.update', { 
    status: 'all-on'
});

/* Consent Object After Update
{
    meta: { ... }, // automatically updated
    consent: {
        status: "all-on",
        categories: {
            "1": { status: "on" }, // automatically updated
            "2": { status: "on" } // automatically updated
        },
        vendors: {
            "1": { status: "on" }, // automatically updated
            "2": { status: "on"} // automatically updated
        }     
    }
}
*/

Refuse all categories and vendors

cact('consent.update', { 
    status: 'all-off'
});

Specifying a category or vendor will not have any effect.

cact('consent.update', { 
    status: 'all-off', 
    categories: {
        '2': { status: 'on' } // ignored as global status is specified
    }
});

Below you can see how the Consent Object is affected by this update. Note: required categories are not affected.

/* Consent Object Before Update
{
    meta: { ... },
    consent: {
        status: "mixed",
        categories: {
            "1": { status: "on" },
            "2": { status: "off" },
            "3": { status: "on", required: true }
        },
        vendors: {
            "1": { status: "on" },
            "2": { status: "on"}
        }     
    }
}
*/

// Update Method
cact('consent.update', { 
    status: 'all-off'
});

/* Consent Object After Update
{
    meta: { ... }, // automatically updated
    consent: {
        status: "all-off",
        categories: {
            "1": { status: "off" }, // automatically updated
            "2": { status: "off" }, // automatically updated
            "3": { status: "on", required: true } // unchanged
        },
        vendors: {
            "1": { status: "off" }, // automatically updated
            "2": { status: "off"} // automatically updated
        }     
    }
}
*/

Specify update action

You can specify an action inside the update parameters:

cact('consent.update', {
    action: 'banner_button',
    categories: {
        '2': { status: 'on' }
    },
    vendors: {
        '1': { status: 'on' }
    }
});

This action value will be used to compute your dashboard metrics. If it is omitted, the default value is banner_button.

The allowed values are:

banner_button
pc_save
page_click
scroll
browse

Additionally, the following values are allowed for optout only (status: 'all-off' ):

banner_cross

consent.revoke

Method to revoke Commanders Act consent OnSite via JavaScript.

consent.revoke is called with no options and no callback function. It resets the consent, consent id and initiates two consen.onUpdate events, one with the updateEvent set to changed, and a second one set torevoked that allows to perform cleanup tasks like removing cookie identifiers.

consent.onUpdate

Method to subscribe to Commanders Act consent status updates OnSite via JavaScript.

Method to subscribe to Commanders Act consent updates OnSite via JavaScript.The Commanders Act OnSite API stub has to be installed before using any of the OnSite API functions.

cact('consent.onUpdate', function (result) { ... })

The consent.onUpdate method allow to subscribe a callback function for consent updates. The callback function will be called with the updated Consent Object. It is called whenever the consent is changed via a Commanders Act banner interaction or the consent.update method of the OnSite API.

The consentObject argument will also be enriched with an additional property updateEvent to signal how the update happened. It can have following values:

When consent is revoked it fires two events: One changed followed by one revoked.

Examples

In this example the Analytics category was configured with the consent category id 2 in Commanders Act Consent settings.

cact('consent.onUpdate', function (result) { 
    
    var ANALYTICS_ID = 2;
    var analyticsCategory = result.consent.categories[ANALYTICS_ID] || {};
     
    if (analyticsCategory.status === 'on') {
    
        // Consent was provided for the category. 
    
    } else {
        
        // Consent was not provided for the category. 
           
    }
    
});

In this example the Analytics category was configured with the consent category id 2 in TrustCommander.

cact('consent.onUpdate', function (result) { 

    var ANALYTICS_ID = 2;
    var analyticsCategory = result.consent.categories[ANALYTICS_ID] || {};

    if (result.updateEvent === "changed" && analyticsCategory.status === 'on') {
    
        // Consent was provided for the category during an update.
    
    } 
    
});

consent.onReady

Method to obtain Commanders Act consent when it becomes available.

Method to obtain consent when it becomes available.The Commanders Act OnSite API stub has to be installed before using any of the OnSite API functions.

cact('consent.onReady', function (result) { ... })

The consent.onReady method allow to subscribe a callback function for when consent is set. The callback function will be called only once, with the updated Consent Object. It is called whenever the consent is set via a consent banner interaction or when a consent cookie is already set.

Like in the command consent.onUpdate, the consentObject argument will be enriched with the property updateEvent, but only with the value 'set'.

Example

In this example, the code is waiting for the user's interaction with the consent banner. The Analytics category was configured with the consent category id 2 on privacy banner.

cact('consent.onReady', function (result) { 
    
    var ANALYTICS_ID = 2;
    var analyticsCategory = result.consent.categories[ANALYTICS_ID] || {};
     
    if (analyticsCategory.status === 'on') {
    
        // Consent was provided for the category. 
    
    } else {
        
        // Consent was not provided for the category. 
           
    }
    
});

consentBanner.show

JavaScript method to display your consent banner.

The command consentBanner.show allows to redisplay the consent banner for specific reasons. Simply use the following Javascript method:

cact('consentBanner.show')

This command allows you to display the consent banner after the user consent is given

consentBanner.hide

JavaScript method to hide your consent banner.

The command consentBanner.hideallows to hide the consent banner for specific reasons. Simply use the following Javascript method:

cact('consentBanner.hide')

consentCenter.show

JavaScript method to display your consent center (consent categories menu).

The command consentCenter.show allows to redisplay the consent center for specific reasons. Simply use the following Javascript method:

cact('consentCenter.show')

This command allows you to display the consent center after the user consent is given

consentCenter.hide

JavaScript method to hide your consent center (consent categories menu).

The command consentCenter.hide allows to hide the consent center for specific reasons. Simply use the following Javascript method:

cact('consentCenter.hide')

consent.update

Method to update Commanders Act consent status OnSite via JavaScript.

The Commanders Act OnSite API stub has to be installed before using any of the OnSite API functions.

cact('consent.update', consentObject)

All not configured categories and vendors are ignored when deep-merging the consent objects.

Examples

Update categories and vendors

cact('consent.update', {
    categories: {
        '2': { status: 'on' }
    },
    vendors: {
        '1': { status: 'on' }
    }
});

Below you can see how the Consent Object is affected by this update.

/* Consent Object Before Update
{
    meta: { ... },
    consent: {
        status: "mixed",
        categories: {
            "1": { status: "on" },
            "2": { status: "off" }
        },
        vendors: {
            "1": { status: "off" },
            "2": { status: "on"}
        }     
    }
}
*/

// Update
cact('consent.update', {
    categories: {
        '2': { status: 'on' }
    },
    vendors: {
        '1': { status: 'on' }
    }
});

/* Consent Object After Update
{
    meta: { ... }, // automatically updated
    consent: {
        status: "all-on", // automatically updated
        categories: {
            "1": { status: "on" },
            "2": { status: "on" } // updated
        },
        vendors: {
            "1": { status: "on" }, // updated
            "2": { status: "on"}
        }     
    }
}
*/

Update IAB TCF/ACM categories and vendors

cact('consent.update', {
    categories: {
        '1': { // non-IAB category
            status: 'on' 
        },
        'tcf2_1': { // TCF purpose 1
            status: 'on' // no legintStatus for purpose 1
        },
        'tcf2_2': { // TCF purpose 2
            status: 'off',
            legIntStatus: 'on'
        },
        'tcf2_sf_1': { // TCF special feature 1
            status: 'on'
        }
    },
    vendors: {
        'tcf2_1': { // TCF vendor 1
            status: 'on',
            legIntStatus: 'off'
        },
        'tcf2_2': { // TCF vendor 2
            status: 'on',
            legIntStatus: 'on'
        },
        'acm_1': { // ACM vendor 1
            status: 'on'
        }
    }
});

Accept all categories and vendors

cact('consent.update', { 
    status: 'all-on'
});

Specifying a category or vendor will not have any effect.

cact('consent.update', { 
    status: 'all-on', 
    categories: {
        '2': { status: 'unset' } // ignored as global status is specified
    }
});

Below you can see how the Consent Object is affected by this update.

/* Consent Object Before Update
{
    meta: { ... },
    consent: {
        status: "unset",
        categories: {
            "1": { status: "unset" },
            "2": { status: "unset" }
        },
        vendors: {
            "1": { status: "unset" },
            "2": { status: "unset"}
        }     
    }
}
*/

// Update Method
cact('consent.update', { 
    status: 'all-on'
});

/* Consent Object After Update
{
    meta: { ... }, // automatically updated
    consent: {
        status: "all-on",
        categories: {
            "1": { status: "on" }, // automatically updated
            "2": { status: "on" } // automatically updated
        },
        vendors: {
            "1": { status: "on" }, // automatically updated
            "2": { status: "on"} // automatically updated
        }     
    }
}
*/

Refuse all categories and vendors

cact('consent.update', { 
    status: 'all-off'
});

Specifying a category or vendor will not have any effect.

cact('consent.update', { 
    status: 'all-off', 
    categories: {
        '2': { status: 'on' } // ignored as global status is specified
    }
});

Below you can see how the Consent Object is affected by this update. Note: required categories are not affected.

/* Consent Object Before Update
{
    meta: { ... },
    consent: {
        status: "mixed",
        categories: {
            "1": { status: "on" },
            "2": { status: "off" },
            "3": { status: "on", required: true }
        },
        vendors: {
            "1": { status: "on" },
            "2": { status: "on"}
        }     
    }
}
*/

// Update Method
cact('consent.update', { 
    status: 'all-off'
});

/* Consent Object After Update
{
    meta: { ... }, // automatically updated
    consent: {
        status: "all-off",
        categories: {
            "1": { status: "off" }, // automatically updated
            "2": { status: "off" }, // automatically updated
            "3": { status: "on", required: true } // unchanged
        },
        vendors: {
            "1": { status: "off" }, // automatically updated
            "2": { status: "off"} // automatically updated
        }     
    }
}
*/

Specify update action

You can specify an action inside the update parameters:

cact('consent.update', {
    action: 'banner_button',
    categories: {
        '2': { status: 'on' }
    },
    vendors: {
        '1': { status: 'on' }
    }
});

This action value will be used to compute your dashboard metrics. If it is omitted, the default value is banner_button.

The allowed values are:

banner_button
pc_save
page_click
scroll
browse

Additionally, the following values are allowed for optout only (status: 'all-off' ):

banner_cross

OnSite API

Getting Started

API Stub

Methods

consent.get

Examples

Executing code based on the consent setting of a category

Executing code based on the consent setting of a category and vendor

Check if consent was already set by the visitor

Checking when the current consent expires

consent.update

Examples

Update categories and vendors

Update IAB TCF/ACM categories and vendors

Accept all categories and vendors

Refuse all categories and vendors

Specify update action

consent.revoke

consent.onUpdate

Examples

Example to react to consent changes of a specific category

Example only react to consent changes of a specific category after the initial consent was given

consent.onReady

Example

Example to wait for consent availability and do something on a specific category

consentBanner.show

consentBanner.hide

consentCenter.show

consentCenter.hide

consent.get

Examples

Executing code based on the consent setting of a category

Executing code based on the consent setting of a category and vendor

Check if consent was already set by the visitor

Checking when the current consent expires

Getting Started

API Stub

Methods

consent.update

Examples

Update categories and vendors

Update IAB TCF/ACM categories and vendors

Accept all categories and vendors

Refuse all categories and vendors

Specify update action

consent.onReady

Example

Example to wait for consent availability and do something on a specific category

consentBanner.show

consent.onUpdate

Examples

Example to react to consent changes of a specific category

Example only react to consent changes of a specific category after the initial consent was given

consent.revoke

consentBanner.hide

consentCenter.show

consentCenter.hide