Files
PaperClipAI/doc/cloud-browser-analytics.md
T
DottaandClaude Opus 5.5 3c460f20cc feat(analytics): ask EU, UK and Swiss visitors before Cloud browser analytics (#22186)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip Cloud can send browser product analytics and session
replays to PostHog. Self-hosted installs never do this.
> - Today, browser analytics starts for every Cloud visitor after the
page settles.
> - Visitors in the EU, the EEA, the UK and Switzerland must agree
before analytics cookies and session recordings start.
> - This pull request adds a consent step for these visitors and a
switch in the user's profile settings.
> - The benefit is that Cloud analytics follows the owner decision: ask
in Europe, keep the current behavior elsewhere, and let every user
change the choice.

## Linked Issues or Issue Description

**Subsystem affected**
Paperclip Cloud browser product analytics (`ui/src/lib/analytics`,
`ProductAnalyticsGate`, the session route, and Profile settings).

**Problem or motivation**
Browser analytics and session replay start for every Cloud visitor
without a choice. EU, EEA, UK and Swiss visitors must consent first. The
privacy policy draft also says that users can change the choice in
settings. No such setting exists.

**Proposed solution**
Ask visitors in the EU, the EEA, the UK and Switzerland with a small
bottom banner (Accept or Decline). Do not load posthog-js before they
accept. Treat Do Not Track and Global Privacy Control as a decline for
these visitors. Keep the choice in `localStorage`. Add a "Product
analytics" switch to Profile settings for every user when browser
analytics is on.

**Alternatives considered**
A server-side country from a trusted edge header. Paperclip Cloud has no
such header today: Cloudflare records are DNS-only, so no `CF-IPCountry`
arrives, and the Railway edge adds no country header. This PR supports
an optional header (`PAPERCLIP_POSTHOG_COUNTRY_HEADER`) for a future
edge, and uses the browser time zone until then.

## What Changed

- `packages/shared`: `browserAnalytics` has a new optional
`consentRequired: boolean | null`.
- `packages/shared/src/analytics-consent.ts` (new): the one region
policy. `countryRequiresAnalyticsConsent` (EU and EEA with outermost
regions and Svalbard, GB with the Crown Dependencies and Gibraltar, CH)
and `timeZoneRequiresAnalyticsConsent` (`Europe/*`, EU, EEA and UK zones
outside Europe, and unknown zones such as `UTC` or `Etc/*`). The server
and the UI both use it.
- `server`: `resolveBrowserAnalyticsConfig` sets `consentRequired` from
the header that `PAPERCLIP_POSTHOG_COUNTRY_HEADER` names. No header or
an unknown code (`XX`) gives `null`.
- `ui/src/lib/analytics/consent.ts` (new): decides `granted`, `denied`
or `ask`. Order: for a visitor who must consent, Do Not Track or Global
Privacy Control gives `denied` (also over a stored Accept); then the
choice made on this page; then the stored choice; then the region
(server value, else browser time zone). The choice is in `localStorage`
key `paperclip.analyticsConsent`. All storage access is in `try/catch`.
A cross-tab `storage` event updates the page.
- `ProductAnalyticsGate`: one effect calls `syncProductAnalytics(config,
consent)`. Shows `AnalyticsConsentBanner` when consent is `ask`. Accept
loads posthog-js at once, without a reload.
- `product-analytics.ts`: new `syncProductAnalytics`. It starts, opts
in, opts out (`opt_out_capturing()` and `stopSessionRecording()`) or
cancels a pending load. Any consent other than `granted` stops
analytics. If consent is withdrawn while the script downloads, `init()`
does not run until a later opt-in.
- `AnalyticsConsentBanner` (new): a labelled bottom region with plain
copy, a privacy policy link, and Decline and Accept buttons (shared
`Button`). The copy says that recordings hide what you type and your
messages, documents and connected accounts, but may show page names like
task titles. It does not block the page. On mobile it sits above the
bottom navigation.
- `ProductAnalyticsSetting` (new) in Profile settings: a "Product
analytics" switch (shared `ToggleSwitch`). It shows only when browser
analytics is on for the instance. When GPC or DNT blocks analytics, it
is off and disabled and says why.
- `doc/cloud-browser-analytics.md`: new Consent section (signal,
behavior table, storage key, how to reset) and the new variable.
- `tests/runner-e2e/source-sdk-public-inputs.json`: refreshed for the
changed shared validator.

## Verification

- Red/green: the 7 new `ProductAnalyticsGate` consent tests fail against
the master gate (7 failed, 3 passed). The 5 review-fix tests (failed
write with working read, cross-tab change, decline during script
download, granted -> ask from another tab, granted -> ask from a session
refresh) fail on the first commit (5 failed, 16 passed). All pass now.
- `cd ui && npx vitest run src/lib/analytics
src/components/ProductAnalyticsGate.test.tsx
src/components/AnalyticsConsentBanner.test.tsx
src/components/ProductAnalyticsSetting.test.tsx
src/pages/ProfileSettings.test.tsx`: 267 tests pass.
- `cd server && npx vitest run
src/__tests__/cloud-posthog-browser.test.ts
src/__tests__/auth-routes.test.ts
src/__tests__/auth-session-route.test.ts`: 87 tests pass.
`packages/shared` `analytics-consent.test.ts` passes. `tsc --noEmit` for
`ui`, `server` and `packages/shared` shows no new errors.
- `pnpm verify` exits 2 (a doc is a global CI input). Required CI gives
the broad coverage.
- Real check in headless Chromium. I ran a local Cloud-managed instance
(external local PostgreSQL, `PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN`,
`PAPERCLIP_POSTHOG_BROWSER_ENABLED=1`). `PAPERCLIP_POSTHOG_HOST` pointed
at a local capture server, not PostHog. The capture server served a
small stand-in for `array.js` that sets a `ph_*` cookie and
`localStorage` key and posts `/e/` events. I set the visitor region with
the browser time zone:

| Visitor | Result |
| --- | --- |
| `Europe/Berlin`, no choice, 18 s wait | Banner shows. 0 `/_ph`
requests. No `ph_*` cookie or storage key. |
| Then Accept (keyboard Enter) | Banner closes. `GET
/_ph/static/array.js` and `POST /_ph/e/` in 3 s. Key is `granted`. After
reload: no banner, events continue. |
| `Europe/London`, Decline, wait, reload, wait | No banner. 0 `/_ph`
requests. No `ph_*` cookie or storage key. Key is `denied`. |
| `Europe/Zurich` with Global Privacy Control | No banner. 0 `/_ph`
requests. No `ph_*` cookie or storage key. |
| `America/New_York` | No banner. posthog-js loads after the page
settles, as before. |
| Profile settings switch (US) | Shows on. Off: client is opted out at
once. On: opt-in, events continue. |

- I ran the browser check again after the review fixes, with the same
results.
- Screenshots (banner light, banner dark, mobile 375 px light and dark,
settings switch): see the PR comment.
- Cold load (local dev server, fresh browser context per run, median of
7, ms):

| Build | Time zone | FCP | DOMContentLoaded | load |
| --- | --- | --- | --- | --- |
| master | New York | 728 / 724 | 687 / 684 | 689 / 686 |
| this PR | New York | 748 / 724 | 708 / 684 | 710 / 686 |
| master | Berlin | 740 | 694 | 697 |
| this PR | Berlin | 756 / 724 | 716 / 684 | 718 / 686 |

The second round gives the same medians for master and this PR. The
first-round difference is noise. The consent code adds no request and no
load-time wait.

## Risks

- Region by time zone is approximate. It asks some visitors outside the
EU (for example `Europe/Istanbul`, or `UTC` browsers). This is the safe
direction.
- A forged country header (only when `PAPERCLIP_POSTHOG_COUNTRY_HEADER`
is set) changes only the default for that visitor's own browser.
- The choice is per browser. A user on a new browser sees the banner
again (in consent regions).
- Visitors in consent regions now send no browser analytics until they
accept. Expect fewer EU/UK sessions in PostHog.
- Self-hosted installs: no change. They get no `browserAnalytics`
config, so no banner, no switch and no load.

## Model Used

- Claude Opus 5.5 (claude-opus-5-5), Anthropic, used through Claude Code
with tool use (shell, file edits, headless browser).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 10:52:20 -06:00

16 KiB

Cloud Browser Product Analytics

On Paperclip Cloud, the board UI can send page views, sessions, autocapture clicks, heatmaps, Web Vitals and session replays to PostHog. Self-hosted installs never do this: they do not download posthog-js and do not serve the PostHog proxy.

Who gets it

The server decides, in server/src/services/cloud-posthog-browser.ts. The authenticated GET /api/auth/get-session response carries a browserAnalytics object only when all of these hold:

  1. The instance is cloud managed (isCloudManagedInstance).
  2. PAPERCLIP_POSTHOG_PROJECT_TOKEN and PAPERCLIP_CLOUD_STACK_ID are set.
  3. PAPERCLIP_POSTHOG_BROWSER_ENABLED=1.

Otherwise the field is null, and the browser loads nothing. When it is set, the browser loads PostHog's browser script (/_ph/static/array.js, through the proxy) only after the page settles (first paint, page reads finished, browser idle), so cold loads do not wait for it. posthog-js is not an npm dependency of the board and is in no bundle chunk; PostHog serves it, as it serves the extensions posthog-js loads at run time (recorder, web vitals).

Configuration

Variable Default Meaning
PAPERCLIP_POSTHOG_PROJECT_TOKEN — PostHog project token. It is public by design: it can send events but cannot read data.
PAPERCLIP_POSTHOG_HOST https://us.i.posthog.com PostHog ingest host. The proxy forwards to it.
PAPERCLIP_POSTHOG_ENVIRONMENT — staging or production. Added to every event as environment.
PAPERCLIP_POSTHOG_BROWSER_ENABLED off 1 turns browser analytics on for this stack. Leave it unset to keep it off.
PAPERCLIP_POSTHOG_REPLAY_ENABLED on (when browser analytics is on) 0 turns session replay off for this stack and keeps the other browser analytics.
PAPERCLIP_POSTHOG_COUNTRY_HEADER — Name of a request header that the platform edge sets to the visitor's two-letter country code (for example CF-IPCountry behind a proxied Cloudflare zone). Leave it unset unless the edge sets the header and drops a value from the client. See Consent.

Per-stack opt-out

For a customer whose contract forbids recording, set PAPERCLIP_POSTHOG_REPLAY_ENABLED=0 on that stack. To turn off all browser analytics for a stack, unset PAPERCLIP_POSTHOG_BROWSER_ENABLED. Both take effect on the next server restart.

Visitors in the EU, the EEA, the UK and Switzerland must agree before browser analytics and session replay start. Everyone else keeps analytics on by default. Both can change the choice later. Server events are not affected: they set no cookies.

Who must agree

  1. The server decides when it knows the visitor's country. If PAPERCLIP_POSTHOG_COUNTRY_HEADER names a header and the request carries a valid two-letter code in it, browserAnalytics.consentRequired is true for the EU and EEA countries (and their outermost regions and Svalbard), the UK (and the Crown Dependencies and Gibraltar) and Switzerland, and false for every other ISO 3166-1 alpha-2 country. The aliases UK and EL count as GB and GR, and EU and EZ count as consent required. Any other value (for example XX, UN, XK or T1) gives null.
  2. Otherwise consentRequired is null, and the browser decides from its time zone. It asks when the zone starts with Europe/, is an EU, EEA or UK zone outside Europe (for example Atlantic/Canary, Atlantic/Reykjavik, Asia/Nicosia, Indian/Reunion), or is unknown (UTC, Etc/*, empty, or Intl fails). When unsure, it asks.

Both lists live in one place, packages/shared/src/analytics-consent.ts (countryRequiresAnalyticsConsent, timeZoneRequiresAnalyticsConsent). The browser's choice logic is in ui/src/lib/analytics/consent.ts.

Paperclip Cloud uses the time zone today. Requests reach Railway through DNS-only Cloudflare records, so no Cloudflare country header arrives, and the Railway edge adds no country header. Set PAPERCLIP_POSTHOG_COUNTRY_HEADER only when an edge that sets and overwrites a country header is in front of the stack. A visitor who forges the header can only change the default for their own browser.

What happens

Visitor Before a choice Accept / switch on Decline / switch off
Must agree, no Do Not Track or Global Privacy Control Banner. posthog-js does not load: no /_ph requests, no PostHog cookies or storage. posthog-js loads at once, without a reload. Nothing loads.
Must agree, navigator.doNotTrack === "1" or navigator.globalPrivacyControl === true No banner. Counts as Decline, also over a stored Accept. Not possible: the settings switch is off and disabled, and says why. Nothing loads. A running client opts out.
Everyone else Loads after the page settles, as before. — opt_out_capturing() and stopSessionRecording() run at once. After the next load, posthog-js does not load.

The gate calls one function, syncProductAnalytics(config, consent) in ui/src/lib/analytics/product-analytics.ts. It starts, opts in, opts out or cancels. Analytics stops whenever the choice is not granted, also when it goes back to "ask" (another tab removes the stored choice, or a session refresh changes consentRequired to true). If the choice changes while posthog-js is still downloading, init() does not run until the choice is granted again.

The banner sits at the bottom of the page and does not block the board. It says that recordings hide what the visitor types and their messages, documents and connected accounts, but can show page names such as task titles. It links to the privacy policy (https://paperclip.ing/privacy/).

Where the choice is kept

The choice is per browser, in localStorage under paperclip.analyticsConsent (granted or denied). The latest choice on the page wins, also when storage rejects the write; it then lasts for the open page only. Each user can change it in Settings → Profile → Product analytics. The switch shows only when browser analytics is on for the instance. Turning it on after an earlier opt-out also clears the PostHog opt-out (opt_in_capturing()).

To reset the choice and see the banner again, remove the key in the browser console: localStorage.removeItem("paperclip.analyticsConsent"), then reload.

Reverse proxy

The browser sends to /_ph on its own origin, so ad blockers do not drop events. server/src/routes/posthog-proxy.ts is not a generic proxy. It forwards only the requests posthog-js makes:

Method Path Upstream
POST /e/, /i/v0/e/, /batch/ ingest host
POST /s/ (session replay) ingest host
POST /flags/, /decide/ ingest host
GET /array/<token>/config, /array/<token>/config.js assets host
GET /static/<name>.js assets host

The ingest host is PAPERCLIP_POSTHOG_HOST. The assets host is derived from it (us.i.posthog.com → us-assets.i.posthog.com). Every other method or path answers 404 without contacting PostHog. The proxy streams bodies, builds a new header set from an allowlist plus X-Forwarded-For, and never forwards the inbound Host, Cookie or Authorization headers. It drops Set-Cookie from responses. It refuses bodies over 64 MiB (413) and limits requests in flight to 16 per client address and 256 in total (429). It is mounted only when browser analytics is on. It does not require a session: posthog-js sends some events while a page unloads, and the proxy can only reach the two PostHog hosts with the public project token, like PostHog's own ingest endpoint.

Visitor address behind the platform proxy

The per-client limit uses req.ip, which comes from the server's trusted proxy settings (TRUST_PROXY). It never comes from a header the client controls. If TRUST_PROXY is unset behind a platform proxy, req.ip is the proxy's private hop, so every visitor behind that hop shares one 16-request limit. Set TRUST_PROXY to the platform's proxy range so that req.ip is the visitor.

The X-Forwarded-For value that the proxy sends to PostHog carries the visitor's location. When the socket peer is private, the proxy uses the rightmost public X-Forwarded-For entry, which the platform edge appended. This value is used only for location, never for limits.

Identity

  • After sign-in: identify(session.userId, { email, name }). session.userId is the authenticated actor's user id verbatim (req.actor.userId, for example paperclip-id:...), the same id server events use as distinct_id. Email and name are person properties only, never event properties.
  • group("workspace", stackId).
  • Every event carries deployment_source: "cloud" and environment. Without PAPERCLIP_POSTHOG_ENVIRONMENT, environment is staging on a *.staging.paperclip.app host and production otherwise.
  • Sign-out: reset(), called by useSignOut before it leaves the page.
  • API requests to our own host carry PostHog tracing headers, so server events link to the browser session.

Privacy

Session replay shows text by default, the way PostHog normally works. Text is masked only inside marked customer content. Input values and attribute values are always masked.

  • Session replay masks every input value (maskAllInputs).

  • Replay masks text only inside these markers (ANALYTICS_MASK_TEXT_SELECTOR in ui/src/lib/analytics/privacy.ts, passed as rrweb maskTextSelector):

    • ANALYTICS_MASK_CLASS (ph-mask ph-sensitive): customer content.
    • ANALYTICS_NO_CAPTURE_CLASS (ph-no-capture): secrets. Replay blocks these elements entirely.
    • contenteditable editors (not contenteditable="false").

    rrweb masks a text node only when its parent matches the selector or has an ancestor that matches it. All other text, for example navigation, headings, buttons, task titles, agent names, project names and company names, is recorded as it is.

  • Replay also masks attribute values (maskReplayAttribute): only layout attributes (class, style, role, data-state, SVG geometry and similar), rrweb metadata and stylesheet links keep their values. title, aria-label, alt, placeholder, src, href, data-* values and element references (id, for, aria-labelledby) are always masked, so images record as empty boxes and link targets (for example download links with file paths) never leave.

  • The masking options in posthog.init take precedence over the PostHog project's "Privacy and masking" settings (posthog-js 1.450). posthog-js ignores the project setting and logs a warning when the two differ. Keep the project masking settings empty, and change masking only in privacy.ts. The ph-mask class is also the posthog-js default maskTextClass.

  • ANALYTICS_NO_CAPTURE_CLASS replaces secrets with a blank box in replays: every password-type Input, environment variable values, new secret values, and secrets shown as text: one-time sign-in and device codes, pairing and setup prompts, identity confirmation links, newly issued API keys and gateway tokens, gateway client snippets, webhook URLs and secrets, invite claim secrets, raw provider frames and SSH fallback commands.

  • Every event and replay meta event goes through scrubCapturedEvent (before_send). Every URL keeps only its origin and path: query and hash values never leave, because they can hold credentials, file paths or search text. The token segment of /board-claim/<token> and /invite/<token> is redacted (redactAnalyticsUrl). Other strings only have secret key=value pairs redacted.

  • Events never carry the page title (before_send drops title), because Paperclip page titles name the task and the organization.

  • Autocapture never records element text or attribute values (mask_all_text, mask_all_element_attributes). It keeps the click, the element tree and the page.

  • Connected-account content is Google user data or Slack data. No human may read it in a replay (privacy policy and Google API Limited Use). The surfaces below, and other free-form text that agents or customers write, carry ANALYTICS_MASK_CLASS on their content element (not on the chrome around it):

    • Rendered markdown (task bodies, comments, chat messages, documents), the rich editor, task and issue chat threads (messages, tool calls, tool results, interaction cards), the comment timeline and the file viewer.
    • Link preview cards, task quicklook descriptions, external object pills and rows, and related-work titles.
    • Email message cards and email send intents.
    • Connection names, connected account names, aliases and email addresses (Browse rows and the remove dialog, Connections, app detail headers, the app sidebar, connection choice lists and instructions, aggregator and Composio account dialogs, Tailscale networks, agent tool and audit tables, AI connection names, pickers, selects, account details and controls, pool run details, subscription and quota panels, adapter sign-in status, connection access and repair cards), GitHub logins (identity rows, bot people, chat setup, run identity history) and repositories, Slack workspace names (list and selected value), Slack account pickers, chat channels, linked user labels, the external task banner and chat identity pages.
    • Connection and account management surfaces are masked by section, not label by label: the Browse connector list, the App detail body below its header, the Connections table, Tailscale networks, the chat connection detail body and its account subtitle, GitHub chat setup, the AI connection pool editor and the chat identity confirmation. Every dialog, alert dialog, select (trigger and list), popover, dropdown, sheet and tooltip under pages/apps, features/connections and components/ai-connections carries its own mask, because portals escape the page's masked container; replay-masking.test.tsx fails when one does not.
    • App action test results (parsed preview and raw response).
    • Inbox and decision rows (subject and detail line), obligation evidence, Needs You notes and receipts, decision cards and compact decisions, decision records, and interaction cards (questions, options, answers, tool action requests, suggested tasks) wherever they render.
    • Approval payloads, action card input and reason, recovery card headline, evidence and options, run ledger retry details and interrupt handoff previews.
    • Run transcripts, run failure details, run events, run stdout and stderr excerpts (agent page and execution workspace operations), the run invocation command, notes, prompt, context and environment, Runner inspector frames, and every preformatted block that shows run output, tool or webhook payloads, request or response bodies, instructions, skills or package files.
    • Saved connection instructions for agents.
    • Document and case revision diffs.
    • Search result snippets, toasts (title and body), voice and call transcripts, case summaries, files and fields, attachment previews and artifact previews (text, tables, patches and documents).

    Component tests render these surfaces with distinctive fixture text and assert, through ui/src/lib/analytics/replay-recording.test-utils.ts, that the text is rendered but not recorded (or is blocked, for secrets), including alternate branches, dialog portals and selected values in closed pickers. ui/src/lib/analytics/replay-masking.test.tsx also pins the remaining surfaces at source level. A new surface that shows connected-account content needs the class and a test.

  • Residual risk: text that the owner accepted as visible can still hold customer words. Task titles, agent names, project names, company names, routine names, artifact and document titles, and activity rows (which name the task or entity) are recorded as they are. Paperclip member names and email addresses on member, access and profile pages are recorded too. An agent can copy email or Slack text into a task title. Masking is opt-in per surface, so a new surface that renders connected-account content without the class is recorded until somebody marks it.

  • The UI never captures an event that the server already sends (PAPERCLIP_EVENTS); product-analytics-events.test.ts enforces this.