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() { + + );