Appearance

API Reference ​

Complete reference for the Consent Pro V2 JavaScript API.

Table of Contents ​

Global API Access ​

Use the callback queue to guarantee that Consent Pro is initialized before using the API. This is generally only needed if you load the script asynchronously. By default, we recommend placing the script tag directly in the <head> without async or defer, which allows you to use the API immediately after the script tag.

html
<script>
  window.FinsweetConsentPro = window.FinsweetConsentPro || [];
  window.FinsweetConsentPro.push([
    'consent',
    (FinsweetConsentPro) => {
      console.log('Consent Pro loaded:', FinsweetConsentPro.version);

      const choices = FinsweetConsentPro.consents.get();
      console.log('Current choices:', choices);

      FinsweetConsentPro.elements.preferences.show();
    },
  ]);
</script>

Direct Access ​

After initialization, the runtime API is available at window.FinsweetConsentPro.

javascript
console.log(window.FinsweetConsentPro);

Main API Object ​

ts
type FinsweetConsentPro = {
  version: string;
  config: ConsentV2SanitizedRuntimeConfiguration;
  instanceConfig: ConsentV2SanitizedRuntimeConfiguration['instances'][string];

  consents: {
    essential: boolean;
    marketing: boolean;
    analytics: boolean;
    personalization: boolean;

    get: () => ConsentChoices;
    set: (consents: ConsentChoices) => void;
    acceptAll: () => void;
    rejectAll: () => void;
    denyAll: () => void;
    renew: () => void;
  };

  elements: {
    banner: { show: () => void; hide: () => void };
    preferences: { show: () => void; hide: () => void };
    fixedPreferences: { show: () => void; hide: () => void };
  };

  push: (...args: ConsentProCallback[]) => void;
  destroy: () => void;
};

consents.essential ​

Returns the current essential consent state.

Type: boolean

consents.marketing ​

Returns the current marketing consent state.

Type: boolean

consents.analytics ​

Returns the current analytics consent state.

Type: boolean

consents.personalization ​

Returns the current personalization consent state.

Type: boolean

consents.get() ​

Returns all current consent choices.

Returns: ConsentChoices

javascript
const choices = window.FinsweetConsentPro.consents.get();
console.log(choices.analytics, choices.marketing);

consents.set(consents) ​

Sets all consent choices at once.

Parameters:

  • consents (ConsentChoices)

Returns: void

javascript
window.FinsweetConsentPro.consents.set({
  essential: true,
  analytics: true,
  marketing: false,
  personalization: false,
});

consents.acceptAll() ​

Accepts all consent categories.

Returns: void

javascript
window.FinsweetConsentPro.consents.acceptAll();

consents.rejectAll() ​

Rejects all optional consent categories.

Returns: void

javascript
window.FinsweetConsentPro.consents.rejectAll();

consents.denyAll() ​

Alias for consents.rejectAll().

Returns: void

javascript
window.FinsweetConsentPro.consents.denyAll();

consents.renew() ​

Resets consent to defaults and shows the banner again.

Returns: void

javascript
window.FinsweetConsentPro.consents.renew();

Elements API ​

elements.banner.show() / elements.banner.hide() ​

Shows or hides the consent banner.

javascript
window.FinsweetConsentPro.elements.banner.show();
window.FinsweetConsentPro.elements.banner.hide();

elements.preferences.show() / elements.preferences.hide() ​

Shows or hides the preferences UI.

javascript
window.FinsweetConsentPro.elements.preferences.show();
window.FinsweetConsentPro.elements.preferences.hide();

elements.fixedPreferences.show() / elements.fixedPreferences.hide() ​

Shows or hides the fixed preferences control.

javascript
window.FinsweetConsentPro.elements.fixedPreferences.show();
window.FinsweetConsentPro.elements.fixedPreferences.hide();

Events API ​

Consent Pro emits runtime events that you can consume in two ways:

  1. Through the runtime emitter API: window.FinsweetConsentPro.on(eventName, callback)
  2. Through DOM events prefixed with consentpro:

The runtime dispatches DOM events with:

ts
document.documentElement.dispatchEvent(new CustomEvent(`consentpro:${event}`, { detail }));

Using window.FinsweetConsentPro.on() ​

javascript
window.FinsweetConsentPro.on('ready', () => {
  console.log('Consent Pro is ready');
});

window.FinsweetConsentPro.on('updated', (detail) => {
  console.log('Consent updated', detail.choices);
});

Using DOM events (consentpro:*) ​

javascript
document.documentElement.addEventListener('consentpro:banner-shown', () => {
  console.log('Banner became visible');
});

document.documentElement.addEventListener('consentpro:updated', (event) => {
  console.log('Consent updated', event.detail);
});

Available events ​

  • ready
  • accept-all
  • reject-all
  • updated
  • banner-shown
  • banner-hidden
  • preferences-shown
  • preferences-hidden
  • fixed-preferences-shown
  • fixed-preferences-hidden
  • script-blocked
  • script-unblocked
  • iframe-blocked
  • iframe-unblocked
  • map-blocked
  • map-unblocked

Event payloads ​

  • ready, accept-all, reject-all, banner-shown, banner-hidden, preferences-shown, preferences-hidden, fixed-preferences-shown, fixed-preferences-hidden: no payload (void)
  • updated:
ts
{
  id: string;
  choices: ConsentChoices;
  previousChoices?: ConsentChoices;
  action?: ConsentAction;
  source?: ConsentSource;
  timestamp: number;
}
  • script-blocked / script-unblocked:
ts
{
  src: string;
  element: HTMLScriptElement;
  categories: CookieCategory[];
}
  • iframe-blocked / iframe-unblocked:
ts
{
  src: string;
  element: HTMLIFrameElement;
  categories: CookieCategory[];
}
  • map-blocked / map-unblocked:
ts
{
  element: HTMLElement;
  categories: CookieCategory[];
}

Lifecycle API ​

push(...args) ​

Queues one or more callbacks to run after Consent Pro is initialized.

javascript
window.FinsweetConsentPro = window.FinsweetConsentPro || [];
window.FinsweetConsentPro.push((consent) => {
  console.log('Ready with version', consent.version);
});

destroy() ​

Destroys Consent Pro and runs cleanup handlers.

javascript
window.FinsweetConsentPro.destroy();

Next Steps ​