From 3c460f20cc4fd30c2ef184023279880b3619bf5a Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Wed, 18 Nov 2026 10:52:20 -0600 Subject: [PATCH] feat(analytics): ask EU, UK and Swiss visitors before Cloud browser analytics (#22186) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 --- doc/cloud-browser-analytics.md | 68 +++++++ packages/shared/src/analytics-consent.test.ts | 43 +++++ packages/shared/src/analytics-consent.ts | 82 ++++++++ packages/shared/src/index.ts | 1 + packages/shared/src/validators/access.ts | 1 + server/src/__tests__/auth-routes.test.ts | 7 + .../__tests__/cloud-posthog-browser.test.ts | 15 ++ server/src/routes/auth.ts | 2 +- server/src/services/cloud-posthog-browser.ts | 17 +- .../runner-e2e/source-sdk-public-inputs.json | 6 +- .../AnalyticsConsentBanner.test.tsx | 54 ++++++ ui/src/components/AnalyticsConsentBanner.tsx | 47 +++++ .../components/ProductAnalyticsGate.test.tsx | 177 +++++++++++++++++- ui/src/components/ProductAnalyticsGate.tsx | 29 ++- .../ProductAnalyticsSetting.test.tsx | 76 ++++++++ ui/src/components/ProductAnalyticsSetting.tsx | 47 +++++ ui/src/lib/analytics/consent.test.tsx | 134 +++++++++++++ ui/src/lib/analytics/consent.ts | 93 +++++++++ ui/src/lib/analytics/product-analytics.ts | 86 ++++++++- ui/src/pages/ProfileSettings.tsx | 3 + 20 files changed, 959 insertions(+), 29 deletions(-) create mode 100644 packages/shared/src/analytics-consent.test.ts create mode 100644 packages/shared/src/analytics-consent.ts create mode 100644 ui/src/components/AnalyticsConsentBanner.test.tsx create mode 100644 ui/src/components/AnalyticsConsentBanner.tsx create mode 100644 ui/src/components/ProductAnalyticsSetting.test.tsx create mode 100644 ui/src/components/ProductAnalyticsSetting.tsx create mode 100644 ui/src/lib/analytics/consent.test.tsx create mode 100644 ui/src/lib/analytics/consent.ts diff --git a/doc/cloud-browser-analytics.md b/doc/cloud-browser-analytics.md index e9cd8427eca..70f09f0b63b 100644 --- a/doc/cloud-browser-analytics.md +++ b/doc/cloud-browser-analytics.md @@ -31,6 +31,7 @@ extensions posthog-js loads at run time (recorder, web vitals). | `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](#consent). | ### Per-stack opt-out @@ -39,6 +40,73 @@ For a customer whose contract forbids recording, set analytics for a stack, unset `PAPERCLIP_POSTHOG_BROWSER_ENABLED`. Both take effect on the next server restart. +## Consent + +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 diff --git a/packages/shared/src/analytics-consent.test.ts b/packages/shared/src/analytics-consent.test.ts new file mode 100644 index 00000000000..0c69d867d4f --- /dev/null +++ b/packages/shared/src/analytics-consent.test.ts @@ -0,0 +1,43 @@ +import { describe, expect, it } from "vitest"; +import { countryRequiresAnalyticsConsent, timeZoneRequiresAnalyticsConsent } from "./analytics-consent.js"; + +describe("countryRequiresAnalyticsConsent", () => { + it.each(["DE", "fr", " GB ", "CH", "NO", "IS", "LI", "SJ", "RE", "JE", "UK", "uk", "EL", "GR", "EU", "EZ"])("requires consent for %s", (country) => { + expect(countryRequiresAnalyticsConsent(country)).toBe(true); + }); + + it.each(["US", "CA", "JP", "BR", "TR", "UA"])("does not require consent for %s", (country) => { + expect(countryRequiresAnalyticsConsent(country)).toBe(false); + }); + + it.each([null, undefined, "", "XX", "ZZ", "QQ", "AA", "UN", "QO", "XA", "XB", "XK", "T1", "DEU", "U"])("cannot tell for %s", (country) => { + expect(countryRequiresAnalyticsConsent(country)).toBeNull(); + }); +}); + +describe("timeZoneRequiresAnalyticsConsent", () => { + it.each([ + "Europe/Berlin", + "Europe/London", + "Europe/Zurich", + "Atlantic/Canary", + "Atlantic/Reykjavik", + "Arctic/Longyearbyen", + "Asia/Nicosia", + "Indian/Reunion", + "UTC", + "Etc/GMT+1", + "", + null, + undefined, + ])("requires consent for %s", (zone) => { + expect(timeZoneRequiresAnalyticsConsent(zone)).toBe(true); + }); + + it.each(["America/New_York", "America/Los_Angeles", "Asia/Tokyo", "Australia/Sydney", "America/Sao_Paulo"])( + "does not require consent for %s", + (zone) => { + expect(timeZoneRequiresAnalyticsConsent(zone)).toBe(false); + }, + ); +}); diff --git a/packages/shared/src/analytics-consent.ts b/packages/shared/src/analytics-consent.ts new file mode 100644 index 00000000000..00c4bfbd24a --- /dev/null +++ b/packages/shared/src/analytics-consent.ts @@ -0,0 +1,82 @@ +const CONSENT_REQUIRED_COUNTRIES = new Set([ + "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IE", + "IT", "LV", "LT", "LU", "MT", "NL", "PL", "PT", "RO", "SK", "SI", "ES", "SE", + "AX", "GF", "GP", "MQ", "RE", "YT", "MF", + "IS", "LI", "NO", "SJ", + "GB", "GG", "JE", "IM", "GI", + "CH", + "EU", +]); + +const CONSENT_REQUIRED_TIME_ZONES = new Set([ + "Arctic/Longyearbyen", + "Asia/Famagusta", + "Asia/Nicosia", + "Atlantic/Azores", + "Atlantic/Canary", + "Atlantic/Faeroe", + "Atlantic/Faroe", + "Atlantic/Jan_Mayen", + "Atlantic/Madeira", + "Atlantic/Reykjavik", + "America/Cayenne", + "America/Guadeloupe", + "America/Marigot", + "America/Martinique", + "America/St_Barthelemy", + "Indian/Mayotte", + "Indian/Reunion", + "CET", + "EET", + "Eire", + "GB", + "GB-Eire", + "Iceland", + "MET", + "Poland", + "Portugal", + "WET", +]); + +const UNKNOWN_TIME_ZONES = new Set(["", "UTC", "GMT", "UCT", "Universal", "Zulu", "Greenwich"]); + +const COUNTRY_ALIASES = new Map([ + ["UK", "GB"], + ["EL", "GR"], + ["EU", "EU"], + ["EZ", "EU"], +]); + +const ISO_COUNTRY_CODES = new Set( + ` + AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE + BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD + CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM + DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF + GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU + ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN + KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME + MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA + NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM + PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI + SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK + TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI + VN VU WF WS YE YT ZA ZM ZW + ` + .trim() + .split(/\s+/), +); + +export function countryRequiresAnalyticsConsent(country: string | null | undefined): boolean | null { + const raw = country?.trim().toUpperCase(); + if (!raw || !/^[A-Z]{2}$/.test(raw)) return null; + const code = COUNTRY_ALIASES.get(raw) ?? raw; + if (CONSENT_REQUIRED_COUNTRIES.has(code)) return true; + return ISO_COUNTRY_CODES.has(code) ? false : null; +} + +export function timeZoneRequiresAnalyticsConsent(timeZone: string | null | undefined): boolean { + const zone = timeZone?.trim() ?? ""; + if (UNKNOWN_TIME_ZONES.has(zone) || zone.startsWith("Etc/")) return true; + return zone.startsWith("Europe/") || CONSENT_REQUIRED_TIME_ZONES.has(zone); +} diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts index 05291116712..aa3cc0be784 100644 --- a/packages/shared/src/index.ts +++ b/packages/shared/src/index.ts @@ -1,6 +1,7 @@ export type { InboxMineSnapshot, InboxSourceError } from "./types/inbox-mine.js"; export { CASE_HANDOFF_STATES, handoffCaseSchema, agentCaseHandoffSchema, doneCaseHandoffSchema, caseWorkflowDocumentTextSchema, caseInitialDocumentSchema, caseInitialDocumentsSchema, type CaseInitialDocument, type CaseHandoffState, type CaseHandoffDestinationKind, type AgentCaseHandoffInput, type DoneCaseHandoffInput, type HandoffCaseInput, type HandoffCaseResult, type CaseHandoff, type CaseWorkflowTransition } from "./case-handoffs.js"; export * from "./slack-app-manifest.js"; +export * from "./analytics-consent.js"; export * from "./routine-suggestions.js"; export * from "./responsibility-automation.js"; export * from "./standing-checks.js"; diff --git a/packages/shared/src/validators/access.ts b/packages/shared/src/validators/access.ts index 110a49f427a..b89c803b03d 100644 --- a/packages/shared/src/validators/access.ts +++ b/packages/shared/src/validators/access.ts @@ -233,6 +233,7 @@ export const browserAnalyticsConfigSchema = z.object({ environment: z.string().min(1), stackId: z.string().min(1), replayEnabled: z.boolean(), + consentRequired: z.boolean().nullable().optional(), }); export type BrowserAnalyticsConfig = z.infer; diff --git a/server/src/__tests__/auth-routes.test.ts b/server/src/__tests__/auth-routes.test.ts index 8098f990864..b8546e24f6e 100644 --- a/server/src/__tests__/auth-routes.test.ts +++ b/server/src/__tests__/auth-routes.test.ts @@ -131,7 +131,14 @@ describe("auth routes", () => { environment: "staging", stackId: "stack-1", replayEnabled: true, + consentRequired: null, }); + + vi.stubEnv("PAPERCLIP_POSTHOG_COUNTRY_HEADER", "cf-ipcountry"); + const eu = await request(createApp(actor, baseUser)).get("/api/auth/get-session").set("CF-IPCountry", "FR"); + expect(eu.body.browserAnalytics.consentRequired).toBe(true); + const us = await request(createApp(actor, baseUser)).get("/api/auth/get-session").set("CF-IPCountry", "US"); + expect(us.body.browserAnalytics.consentRequired).toBe(false); }); it("preserves the session when optional navigation bootstrap cannot load", async () => { diff --git a/server/src/__tests__/cloud-posthog-browser.test.ts b/server/src/__tests__/cloud-posthog-browser.test.ts index 4a913a0b7c9..75a7ad903ad 100644 --- a/server/src/__tests__/cloud-posthog-browser.test.ts +++ b/server/src/__tests__/cloud-posthog-browser.test.ts @@ -44,9 +44,24 @@ describe("browser analytics config exposure", () => { environment: "production", stackId: "stack-1", replayEnabled, + consentRequired: null, }); }); + it("decides consent from the configured edge country header, and leaves it to the browser otherwise", () => { + const on = { ...CLOUD, ...TOKEN, ...BROWSER }; + const withHeader = { ...on, PAPERCLIP_POSTHOG_COUNTRY_HEADER: "CF-IPCountry" }; + expect(resolveBrowserAnalyticsConfig(on, { "cf-ipcountry": "DE" })?.consentRequired).toBeNull(); + expect(resolveBrowserAnalyticsConfig(withHeader, { "cf-ipcountry": "DE" })?.consentRequired).toBe(true); + expect(resolveBrowserAnalyticsConfig(withHeader, { "cf-ipcountry": "gb" })?.consentRequired).toBe(true); + expect(resolveBrowserAnalyticsConfig(withHeader, { "cf-ipcountry": "CH" })?.consentRequired).toBe(true); + expect(resolveBrowserAnalyticsConfig(withHeader, { "cf-ipcountry": "NO" })?.consentRequired).toBe(true); + expect(resolveBrowserAnalyticsConfig(withHeader, { "cf-ipcountry": "US" })?.consentRequired).toBe(false); + expect(resolveBrowserAnalyticsConfig(withHeader, { "cf-ipcountry": "XX" })?.consentRequired).toBeNull(); + expect(resolveBrowserAnalyticsConfig(withHeader, {})?.consentRequired).toBeNull(); + expect(resolveBrowserAnalyticsConfig(withHeader, { "cf-ipcountry": ["FR", "US"] })?.consentRequired).toBe(true); + }); + it("always sends an environment: the explicit variable, else staging or production from the host", () => { const on = { ...CLOUD, ...TOKEN, ...BROWSER }; expect(resolveBrowserAnalyticsConfig({ ...on, PAPERCLIP_POSTHOG_ENVIRONMENT: "qa" })?.environment).toBe("qa"); diff --git a/server/src/routes/auth.ts b/server/src/routes/auth.ts index 0da917b6bcf..9414086fec3 100644 --- a/server/src/routes/auth.ts +++ b/server/src/routes/auth.ts @@ -76,7 +76,7 @@ export function authRoutes(db: Db) { browserTracing: resolveBrowserTracingConfig(process.env, warnBrowserTracing), // Hosted Paperclip Cloud with PAPERCLIP_POSTHOG_BROWSER_ENABLED=1 only; // null everywhere else. See `server/src/services/cloud-posthog-browser.ts`. - browserAnalytics: resolveBrowserAnalyticsConfig(process.env), + browserAnalytics: resolveBrowserAnalyticsConfig(process.env, req.headers), }); res.json({ ...session, ...(boardBootstrap ? { boardBootstrap } : {}) }); }); diff --git a/server/src/services/cloud-posthog-browser.ts b/server/src/services/cloud-posthog-browser.ts index a0331033f1b..123f2de87e9 100644 --- a/server/src/services/cloud-posthog-browser.ts +++ b/server/src/services/cloud-posthog-browser.ts @@ -9,7 +9,7 @@ // The browser sends to `POSTHOG_PROXY_PATH` on its own origin, not to PostHog, // so ad blockers do not drop the events. See `routes/posthog-proxy.ts`. -import type { BrowserAnalyticsConfig } from "@paperclipai/shared"; +import { countryRequiresAnalyticsConsent, type BrowserAnalyticsConfig } from "@paperclipai/shared"; import { isCloudStagingInstance, type CloudInstanceEnv } from "./cloud-instance.js"; import { resolveCloudPostHogConfig, type CloudPostHogConfig } from "./cloud-posthog-config.js"; @@ -18,6 +18,15 @@ export const POSTHOG_PROXY_PATH = "/_ph"; const POSTHOG_CLOUD_INGEST_HOST = /^(us|eu)\.i\.posthog\.com$/i; +export type RequestHeaders = Record; + +export function resolveAnalyticsConsentRequired(env: CloudInstanceEnv, headers: RequestHeaders): boolean | null { + const headerName = env.PAPERCLIP_POSTHOG_COUNTRY_HEADER?.trim().toLowerCase(); + if (!headerName) return null; + const value = headers[headerName]; + return countryRequiresAnalyticsConsent(Array.isArray(value) ? value[0] : value); +} + /** The browser analytics part of the Cloud PostHog config, or null when it is off. */ export function resolveBrowserPostHogConfig(env: CloudInstanceEnv = process.env): CloudPostHogConfig | null { const config = resolveCloudPostHogConfig(env); @@ -42,7 +51,10 @@ export function posthogUiHost(ingestHost: string): string | null { return match ? `https://${match[1]!.toLowerCase()}.posthog.com` : null; } -export function resolveBrowserAnalyticsConfig(env: CloudInstanceEnv = process.env): BrowserAnalyticsConfig | null { +export function resolveBrowserAnalyticsConfig( + env: CloudInstanceEnv = process.env, + headers: RequestHeaders = {}, +): BrowserAnalyticsConfig | null { const config = resolveBrowserPostHogConfig(env); if (!config) return null; let uiHost: string | null; @@ -61,5 +73,6 @@ export function resolveBrowserAnalyticsConfig(env: CloudInstanceEnv = process.en environment: config.environment ?? (isCloudStagingInstance(env) ? "staging" : "production"), stackId: config.stackId, replayEnabled: config.replayEnabled, + consentRequired: resolveAnalyticsConsentRequired(env, headers), }; } diff --git a/tests/runner-e2e/source-sdk-public-inputs.json b/tests/runner-e2e/source-sdk-public-inputs.json index 2235e82a0a1..55d9bfc53ac 100644 --- a/tests/runner-e2e/source-sdk-public-inputs.json +++ b/tests/runner-e2e/source-sdk-public-inputs.json @@ -65,6 +65,8 @@ "packages/shared/src/ai-connection-usage.ts": "4b51573ee92f8a2ae0f80dd15288a0e59b4dddc7", "packages/shared/src/ai-connections.ts": "6aba41f15e8879fed5d9e3d9199e9a9983647a4e", "packages/shared/src/ai-provider-routing.ts": "519c93bd489100125e9a4ad096611f25fd60af4e", + "packages/shared/src/analytics-consent.test.ts": "0c69d867d4f108cb57c07b4e71633e058cb7506b", + "packages/shared/src/analytics-consent.ts": "00c4bfbd24ac3a288a68caae52468dfcd26df3e7", "packages/shared/src/announcements.test.ts": "121ed97b560e0dd271fe6602c97e2415ee4e4bf7", "packages/shared/src/announcements.ts": "1405e849eeeeb67239bacc1bbb3903385a5faa6f", "packages/shared/src/antigravity-runtime.test.ts": "f9ebcc9430be51c342b42644b735f1434b405ec7", @@ -268,7 +270,7 @@ "packages/shared/src/home-paths.ts": "fa4f1c440653b76b3dbb7a51026d557287deb45d", "packages/shared/src/humanize-connection.test.ts": "ba9e90a44c63452b0bf9f733adb90241921e8eca", "packages/shared/src/humanize-connection.ts": "fbd414476a0ef7106a7c80d8572208781b091699", - "packages/shared/src/index.ts": "0529111671263074c36593a4180637070e6af1d2", + "packages/shared/src/index.ts": "aa3cc0be784184791368508977d97d89c2f58530", "packages/shared/src/issue-activity-identity.test.ts": "3dc294640f54c2be67943e3e0149cf4eff2c95ca", "packages/shared/src/issue-activity-identity.ts": "1b0f07ec3fe0506aaaf80a4fa9893f3baf8f0075", "packages/shared/src/issue-attribution.test.ts": "84563685e7f3c48029243cf1cc24a3a09ee3cde9", @@ -459,7 +461,7 @@ "packages/shared/src/types/workspace-runtime.ts": "00ab237577d3ea3a1fa946ce6ab6ef8b389b1739", "packages/shared/src/types/workspace-source-verification.ts": "647f5c8817590629439813df5dc63750b316206d", "packages/shared/src/validators/access.test.ts": "0df0e096658a31c4f21462a992e38cf8bd7082b1", - "packages/shared/src/validators/access.ts": "110a49f427a9deb194b51d671c6007120c2af0a6", + "packages/shared/src/validators/access.ts": "b89c803b03d7bd966ecd4b079ccb445b2a8ffb15", "packages/shared/src/validators/adapter-auth-session.ts": "14cffbd7281265bf3f059bcf1b97739ebe0e1f81", "packages/shared/src/validators/adapter-registry.test.ts": "567c113e50dd0c0d259b095375f8f8f403ffa893", "packages/shared/src/validators/adapter-registry.ts": "6fb9f655d49f774ef7f082bf842f388f1187e545", diff --git a/ui/src/components/AnalyticsConsentBanner.test.tsx b/ui/src/components/AnalyticsConsentBanner.test.tsx new file mode 100644 index 00000000000..0bd9bbc3709 --- /dev/null +++ b/ui/src/components/AnalyticsConsentBanner.test.tsx @@ -0,0 +1,54 @@ +// @vitest-environment jsdom + +import { act } from "react"; +import { createRoot } from "react-dom/client"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { AnalyticsConsentBanner } from "./AnalyticsConsentBanner"; + +Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true }); + +describe("AnalyticsConsentBanner", () => { + let container: HTMLDivElement; + + afterEach(() => { + container.remove(); + }); + + function render(props: Parameters[0]) { + container = document.createElement("div"); + document.body.appendChild(container); + const root = createRoot(container); + act(() => root.render()); + return root; + } + + it("is a labelled region with plain copy, a privacy link and two keyboard buttons", () => { + const onAccept = vi.fn(); + const onDecline = vi.fn(); + const root = render({ recordings: true, onAccept, onDecline }); + const region = container.querySelector("section")!; + expect(region.getAttribute("aria-label")).toBe("Analytics choice"); + const description = document.getElementById(region.getAttribute("aria-describedby")!); + expect(description?.textContent).toContain( + "Paperclip uses analytics and session recordings to improve the product. Recordings hide what you type and your messages, documents and connected accounts, but may show page names like task titles.", + ); + const link = region.querySelector("a")!; + expect(link.textContent).toBe("Privacy policy"); + expect(link.getAttribute("href")).toBe("https://paperclip.ing/privacy/"); + const buttons = [...region.querySelectorAll("button")]; + expect(buttons.map((button) => button.textContent)).toEqual(["Decline", "Accept"]); + expect(buttons.every((button) => button.type === "button")).toBe(true); + act(() => buttons[0]!.click()); + act(() => buttons[1]!.click()); + expect(onDecline).toHaveBeenCalledTimes(1); + expect(onAccept).toHaveBeenCalledTimes(1); + expect(container.querySelector("[aria-modal]")).toBeNull(); + act(() => root.unmount()); + }); + + it("does not mention recordings when replay is off", () => { + const root = render({ recordings: false, onAccept: vi.fn(), onDecline: vi.fn() }); + expect(container.textContent).not.toContain("recordings"); + act(() => root.unmount()); + }); +}); diff --git a/ui/src/components/AnalyticsConsentBanner.tsx b/ui/src/components/AnalyticsConsentBanner.tsx new file mode 100644 index 00000000000..7a5525bbb60 --- /dev/null +++ b/ui/src/components/AnalyticsConsentBanner.tsx @@ -0,0 +1,47 @@ +import { useId } from "react"; +import { Button } from "@/components/ui/button"; + +export const PRIVACY_POLICY_URL = "https://paperclip.ing/privacy/"; + +export function AnalyticsConsentBanner({ + recordings, + onAccept, + onDecline, +}: { + recordings: boolean; + onAccept: () => void; + onDecline: () => void; +}) { + const textId = useId(); + return ( +
+
+

+ {recordings + ? "Paperclip uses analytics and session recordings to improve the product. Recordings hide what you type and your messages, documents and connected accounts, but may show page names like task titles. " + : "Paperclip uses analytics to improve the product. "} + + Privacy policy + +

+
+ + +
+
+
+ ); +} diff --git a/ui/src/components/ProductAnalyticsGate.test.tsx b/ui/src/components/ProductAnalyticsGate.test.tsx index 051d113118d..892919c2701 100644 --- a/ui/src/components/ProductAnalyticsGate.test.tsx +++ b/ui/src/components/ProductAnalyticsGate.test.tsx @@ -5,6 +5,12 @@ import { createRoot } from "react-dom/client"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { resetProductAnalyticsForTest } from "@/lib/analytics/product-analytics"; +import { + ANALYTICS_CONSENT_STORAGE_KEY, + resetAnalyticsConsentForTest, + storeAnalyticsChoice, +} from "@/lib/analytics/consent"; +import { queryKeys } from "@/lib/queryKeys"; import { ProductAnalyticsGate } from "./ProductAnalyticsGate"; const getSessionMock = vi.hoisted(() => vi.fn()); @@ -14,12 +20,19 @@ const posthogMock = vi.hoisted(() => ({ identify: vi.fn(), group: vi.fn(), reset: vi.fn(), + opt_out_capturing: vi.fn(), + opt_in_capturing: vi.fn(), + has_opted_out_capturing: vi.fn(() => false), + startSessionRecording: vi.fn(), + stopSessionRecording: vi.fn(), })); vi.mock("@/api/auth", () => ({ authApi: { getSession: () => getSessionMock() }, })); +const scriptDownload: { hold: boolean; pending: Array<() => void> } = { hold: false, pending: [] }; + /** PostHog script elements the module adds to the page. */ function injectedScripts() { return [...document.querySelectorAll("script")].filter((script) => script.src.includes("/static/array.js")); @@ -32,7 +45,9 @@ vi.spyOn(document.head, "appendChild").mockImplementation((node: const result = appendChild(node); if (node instanceof HTMLScriptElement && node.src.includes("/static/array.js")) { (window as unknown as { posthog: typeof posthogMock }).posthog = posthogMock; - queueMicrotask(() => node.onload?.(new Event("load"))); + const finish = () => node.onload?.(new Event("load")); + if (scriptDownload.hold) scriptDownload.pending.push(finish); + else queueMicrotask(finish); } return result; }); @@ -43,6 +58,26 @@ vi.spyOn(document.head, "appendChild").mockImplementation((node: const ACTOR_ID = "paperclip-id:uf2X8Ha4H9hNdAMnc1rOy91VIRos5pch"; const user = { id: ACTOR_ID, email: "jane@example.com", name: "Jane", image: null }; +function analyticsConfig(overrides: Record = {}) { + return { + token: "phc_test", + apiHost: "/_ph", + uiHost: null, + environment: "production", + stackId: "stack-1", + replayEnabled: false, + ...overrides, + }; +} + +function banner() { + return document.querySelector('section[aria-label="Analytics choice"]'); +} + +function bannerButton(name: string) { + return [...(banner()?.querySelectorAll("button") ?? [])].find((button) => button.textContent === name)!; +} + function session(browserAnalytics: unknown) { return { session: { id: `paperclip:session:${ACTOR_ID}`, userId: ACTOR_ID }, @@ -73,6 +108,11 @@ describe("ProductAnalyticsGate", () => { vi.useRealTimers(); container.remove(); resetProductAnalyticsForTest(); + resetAnalyticsConsentForTest(); + window.localStorage.clear(); + scriptDownload.hold = false; + scriptDownload.pending = []; + Object.defineProperty(navigator, "globalPrivacyControl", { value: undefined, configurable: true }); for (const script of injectedScripts()) script.remove(); delete (window as unknown as { posthog?: unknown }).posthog; vi.clearAllMocks(); @@ -107,14 +147,7 @@ describe("ProductAnalyticsGate", () => { }); it("loads posthog-js and identifies the user when the session carries a config", async () => { - getSessionMock.mockResolvedValue(session({ - token: "phc_test", - apiHost: "/_ph", - uiHost: null, - environment: "production", - stackId: "stack-1", - replayEnabled: false, - })); + getSessionMock.mockResolvedValue(session(analyticsConfig({ consentRequired: false }))); const root = await renderGate(); // PostHog's script comes through the same-origin proxy, never from PostHog directly. expect(injectedScripts().map((script) => new URL(script.src).pathname)).toEqual(["/_ph/static/array.js"]); @@ -125,4 +158,130 @@ describe("ProductAnalyticsGate", () => { expect(posthogMock.register).toHaveBeenCalledWith({ deployment_source: "cloud", environment: "production" }); act(() => root.unmount()); }); + + it("asks first and loads nothing for a visitor who must consent", async () => { + getSessionMock.mockResolvedValue(session(analyticsConfig({ consentRequired: true }))); + const root = await renderGate(); + expect(banner()).not.toBeNull(); + expect(banner()?.textContent).toContain("Paperclip uses analytics to improve the product."); + expect(banner()?.querySelector("a")?.getAttribute("href")).toBe("https://paperclip.ing/privacy/"); + expect(injectedScripts()).toHaveLength(0); + expect(posthogMock.init).not.toHaveBeenCalled(); + act(() => root.unmount()); + }); + + it("loads analytics at once when the visitor accepts, and remembers the choice", async () => { + getSessionMock.mockResolvedValue(session(analyticsConfig({ consentRequired: true, replayEnabled: true }))); + const root = await renderGate(); + await act(async () => { + bannerButton("Accept").click(); + await Promise.resolve(); + await Promise.resolve(); + }); + expect(window.localStorage.getItem(ANALYTICS_CONSENT_STORAGE_KEY)).toBe("granted"); + expect(banner()).toBeNull(); + expect(injectedScripts()).toHaveLength(1); + expect(posthogMock.init).toHaveBeenCalledWith("phc_test", expect.objectContaining({ disable_session_recording: false })); + act(() => root.unmount()); + }); + + it("keeps analytics off when the visitor declines", async () => { + getSessionMock.mockResolvedValue(session(analyticsConfig({ consentRequired: true }))); + const root = await renderGate(); + await act(async () => { + bannerButton("Decline").click(); + }); + await settle(); + expect(window.localStorage.getItem(ANALYTICS_CONSENT_STORAGE_KEY)).toBe("denied"); + expect(banner()).toBeNull(); + expect(injectedScripts()).toHaveLength(0); + act(() => root.unmount()); + }); + + it("treats Global Privacy Control as a decline for a visitor who must consent", async () => { + Object.defineProperty(navigator, "globalPrivacyControl", { value: true, configurable: true }); + getSessionMock.mockResolvedValue(session(analyticsConfig({ consentRequired: true }))); + const root = await renderGate(); + expect(banner()).toBeNull(); + expect(injectedScripts()).toHaveLength(0); + act(() => root.unmount()); + }); + + it("keeps a stored decline across page loads", async () => { + window.localStorage.setItem(ANALYTICS_CONSENT_STORAGE_KEY, "denied"); + getSessionMock.mockResolvedValue(session(analyticsConfig({ consentRequired: false }))); + const root = await renderGate(); + expect(banner()).toBeNull(); + expect(injectedScripts()).toHaveLength(0); + act(() => root.unmount()); + }); + + it("opts out and stops recording now when the choice changes to off, and opts back in", async () => { + getSessionMock.mockResolvedValue(session(analyticsConfig({ consentRequired: false, replayEnabled: true }))); + const root = await renderGate(); + expect(posthogMock.init).toHaveBeenCalledTimes(1); + act(() => storeAnalyticsChoice("denied")); + expect(posthogMock.opt_out_capturing).toHaveBeenCalledTimes(1); + expect(posthogMock.stopSessionRecording).toHaveBeenCalledTimes(1); + act(() => storeAnalyticsChoice("granted")); + expect(posthogMock.opt_in_capturing).toHaveBeenCalledTimes(1); + expect(posthogMock.startSessionRecording).toHaveBeenCalledTimes(1); + expect(posthogMock.init).toHaveBeenCalledTimes(1); + expect(injectedScripts()).toHaveLength(1); + act(() => root.unmount()); + }); + + it("clears an earlier PostHog opt-out when the stored choice is on", async () => { + posthogMock.has_opted_out_capturing.mockReturnValueOnce(true); + window.localStorage.setItem(ANALYTICS_CONSENT_STORAGE_KEY, "granted"); + getSessionMock.mockResolvedValue(session(analyticsConfig({ consentRequired: true }))); + const root = await renderGate(); + expect(posthogMock.opt_in_capturing).toHaveBeenCalledTimes(1); + act(() => root.unmount()); + }); + + it("never initializes PostHog when the visitor turns analytics off while its script is downloading", async () => { + scriptDownload.hold = true; + getSessionMock.mockResolvedValue(session(analyticsConfig({ consentRequired: false, replayEnabled: true }))); + const root = await renderGate(); + expect(injectedScripts()).toHaveLength(1); + act(() => storeAnalyticsChoice("denied")); + await act(async () => { + for (const finish of scriptDownload.pending.splice(0)) finish(); + await Promise.resolve(); + }); + expect(posthogMock.init).not.toHaveBeenCalled(); + act(() => storeAnalyticsChoice("granted")); + expect(posthogMock.init).toHaveBeenCalledTimes(1); + expect(injectedScripts()).toHaveLength(1); + act(() => root.unmount()); + }); + + it("stops analytics when another tab clears the choice and the visitor must be asked again", async () => { + window.localStorage.setItem(ANALYTICS_CONSENT_STORAGE_KEY, "granted"); + getSessionMock.mockResolvedValue(session(analyticsConfig({ consentRequired: true, replayEnabled: true }))); + const root = await renderGate(); + expect(posthogMock.init).toHaveBeenCalledTimes(1); + act(() => { + window.localStorage.removeItem(ANALYTICS_CONSENT_STORAGE_KEY); + window.dispatchEvent(new StorageEvent("storage", { key: ANALYTICS_CONSENT_STORAGE_KEY })); + }); + expect(banner()).not.toBeNull(); + expect(posthogMock.opt_out_capturing).toHaveBeenCalledTimes(1); + expect(posthogMock.stopSessionRecording).toHaveBeenCalledTimes(1); + act(() => root.unmount()); + }); + + it("stops analytics when a session refresh says the visitor must consent", async () => { + getSessionMock.mockResolvedValue(session(analyticsConfig({ consentRequired: false }))); + const root = await renderGate(); + expect(posthogMock.init).toHaveBeenCalledTimes(1); + await act(async () => { + queryClient.setQueryData(queryKeys.auth.session, session(analyticsConfig({ consentRequired: true }))); + await vi.advanceTimersByTimeAsync(10); + }); + expect(banner()).not.toBeNull(); + expect(posthogMock.opt_out_capturing).toHaveBeenCalledTimes(1); + act(() => root.unmount()); + }); }); diff --git a/ui/src/components/ProductAnalyticsGate.tsx b/ui/src/components/ProductAnalyticsGate.tsx index dfa5fa46fd2..211fce89a2f 100644 --- a/ui/src/components/ProductAnalyticsGate.tsx +++ b/ui/src/components/ProductAnalyticsGate.tsx @@ -4,14 +4,19 @@ import { authApi } from "@/api/auth"; import { queryKeys } from "@/lib/queryKeys"; import { whenPageSettles } from "@/lib/when-page-settles"; import { - cancelPendingProductAnalytics, PRODUCT_ANALYTICS_LOAD_DEADLINE_MS, setProductAnalyticsUser, - startProductAnalytics, + syncProductAnalytics, } from "@/lib/analytics/product-analytics"; +import { + analyticsChoiceMadeOnThisPage, + storeAnalyticsChoice, + useAnalyticsConsent, +} from "@/lib/analytics/consent"; +import { AnalyticsConsentBanner } from "./AnalyticsConsentBanner"; /** - * Browser product analytics for hosted Paperclip Cloud. Renders nothing. + * Browser product analytics for hosted Paperclip Cloud. * * It reads the signed-in session, like `SentryGate` (same query, so no extra * request). The server sends `browserAnalytics` only for a cloud-managed @@ -34,10 +39,12 @@ export function ProductAnalyticsGate() { const userId = session?.session.userId ?? null; const email = session?.user.email ?? null; const name = session?.user.name ?? null; + const consent = useAnalyticsConsent(config); useEffect(() => { - if (!config) return; - startProductAnalytics(config, { + if (!config || !consent) return; + return syncProductAnalytics(config, consent, { + immediate: analyticsChoiceMadeOnThisPage(), schedule: (start) => { const cancelSettle = whenPageSettles(queryClient, start); const deadline = window.setTimeout(start, PRODUCT_ANALYTICS_LOAD_DEADLINE_MS); @@ -47,13 +54,19 @@ export function ProductAnalyticsGate() { }; }, }); - return () => cancelPendingProductAnalytics(); // Keyed by value: the config object identity changes on every session refetch. - }, [configKey, queryClient]); + }, [configKey, consent, queryClient]); useEffect(() => { setProductAnalyticsUser(userId ? { id: userId, email, name } : null); }, [userId, email, name]); - return null; + if (!config || consent !== "ask") return null; + return ( + storeAnalyticsChoice("granted")} + onDecline={() => storeAnalyticsChoice("denied")} + /> + ); } diff --git a/ui/src/components/ProductAnalyticsSetting.test.tsx b/ui/src/components/ProductAnalyticsSetting.test.tsx new file mode 100644 index 00000000000..272c7145f64 --- /dev/null +++ b/ui/src/components/ProductAnalyticsSetting.test.tsx @@ -0,0 +1,76 @@ +// @vitest-environment jsdom + +import { act } from "react"; +import { createRoot } from "react-dom/client"; +import { afterEach, describe, expect, it } from "vitest"; +import type { BrowserAnalyticsConfig } from "@paperclipai/shared"; +import { ANALYTICS_CONSENT_STORAGE_KEY, resetAnalyticsConsentForTest } from "@/lib/analytics/consent"; +import { ProductAnalyticsSetting } from "./ProductAnalyticsSetting"; + +Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true }); + +const config: BrowserAnalyticsConfig = { + token: "phc_test", + apiHost: "/_ph", + uiHost: null, + environment: "production", + stackId: "stack-1", + replayEnabled: true, + consentRequired: false, +}; + +describe("ProductAnalyticsSetting", () => { + let container: HTMLDivElement; + + afterEach(() => { + container.remove(); + window.localStorage.clear(); + resetAnalyticsConsentForTest(); + }); + + function render(value: BrowserAnalyticsConfig | null) { + container = document.createElement("div"); + document.body.appendChild(container); + const root = createRoot(container); + act(() => root.render()); + return root; + } + + it("shows nothing when browser analytics is off for the instance", () => { + const root = render(null); + expect(container.innerHTML).toBe(""); + act(() => root.unmount()); + }); + + it("turns analytics off and on for this browser", () => { + const root = render(config); + const toggle = container.querySelector('[role="switch"]')!; + expect(document.getElementById(toggle.getAttribute("aria-labelledby")!)?.textContent).toBe("Product analytics"); + expect(toggle.getAttribute("aria-checked")).toBe("true"); + act(() => toggle.click()); + expect(window.localStorage.getItem(ANALYTICS_CONSENT_STORAGE_KEY)).toBe("denied"); + expect(toggle.getAttribute("aria-checked")).toBe("false"); + act(() => toggle.click()); + expect(window.localStorage.getItem(ANALYTICS_CONSENT_STORAGE_KEY)).toBe("granted"); + expect(toggle.getAttribute("aria-checked")).toBe("true"); + act(() => root.unmount()); + }); + + it("is off before a visitor who must consent has chosen", () => { + const root = render({ ...config, consentRequired: true }); + expect(container.querySelector('[role="switch"]')?.getAttribute("aria-checked")).toBe("false"); + act(() => root.unmount()); + }); + + it("stays off and cannot be turned on when the browser asks not to be tracked where consent is required", () => { + Object.defineProperty(navigator, "globalPrivacyControl", { value: true, configurable: true }); + window.localStorage.setItem(ANALYTICS_CONSENT_STORAGE_KEY, "granted"); + const root = render({ ...config, consentRequired: true }); + const toggle = container.querySelector('[role="switch"]')!; + expect(toggle.getAttribute("aria-checked")).toBe("false"); + expect(toggle.disabled).toBe(true); + expect(container.textContent).toContain("Your browser asks sites not to track you"); + Object.defineProperty(navigator, "globalPrivacyControl", { value: undefined, configurable: true }); + act(() => root.unmount()); + }); +}); diff --git a/ui/src/components/ProductAnalyticsSetting.tsx b/ui/src/components/ProductAnalyticsSetting.tsx new file mode 100644 index 00000000000..943805fd5e2 --- /dev/null +++ b/ui/src/components/ProductAnalyticsSetting.tsx @@ -0,0 +1,47 @@ +import { useId } from "react"; +import { ChartNoAxesColumn } from "lucide-react"; +import type { BrowserAnalyticsConfig } from "@paperclipai/shared"; +import { ToggleSwitch } from "@/components/ui/toggle-switch"; +import { browserBlocksAnalytics, storeAnalyticsChoice, useAnalyticsConsent } from "@/lib/analytics/consent"; +import { PRIVACY_POLICY_URL } from "./AnalyticsConsentBanner"; + +export function ProductAnalyticsSetting({ config }: { config: BrowserAnalyticsConfig | null | undefined }) { + const consent = useAnalyticsConsent(config ?? null); + const labelId = useId(); + const descriptionId = useId(); + if (!config || !consent) return null; + const blocked = browserBlocksAnalytics(config); + return ( +
+
+
+
+ +

Product analytics

+
+

+ {config.replayEnabled + ? "Share usage analytics and session recordings from this browser to help improve Paperclip. Recordings hide what you type and your messages, documents and connected accounts, but may show page names like task titles. " + : "Share usage analytics from this browser to help improve Paperclip. "} + {blocked ? "Your browser asks sites not to track you, so analytics stays off. " : null} + + Privacy policy + +

+
+ storeAnalyticsChoice(checked ? "granted" : "denied")} + aria-labelledby={labelId} + aria-describedby={descriptionId} + /> +
+
+ ); +} diff --git a/ui/src/lib/analytics/consent.test.tsx b/ui/src/lib/analytics/consent.test.tsx new file mode 100644 index 00000000000..22a472d75f6 --- /dev/null +++ b/ui/src/lib/analytics/consent.test.tsx @@ -0,0 +1,134 @@ +// @vitest-environment jsdom + +import { act } from "react"; +import { createRoot } from "react-dom/client"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import type { BrowserAnalyticsConfig } from "@paperclipai/shared"; +import { + ANALYTICS_CONSENT_STORAGE_KEY, + resetAnalyticsConsentForTest, + resolveAnalyticsConsent, + storeAnalyticsChoice, + useAnalyticsConsent, +} from "./consent"; + +Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true }); + +const config: BrowserAnalyticsConfig = { + token: "phc_test", + apiHost: "/_ph", + uiHost: null, + environment: "production", + stackId: "stack-1", + replayEnabled: true, +}; + +function useTimeZone(timeZone: string) { + vi.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions").mockReturnValue({ + ...new Intl.DateTimeFormat("en-US", { timeZone: "UTC" }).resolvedOptions(), + timeZone, + }); +} + +function setNavigatorSignal(name: "doNotTrack" | "globalPrivacyControl", value: unknown) { + Object.defineProperty(navigator, name, { value, configurable: true }); +} + +afterEach(() => { + vi.restoreAllMocks(); + window.localStorage.clear(); + resetAnalyticsConsentForTest(); + setNavigatorSignal("doNotTrack", null); + setNavigatorSignal("globalPrivacyControl", undefined); +}); + +describe("resolveAnalyticsConsent", () => { + it("uses the server's decision when it has one", () => { + useTimeZone("Europe/Paris"); + expect(resolveAnalyticsConsent({ ...config, consentRequired: false })).toBe("granted"); + useTimeZone("America/Chicago"); + expect(resolveAnalyticsConsent({ ...config, consentRequired: true })).toBe("ask"); + }); + + it("falls back to the browser time zone when the server cannot tell", () => { + useTimeZone("Europe/Paris"); + expect(resolveAnalyticsConsent({ ...config, consentRequired: null })).toBe("ask"); + useTimeZone("America/Chicago"); + expect(resolveAnalyticsConsent(config)).toBe("granted"); + }); + + it("requires consent when the browser time zone cannot be read", () => { + vi.spyOn(Intl, "DateTimeFormat").mockImplementation(() => { + throw new Error("no Intl"); + }); + expect(resolveAnalyticsConsent(config)).toBe("ask"); + }); + + it("treats Do Not Track and Global Privacy Control as a decline only where consent is required", () => { + setNavigatorSignal("doNotTrack", "1"); + expect(resolveAnalyticsConsent({ ...config, consentRequired: true })).toBe("denied"); + expect(resolveAnalyticsConsent({ ...config, consentRequired: false })).toBe("granted"); + setNavigatorSignal("doNotTrack", null); + setNavigatorSignal("globalPrivacyControl", true); + expect(resolveAnalyticsConsent({ ...config, consentRequired: true })).toBe("denied"); + }); + + it("a stored choice wins over the region default", () => { + window.localStorage.setItem(ANALYTICS_CONSENT_STORAGE_KEY, "granted"); + expect(resolveAnalyticsConsent({ ...config, consentRequired: true })).toBe("granted"); + window.localStorage.setItem(ANALYTICS_CONSENT_STORAGE_KEY, "denied"); + expect(resolveAnalyticsConsent({ ...config, consentRequired: false })).toBe("denied"); + }); + + it("lets Global Privacy Control and Do Not Track win over a stored grant where consent is required", () => { + window.localStorage.setItem(ANALYTICS_CONSENT_STORAGE_KEY, "granted"); + setNavigatorSignal("globalPrivacyControl", true); + expect(resolveAnalyticsConsent({ ...config, consentRequired: true })).toBe("denied"); + storeAnalyticsChoice("granted"); + expect(resolveAnalyticsConsent({ ...config, consentRequired: true })).toBe("denied"); + expect(resolveAnalyticsConsent({ ...config, consentRequired: false })).toBe("granted"); + setNavigatorSignal("globalPrivacyControl", undefined); + setNavigatorSignal("doNotTrack", "1"); + expect(resolveAnalyticsConsent({ ...config, consentRequired: true })).toBe("denied"); + }); + + it("keeps the choice for this page when storage is unavailable", () => { + vi.spyOn(Storage.prototype, "getItem").mockImplementation(() => { + throw new Error("blocked"); + }); + vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => { + throw new Error("blocked"); + }); + expect(resolveAnalyticsConsent({ ...config, consentRequired: true })).toBe("ask"); + storeAnalyticsChoice("granted"); + expect(resolveAnalyticsConsent({ ...config, consentRequired: true })).toBe("granted"); + }); + + it("lets the latest choice on this page win when saving fails but reading still works", () => { + window.localStorage.setItem(ANALYTICS_CONSENT_STORAGE_KEY, "granted"); + vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => { + throw new Error("quota"); + }); + storeAnalyticsChoice("denied"); + expect(window.localStorage.getItem(ANALYTICS_CONSENT_STORAGE_KEY)).toBe("granted"); + expect(resolveAnalyticsConsent({ ...config, consentRequired: false })).toBe("denied"); + }); + + it("follows a choice that another tab changes", () => { + const seen: string[] = []; + const container = document.createElement("div"); + function Probe() { + seen.push(String(useAnalyticsConsent({ ...config, consentRequired: true }))); + return null; + } + const root = createRoot(container); + act(() => root.render()); + act(() => storeAnalyticsChoice("granted")); + act(() => { + window.localStorage.removeItem(ANALYTICS_CONSENT_STORAGE_KEY); + window.dispatchEvent(new StorageEvent("storage", { key: ANALYTICS_CONSENT_STORAGE_KEY })); + }); + expect(seen.at(-1)).toBe("ask"); + act(() => root.unmount()); + }); +}); diff --git a/ui/src/lib/analytics/consent.ts b/ui/src/lib/analytics/consent.ts new file mode 100644 index 00000000000..c75757cf60c --- /dev/null +++ b/ui/src/lib/analytics/consent.ts @@ -0,0 +1,93 @@ +import { useSyncExternalStore } from "react"; +import { timeZoneRequiresAnalyticsConsent, type BrowserAnalyticsConfig } from "@paperclipai/shared"; + +export const ANALYTICS_CONSENT_STORAGE_KEY = "paperclip.analyticsConsent"; + +export type AnalyticsChoice = "granted" | "denied"; +export type AnalyticsConsent = AnalyticsChoice | "ask"; + +function browserTimeZone(): string | null { + try { + return Intl.DateTimeFormat().resolvedOptions().timeZone ?? null; + } catch { + return null; + } +} + +export function consentRequired(config: BrowserAnalyticsConfig): boolean { + if (typeof config.consentRequired === "boolean") return config.consentRequired; + return timeZoneRequiresAnalyticsConsent(browserTimeZone()); +} + +export function browserAsksNotToTrack(): boolean { + if (typeof navigator === "undefined") return false; + const nav = navigator as Navigator & { globalPrivacyControl?: boolean }; + return nav.globalPrivacyControl === true || nav.doNotTrack === "1"; +} + +export function readStoredAnalyticsChoice(): AnalyticsChoice | null { + try { + const value = window.localStorage.getItem(ANALYTICS_CONSENT_STORAGE_KEY); + return value === "granted" || value === "denied" ? value : null; + } catch { + return null; + } +} + +const listeners = new Set<() => void>(); +let pageChoice: AnalyticsChoice | null = null; + +function writeStoredAnalyticsChoice(choice: AnalyticsChoice): void { + try { + window.localStorage.setItem(ANALYTICS_CONSENT_STORAGE_KEY, choice); + } catch { + return; + } +} + +export function storeAnalyticsChoice(choice: AnalyticsChoice): void { + pageChoice = choice; + writeStoredAnalyticsChoice(choice); + for (const listener of listeners) listener(); +} + +export function analyticsChoiceMadeOnThisPage(): boolean { + return pageChoice !== null; +} + +export function browserBlocksAnalytics(config: BrowserAnalyticsConfig): boolean { + return consentRequired(config) && browserAsksNotToTrack(); +} + +export function resolveAnalyticsConsent(config: BrowserAnalyticsConfig): AnalyticsConsent { + if (browserBlocksAnalytics(config)) return "denied"; + const stored = pageChoice ?? readStoredAnalyticsChoice(); + if (stored) return stored; + return consentRequired(config) ? "ask" : "granted"; +} + +function subscribe(listener: () => void) { + listeners.add(listener); + const onStorage = (event: StorageEvent) => { + if (event.key !== null && event.key !== ANALYTICS_CONSENT_STORAGE_KEY) return; + pageChoice = null; + listener(); + }; + window.addEventListener("storage", onStorage); + return () => { + listeners.delete(listener); + window.removeEventListener("storage", onStorage); + }; +} + +export function useAnalyticsConsent(config: BrowserAnalyticsConfig | null): AnalyticsConsent | null { + return useSyncExternalStore( + subscribe, + () => (config ? resolveAnalyticsConsent(config) : null), + () => null, + ); +} + +export function resetAnalyticsConsentForTest(): void { + pageChoice = null; +} diff --git a/ui/src/lib/analytics/product-analytics.ts b/ui/src/lib/analytics/product-analytics.ts index f77e5fd955c..4468de6765b 100644 --- a/ui/src/lib/analytics/product-analytics.ts +++ b/ui/src/lib/analytics/product-analytics.ts @@ -37,6 +37,11 @@ export interface ProductAnalyticsClient { identify(distinctId: string, personProperties?: Record): void; group(groupType: string, groupKey: string): void; reset(): void; + opt_out_capturing?(): void; + opt_in_capturing?(): void; + has_opted_out_capturing?(): boolean; + startSessionRecording?(): void; + stopSessionRecording?(): void; } /** An event as posthog-js hands it to `before_send`. */ @@ -202,7 +207,9 @@ type State = { config: BrowserAnalyticsConfig; client: ProductAnalyticsClient | null; cancelSchedule: (() => void) | null; + pendingClient: ProductAnalyticsClient | null; loading: boolean; + optedOut: boolean; }; let state: State | null = null; @@ -229,6 +236,25 @@ function applyIdentity(client: ProductAnalyticsClient, config: BrowserAnalyticsC } } +function optOut(client: ProductAnalyticsClient) { + client.opt_out_capturing?.(); + client.stopSessionRecording?.(); +} + +function optIn(client: ProductAnalyticsClient, config: BrowserAnalyticsConfig) { + client.opt_in_capturing?.(); + if (config.replayEnabled) client.startSessionRecording?.(); +} + +function initialize(current: State, client: ProductAnalyticsClient) { + const { config } = current; + client.init(config.token, buildPostHogInitOptions(config, window.location.hostname)); + if (client.has_opted_out_capturing?.()) optIn(client, config); + client.register(superProperties(config)); + current.client = client; + applyIdentity(client, config); +} + /** * Start browser analytics for this page session. Idempotent: posthog-js is a * page-wide singleton, so later calls (session refetches) keep the first @@ -238,8 +264,26 @@ export function startProductAnalytics( config: BrowserAnalyticsConfig, options: ProductAnalyticsOptions, ): void { - if (state) return; - const current: State = { config, client: null, cancelSchedule: null, loading: false }; + if (state) { + if (!state.optedOut) return; + state.optedOut = false; + if (state.client) { + optIn(state.client, state.config); + } else if (state.pendingClient) { + const client = state.pendingClient; + state.pendingClient = null; + initialize(state, client); + } + return; + } + const current: State = { + config, + client: null, + pendingClient: null, + cancelSchedule: null, + loading: false, + optedOut: false, + }; state = current; const load = options.load ?? loadPostHog; current.cancelSchedule = options.schedule(() => { @@ -252,10 +296,8 @@ export function startProductAnalytics( load(config) .then((client) => { if (state !== current) return; - client.init(config.token, buildPostHogInitOptions(config, window.location.hostname)); - client.register(superProperties(config)); - current.client = client; - applyIdentity(client, config); + if (current.optedOut) current.pendingClient = client; + else initialize(current, client); }) .catch(() => { // Analytics must never break the board. A failed script load leaves it @@ -286,11 +328,41 @@ export function resetProductAnalyticsIdentity(): void { * through `setProductAnalyticsUser(null)`. */ export function cancelPendingProductAnalytics(): void { - if (!state || state.client || state.loading) return; + if (!state || state.client || state.pendingClient || state.loading) return; state.cancelSchedule?.(); state = null; } +function stopProductAnalytics(): void { + if (!state) return; + if (!state.client && !state.pendingClient && !state.loading) { + state.cancelSchedule?.(); + state = null; + return; + } + state.optedOut = true; + if (state.client) optOut(state.client); +} + +export function syncProductAnalytics( + config: BrowserAnalyticsConfig, + consent: "granted" | "denied" | "ask", + options: ProductAnalyticsOptions & { immediate?: boolean }, +): () => void { + if (consent !== "granted") { + stopProductAnalytics(); + return () => undefined; + } + const schedule: ProductAnalyticsOptions["schedule"] = options.immediate + ? (start) => { + start(); + return () => undefined; + } + : options.schedule; + startProductAnalytics(config, { ...options, schedule }); + return cancelPendingProductAnalytics; +} + export function resetProductAnalyticsForTest(): void { state?.cancelSchedule?.(); state = null; diff --git a/ui/src/pages/ProfileSettings.tsx b/ui/src/pages/ProfileSettings.tsx index 1cbf197784f..4969d4a8aa5 100644 --- a/ui/src/pages/ProfileSettings.tsx +++ b/ui/src/pages/ProfileSettings.tsx @@ -10,6 +10,7 @@ import { useBreadcrumbs } from "../context/BreadcrumbContext"; import { useCompany } from "../context/CompanyContext"; import { queryKeys } from "../lib/queryKeys"; import { InboxAgentPolicyControl } from "@/components/InboxAgentPolicyControl"; +import { ProductAnalyticsSetting } from "@/components/ProductAnalyticsSetting"; import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"; import { Card } from "@/components/ui/card"; import { Button } from "@/components/ui/button"; @@ -289,6 +290,8 @@ export function ProfileSettings() { + + );