Skip to content

Add PostHog and GA4 for logged-out visitors outside the EEA/UK - #2540

Draft
alexleventer wants to merge 3 commits into
mainfrom
docs-analytics-consent
Draft

alexleventer wants to merge 3 commits into
mainfrom
docs-analytics-consent

Conversation

@alexleventer

@alexleventer alexleventer commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Part of superfly/docs-tracking#304. Depends on superfly/ui-ex#5903. #security approved it (thread); merge that first. Until it ships, this script fails closed and loads nothing.

Adds PostHog and GA4 to docs.fly.io for logged-out visitors outside the EEA/UK. There is no consent banner on docs:

Visitor fly.io docs.fly.io
Outside EEA/UK, logged out No banner, tracked No banner, tracked
EEA/UK, logged out Banner, tracked after Accept No banner, Plausible only
Logged in Not tracked Not tracked

A docs banner would keep its own consent record (per-origin localStorage) while PostHog and GA4 cookies are shared on .fly.io, so the two sites' choices would disagree. If EEA docs data matters later, the follow-up is a shared .fly.io consent cookie that docs reads, so docs can honor an Accept made on fly.io.

What fly-analytics.js does:

  • It's one self-contained file, because Mintlify runs content-dir JS in no guaranteed order. It loads the vendored PostHog bundle from fly.io/static/javascripts/posthog.js itself, so it doesn't depend on auth-nav.js.
  • It fetches https://fly.io/api/consent-scope with credentials. It only loads anything when the answer is "not EEA/UK, logged out". Fetch failures (Mintlify previews, mint dev, network errors) load nothing.
  • PostHog uses capture_pageview: "history_change", because Mintlify navigates client-side. Internal referrers are rewritten to $direct, as on landing and ui-ex.
  • GA4 goes through the analytics.fly.io proxy, same as fly.io. No GTM, because ui-ex dropped it for double-reporting conversions to GA4.
  • docs.json gets a Legal footer linking the Privacy Policy.

Not tested in a browser yet: the CORS change has to be live first. To check after it ships, load docs.fly.io logged out from outside the EEA/UK and confirm posthog.fly.io requests and $pageview on navigation. Logged in, or through an EEA edge, there should be none.

Open: GA4 counts a page_view per full load. Unless the GA4 stream's "page changes based on browser history events" setting is on, client-side docs navigations are undercounted in GA4.

Plausible is unchanged. CSP directives for Mintlify are still a separate open item.

🤖 Generated with Claude Code

Ports landing's posthog-consent.js to Mintlify as one self-contained
file: it loads the vendored PostHog bundle from fly.io, asks
fly.io/api/consent-scope for the EEA/UK and logged-in checks, and shows
the same banner. Pageviews are captured on client-side route changes.
A Legal footer adds a Cookie preferences link to reopen the banner.

Refs superfly/docs-tracking#304

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Oct 8, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
fly-io 🟢 Ready View Preview Oct 9, 2026, 10:41 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

- A stored Reject now holds outside the EEA/UK too (the footer link is shown to everyone).
- Read consent when posthog.js loads, so an Accept clicked before then isn't lost.
- Switch PostHog to persistent storage on Accept; Mintlify's client-side nav kept the
  whole session on a memory-only id.
- Only send the catch-up $pageview if PostHog was opted out.
- 'Cookie preferences' falls through to the Privacy Policy when the banner can't open.
- Drop GTM: ui-ex removed it for double-reporting conversions to GA4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…the EEA/UK

The banner on docs kept its own consent record, separate from fly.io's, while the
cookies it governs are shared on .fly.io. Rather than sync the two, docs shows no
banner: EEA/UK visitors get Plausible only, and the banner stays on fly.io.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@alexleventer alexleventer changed the title Add PostHog and GA4 behind the consent banner Add PostHog and GA4 for logged-out visitors outside the EEA/UK Oct 9, 2026

This branch was successfully deployed

1 active deployment
staging — 5e9a98fe Deployed Oct 9, 2026 by mintlify[bot]
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