This is the SDK's whole compliance story. Nothing is transmitted unless BOTH gates below pass.
The gate logic lives in Consent\Gate; the reusable opt-in UI lives in
Consent\Notice. This document describes what that code does — if the
two ever disagree, the code is right and this file is stale.
The SDK is the only part of this project exposed to WordPress.org review. A consumer bundles this code into their own plugin and lists that plugin on WP.org; the reviewer is reading this consent logic, under that plugin's name. Every plugin that adopts the SDK inherits this exposure, which is why the gate is fail-closed at every step rather than merely "off by default."
The plugin author passes enabled in the array given to Tracker::init():
Tracker::init( array(
'hash' => 'a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4', // dashboard-issued, public; from the pasted snippet
'file' => __FILE__, // the MAIN plugin file; also the source of the name shown in the prompt
'enabled' => true, // Gate 1
) );The name the prompt shows an administrator is read from that file's Plugin Name: header, not passed
here — see SNIPPET.md. It can still be overridden with an explicit name.
In practice a consumer does not type this call by hand -- the dashboard generates it as part of the pasted
snippet described in SNIPPET.md, and hash/file are validated as required by Config. It is
shown here only to name gate 1 explicitly.
This is a decision made once, by the author, at build time — it says "this project is allowed to
telemeter at all." It is checked via Config::enabled(). If it is false (or omitted), the gate
never proceeds to ask the site administrator anything: Gate::granted() returns false and
Notice never renders the opt-in prompt (Notice::render() bails out early when
! $this->config->enabled()).
Even with the author's project enabled, nothing is sent until this site's administrator explicitly
agrees. The agreement is recorded per site, per plugin slug, in an option keyed by
Config::option( 'consent' ), as:
array( 'opted_in' => true, 'policy' => Gate::POLICY, 'at' => time() )Gate::site_opted_in() requires all of:
opted_inis truthy, and- the stored
policymatches the currentGate::POLICYconstant.
Bumping Gate::POLICY is not free: it re-prompts every site that had already agreed. So each bump is
recorded here with what changed and why it was material.
| Version | Change |
|---|---|
| 1 | The original wording. |
| 2 | States that this is a beta programme and that what is collected may change. Issue #40 is "consent (opt-in beta)" and PLANS.md §11.E calls it "Telemetry beta" with "supported beta events" — so the event set, the retention window and the endpoints are all still subject to change, which is material to the decision an administrator is being asked to make. Bumped while the SDK was still unreleased, deliberately: the re-prompt cost nothing then and would have cost every consumer's users a fresh prompt afterwards. |
Gate::POLICY is a version number for the consent text — what the admin was actually told before
they clicked "Allow." If that wording changes materially, an agreement recorded under the old
version is bumped to no longer count, and site_opted_in() returns false again even though
opted_in is still true in the stored record.
This is deliberate, not a bug: an admin who agreed to policy version 1 agreed to what version 1 said. If version 2 says something different, the admin agreed to different terms than the ones now in force — they have not agreed to this policy, so treating the old record as current consent would be transmitting on the strength of an agreement that was never actually made. The SDK asks again instead of assuming.
An opt-out record is versioned the same way (opt_out() also stamps the current POLICY), so
Gate::answered() — "has the admin been asked, either way?" — is also policy-scoped, and Notice
correctly re-prompts under a new policy rather than treating "declined under the old wording" as
"declined under the new one."
Gate::opt_out() does more than record the decision. It unschedules the flush, clears the local
queue, discards the stored token -- and calls Install::forget(), which deletes the local salt
the anonymous install ID is derived from (see
EVENTS.md).
That cleanup used to live one level up, in Tracker::handle_consent() — the handler behind the
built-in notice — and nowhere else. So the guarantee below held for an admin clicking "No thanks" and
not for a consumer calling $tracker->consent()->opt_out() from their own settings screen, which is
the very thing Tracker::consent() is exposed for. It now lives at the point the decision is
recorded, so every caller gets it.
That means state does not survive an explicit opt-out. Consequence, accepted deliberately: a site that opts out and later opts back in gets a new install ID, so a site that cycles consent counts more than once on the dashboard. The alternative -- keeping a live identifier on a site that explicitly said no -- was judged the worse trade: nothing should remain that could be correlated to data already reported, once an admin has declined.
define( 'CX_TRACKER_DISABLE', true );Checked first, unconditionally, before either consent gate. A site owner or host must be able to
stop all telemetry — for every plugin bundling this SDK on that install — without touching any
plugin's settings. If it's defined and truthy, Gate::granted() returns false immediately, and
Notice::render() also refuses to show the opt-in prompt while it's set.
/**
* @param bool $granted Whether transmission is permitted.
* @param string $plugin Consumer plugin slug.
*/
apply_filters( 'cx_tracker_consent', true, $plugin_slug );This filter is applied last in Gate::granted(), after the kill switch and both consent gates
have already passed. That ordering is the whole design point: by the time the filter runs, true
is only ever reached because every prior check already allowed it. A filter callback can therefore
only turn the result to false — it can never turn a false result (kill switch set, author not
enabled, admin not opted in) into true. It is a final veto for site owners and hosts, not a way
to grant consent the admin never gave.
public function track( $name, array $props = array() ) {
if ( ! $this->consent->granted() ) {
return false;
}
// ...
}Without consent, track() returns immediately — it does not write anything to the local queue,
let alone attempt to send. This holds even though queuing alone never touches the network.
Why buffering "for later" would be wrong. It might seem safer to queue events locally while consent is pending, and only send them once (if) the admin agrees. It is not safer — it is a violation on its own: it means the SDK is already holding data about the site (event names, timestamps, environment facts) that the administrator never agreed to it holding. Consent has to precede collection, not just transmission. A site that never opts in must have zero footprint from this SDK beyond the schema-less presence of the code itself.
Tracker::flush() re-checks consent independently, for the same reason from the other direction:
an admin can opt out after events were already queued (with consent, at the time), and that later
decision must win. On a lost consent check, flush() clears the queue and unschedules the cron job
rather than sending what's already sitting there.
handle_consent() does three things on choice=in beyond recording the answer: it backfills the
events the site could not report before it was allowed to (Lifecycle::on_consent() -- normally its
own install), then flushes synchronously, then schedules.
The synchronous flush is the point. ensure_scheduled() alone arms a single event jittered across
the whole interval, so opting in bought up to a day of silence before the site even obtained a
token -- longer on a low-traffic site, where WP-Cron runs only on incoming requests and may not run
at all. An administrator who clicks "Allow" and then sees nothing has no way to distinguish that
from a broken integration, and neither does anybody supporting them.
Unlike the deactivation flush, this one is not guarded on a non-empty queue. Registering is precisely what has to happen: it is the call that obtains the token and creates the install record, so it must run even when there is nothing queued to carry it.
The opt-out branch makes no request at all. Reaching the network on the way to recording a refusal is the one thing a refusal must never do.
The SDK ships a ready-made admin_notices prompt (Notice::render_prompt()) rather than leaving
each consumer to build their own. The reasoning: every consumer who hand-rolls a consent UI is a
chance to get it wrong — a pre-checked box, vague wording, a "no thanks" that's harder to find than
"allow" — and a botched consent flow is what gets that consumer's plugin pulled from
WordPress.org, not the SDK's. Shipping one honest, correct implementation means every consumer gets
it right by default.
The shipped prompt:
- names the categories of data that would be sent (install ID, plugin version, WP/PHP versions, locale, multisite flag, feature usage) and explicitly states what is never sent (site address, email, user accounts, content);
- is only shown when the author has enabled the project (
Config::enabled()) and the admin hasn't already answered for the current policy version (Gate::answered()); - is suppressed entirely when
CX_TRACKER_DISABLEis set, and per-notice by thecx_tracker_show_noticefilter — which is how a consumer moves consent onto their own settings screen without also switching telemetry off; - is not shown before
consent_afterhas elapsed, which is at minimum one second and never zero; - appears on site admin screens only. Consent is stored per blog, so a network admin screen has no per-site answer to collect;
- offers "Allow" and "No thanks" as two equally-weighted submit buttons in the same form area — no pre-selection, no nagging on every subsequent page load once answered.
Notice also renders two unrelated but similarly "ship it once" concerns: a server-supplied
deprecation/advisory message (the only channel that reaches a site running a years-old bundled copy
of the SDK), and a WP_DEBUG-only developer warning when Config fails validation. Both reach
network_admin_notices as well, because a network-activated plugin's only administrator may never
open a site admin screen.
A server-supplied notice is bounded in three ways the site controls rather than the server: it
expires (Notice::NOTICE_TTL, ninety days, when the response did not say when), it can be dismissed
per message, and it is deleted outright by an opt-out along with everything else in
Gate::discard_state(). A successful ingestion response carrying no notice retracts a stored one, so
the channel can be taken back and not only written to.
Tracker::hook() also registers Feedback\Deactivation, which shows a
dialog on this plugin's row in plugins.php asking why an administrator is deactivating. That dialog is not
gated by Gate::granted() -- it does not require gate 2, and does not even require the site to have ever been
asked. Its consent basis is the submission itself: the administrator reads an itemised disclosure of exactly what
will be sent and presses a button, which is contemporaneous, informed consent for that one transmission --
stronger than a general opt-in recorded months earlier, not weaker.
Two things from this document still apply to it: CX_TRACKER_DISABLE wins unconditionally over the modal too,
and gate 1 (Config::enabled()) still governs whether it can appear at all -- if the author never enabled the
project there is nowhere to report to. Full reasoning and the exact payload live in
FEEDBACK.md; do not assume anything said above about gate 2 or Notice applies to it.
- Pass
enableddeliberately (gate 1) — do not default it totruein a way that makes gate 2 the only real gate. - Do nothing else for the opt-in UI —
Tracker::hook()wiresNotice::render()intoadmin_noticesand theadmin_post_cx_tracker_consent_{slug}handler automatically onceTracker::init()is called on an admin request. The deactivation-feedback modal is wired the same automatic way (admin_footer-plugins.phpand its submit handler) -- see the section above andFEEDBACK.md. - Disclose the external service in
readme.txt. WordPress.org requires plugins that transmit data to a third-party service to declare it in the "External services" section ofreadme.txt, with what is sent, when, and a link to the service's terms. Seereadme-txt-block.mdfor a copy-paste block sourced fromEVENTS.md's field list. - Not bypass the gate — e.g. by calling
track()beforeTracker::init()has registered the consent hooks, or by wrappingCX_TRACKER_DISABLEin application logic that could unset it.
Because the SDK is the only part of this project a WP.org reviewer ever sees, everything above is not a suggestion — it is the difference between a consumer's plugin passing review and being rejected or pulled for an undisclosed external service.