Creating your own UI

We provide an open source reference UI package that can be extended however you see fit. This package provides a strong foundation with full regime-specific UI integration, compatibility with our auto-prompt functionality, and translations for 54 languages.

https://github.com/transcend-io/consent-manager-ui

See this doc to learn more about customizing the stylesheet (CSS) for our out-of-the-box UIs rather than building an entirely custom UI.

To prevent our default UI module from loading, add a data-ui="off" attribute to your airgap.js script tag.

If your own UI is available as a discrete external JavaScript file, you can optionally replace our UI module and airgap.js will asynchronously auto-load your module instead by specifying a URL in the data-ui script attribute.

If your UI setup code runs before airgap.js core is initialized, you will need to use airgap.ready() as demonstrated below:

if (!self.airgap) {
self.airgap = {
readyQueue: [],
ready(callback) {
this.readyQueue.push(callback);
},
...self.airgap,
};
}
// Wait for airgap.js core to load
self.airgap.ready((airgap) => {
// Init your UI DOM here
});

Every airgap.js API that can mutate consent state requires a genuine user gesture (event.isTrusted == true) which can be either any UIEvent (e.g. click) or a form submit event. Script load events that fired prior to airgap.js initialization can also be used as valid consent authorization.

airgap.getConsent() returns an TrackingConsentDetails descriptor. This descriptor has a purposes field which returns an object keyed by all consentable tracking purpose types. The descriptor also has an ISO 8601 timestamp accessible via the timestamp field.

getConsent() Example

await airgap.sync();
const consent = airgap.getConsent().purposes;
console.log(JSON.stringify(consent, null, 2));

airgap.getConsent().purposes output:

{
"Functional": false,
"Analytics": false,
"Advertising": false
}

airgap.setConsent() sets user consent for individual tracking purposes. A trusted interaction Event (or the script load event for the airgap.js script) is required by this API.

Example

saveConsentButton.addEventListener('click', (interaction) => {
airgap.setConsent(interaction, serializeConsent());
});

ℹ️ The first argument to airgap.setConsent must be a native click or submit Event. If you're using React, your event may be a SyntheticEvent. In this case, you will need to pass interaction.nativeEvent.

await airgap.sync();
const hasPrivacyRights = airgap.getRegimePurposes().size !== 0;
// Is user fully opted-in to core unessential tracking purposes:
// Functional, Analytics, and Advertising
const isOptedIn = airgap.isOptedIn();
// a similar utility is available for detecting full opt-out
// of these purposes:
// const isOptedOut = airgap.isOptedOut();
const consentForm = document.getElementById('...');
const consentCheckbox = document.getElementById('...');
consentCheckbox.checked = isOptedIn;
if (hasPrivacyRights) {
consentCheckbox.addEventListener('change', (interaction) => {
if (interaction.target.checked) {
// Consent to all user-configurable tracking purposes
airgap.optIn({ interaction });
} else {
// Opt-out of all user-configurable tracking purposes
airgap.optOut({ interaction });
}
});
} else {
consentForm.style.display = 'none';
consentCheckbox.disabled = true;
}

Consent can be set on a per-purpose level using airgap.getConsent()airgap.setConsent(), and airgap.getPurposesTypes().

airgap.getPurposesTypes() returns airgap's current TrackingPurposesTypes config. This config data can be used in conjunction with airgap.getConsent() to inform the content of a custom consent UI.

const purposes = airgap.getPurposesTypes();
console.log(JSON.stringify(purposes, null, 2));

airgap.getPurposesTypes() example output:

{
"Functional": {
"name": "Functionality",
"description": "Personalization, autofilled forms, etc.",
"defaultConsent": false,
"showInConsentManager": true,
"configurable": true,
"essential": false
},
"Analytics": {
"name": "Analytics + Performance",
"description": "Help us learn how our site is used and how it performs.",
"defaultConsent": false,
"showInConsentManager": true,
"configurable": true,
"essential": false
},
"Advertising": {
"name": "Targeting / Advertising",
"description": "Helps us and others serve ads relevant to you.",
"defaultConsent": false,
"showInConsentManager": true,
"configurable": true,
"essential": false
},
"Essential": {
"name": "Essential",
"description": "",
"defaultConsent": true,
"showInConsentManager": false,
"configurable": false,
"essential": true
},
"Unknown": {
"name": "Unknown",
"description": "",
"defaultConsent": false,
"showInConsentManager": false,
"configurable": false,
"essential": false
}
}