Skip to content
Subset

For developers

Developer reference

How a theme or plugin will ask whether a category is consented, and the JavaScript event to wait on before loading your own script.

Asking, in PHP

The common case is a theme that wants to print an embed only if the visitor has consented to the category it belongs to.

<?php
// PLACEHOLDER — function name and category slugs are not final.
if ( subset_cookie_consent_given( 'marketing' ) ) {
	get_template_part( 'partials/retargeting-pixel' );
} else {
	get_template_part( 'partials/consent-required-notice' );
}

The second branch matters more than it looks. A blocked third-party embed leaves a hole in the page, and a hole with no explanation reads as a broken site. Printing a short “this content needs marketing cookies, here is how to allow them” is the difference between a site that respects a choice and a site that looks broken to anyone who made one.

Asking, in JavaScript

Consent can change without a page load, so the browser side is an event rather than a value read once.

// PLACEHOLDER — event name and detail shape are not final.
document.addEventListener("subset:consent-change", (event) => {
  const { analytics } = event.detail.categories;
  if (analytics) loadAnalytics();
});

Planned for 1.0.0Changelog

A PHP predicate and a browser event are both in the free version. Google Consent Mode signalling is part of Pro.

Registering your own script for blocking

A plugin that enqueues a tracker should declare which category it belongs to, so the site owner does not have to find it in an inventory and guess.

<?php
// PLACEHOLDER — action name and argument order are not final.
add_action( 'subset_cookie_register_scripts', function ( $registry ) {
	$registry->assign( 'my-plugin-tracker', 'analytics' );
} );

Declaring a category is not the same as asking to be allowed. The site owner can always override an assignment, and an override wins — the plugin that owns the site is the one the visitor is trusting.

What will deliberately not be extensible

The default cannot be changed to allow. There is no filter that makes an unassigned script run before consent, and there will not be one. That is the plugin’s entire premise; a setting that switches it off is a setting that makes the plugin lie about what it does.

The consent record is append-only. No API deletes or rewrites a stored decision. An audit trail that can be edited by the party being audited is not an audit trail. Erasure requests are handled by the plugin’s own export and erase integration with WordPress’s privacy tools, which is the route that is actually accountable.

Testing

The thing worth testing is not that the banner appears. It is that declining works:

  1. Load a page in a fresh profile and decline everything.
  2. Open the network panel and reload.
  3. Assert that no request goes to any third-party host.

That third step is the whole product, and it is the one an automated test can hold onto. Our own marketing site has exactly that test — see apps/web/e2e/marketing.spec.ts in the repository — for the same reason.