Skip to content

[00] Subset Opt-Out, For developers

How Subset Opt-Out works

Last updated

The head script, GPC handling, the text/plain blocking engine and why Subset Opt-Out prints the same HTML for every visitor, with the hooks for each.

This page explains how Subset Opt-Out holds tracking scripts back and releases them in the browser. It covers the two scripts it prints in <head>, the blocking engine, and why the HTML stays the same for every visitor. For the API and hook reference, see the developer reference.

What it prints in the head

Subset Opt-Out adds three things at the top of <head>, at wp_head priorities lower than WordPress’s default of 10:

PriorityElementWhat it is
0<script type="application/json" id="subset-cm-config">The site’s settings as inert JSON. The browser doesn’t run it.
1<script id="subset-cm-head">The head script, printed inline from assets/js/build/head.js. It creates window.subsetCM.
2<script id="subset-cm-consent-mode">Google Consent Mode v2 defaults and the visitor’s update, read from subsetCM.get().

The main bundle, assets/js/build/main.js, is enqueued in the head with the defer strategy. It adds onChange() and setRegime() to the API and runs the features that can wait, including the loader that releases held scripts.

The config block comes from the Config class and passes through the subset_cm_frontend_config filter. It holds the regime (optout by default), whether an opt-out also covers analytics, and a blocking.services section listing each enabled service’s category, the cookies to delete on opt-out and its own consent calls. The JSON is encoded with <, >, & and quotes escaped, so a value can’t close the element.

The head script

The head script is the first script WordPress prints. A theme that echoes a script above wp_head() in header.php, or a callback on wp_head at priority 0 or lower, still runs before it, and no plugin can change that. Hold those scripts with data-subset-cm-category or move them below wp_head().

The script reads the config block, then reads the subset_cm_consent cookie. The cookie value is JSON with three keys: a version v, a source (user or gpc) and categories, where functional is always true and statistics and marketing are true or false. A value that doesn’t parse, has an unknown version or source, or has a non-boolean category is ignored as if there were no cookie.

If there’s no usable cookie and navigator.globalPrivacyControl is true, the script records an opt-out with source gpc and writes the cookie at once, with no click. Under the default optout regime, an opt-out denies marketing, and statistics too when Opt-out also covers analytics is on. A visitor with no cookie and no GPC signal gets the regime’s default: everything allowed under optout, only functional under optin.

The cookie is set from JavaScript: path=/, SameSite=Lax, Secure on HTTPS, and a max-age of 31,536,000 seconds (12 months). It isn’t HttpOnly, because the browser is where it’s written.

The built head script has a budget of 1,536 bytes, minified and before gzip, because it’s printed inline on every page. Anything that can wait goes in the deferred bundle instead.

The blocking engine

Subset Opt-Out holds a script by rewriting it on the server into inert markup:

<script
  type="text/plain"
  data-subset-cm-category="marketing"
  data-subset-cm-service="meta-pixel"
  src="…"
  async
></script>

A browser doesn’t run a text/plain script. Every other attribute is kept, so src, async, defer, id and nonce survive. A module script keeps its type in data-subset-cm-type.

Three routes to the same rewrite

The Blocker class catches scripts three ways, from most to least exact:

  1. The script_loader_tag filter, for a script enqueued by handle or URL. The handle’s before and after inline code is held with it.
  2. The wp_script_attributes and wp_inline_script_attributes filters, for scripts printed with wp_print_script_tag() and wp_print_inline_script_tag().
  3. An output buffer started on template_redirect at priority PHP_INT_MAX, for tags a theme or plugin echoes by hand.

The buffer starts as late as possible so it sees the page before optimisers that also buffer on template_redirect defer, move or inline the tags. It only starts on front-end HTML requests, and only when at least one service is enabled. It skips any response whose Content-Type isn’t HTML. Return false from subset_cm_blocking_buffer to turn the buffer pass off, or from subset_cm_blocking_applies to turn blocking off on a request, for example in a page builder’s editor.

The routes overlap. A script that’s already held has data-subset-cm-category, so later routes skip it.

Matching scripts to services

A service is defined by label, category (statistics or marketing) and at least one of:

  • handles: WordPress script handles, matched exactly.
  • src: substrings of the script’s URL.
  • inline: substrings of inline code.

URL and inline matching are case-insensitive, and the first matching service wins. Matching depends on the definitions only, never on the visitor.

Eight services are built in, from data/services.json: Meta Pixel, TikTok Pixel, Google Ads, LinkedIn Insight Tag, Pinterest Tag, X Pixel, Microsoft UET and Snap Pixel, all in marketing. They’re added to the subset_cm_services filter at priority 5, so your own callback at the default priority can edit or remove them. Rules saved in the settings screen, up to 100, are added at priority 6, and you can add rules from code with subset_cm_blocking_rules. A built-in service listed in the disabled_services setting isn’t matched.

Some scripts are never held: the plugin’s own (an id starting subset-cm, or inline code containing subset_cm_consent), anything with data-subset-cm-ignore, and scripts whose type isn’t JavaScript, such as JSON or an import map. Scripts inside comments, <noscript>, <textarea> and <style> are skipped.

Subset Opt-Out holds <script> elements only. It doesn’t rewrite iframes.

Releasing held scripts

The loader in the deferred bundle finds every script[data-subset-cm-category] and checks subsetCM.has( category ). For each allowed one, it builds a live <script> with the same attributes, restores the original type, and swaps it in. It works in document order: an external script without async finishes loading before the next held script starts, because inline code often needs the library above it.

When subset-cm:consent-changed fires, the loader runs again:

  • A category that’s now allowed: its held scripts run, and the service’s grant call runs if it has one.
  • A category that’s now denied: the service’s revoke call runs (for Meta Pixel, fbq( 'consent', 'revoke' )), and its cookies are deleted across the domain and path variants they might have been set with. A name ending in *, such as _gcl_*, is a prefix.

A script that already ran can’t be undone. If any did, subsetCM.needsReload becomes true and subset-cm:reload-needed fires with the denied categories.

Cache safety

Every visitor gets the same HTML, so a full-page cache can store one copy of each page and serve it to everyone. The server never reads the consent cookie, the current user, the URL or the time when it builds the page:

  • Scripts are held for every visitor, whether or not they’ve opted out. The browser decides which ones run.
  • The config block is built from settings only. The subset_cm_frontend_config, subset_cm_services and subset_cm_blocking_applies filters carry the same rule: their result must not depend on the visitor or the request.
  • The head script is read from a file, so it’s identical on every request. It adds no nonce of its own, because a per-request nonce would make pages differ. It goes through wp_print_inline_script_tag(), so a security policy plugin can add one with wp_inline_script_attributes.
  • The plugin sends no Vary header and sets no cookie from PHP when it renders a page.

The Reader class reads a visitor’s consent on the server for server-side integrations such as the WP Consent API. It isn’t used to change page output.

Pro’s by-region opt-in follows the same rule. The server prints the optin regime for every visitor. In the browser, a visitor known to be outside the chosen regions is switched to optout with subsetCM.setRegime(), which changes the default for that page view without writing a choice. The browser gets the country from a separate request to /wp-json/subset-cookie-manager-pro/v1/geo, once per session. That response is sent private, no-store and varies on the geo headers, so no cache keeps it.

Optimisers

Caching plugins often delay, combine or minify JavaScript, which would break the order the scripts above depend on. Subset Opt-Out marks its own tags with data-cfasync="false", data-no-optimize, data-no-defer and nowprocket, and adds itself to the exclusion filters of WP Rocket, LiteSpeed Cache, Autoptimize, Perfmatters and SiteGround Optimizer. Held scripts are text/plain, which most optimisers skip. For the two combiners that ignore an external script’s type, SiteGround Optimizer’s JavaScript combine and WP Rocket’s file combine, the held services’ URLs and handles are excluded too.