feat(analytics): ask EU, UK and Swiss visitors before Cloud browser analytics (#22186)

## Thinking Path

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

## Linked Issues or Issue Description

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

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

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

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

## What Changed

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

## Verification

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

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

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

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

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

## Risks

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

## Model Used

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

## Checklist

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

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-18 10:52:20 -06:00
1 parent 875e4d375e
commit 3c460f20cc
20 files changed
+959 -29

No files matched your search

+68
View File
@@ -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
@@ -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);
},
);
});
+82
View File
@@ -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);
}
+1
View File
@@ -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";
+1
View File
@@ -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<typeof browserAnalyticsConfigSchema>;
+7
View File
@@ -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 () => {
@@ -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");
+1 -1
View File
@@ -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 } : {}) });
});
+15 -2
View File
@@ -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<string, string | string[] | undefined>;
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),
};
}
@@ -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",
@@ -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<typeof AnalyticsConsentBanner>[0]) {
container = document.createElement("div");
document.body.appendChild(container);
const root = createRoot(container);
act(() => root.render(<AnalyticsConsentBanner {...props} />));
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());
});
});
@@ -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 (
<section
aria-label="Analytics choice"
aria-describedby={textId}
className="fixed inset-x-4 bottom-(--sz-calc-14) z-40 mx-auto max-w-xl rounded-md border bg-popover text-popover-foreground shadow-lg md:bottom-4"
>
<div className="flex flex-col gap-3 p-4 sm:flex-row sm:items-center">
<p id={textId} className="flex-1 text-sm text-muted-foreground">
{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. "}
<a
href={PRIVACY_POLICY_URL}
target="_blank"
rel="noreferrer"
className="font-medium text-foreground underline underline-offset-4 hover:opacity-90"
>
Privacy policy
</a>
</p>
<div className="flex shrink-0 gap-2">
<Button type="button" variant="outline" size="sm" onClick={onDecline}>
Decline
</Button>
<Button type="button" size="sm" onClick={onAccept}>
Accept
</Button>
</div>
</div>
</section>
);
}
+168 -9
View File
@@ -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(<T extends Node>(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(<T extends Node>(node:
const ACTOR_ID = "paperclip-id:uf2X8Ha4H9hNdAMnc1rOy91VIRos5pch";
const user = { id: ACTOR_ID, email: "jane@example.com", name: "Jane", image: null };
function analyticsConfig(overrides: Record<string, unknown> = {}) {
return {
token: "phc_test",
apiHost: "/_ph",
uiHost: null,
environment: "production",
stackId: "stack-1",
replayEnabled: false,
...overrides,
};
}
function banner() {
return document.querySelector<HTMLElement>('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());
});
});
+21 -8
View File
@@ -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 (
<AnalyticsConsentBanner
recordings={config.replayEnabled}
onAccept={() => storeAnalyticsChoice("granted")}
onDecline={() => storeAnalyticsChoice("denied")}
/>
);
}
@@ -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(<ProductAnalyticsSetting config={value} />));
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<HTMLButtonElement>('[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<HTMLButtonElement>('[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());
});
});
@@ -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 (
<section className="space-y-4" aria-labelledby={labelId}>
<div className="flex max-w-2xl items-start justify-between gap-4">
<div className="space-y-1">
<div className="flex items-center gap-2">
<ChartNoAxesColumn className="h-5 w-5 text-muted-foreground" />
<h2 id={labelId} className="text-base font-semibold">Product analytics</h2>
</div>
<p id={descriptionId} className="text-sm text-muted-foreground">
{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}
<a
href={PRIVACY_POLICY_URL}
target="_blank"
rel="noreferrer"
className="font-medium text-foreground underline underline-offset-4 hover:opacity-90"
>
Privacy policy
</a>
</p>
</div>
<ToggleSwitch
checked={consent === "granted"}
disabled={blocked}
onCheckedChange={(checked) => storeAnalyticsChoice(checked ? "granted" : "denied")}
aria-labelledby={labelId}
aria-describedby={descriptionId}
/>
</div>
</section>
);
}
+134
View File
@@ -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(<Probe />));
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());
});
});
+93
View File
@@ -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;
}
+79 -7
View File
@@ -37,6 +37,11 @@ export interface ProductAnalyticsClient {
identify(distinctId: string, personProperties?: Record<string, unknown>): 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;
+3
View File
@@ -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() {
</form>
<InboxAgentPolicyControl companyId={selectedCompanyId} />
<ProductAnalyticsSetting config={sessionQuery.data.browserAnalytics} />
</section>
</div>
);