Frontend JavaScript API & Events (surecookieManager)

If you write your own frontend code, a custom widget, a map, a tracking snippet, it should respect your visitors’ consent just like the plugins SureCookie manages. For that, SureCookie exposes a small JavaScript API on every page where the banner is active: the window.surecookieManager object for reading consent state, and a set of events for reacting when it changes.

This reference covers that supported surface, reading state, listening for changes, and opening the preferences UI.

Note: The manager object contains other methods used internally by the banner itself. Those are implementation details, they can change between releases, and they aren’t supported for external use. Stick to what’s on this page.

Before You Start

SureCookie’s script loads in the footer, so guard your code against running too early. The simplest pattern:

window.addEventListener( 'load', () => {
	if ( ! window.surecookieManager ) {
		return; // Banner disabled or SureCookie not active.
	}
	// Your code here.
} );

Reading Consent State

isAllowed( category )

The method you’ll use most. Returns true when the given category ('essential', 'functional', 'analytics', 'marketing', or a custom category ID) is currently allowed. It handles the defaults correctly: before a visitor chooses, only essential is allowed under opt-in, while everything is allowed under opt-out.

if ( window.surecookieManager.isAllowed( 'functional' ) ) {
	initMyMapWidget();
}

hasConsent()

Returns true once the visitor has made a choice, and false while they haven’t responded yet.

getConsent()

Returns the stored consent object, with the visitor’s per-category preferences, the action they took, and a timestamp, or null before any choice.

getConsentSummary()

A convenience for debugging: returns an object with the action, timestamp, and the list of allowed categories, or the string 'No consent given' when there’s no choice yet.

Events

SureCookie dispatches these as CustomEvents on window:

Event	Fires when	event.detail
surecookie_changed	The visitor makes or changes their choice	The consent data
surecookie_applied	The current consent state has been applied to the page, on load and after every change	The consent data
surecookie_gcm_updated	Consent signals have been pushed to Google Consent Mode	The updated signals

Use surecookie_changed to react to decisions, and surecookie_applied when you also want to run for returning visitors whose stored consent is applied on page load:

window.addEventListener( 'surecookie_applied', () => {
	if ( window.surecookieManager.isAllowed( 'analytics' ) ) {
		startMyCustomAnalytics();
	} else {
		stopMyCustomAnalytics();
	}
} );

This pattern covers every case with one listener: first-time choices, changed preferences, and returning visitors.

Opening the Preferences UI

To let visitors reopen their cookie preferences from your own element, add the data-surecookie-reconsent attribute to any link or button:

<button data-surecookie-reconsent="true">Cookie Preferences</button>

This is the same mechanism the surecookie_reconsent_button shortcode uses. See Shortcodes Reference (Re-consent, Policy Content).

Don’t Set Consent Programmatically

The manager includes methods the banner itself uses to record, change, and clear consent. Don’t call them from your own code.

Important: Consent is only valid when it comes from the visitor’s own action on the banner. Recording or clearing consent programmatically undermines its validity and your compliance posture. If you need consent recorded differently, that’s a banner-configuration question, not a JavaScript one.

For testing your integration as a fresh visitor, use a private browsing window instead of clearing consent in code.

Good Practices

• Gate your own scripts with isAllowed() and re-check inside a surecookie_applied listener, so they start and stop as consent changes.
• For a standardized, plugin-neutral way to check consent, the WP Consent API works alongside this API; SureCookie keeps it in sync. See WP Consent API Compatibility.
• Server-side customization belongs in hooks, not JS. See Developer Reference: Hooks & Filters.