Skip to content

API Reference

Complete reference for the Consent Pro V2 JavaScript API.

Table of Contents

Global API Access

The recommended way to access the Consent Pro API is through the callback queue. This ensures your code runs after the API is fully loaded:

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

      // Access the current consent state
      const consent = instance.getConsent();
      console.log('Current consent:', consent);

      // Use any API method
      await instance.showPreferences();
    },
  ]);
</script>

Why use the callback approach?

  • Automatically waits for the API to be ready
  • No need to check isReady() or wait for events
  • Works reliably with async script loading
  • Cleaner, more maintainable code

Alternative: Direct Access

For advanced use cases, the global API is also available at window.FinsweetConsentProAPI after initialization:

javascript
// Check if API is ready first
if (window.FinsweetConsentProAPI?.isReady()) {
  const consent = window.FinsweetConsentProAPI.getConsent();
}

Note: Majority of examples in this documentation use the direct access approach. Both methods work identically and callback approach is recommended for most use cases.

getConsent()

Get the current global consent record.

Returns: ConsentRecord | null

javascript
const consent = window.FinsweetConsentProAPI.getConsent();

if (consent) {
  console.log('Consent ID:', consent.id);
  console.log('Choices:', consent.choices);
  console.log('Timestamp:', consent.timestamp);
  console.log('Region:', consent.region);
  console.log('Mode:', consent.mode);
}

Response Structure:

ts
interface ConsentRecord {
  id: string; // Unique consent ID (UUID)
  choices: {
    essential: boolean; // Always true
    analytics: boolean;
    marketing: boolean;
    personalization: boolean;
  };
  timestamp: string; // ISO 8601 date string
  version: string; // Script version
  region: string; // Detected region (e.g., 'eu', 'us-ca')
  source: 'banner' | 'preferences' | 'form' | 'api';
  donotsell?: boolean; // CCPA Do Not Sell state
  mode?: 'opt-in' | 'opt-out' | 'informational';
}

updateConsent(choices, instanceKey?)

Update user consent choices programmatically.

Parameters:

  • choices (Partial<ConsentChoices>): Consent choices to update
  • instanceKey (string, optional): Specific instance to update

Returns: Promise&lt;void&gt;

javascript
// Update global consent
await window.FinsweetConsentProAPI.updateConsent({
  analytics: true,
  marketing: false,
  personalization: true,
});

// Update specific instance
await window.FinsweetConsentProAPI.updateConsent({ analytics: true }, 'eu-banner');

resetConsent(instanceKey?)

Reset consent to default values and clear storage.

Parameters:

  • instanceKey (string, optional): Specific instance to reset

Returns: Promise&lt;void&gt;

javascript
// Reset global consent
await window.FinsweetConsentProAPI.resetConsent();

// Reset specific instance
await window.FinsweetConsentProAPI.resetConsent('eu-banner');

hasConsent(category, instanceKey?)

Check if a specific consent category is granted.

Parameters:

  • category (keyof ConsentChoices): Category to check ('essential' | 'analytics' | 'marketing' | 'personalization')
  • instanceKey (string, optional): Specific instance to check

Returns: boolean

javascript
if (window.FinsweetConsentProAPI.hasConsent('analytics')) {
  // Initialize analytics
  initializeAnalytics();
}

if (window.FinsweetConsentProAPI.hasConsent('marketing', 'eu-banner')) {
  // Initialize marketing for EU banner
}

Visibility Control

showBanner(instanceKey?)

Show the consent banner.

Parameters:

  • instanceKey (string, optional): Specific instance banner to show

Returns: Promise&lt;void&gt;

javascript
// Show default banner
await window.FinsweetConsentProAPI.showBanner();

// Show specific instance banner
await window.FinsweetConsentProAPI.showBanner('eu-banner');

hideBanner(instanceKey?)

Hide the consent banner.

Parameters:

  • instanceKey (string, optional): Specific instance banner to hide

Returns: Promise&lt;void&gt;

javascript
await window.FinsweetConsentProAPI.hideBanner();

showPreferences(instanceKey?)

Show the preferences modal.

Parameters:

  • instanceKey (string, optional): Specific instance preferences to show

Returns: Promise&lt;void&gt;

javascript
// Open preferences modal
await window.FinsweetConsentProAPI.showPreferences();

// Custom trigger button
document.getElementById('cookie-settings').addEventListener('click', async () => {
  await window.FinsweetConsentProAPI.showPreferences();
});

hidePreferences(instanceKey?)

Hide the preferences modal.

Parameters:

  • instanceKey (string, optional): Specific instance preferences to hide

Returns: void

javascript
window.FinsweetConsentProAPI.hidePreferences();

visibility

Object containing visibility state methods.

visibility.getBannerState(instanceKey?)

Get current banner visibility state.

Returns: boolean

javascript
const isBannerVisible = window.FinsweetConsentProAPI.visibility.getBannerState();

visibility.getPreferencesState(instanceKey?)

Get current preferences modal visibility state.

Returns: boolean

javascript
const isPreferencesVisible = window.FinsweetConsentProAPI.visibility.getPreferencesState();

visibility.getFixedPreferencesState(instanceKey?)

Get current fixed preferences visibility state.

Returns: boolean

javascript
const isFixedPrefsVisible = window.FinsweetConsentProAPI.visibility.getFixedPreferencesState();

visibility.getAllStates(instanceKey?)

Get all visibility states.

Returns: { banner: boolean; preferences: boolean; fixedPreferences: boolean }

javascript
const states = window.FinsweetConsentProAPI.visibility.getAllStates();
console.log('Banner:', states.banner);
console.log('Preferences:', states.preferences);
console.log('Fixed Preferences:', states.fixedPreferences);

Event System

on(event, callback)

Subscribe to an event.

Parameters:

  • event (ConsentEvent): Event name
  • callback (EventCallback): Function to call when event fires

Returns: () => void (unsubscribe function)

javascript
const unsubscribe = window.FinsweetConsentProAPI.on('consent-updated', (data) => {
  console.log('Consent updated:', data.choices);
  console.log('Previous choices:', data.previousChoices);
  console.log('Source:', data.source);
});

// Later: remove listener
unsubscribe();

off(event, callback)

Unsubscribe from an event.

Parameters:

  • event (ConsentEvent): Event name
  • callback (EventCallback): Previously registered callback

Returns: void

javascript
function handleConsentUpdate(data) {
  console.log('Consent updated:', data);
}

window.FinsweetConsentProAPI.on('consent-updated', handleConsentUpdate);

// Later: remove this specific listener
window.FinsweetConsentProAPI.off('consent-updated', handleConsentUpdate);

once(event, callback)

Subscribe to an event that will only fire once.

Parameters:

  • event (ConsentEvent): Event name
  • callback (EventCallback): Function to call when event fires

Returns: () => void (unsubscribe function)

javascript
window.FinsweetConsentProAPI.once('ready', (data) => {
  console.log('Consent Pro initialized once:', data);
  // This will only fire once
});

subscribe(callback)

Subscribe to all events with a single callback.

Parameters:

  • callback ((event: ConsentEvent, data: any) => void): Universal callback

Returns: () => void (unsubscribe function)

javascript
const unsubscribe = window.FinsweetConsentProAPI.subscribe((event, data) => {
  console.log(`Event fired: ${event}`, data);

  // Log all events to analytics
  analytics.track(`consentpro:${event}`, data);
});

Instance Management

getInstances()

Get list of all instance keys.

Returns: string[]

javascript
const instances = window.FinsweetConsentProAPI.getInstances();
console.log('Available instances:', instances);
// ['eu-banner', 'us-banner', 'global']

getInstance(instanceKey)

Get a specific instance with its own API methods.

Parameters:

  • instanceKey (string): Instance identifier

Returns: InstanceAPI | null

javascript
const euBanner = window.FinsweetConsentProAPI.getInstance('eu-banner');

if (euBanner) {
  // Instance-specific methods
  const consent = euBanner.getConsent();
  await euBanner.updateConsent({ analytics: true });
  await euBanner.showBanner();
  await euBanner.showPreferences();

  // Event listeners
  euBanner.on('consent-updated', (data) => {
    console.log('EU banner consent updated:', data);
  });

  // Visibility
  const states = euBanner.getVisibilityStates();

  // Configuration
  const config = euBanner.getConfig();

  // Cookies and providers
  const categories = euBanner.getCookieCategories();
  const providers = euBanner.getProviders();
}

Instance API Methods:

typescript
interface InstanceAPI {
  getConsent(): ConsentRecord | null;
  updateConsent(choices: Partial<ConsentChoices>): Promise<void>;
  resetConsent(): Promise<void>;
  hasConsent(category: keyof ConsentChoices): boolean;

  showBanner(): Promise<void>;
  hideBanner(): Promise<void>;
  showPreferences(): Promise<void>;
  hidePreferences(): Promise<void>;

  on<T extends ConsentEvent>(event: T, callback: EventCallback<T>): () => void;
  off<T extends ConsentEvent>(event: T, callback: EventCallback<T>): void;

  isVisible(): boolean;
  getVisibilityStates(): {
    banner: boolean;
    preferences: boolean;
    fixedPreferences: boolean;
  };

  getConfig(): InstanceSettings;
  getCookieCategories(): string[];
  getCookiesForCategory(category: string): CookieDefinition[];
  getProviders(): TrackerProvider[];
}

Storage API

storage.getAllConsent()

Get all stored consent data.

Returns: Record&lt;string, ConsentRecord&gt;

javascript
const allConsent = window.FinsweetConsentProAPI.storage.getAllConsent();
console.log('Stored consent records:', allConsent);

storage.isAvailable()

Check if storage mechanisms are available.

Returns: { localStorage: boolean; cookies: boolean }

javascript
const availability = window.FinsweetConsentProAPI.storage.isAvailable();
console.log('LocalStorage available:', availability.localStorage);
console.log('Cookies available:', availability.cookies);

storage.clearAll()

Clear all consent data from storage.

Returns: void

javascript
// Clear all stored consent
window.FinsweetConsentProAPI.storage.clearAll();

storage.clearInstance(instanceKey)

Clear consent data for a specific instance.

Parameters:

  • instanceKey (string): Instance to clear

Returns: void

javascript
window.FinsweetConsentProAPI.storage.clearInstance('eu-banner');

storage.isExpired(instanceKey)

Check if consent has expired for an instance.

Parameters:

  • instanceKey (string): Instance to check

Returns: boolean

javascript
if (window.FinsweetConsentProAPI.storage.isExpired('eu-banner')) {
  console.log('Consent has expired, showing banner again');
  await window.FinsweetConsentProAPI.showBanner('eu-banner');
}

storage.getLastUpdate(instanceKey)

Get timestamp of last consent update.

Parameters:

  • instanceKey (string): Instance to check

Returns: string | null (ISO 8601 date string)

javascript
const lastUpdate = window.FinsweetConsentProAPI.storage.getLastUpdate('eu-banner');
console.log('Last updated:', new Date(lastUpdate));

Cookies API

cookies.getCategoryCookies(category, instanceKey?)

Get cookies for a specific category.

Parameters:

  • category (string): Category name
  • instanceKey (string, optional): Specific instance

Returns: CookieDefinition[]

javascript
const analyticsCookies = window.FinsweetConsentProAPI.cookies.getCategoryCookies('analytics');

analyticsCookies.forEach((cookie) => {
  console.log('Cookie:', cookie.cookieID);
  console.log('Purpose:', cookie.trackerInfo?.purpose);
  console.log('Domain:', cookie.domain);
});

Cookie Definition Structure:

typescript
{
  cookieID: string;
  domain?: string;
  path?: string;
  storage?: 'cookies' | 'local-storage' | 'session-storage';
  categories: string[];
  trackerInfo?: {
    name?: string;
    purpose?: string;
    domain?: string;
    retention?: string;
    dataCollected?: string[];
    privacy?: string;
  };
}

cookies.getAllCategories(instanceKey?)

Get all cookie categories.

Parameters:

  • instanceKey (string, optional): Specific instance

Returns: string[]

javascript
const categories = window.FinsweetConsentProAPI.cookies.getAllCategories();
console.log('Available categories:', categories);
// ['essential', 'analytics', 'marketing', 'personalization']

cookies.triggerCleanup(categories, instanceKey?)

Manually trigger cookie cleanup for specific categories.

Parameters:

  • categories (string[]): Categories to clean up
  • instanceKey (string, optional): Specific instance

Returns: void

javascript
// Clean up marketing and analytics cookies
window.FinsweetConsentProAPI.cookies.triggerCleanup(['marketing', 'analytics']);

Analytics API

analytics.sendEvent(eventName, parameters)

Send custom analytics event.

Parameters:

  • eventName (string): Event name
  • parameters (Record<string, unknown>): Event parameters

Returns: void

javascript
window.FinsweetConsentProAPI.analytics.sendEvent('custom_consent_action', {
  action: 'preferences_opened',
  source: 'footer_link',
  timestamp: Date.now(),
});

analytics.getGTMStatus()

Get Google Tag Manager status.

Returns: { initialized: boolean; available: boolean; dataLayerName: string }

javascript
const gtmStatus = window.FinsweetConsentProAPI.analytics.getGTMStatus();
console.log('GTM initialized:', gtmStatus.initialized);
console.log('GTM available:', gtmStatus.available);

analytics.getCurrentConsentModes()

Get current Google Consent Mode values.

Returns: Record&lt;string, 'granted' | 'denied'&gt;

javascript
const consentModes = window.FinsweetConsentProAPI.analytics.getCurrentConsentModes();
console.log('Consent modes:', consentModes);
// {
//   ad_storage: 'granted',
//   ad_user_data: 'granted',
//   ad_personalization: 'granted',
//   analytics_storage: 'granted',
//   functionality_storage: 'granted',
//   personalization_storage: 'granted',
//   security_storage: 'granted'
// }

Configuration API

config.getInstance(instanceKey)

Get configuration for a specific instance.

Parameters:

  • instanceKey (string): Instance identifier

Returns: InstanceSettings | null

javascript
const config = window.FinsweetConsentProAPI.config.getInstance('eu-banner');

if (config) {
  console.log('Mode:', config.mode);
  console.log('Regions:', config.regions);
  console.log('Categories:', config.categories);
  console.log('Animation:', config.animation);
}

Instance Settings Structure:

typescript
{
  mode: 'opt-in' | 'opt-out' | 'informational';
  regions: string;  // Comma-separated regions
  categories: {
    analytics: { enabled: boolean; defaultValue: boolean };
    marketing: { enabled: boolean; defaultValue: boolean };
    personalization: { enabled: boolean; defaultValue: boolean };
  };
  animation?: {
    animation: string;
    easing: string;
    duration: number;
  };
  showTrackers?: boolean;
  source?: string;
  pages?: string[];
  metadata?: {
    instance: string;
  };
}

config.getRuntime()

Get full runtime configuration.

Returns: RuntimeConfiguration

javascript
const runtime = window.FinsweetConsentProAPI.config.getRuntime();
console.log('Project ID:', runtime.projectId);
console.log('Version:', runtime.version);
console.log('Instances:', runtime.instances);
console.log('Providers:', runtime.providers);
console.log('Cookies:', runtime.cookies);

Elements API

elements.getAll(instanceKey?)

Get all discovered consent elements.

Parameters:

  • instanceKey (string, optional): Specific instance

Returns: Object

javascript
const elements = window.FinsweetConsentProAPI.elements.getAll();
console.log('Banner:', elements.instance?.banner);
console.log('Preferences:', elements.instance?.preferences);
console.log('Fixed Preferences:', elements.instance?.fixedPreferences);
console.log('Templates:', elements.templates);
console.log('DOM Scope:', elements.domScope);

elements.getInstance(instanceKey)

Get elements for a specific instance.

Parameters:

  • instanceKey (string): Instance identifier

Returns: ConsentElements | null

javascript
const elements = window.FinsweetConsentProAPI.elements.getInstance('eu-banner');

if (elements) {
  console.log('Banner element:', elements.banner);
  console.log('Preferences:', elements.preferences);
  console.log('Fixed preferences:', elements.fixedPreferences);
  console.log('Form:', elements.form);
  console.log('Buttons:', elements.buttons);
  console.log('Checkboxes:', elements.checkboxes);
}

Consent Elements Structure:

typescript
{
  banner?: HTMLElement;
  preferences?: HTMLElement;
  fixedPreferences?: HTMLElement;
  form?: HTMLFormElement;
  buttons: {
    allow: HTMLButtonElement[];
    deny: HTMLButtonElement[];
    openPreferences: HTMLButtonElement[];
    close: HTMLButtonElement[];
    doNotSell: HTMLButtonElement[];
    save?: HTMLButtonElement;
  };
  checkboxes: {
    analytics?: HTMLInputElement;
    marketing?: HTMLInputElement;
    personalization?: HTMLInputElement;
    donotsell?: HTMLInputElement;
  };
}

elements.getTemplates()

Get template elements.

Returns: { placeholder: HTMLElement | null; trackers: HTMLElement | null; dom: Document | ShadowRoot; styles: string[] }

javascript
const templates = window.FinsweetConsentProAPI.elements.getTemplates();
console.log('Placeholder template:', templates.placeholder);
console.log('Trackers template:', templates.trackers);
console.log('DOM scope:', templates.dom);
console.log('Styles:', templates.styles);

elements.getDOMScope()

Get current DOM scope (document or shadow root).

Returns: Document | ShadowRoot

javascript
const scope = window.FinsweetConsentProAPI.elements.getDOMScope();
console.log('Using Shadow DOM:', scope !== document);

Debug API

debug.enableDebug()

Enable debug mode for detailed console logging.

Returns: void

javascript
window.FinsweetConsentProAPI.debug.enableDebug();
// Console will now show detailed debug logs

debug.disableDebug()

Disable debug mode.

Returns: void

javascript
window.FinsweetConsentProAPI.debug.disableDebug();

debug.getInternalState()

Get complete internal state for debugging.

Returns: DebugInternalState

javascript
const state = window.FinsweetConsentProAPI.debug.getInternalState();
console.log('Global state:', state.global);
console.log('All instances:', state.instances);
console.log('Configuration:', state.config);

debug.exportData()

Export all data for debugging or support.

Returns: Promise&lt;DebugExportData&gt;

javascript
const data = await window.FinsweetConsentProAPI.debug.exportData();
console.log('State:', data.state);
console.log('Storage:', data.storage);
console.log('Events:', data.events);
console.log('Analytics:', data.analytics);

// Export to JSON for support
const json = JSON.stringify(data, null, 2);
console.log(json);

Emergency Controls

Safety mechanisms for the auto-blocking system.

emergency.disableBlocking()

Disable automatic script/iframe blocking.

Returns: void

javascript
// If something breaks, disable blocking
window.FinsweetConsentProAPI.emergency.disableBlocking();
console.warn('Auto-blocking disabled');

emergency.unblockAll()

Immediately unblock all blocked elements.

Returns: void

javascript
// Emergency unblock everything
window.FinsweetConsentProAPI.emergency.unblockAll();
console.warn('All elements unblocked');

emergency.getBlockedProviders()

Get list of currently blocked providers.

Returns: Array<{ name: string; purpose: string; categories: string[] }>

javascript
const blocked = window.FinsweetConsentProAPI.emergency.getBlockedProviders();
console.log('Blocked providers:', blocked);

blocked.forEach((provider) => {
  console.log(`${provider.name}: ${provider.purpose}`);
  console.log('Categories:', provider.categories);
});

emergency.testProviderMatch(url)

Test if a URL matches any blocking providers.

Parameters:

  • url (string): URL to test

Returns: BlockingProvider | null

javascript
const match = window.FinsweetConsentProAPI.emergency.testProviderMatch('https://www.googletagmanager.com/gtag/js');

if (match) {
  console.log('URL matches provider:', match.url);
  console.log('Categories:', match.categories);
  console.log('Tracker info:', match.trackerInfo);
}

Utility Methods

isReady()

Check if Consent Pro is fully initialized.

Returns: boolean

javascript
if (window.FinsweetConsentProAPI.isReady()) {
  // Safe to use all API methods
  const consent = window.FinsweetConsentProAPI.getConsent();
}

getState()

Get current reactive state snapshot.

Returns: { global: GlobalState; instances: Record<string, InstanceState> }

javascript
const state = window.FinsweetConsentProAPI.getState();
console.log('Is ready:', state.global.isReady);
console.log('Detected region:', state.global.detectedRegion);
console.log('Version:', state.global.version);
console.log('Debug mode:', state.global.debug);

getVersion()

Get Consent Pro version.

Returns: string

javascript
const version = window.FinsweetConsentProAPI.getVersion();
console.log('Consent Pro version:', version);

getDetectedRegion()

Get detected user region.

Returns: string

javascript
const region = window.FinsweetConsentProAPI.getDetectedRegion();
console.log('User region:', region);
// 'eu', 'us-ca', 'us-va', 'br', 'global', etc.

destroy()

Destroy the Consent Pro instance and clean up.

Returns: void

javascript
// Clean up when no longer needed
window.FinsweetConsentProAPI.destroy();

Next Steps