Developer Reference: Hooks & Filters

SureCookie exposes a small, supported set of hooks and filters for the customizations site owners most often need: controlling when blocking applies, adjusting consent behavior, and reacting to consent events. This reference covers that public set, with a short example for each.

Add these snippets to your child theme’s functions.php or a code-snippets plugin. Test on a staging site first.

Note: The plugin contains other internal hooks that aren’t listed here. Those are implementation details, they can change between releases without notice, and they aren’t supported for external use. Stick to the hooks on this page.

Blocking and Banner Filters

surecookie_should_block_scripts

Controls whether script and content blocking runs for the current page request. Return false to skip blocking, for example for logged-in editors working on content.

add_filter( 'surecookie_should_block_scripts', function ( $should_block ) {
	if ( current_user_can( 'edit_posts' ) ) {
		return false;
	}
	return $should_block;
} );

surecookie_show_reconsent_button

Controls whether the surecookie_reconsent_button shortcode renders. Return false to hide it conditionally. The second argument is the shortcode’s attributes.

add_filter( 'surecookie_show_reconsent_button', function ( $show, $atts ) {
	return ! is_front_page();
}, 10, 2 );

A sibling filter, surecookie_show_reconsent_menu_item, does the same for the re-consent link added through a navigation menu.

surecookie_trust_proxy_headers

By default, SureCookie reads the visitor’s IP from the direct connection, which is the safe choice because proxy headers can be spoofed. If your site sits behind a trusted reverse proxy or CDN (such as Cloudflare), enable this so region-aware features see the real visitor IP.

add_filter( 'surecookie_trust_proxy_headers', '__return_true' );

Important: Only enable this when all traffic genuinely passes through your proxy. Otherwise visitors could spoof their location.

surecookie_bypass_blocking_for_editors

Available in SureCookie 1.5.0 and later.

From 1.5.0, script blocking automatically skips logged-in users who can edit content (the edit_posts capability), so frontend page builders keep working. Nothing needs to be enabled. This filter changes that default, and because it runs after the capability check, it can only narrow or disable the bypass – it can never extend it to visitors.

Keep blocking on for your whole team:

add_filter( 'surecookie_bypass_blocking_for_editors', '__return_false' );

Limit the bypass to Administrators only, so Editors and Authors see the site like visitors:

add_filter( 'surecookie_bypass_blocking_for_editors', function () {
	return current_user_can( 'manage_options' );
} );

To preview the visitor experience while logged in, no snippet is needed – open the site in a private window.

Consent Behavior Filters

surecookie_active_consent_model

Overrides the active consent model (opt-in or opt-out) for the current request, taking precedence over your settings and geo rules.

add_filter( 'surecookie_active_consent_model', function ( $model ) {
	return 'opt-in';
} );

Important: The consent model is a compliance decision. Override it only if you understand the legal implications for your audience. See Consent Models Explained (Opt-in vs Opt-out).

surecookie_wp_consent_api_category_map

Customizes how SureCookie’s categories map to WP Consent API types (see WP Consent API Compatibility for the default mapping).

add_filter( 'surecookie_wp_consent_api_category_map', function ( $map ) {
	$map['functional'] = 'functional';
	return $map;
} );

surecookie_searchable_post_types

Controls which post types appear in SureCookie’s page pickers, such as the scanner’s Select Pages field. Useful when your content lives in a custom post type.

add_filter( 'surecookie_searchable_post_types', function ( $post_types ) {
	$post_types[] = 'docs';
	return $post_types;
} );

Actions

Hook	Fires when	Typical use
surecookie_public_enqueue_scripts	The banner’s frontend assets are enqueued	Enqueue your own script alongside the banner
surecookie_scanner_results_updated	The detected cookie data is updated after a scan	Purge your page cache so the updated policy content is served
surecookie_consent_log_deleted	A consent log entry is deleted (receives the log ID and row)	Keep an external audit trail
surecookie_consent_log_deleted_bulk	Multiple log entries are deleted at once	Same, for bulk deletions
surecookie_wp_consent_api_initialized	The WP Consent API integration is ready	Register logic that depends on the integration
surecookie_multilingual_initialized	The WPML/Polylang integration is ready	Register logic that depends on translations

Example, clearing a cache when cookie data changes:

add_action( 'surecookie_scanner_results_updated', function () {
	if ( function_exists( 'wp_cache_flush' ) ) {
		wp_cache_flush();
	}
} );

Reacting to Consent in JavaScript

When a visitor makes or changes their choice, SureCookie dispatches a surecookie_changed event on window, with the consent data in event.detail.

window.addEventListener( 'surecookie_changed', ( event ) => {
	console.log( 'Consent updated:', event.detail );
} );

For checking consent state in a standardized way, activate the WP Consent API plugin and use its wp_has_consent() function; SureCookie keeps it in sync. See WP Consent API Compatibility.

Good Practices

• Prefer these supported hooks over CSS hacks or template overrides; they survive updates.
• Keep overrides narrow. A filter that returns a constant for every request (like forcing a consent model) affects compliance behavior site-wide.
• After adding a snippet, test as a fresh visitor in a private window and clear your caches.