PHP filters, actions and REST API: Cookie Rocks documentation

Written for Cookie Rocks 2.9.14, checked on 5 November 2026. The current version is 2.11.2: some details may have changed.

What you can do here

Change the texts, the categories and the catalogue of tools and cookies that Cookie Rocks knows.
Tune the banner of Cookie Rocks Pro: its configuration, Google Consent Mode, optimisation plugins.
Read the register of proofs from another tool, through the REST API.

This page lists every PHP hook and REST route of Cookie Rocks, and says which plugin provides each one. Add your code to a small plugin of your own, or to the functions.php file of your child theme. All hook names start with cookie_rocks_.

At a glance

Hook	Type	Plugin	Use
`cookie_rocks_categories`	Filter	Audit and Pro	Titles and descriptions of the categories
`cookie_rocks_services`	Filter	Audit and Pro	The catalogue of known tools and their cookies
`cookie_rocks_news`	Filter	Audit	Entries of the “News and alerts” feed
`cookie_rocks_check_home`	Filter	Audit	The daily check of your home page
`cookie_rocks_update_url`	Filter	Audit, outside WordPress.org	Where the Audit looks for updates
`cookie_rocks_feed_keys`	Filter	Audit	Tests only
`cookie_rocks_after_page`	Action	Audit	Your own content after each Cookie Rocks admin page
`cookie_rocks_texts`	Filter	Pro	Texts of the banner and the details
`cookie_rocks_config`	Filter	Pro	The configuration sent to the banner
`cookie_rocks_gcm_map`	Filter	Pro	Which category drives each Google Consent Mode signal
`cookie_rocks_no_optimize`	Filter	Pro	Attributes that keep optimisation plugins away from the banner scripts
`cookie_rocks_protected_page`	Filter	Pro	Pages where payment and anti-fraud tools load without consent
`cookie_rocks_account`	Action	Pro	A visitor signed in with an account managed outside WordPress
`cookie_rocks_banner_update_url`	Filter	Pro	Where Cookie Rocks Pro looks for updates
`cookie_rocks_licence_keys`	Filter	Pro	Tests only
`cookie_rocks_dropbox_app`	Filter	Pro	Tests only

Other hooks link the two plugins together. They are listed at the end of this page, under Internal hooks. They may change from one version to the next: do not build on them.

Filters of the Audit and Pro

cookie_rocks_categories

Changes the categories shown to people. The Audit applies it to its cookie policy and its admin pages. Cookie Rocks Pro applies it to the details panel of the banner and to its cookie policy.

Parameter: array $categories, a list of categories in display order, each with id, locked (true for “Necessary”), title and description. The ids are necessary, preferences, statistics, marketing, and audience when the site uses an audience measurement exempt from consent.
Returns: the list of categories.

add_filter( 'cookie_rocks_categories', function ( $categories ) {
	foreach ( $categories as &$category ) {
		if ( 'statistics' === $category['id'] ) {
			$category['description'] = 'Counting visits, so we know which pages help you.';
		}
	}
	return $categories;
} );

Change titles and descriptions only. Do not add, remove or rename ids: the banner knows only these ones. Your text is shown as written, in every language: use the translation functions of WordPress for a multilingual site.

cookie_rocks_services

Changes the catalogue of known tools and their cookies: add, change or remove a tool. Each plugin has its own copy of the catalogue and applies the filter to it, so one filter changes both. A tool you add is recognised in the analysis of the Audit. With Cookie Rocks Pro, it is also held until consent, and listed in the details and the cookie policy once it is seen on a page.

Parameter: array $services, the catalogue, keyed by tool id. On a site without Google Ads, the Google tag (google-tag) arrives in its form without advertising: named “Google Analytics (gtag.js)”, in the statistics category.
Returns: the catalogue.

Key	Content
`name`	Name of the tool.
`provider`	Company behind it. Empty for a tool that stays on your site: your site is then named as provider.
`category`	`necessary`, `preferences`, `statistics` or `marketing`. Two categories joined by a comma (`statistics,marketing`) mean either one is enough.
`patterns`	Pieces of text searched in script addresses, inline scripts and frame addresses. Case-sensitive.
`purpose`	One key: `tags`, `analytics`, `analytics_ads`, `ads`, `recordings`, `video`, `map`, `antispam`, `attribution`, `analytics_nocookie`, `data_hub`, `crm`, `ads_shown`, `recommendations`, `email_marketing`, `chat`, `social`, `audio`, `booking`, `calendar`, `form`, `payment`, `audience_ads`, `push`, `sharing_ads`, `widgets`, `reviews`, `accessibility`, `translation`, `site_search`, `performance`, `errors`, `ab_testing`, `signup_forms`, `comments`, `affiliate`, `documents`, `login`, `fonts`, `avatars`, `images`, `fraud`. The sentence shown to visitors comes from it, in their language.
`cookies`	Pairs of name and duration, such as `array( '_ga', '2y' )`. A duration is a number followed by `y`, `mo`, `d`, `h` or `min`; anything else reads “session”. `*` stands for any characters in a name.
`privacy`	Address of the privacy policy of the provider.
`api`	Optional: `google`, `clarity`, `uet`, `matomo` or `woocommerce`. These tools receive the visitor’s choice through their own signal instead of being blocked. Google tools are held only in the basic mode of Consent Mode.
`embed`	Optional: `video`, `map`, `audio`, `social`, `calendar`, `form`, `comments`, `search`, `document`, `login` or `chat`. The frame keeps its place and shows a short request with a button until consent. The button names the content (“Load the video”, “Load the map”…), or reads “Load the content” for `chat`.
`gtm`	Optional: `true` for a tool often loaded through Google Tag Manager, so you can declare it by hand.
`reload`	Optional: `true` when the tool must be there when the page loads, as a captcha. The page reloads after consent only for the tools listed in the `reload` key of `cookie_rocks_config`: `recaptcha` and `hcaptcha` by default. The fields already typed in their forms are kept.
`hosts`	Optional: other domains the tool calls once loaded. The analysis attributes these calls to the tool instead of listing them as unknown.

Order matters: when the patterns of several tools match one script, the first tool in the catalogue decides. A tool added with $services['id'] = … comes last.

add_filter( 'cookie_rocks_services', function ( $services ) {
	$services['my-chat'] = array(
		'name'     => 'My Chat',
		'provider' => 'My Chat Inc.',
		'category' => 'preferences',
		'patterns' => array( 'widget.mychat.example/loader.js' ),
		'purpose'  => 'chat',
		'cookies'  => array( array( 'mychat_id', '1y' ) ),
		'privacy'  => 'https://mychat.example/privacy',
	);
	return $services;
} );

Filters and action of the Audit

cookie_rocks_news

Changes the entries that Cookie Rocks adds to the News and alerts feed of the Overview page, for example to add a note from your agency.

Parameter: array $entries, each with id (unique), from (first day shown, YYYY-MM-DD) and message. Optional: link, with tab (the id of a Cookie Rocks page, such as consent) and label; banner set to true to show the entry only when Cookie Rocks Pro is installed.
Returns: the entries.

An entry appears once, from its date. It is skipped when its date is more than 90 days old or before Cookie Rocks was installed. Once closed by an administrator, it does not come back.

add_filter( 'cookie_rocks_news', function ( $entries ) {
	$entries[] = array(
		'id'      => 'agency-2026-10',
		'from'    => '2026-10-15',
		'message' => 'Your agency checked the cookie settings of this site.',
		'link'    => array( 'tab' => 'obligations', 'label' => 'See the obligations' ),
	);
	return $entries;
} );

cookie_rocks_check_home

Turns off the daily check of your home page from your server. This check runs only while the banner of Cookie Rocks Pro is active and turned on. Some hosts block the requests of a site to itself: if the check keeps failing, turn it off.

Parameter: bool $check, true by default.
Returns: false to skip the check.

add_filter( 'cookie_rocks_check_home', '__return_false' );

cookie_rocks_update_url

Changes the address of the file where the Audit looks for its updates. It exists only in the copies of the Audit served by the Cookie Rocks update server. The copy from WordPress.org gets its updates from WordPress.org and does not have this filter.

Parameter: string $url, the address of the update information file.
Returns: the address.

cookie_rocks_feed_keys

For tests only. Changes the public keys that check the signature of the two daily lists of the Cookie Rocks legal watch (alerts and law fact sheets). A list whose signature does not match is ignored. Do not use it on a live site.

Parameter: array $keys, the public keys, in base64.
Returns: the keys.

cookie_rocks_after_page (action)

Runs after each Cookie Rocks admin page, outside the settings form. Use it to add your own notes or links for the administrators of the site.

Parameter: string $tab, the page shown, such as overview, obligations, laws or services.

The example adds a note under the Overview only.

add_action( 'cookie_rocks_after_page', function ( $tab = '' ) {
	if ( 'overview' === $tab ) {
		echo '<p>Questions about cookies? Contact your agency.</p>';
	}
} );

Filters of Cookie Rocks Pro

These filters exist only with Cookie Rocks Pro, because they act on its banner. The banner is the same for every visitor of a language, so that it works with page caches: keep what your filters return the same for every visitor.

cookie_rocks_texts

Changes the texts of the banner and the details panel. It runs after the texts you wrote on the Appearance page are applied, in the language of the page.

Parameter: array $texts, keyed by: bannerLabel, title, text, acceptAll, rejectAll, customize, privacyLink, policy (label of the link in the banner), panelTitle, panelText, save, close, alwaysOn, gpcNotice, saved, widgetLabel, gpcHonored, onlyNecessary, textHeld (only when the banner text says that the site uses only necessary cookies), saleTitle, saleText, saleOptOut, saleDone, saleMore, saleLink (the “Do Not Sell or Share” view, for sites that address the United States), childConfirm (sites for children), servicesLink (contains %d), formRestored, noCookies, consentId (contains %s).
Returns: the texts.

add_filter( 'cookie_rocks_texts', function ( $texts ) {
	$texts['title'] = __( 'Cookies?', 'my-theme' );
	return $texts;
} );

For the eight main texts, the Appearance page is simpler and works per language. Keep “Reject all” as clear as “Accept all”.

cookie_rocks_config

Changes the full configuration of the banner, before Cookie Rocks shortens it for the page.

Parameter: array $config, with readable keys: assets, ver, layout, position, theme, accent, accentText, accentInk, accentDark, radius, shadow, widget, gpc, policy (address of the cookie policy, or of the privacy policy when no cookie policy page is set), siteName, emphasis, gap, categories, services, svc, reload, texts, purge, and when they apply widgetPlace, widgetImage, optout, site, geo, profiles, profileWidget, geoPreview, preview, debug. The address of the register of proofs and the version of the texts are added after the filter.
emphasis is 1 when “Accept all” is highlighted, null otherwise. gap is the distance from the screen edges, in pixels (0 to 40). It is null when the value stays at 20, the default of the stylesheet.
Returns: the configuration.

add_filter( 'cookie_rocks_config', function ( $config ) {
	$config['siteName'] = 'Example Shop';
	return $config;
} );

Prefer the settings pages and the other filters when they cover your need: the keys of this array follow the inner workings of the banner.

cookie_rocks_gcm_map

Changes which Cookie Rocks category drives each Google Consent Mode signal.

Parameter: array $map, signal => category. Default: ad_storage, ad_user_data and ad_personalization => marketing; analytics_storage => statistics; functionality_storage and personalization_storage => preferences; security_storage => necessary.
Returns: the map.

add_filter( 'cookie_rocks_gcm_map', function ( $map ) {
	$map['functionality_storage'] = 'necessary';
	return $map;
} );

cookie_rocks_no_optimize

Changes the attributes added to the scripts of Cookie Rocks Pro so that optimisation plugins do not delay, combine or minify them. The script in the page head must run before the Google tags. Cookie Rocks always adds data-cfasync="false", for Rocket Loader of Cloudflare. It adds the other attributes only for the optimisation plugins it detects: WP Rocket, LiteSpeed Cache, Autoptimize, Jetpack Boost, WP-Optimize, WP Fastest Cache, Swift Performance and NitroPack. Use the filter for a tool it does not detect, such as a module of your server.

Parameter: array $attributes, attribute => value. The value true writes the attribute without a value.
Returns: the attributes.

add_filter( 'cookie_rocks_no_optimize', function ( $attributes ) {
	$attributes['data-no-optimize'] = '1';
	$attributes['data-pagespeed-no-defer'] = true;
	return $attributes;
} );

cookie_rocks_protected_page

Says whether the current page is a protected page: a page where the visitor pays, checks out or manages an account. By default, these are the cart, checkout and account pages of WooCommerce, and the checkout of Easy Digital Downloads.

On a protected page, payment and anti-fraud tools load without consent. On the other pages, they wait for consent: Fingerprint always, and the other payment and anti-fraud tools when Load payment and anti-fraud scripts without consent only on cart, checkout and account pages is ticked on the Consent page.

Parameter: bool $page, true on a cart, checkout or account page.
Returns: true for a protected page.

add_filter( 'cookie_rocks_protected_page', function ( $page ) {
	return $page || is_page( 'donate' );
} );

Decide from the page only, never from the visitor, so that cached pages stay right.

cookie_rocks_account (action)

When the site honours the Global Privacy Control signal, a refusal follows the visitor’s account, so it also applies in the visitor’s other browsers. WordPress accounts (WooCommerce, memberships…) need nothing. If your customers sign in with another system, call this action on each page they see while signed in, before anything is printed (on init, for example), with their account ID. Only a fingerprint of the ID is kept.

Parameter: string|int $customer_id, the ID of the signed-in account.

add_action( 'init', function () {
	if ( my_customer_is_signed_in() ) {
		do_action( 'cookie_rocks_account', my_customer_id() );
	}
} );

cookie_rocks_banner_update_url

Changes the address where Cookie Rocks Pro asks for its updates, for tests or another hosting. Updates are looked for only with a valid key, and every file is still checked against the Cookie Rocks signature before it is installed (see Licence). To move every call about the key, not only updates, define the COOKIE_ROCKS_API constant instead (see Developers).

Parameter: string $url, the update/info address of the Cookie Rocks key service, with the key and the domain of the site as parameters.
Returns: the address.

cookie_rocks_licence_keys

For tests only. Changes the public keys that check the signed answer of the Cookie Rocks key service. An answer whose signature does not match is refused, and the key is not confirmed. Do not use it on a live site.

Parameter: array $keys, the public keys, in base64.
Returns: the keys.

cookie_rocks_dropbox_app

For tests only. Changes the public key of the Cookie Rocks app on Dropbox, used when the register of proofs is copied to Dropbox. An empty value removes Dropbox from the choices. Do not use it on a live site.

Parameter: string $app, the public key of the app.
Returns: the key.

REST API

The namespace is cookie-rocks/v1. The three routes come with Cookie Rocks Pro. The Audit alone has no REST route.

Route	Access	Plugin	Use
`POST /wp-json/cookie-rocks/v1/proof`	Public	Pro	The banner records a proof at the moment of a choice. Returns 204 on success. Returns 400 when the data is not valid or larger than 2 kB, after 30 proofs in 10 minutes from one IP address (300 behind Cloudflare), or above 600 proofs a minute for the whole site. The address is used hashed for this limit, and never stored. When proofs are turned off, the request is ignored and returns 204.
`GET /wp-json/cookie-rocks/v1/proofs`	Administrators (users who can manage options), for example with an application password	Pro	Reads the register of proofs, newest first.
`GET /wp-json/cookie-rocks/v1/geo`	Public	Pro	With Rules by country turned on, answers which rules apply to the visitor. The banner uses it only when the faster file of the plugin cannot answer. Never cached. Returns 404 when Rules by country is off.

Parameters of GET /proofs: from and to (YYYY-MM-DD), consent (the id of one choice), limit (1000 by default, 100000 at most) and offset. Each row has id, consent_id, created (UTC), expires, action (accept, reject, custom, service, or gpc for a refusal sent by the browser without a click), categories, services, revision, text_version, locale, gpc, and with Rules by country profile, country and country_source.

curl -u "admin:APPLICATION PASSWORD" "https://example.com/wp-json/cookie-rocks/v1/proofs?from=2026-10-01&to=2026-10-31"

Create the application password in Users, Profile, Application Passwords, for an administrator. See Proof of consent for what each field means.

Internal hooks

The Audit holds the Cookie Rocks menu; Cookie Rocks Pro adds its pages and blocks to it through these hooks. They are listed so that you know what you see in the code. They may change without notice.

Hook	Type	Applied by	Role
`cookie_rocks_tabs`	Filter	Audit	Pages of the menu; Pro adds its own.
`cookie_rocks_page_{page}`	Action	Audit	Shows a page added by Pro, such as `cookie_rocks_page_appearance`.
`cookie_rocks_setup_steps`	Filter	Audit	Steps of the setup card; Pro adds Google and Appearance.
`cookie_rocks_overview_start`, `cookie_rocks_overview_tools`	Actions	Audit	Blocks of the Overview page: the key card, the update card, the link to the banner.
`cookie_rocks_version_line`	Action	Audit	The Check for updates link next to the version number.
`cookie_rocks_admin_notices`	Action	Audit	Messages of Pro after an action.
`cookie_rocks_developers_css`, `cookie_rocks_developers_code`	Actions	Audit	Sections of Pro on the Developers page.
`cookie_rocks_cookies_form`, `cookie_rocks_cookie_items`, `cookie_rocks_cookie_fields`	Filters	Audit	Classification of the site’s cookies on the Cookies page.
`cookie_rocks_cookies_table_end`, `cookie_rocks_cookie_tools`, `cookie_rocks_gtm_tool`	Actions	Audit	Tools of Pro on the Cookies page: adding a cookie by hand, recording a visit, declaring what Google Tag Manager loads.
`cookie_rocks_checked`	Filter	Audit	Dates of the last checks on the Cookies page.
`cookie_rocks_services_settings`	Action	Audit	Cookie Rocks Pro does not use it.
`cookie_rocks_locked`	Filter	Audit	Whether the settings of the banner are locked (no valid key).
`cookie_rocks_feed_key`	Filter	Audit	The access key sent with the daily lists of the legal watch; Pro sends its licence key.
`cookie_rocks_identity`	Filter	Audit	Name and logo in the header; a Community key changes them.
`cookie_rocks_brand_logos`	Filter	Audit	Logos of the tools; the Audit shows initials, Pro adds the logos.
`cookie_rocks_old_plugin`	Filter	Audit	A plugin that Cookie Rocks Pro replaces, still installed.
`cookie_rocks_checks`	Filter	Audit	Checks of the Overview; Pro adds those of Rules by country.
`cookie_rocks_proof_copy`	Filter	Audit	Where a copy of the register of proofs is kept; Pro answers when the copy is turned on.
`cookie_rocks_page_seen`	Action	Audit and Pro	A page was produced, with the tools recognised in it.
`cookie_rocks_services_found`	Action	Pro	Tools were seen on the pages for the first time; the Audit adds them to the feed.
`cookie_rocks_event`	Action	Pro	Adds an entry to the feed of the Overview page.
`cookie_rocks_daily`	Scheduled event	Audit and Pro	The daily check: home page, legal watch, key, country database, cleaning of old proofs.
`cookie_rocks_thumbnail`	Scheduled event	Pro	Copies a video thumbnail to your site.
`cookie_rocks_proof_delivery`	Scheduled event	Pro	Copies the register of proofs to the storage you chose, every day or every week.

Next step: JavaScript API and events.

Cookie Rocks helps you find your way through cookie and privacy rules. It does not replace a lawyer’s advice.