Developer Hooks

CookieRay exposes a small set of standard WordPress filters and actions. Add them to a child theme’s functions.php, a code-snippets plugin, or your own small plugin. They are for developers, and the code examples assume you are comfortable editing PHP.

Hook names and arguments here match the free plugin’s code. They are not a formal API promise, so test after plugin updates.

Filters

cookieray_should_load_banner

Return false to stop CookieRay from loading on the current request. Default true.

When it returns false, CookieRay outputs nothing on that page: no banner, no blocker script, no Google Consent Mode defaults, and no custom CSS. It also records no consent on that page.

In Strict mode, test any page you hide: a known tracker that WordPress enqueues there may stay blocked because the script that restores it after consent does not load.

add_filter( 'cookieray_should_load_banner', function ( $load ) {
	if ( is_page( 'landing-no-tracking' ) ) {
		return false;
	}
	return $load;
} );

The filter runs while the page head is being output, so WordPress conditional tags such as is_page() and is_singular() work. See the guide Hide the cookie banner on specific pages.

CookieRay Pro’s geo targeting uses this same filter.

cookieray_script_gate_allowlist

In Strict mode, CookieRay’s early blocker neutralizes scripts that match its tracker patterns as they are added to the page. This filter takes an array of host names that should be skipped by that early blocker. A script is skipped when its host contains one of the strings.

add_filter( 'cookieray_script_gate_allowlist', function ( $hosts ) {
	$hosts[] = 'js.example-widget.com';
	return $hosts;
} );

Only use it for scripts that are safe to load before consent. CookieRay Pro uses it for the Meta Pixel script, which loads with consent revoked.

cookieray_frontend_config

Filters the configuration array that CookieRay prints as window.cookieRayConfig for the banner script. Return the array, modified.

add_filter( 'cookieray_frontend_config', function ( $config ) {
	// Inspect or adjust $config here.
	return $config;
} );

The structure is internal and can change between versions. Prefer the admin settings when they cover your need.

cookieray_scan_urls

Filters the list of URLs the cookie scanner crawls. Add a URL the scanner would not find, or remove ones you want skipped. Keep URLs on your own domain.

add_filter( 'cookieray_scan_urls', function ( $urls ) {
	$urls[] = home_url( '/members/' );
	return $urls;
} );

cookieray_scan_sitemap_url_limit

The maximum number of URLs the scanner takes from your XML sitemap. Default 100. Return 0 to skip the sitemap.

add_filter( 'cookieray_scan_sitemap_url_limit', fn() => 40 );

Actions

cookieray_consent_logged

Fires after a consent record is saved. It receives one array with these keys:

add_action( 'cookieray_consent_logged', function ( $payload ) {
	if ( 'declined' === $payload['status'] ) {
		// For example, increment a counter of rejections.
	}
} );

Be careful about copying this data elsewhere. CookieRay stores it only in your own database by design. See Privacy & Data Handling.

Scan events

add_action( 'cookieray_scan_completed', function ( $scan_id ) {
	// For example, clear a cache or notify your team.
} );

Data attributes for manual blocking

You can also control blocking from your markup, without PHP. See Block a script yourself for the data-cookieray-category attribute.

Related

• Script Blocking
• Cookie Scanner
• Consent Logs