API Reference
Complete reference for the Consent Pro V2 JavaScript API.
Table of Contents
- Global API Access
- Consent Management
- Visibility Control
- Event System
- Instance Management
- Storage API
- Cookies API
- Analytics API
- Configuration API
- Elements API
- Debug API
- Emergency Controls
Global API Access
Recommended: Callback Approach
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:
<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:
// 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.
Consent Management
getConsent()
Get the current global consent record.
Returns: ConsentRecord | null
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:
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 updateinstanceKey(string, optional): Specific instance to update
Returns: Promise<void>
// 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<void>
// 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
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<void>
// 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<void>
await window.FinsweetConsentProAPI.hideBanner();showPreferences(instanceKey?)
Show the preferences modal.
Parameters:
instanceKey(string, optional): Specific instance preferences to show
Returns: Promise<void>
// 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
window.FinsweetConsentProAPI.hidePreferences();visibility
Object containing visibility state methods.
visibility.getBannerState(instanceKey?)
Get current banner visibility state.
Returns: boolean
const isBannerVisible = window.FinsweetConsentProAPI.visibility.getBannerState();visibility.getPreferencesState(instanceKey?)
Get current preferences modal visibility state.
Returns: boolean
const isPreferencesVisible = window.FinsweetConsentProAPI.visibility.getPreferencesState();visibility.getFixedPreferencesState(instanceKey?)
Get current fixed preferences visibility state.
Returns: boolean
const isFixedPrefsVisible = window.FinsweetConsentProAPI.visibility.getFixedPreferencesState();visibility.getAllStates(instanceKey?)
Get all visibility states.
Returns: { banner: boolean; preferences: boolean; fixedPreferences: boolean }
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 namecallback(EventCallback): Function to call when event fires
Returns: () => void (unsubscribe function)
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 namecallback(EventCallback): Previously registered callback
Returns: void
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 namecallback(EventCallback): Function to call when event fires
Returns: () => void (unsubscribe function)
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)
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[]
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
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:
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<string, ConsentRecord>
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 }
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
// 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
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
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)
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 nameinstanceKey(string, optional): Specific instance
Returns: CookieDefinition[]
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:
{
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[]
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 upinstanceKey(string, optional): Specific instance
Returns: void
// 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 nameparameters(Record<string, unknown>): Event parameters
Returns: void
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 }
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<string, 'granted' | 'denied'>
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
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:
{
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
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
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
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:
{
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[] }
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
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
window.FinsweetConsentProAPI.debug.enableDebug();
// Console will now show detailed debug logsdebug.disableDebug()
Disable debug mode.
Returns: void
window.FinsweetConsentProAPI.debug.disableDebug();debug.getInternalState()
Get complete internal state for debugging.
Returns: DebugInternalState
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<DebugExportData>
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
// If something breaks, disable blocking
window.FinsweetConsentProAPI.emergency.disableBlocking();
console.warn('Auto-blocking disabled');emergency.unblockAll()
Immediately unblock all blocked elements.
Returns: void
// 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[] }>
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
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
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> }
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
const version = window.FinsweetConsentProAPI.getVersion();
console.log('Consent Pro version:', version);getDetectedRegion()
Get detected user region.
Returns: string
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
// Clean up when no longer needed
window.FinsweetConsentProAPI.destroy();Next Steps
- Events Documentation - Learn about all available events