Integrating dperms.js

There are two methods of interacting with the Dperms library: synchronous and asynchronous. The synchronous implementation requires waiting on the availability of the consent library and optional synchronization with external domain consent. This can be achieved as follows:

if (typeof Dperms !== "undefined" && Dperms.isSynced()) {
    Dperms.get(); // returns all purposes
} else {
    window.addEventListener('Dperms', function (e) {
        Dperms.get(); // returns all purposes
    }, false);
}

The Dperms library dispatches the ‘Dperms’ event when fully loaded and synchronized. If the above script runs before that event, it registers an event listener. Otherwise the API can be used immediately.

The asynchronous method uses a message queue and callbacks:

Dperms = Dperms || [];
Dperms.push(['get', function(perms) { /* all purposes available here */}]);

The API functions in the next section assume the synchronous method. All functions can be used asynchronously where the last parameter is a callback function that accepts one parameter containing the result of the synchronous call.

get(purpose, props)

Returns the current consent for the (optionally) specified purpose.

const analytics = Dperms.get('analytics');
// analytics = 1
const purpose = Dperms.get('analytics', true);
// analytics = {name: 'analytics', value: 1, language: 'nl', 
//              version: 1, maxVersion: 1}

The returned ‘value’ can be a number, usually 0 for no consent and 1 for consent, and null to indicate the value has not yet been set. undefined indicates the purpose is unknown. The ‘props’ parameters can be false or true to indicate interest in all the details concerning the purpose.

When ‘props’ is omitted or false and ‘version’ does not match the current ‘maxVersion’, then the returned value is null. The default behavior of most clients will be to ask for consent again. This ‘maxVersion’ is set server-side and can thus be used to invalidate previous consent for a particular purpose.

When the purpose is omitted in the call to ‘get’, all declared purposes are returned where a ‘value’ of null again indicates the user has not specified their consent yet.

const purposes = Dperms.get();
// purposes = {
//   analytics: {name: 'analytics', value: 1, language: 'nl', 
//               version: 1, maxVersion: 1},
//   social: {name: 'social', value: null}
// }

set(purpose, value, language, version)

Sets the current consent for the specified purpose. The value should be a number equal to or greater than 0 and less than 36. The language should be a lowercase ISO 639-1 code. The optional version can be used to explicitely set the version of consent. Usually this parameter should be omitted and the current ‘maxVersion’ is used.

Dperms.set('social', 1, 'nl');

More than one purpose can be set at once by specifying the parameters in an array of objects using the same format as get:

Dperms.set([
    {name: 'analytics', value: 1, language: 'nl'}, 
    {name: 'social', value: 0, language: 'nl'}]);

on(purpose, callback, history)

Registers a callback function that is called when the specified purpose changes to a value greater than 0. A ‘history’ parameter of true indicates that the callback should also be called if this is the case at the moment the callback is registered.

Dperms.on('social', function(perm) { 
    // consent for 'social' purpose here
}, true);

CSS classes

CSS classes can be used to classify elements on your site that should only be loaded when there is consent for the spcified purpose. Some of the element’s attributes should be altered to prevent the browser from loading or executing content before consent is fully available. E.g.:

<script type="text/plain" data-src="[url]" class="dperms_social"></script>

<iframe src="about:blank" data-src="[url]" class="dperms_marketing"></iframe>