v0.15.0 post-correction: @amplitude/unified + session replay + overlay binding

Mid-Session-L correction to the v0.15.0 release that the dispatched
subagent (Session ξ) shipped. ξ was working from a pre-vendor brief
that specified @amplitude/analytics-browser and treated the API key
as a secret via `flotilla secret set`. Operator subsequently
provisioned the Amplitude project, surfaced the vendor's
recommended installation prompt, and confirmed the key value.
Three downstream changes:

- Package: swap @amplitude/analytics-browser → @amplitude/unified
  (analytics + session replay in one install; vendor-recommended).
- Init call: `amplitude.init(KEY, undefined, { defaultTracking: false })`
  becomes `amplitude.initAll(KEY, { analytics: { autocapture: true },
  sessionReplay: { sampleRate: 1 } })`. Vendor's exact installation-
  wizard shape; gates remain on the v0.13.0 consent banner.
- Binding: Amplitude browser keys are bundle-embedded by design
  (same nature as VITE_TURNSTILE_SITE_KEY from v0.12.0), so the key
  is public, not secret. CHANGELOG MUST step rewritten to bind via
  `flotilla overlay set <deployment> VITE_AMPLITUDE_API_KEY=<key>`
  rather than `flotilla secret set`. The roadmap row #13's
  "new secret: AMPLITUDE_API_KEY" wording predated vendor
  consultation; the roadmap will be updated when this ships.

§19.2 candidate captured in CHANGELOG: split the analytics consent
toggle into a separate session-replay category (recording has a
larger privacy footprint than event counters), follow-up release.

Wrapper structural shape (track/identify/anonymize, queue + drain,
consent-flip → setOptOut, lazy import) is unchanged from ξ's work.
Event taxonomy and Login.jsx / App.jsx / Admin.jsx / etc. instrument
sites are unchanged. Frontend build verified green
(VITE_APP_NAME=… npm run build).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ben Stull
2026-05-28 04:44:33 -07:00
parent 0fd8c52724
commit 6cfbf69e26
5 changed files with 524 additions and 85 deletions
+17 -12
View File
@@ -63,19 +63,24 @@ VITE_COOKIES_POLICY_URL=
# VITE_TURNSTILE_SITE_KEY=0x4AAAAAAA...
VITE_TURNSTILE_SITE_KEY=
# v0.15.0 / roadmap item #13: Amplitude project API key. Embedded in
# the frontend bundle at build time and used by the analytics wrapper
# (`frontend/src/lib/analytics.js`) when the user has granted analytics
# consent (v0.13.0 cookie banner). Provision an Amplitude project at
# app.amplitude.com → Projects → New, copy the API key.
# v0.15.0 / roadmap item #13: Amplitude project API key (public).
# Embedded in the frontend bundle at build time and used by the
# analytics wrapper (`frontend/src/lib/analytics.js`) — which loads
# `@amplitude/unified` (Analytics + Session Replay) when the user
# has granted analytics consent (v0.13.0 cookie banner). Provision
# an Amplitude project at app.amplitude.com → Projects → New, copy
# the API key.
#
# Caveat — secret-vs-overlay binding choice: Amplitude browser API
# keys are visible to anyone with browser dev tools (they ride in the
# shipped bundle). They are conventionally treated as semi-sensitive,
# not truly secret. The roadmap binds the value through flotilla's
# `secret set` verb anyway, to keep all-keys-in-Secret-Manager
# regularity for the OHM deployment. Leave unset in dev; the wrapper
# logs one console warning and no-ops (the app continues to work).
# Public by design: Amplitude browser keys are bundle-embedded
# (visible in dev tools), same nature as VITE_TURNSTILE_SITE_KEY
# (also public; the truly-secret half of that Turnstile pair is
# CLOUDFLARE_TURNSTILE_SECRET on the backend). For deployments
# behind flotilla, bind via `flotilla overlay set <deployment>
# VITE_AMPLITUDE_API_KEY=<key>` — NOT `flotilla secret set`. The
# vendor's installation wizard shows the key inline as a literal
# string in the init call, confirming the public framing. Leave
# unset in dev; the wrapper logs one console warning and no-ops
# (the app continues to work).
#
# Examples:
# VITE_AMPLITUDE_API_KEY=01234567890abcdef01234567890abcd