Skip to content

Consent API, checkout_started, ecommerce-spec properties, PHP error filter (0.10.0) - #3

Merged
ddavidebor merged 3 commits into
mainfrom
posthog-consent-funnel
Nov 20, 2026
Merged

ddavidebor merged 3 commits into
mainfrom
posthog-consent-funnel

Conversation

@ddavidebor

@ddavidebor ddavidebor commented Nov 20, 2026 •

Copy link
Copy Markdown

Why

A PostHog review of chinesecleavers.co.uk found four problems:

  • Session replay, autocapture and cookies ran with no consent (a UK PECR/GDPR risk).
  • checkout_started hadn't fired since 0.9.0, when it was renamed to order_placed, so the funnel insights went stale.
  • Ecommerce properties were thin.
  • About 1.2k $exception events a month were benign PHP warnings.

What changed

  • Consent (WP Consent API). New setting "Wait for cookie consent", off by default: with it off, tracking is exactly as before (cookies, replay, anonymous server events). When the owner turns it on:
    • Before consent: posthog-js runs with persistence: 'memory' and replay off. No PostHog cookie or localStorage is written.
    • After statistics consent: switches to localStorage+cookie and starts replay (if replay is enabled).
    • Withdrawing consent switches back.
    • The decision is made in the browser from the Consent API cookie, then from wp_listen_for_consent_change and wp_has_consent(), so LiteSpeed-cached HTML stays correct.
    • Registers with the Consent API (wp_consent_api_registered_*, only while the setting is on) and describes the cookie (wp_add_cookie_info).
    • Server-side events set no cookies. While consent is required, the server also reads the posthog-js cookie only with consent (Consent::may_read_posthog_cookie()), so a cookie left over from before consent was required isn't used.
  • checkout_started (spec: Checkout Started) fires once per cart, at the first checkout view, deduplicated by cart hash in the WooCommerce session. checkout_viewed still fires on every load; four insights use it.
  • Ecommerce-spec properties:
    • category/price on product events, plus price/value on add to cart.
    • value, revenue, shipping, tax, discount, coupon, currency and a products[] list on cart_viewed, checkout_viewed, checkout_started, order_placed and order_completed.
    • category/price/value/coupon on product_purchased, and coupon on coupon_applied.
    • value still means the order total, so revenue insights keep their meaning.
  • PHP error filter. posthog-php has no hook for dropping errors, so Core/Events/ErrorFilter wraps its error handler.
    • Drops notices, deprecations and the bot-triggered parse_str() nesting warning. They still go to PHP's normal log.
    • Both lists can be changed with filters: tagbridge_posthog_ignored_php_errors and tagbridge_posthog_ignored_php_error_levels.
  • PHPCS: sanitizes the forwarded-IP headers. These errors were what kept CI on main red.
  • Version bumped to 0.10.0, with readme, changelog and upgrade notice. Nothing deploys until a v0.10.0 tag is pushed.

Event names

Existing snake_case names are kept, and checkout_started is added to match the spec. Renaming product_added_to_cart → product_added and product_removed_from_cart → product_removed would break the live dashboard, so that is left to the owner.

Behaviour on upgrade

Nothing changes for visitors on upgrade: the owner chose not to use a consent banner, so consent gating is off by default. The site keeps setting cookies and running replay and autocapture with no consent prompt. That is the UK PECR/GDPR risk the review flagged, and it is now the owner's choice.

If the setting is turned on later without a Consent API banner, every visitor stays cookieless. Measured over the last 30 days, the PostHog cookie was the only id for 964 of 1,149 product_viewed events, and those server events would mostly stop. So install a banner first.

Tests

  • composer test:unit: 64 tests pass. New tests: ErrorFilterTest, ConsentTest (including the off-by-default check), and ConsentSnippetTest, which runs the generated snippet in Node against a fake posthog. SchemaTest updated.
  • composer lint is clean.

🤖 Generated with Claude Code

ddavidebor and others added 3 commits November 20, 2026 14:18
…ilter (0.10.0)

- WP Consent API: posthog-js runs cookieless with replay off until the
  visitor gives statistics consent, decided in the browser so cached pages
  work. New "Wait for cookie consent" setting, on by default.
- checkout_started fires once per cart at the first checkout view;
  checkout_viewed is unchanged.
- Ecommerce-spec properties (category, price, value, revenue, shipping,
  tax, discount, coupon, products) on product, cart and order events.
- ErrorFilter in front of posthog-php's error handler drops notices,
  deprecations and the parse_str nesting warning from PostHog.
- Sanitize forwarded IP headers (fixes PHPCS on main).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When "Wait for cookie consent" is on, Identity no longer reads the
ph_<key>_posthog cookie unless the WP Consent API (or, without it, an
explicit allow cookie) grants the statistics category. A cookie left over
from before consent was required is not read, so server and browser
events don't split one visitor. Order events are unaffected: they use the
WooCommerce session id or the id saved on the order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The shop runs without a consent banner, so 0.10.0 keeps today's
behaviour by default: cookies, session replay and cookie-stitched
server events for anonymous visitors. The Consent API support stays
behind the setting, and Tagbridge only registers with the Consent API
when the setting is on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ddavidebor
ddavidebor merged commit bdf51a2 into main Nov 20, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant