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
  }
}