Core: provider-agnostic analytics plugin with Statsig adapter (full legacy parity)

[stephenliang]

Adds @code-dot-org/core/plugins/analytics so Next Generation Frontend Platform packages can log product analytics without importing the legacy apps/ bundle (closes #73791). The public surface is deliberately small and provider-blind — sendEvent(name, payload), setUser(user), and analyticsPlugin for initializeCore — with Statsig as the first provider, loaded as a lazy chunk so @statsig/js-client stays out of bundles that don't opt in. The governing constraint throughout: full parity with apps/src/metrics/StatsigReporter.js, so the data flowing to Statsig does not change.

How it works

sequenceDiagram
    participant Page as Host page head
    participant OT as OneTrust stub and SDK
    participant A as analyticsPlugin
    participant S as StatsigClient lazy chunk

    Page->>OT: load stub, define oneTrustPromise
    Page->>A: initializeCore -> onCoreReady
    A->>A: read provider from app-config meta
    A->>A: install DeferredAdapter, buffer sendEvent and setUser
    OT-->>A: first report -> consent state + settled signal
    Note over A: no OneTrust on page: settles immediately.<br/>OneTrust present but never loads: never settles,<br/>nothing sends (legacy unresolved-promise parity)
    A->>A: single consent decision per page load:<br/>C0002 grant -> persist stable ID,<br/>else delete our copies, SDK mints its own
    A->>S: dynamic import, init with config and session
    A->>S: flush buffered calls in order

Loading

Consent model (parity, not policy change)

Consent never gates event sending — it gates only stable-ID persistence, decided once per page load at OneTrust's first report, exactly mirroring legacy's oneTrustPromise.then(initializeAfterConsent). A C0002 grant persists the same cookie (statsig_stable_id on .code.org, session-scoped, SameSite=Lax, Secure) and the same localStorage key that other code.org pages use, so IDs carry across legacy pages, new pages, and the Rails server-side session reader. Reads and writes go through js-cookie (added in #74393), which is also what apps/ uses for this cookie. Anything else deletes our persisted copies and passes stableID: undefined so the SDK mints its own, as legacy does. Mid-session consent changes are ignored until the next page load (legacy behavior: OptanonWrapper re-fires but the promise is already resolved).

The settlement signal (whenConsentSettled, stack layer #74392) carries the "has the CMP finished speaking" state: pages without OneTrust settle immediately and send; pages where OneTrust never loads never settle and never send — both faithful to legacy, verified against the production otSDKStub.js pipeline. The consent store itself is unchanged (Set shape).

Legacy quirks replicated deliberately

logEvent(name, name, payload) keeps the event name in Statsig's value slot for dashboard continuity. Identity updates replicate setUserProperties exactly, including its omission of customIDs. Init-time user carries custom.enabledExperiments (via plugins/experiments, stack layer #74393) and geRegion (read from data-ge-region, which the new Studio shell does not stamp yet — documented gap, reads null there). SDK-side storage is left enabled as in legacy. disableErrorLogging was dropped: it never existed in @statsig/js-client and was dead config in the legacy reporter.

Config and environments

The Statsig client key travels in the app-config meta tag (parsed by SiteConfig beside observability), replacing the legacy script[data-statsig-api-client-key] transport for frontend/ pages. The transmit decision is server-side in StatsigAnalyticsHelper#analytics_config; FrontendAppConfigHelper#frontend_app_config states the meta's shape as a literal, composed from the helpers that own each section (the observability engine gains a hash-returning section method; its existing JSON API is unchanged). An environment transmits iff it provisions a client key — production and the managed test server do, everywhere else the key defaults to blank and the page is served 'none', the same environments legacy's client-side local_mode allowed. A developer sets a real statsig_api_client_key in locals.yml to exercise the provider locally. Development without a key gets a console-logging adapter mirroring legacy's local-mode log lines.

Consumers

Studio registers the plugin (after consentPlugin — order matters and is documented). Identity is seeded from the app-config meta when the server renders it (user: {userId, userType}, signed-in pages only), so first events carry userID; pages without the seed boot anonymous and identify via setUser from the router's beforeLoad, which re-asserts with a same-user short-circuit so SPA navigations don't trigger redundant updateUserAsync refetches. The users package fires the legacy Account Settings Page Visited event at mount; the other five legacy account events belong to features (LTI unlink, roster sync, AI-diff toggle) whose UI does not exist in the new page yet, so they intentionally stay on the legacy page.

Links

• Jira: N/A — tracked as GitHub issue Core: add shared browser analytics for Next Generation Frontend Platform apps #73791
• Stack: Core consent: settlement signal for the page's consent source #74392 (consent settlement) → Core: experiments plugin exposing getEnabledExperiments #74393 (experiments plugin) → this PR
• Consumes the consent plugin from feat(core): cookie-consent plugin (@code-dot-org/core/plugins/consent) #73796
• Unblocks analytics parity for Account Settings (Accounts: analytics parity for account settings #73227) and Certificates (feat(certificates): render certificates client-side #73693)

Testing story

Built TDD; 235 core / 186 users / 88 studio vitest tests pass (28 analytics, 27 consent), plus new Ruby tests for analytics_config in dashboard/test/helpers. yarn release:dryrun (build + lint + typecheck + test) green across all 68 turbo tasks; both yarn.locks regenerated and --immutable-clean (apps consumes core via a yarn portal). An adversarial code review (15 confirmed findings) drove a hardening round: generation-guarded async boot, cookie-decode guards, explicit @statsig/js-client peer declarations, bundle-graph verification that the analytics chunk pulls no OneTrust/observability code. Parity was verified against legacy source line-by-line and against the production OneTrust stub's actual initialization pipeline.

Not verifiable locally, needs a deployed environment: a real event landing in Statsig from a non-production deploy, and GDPR-geolocated banner behavior.

Deployment notes

No migrations or feature flags. Frontend Studio pages start reporting to Statsig on deploy (production/managed-test only), under the same event names and stable IDs legacy uses. Known gap: geRegion reads null on the new Studio shell until it stamps data-ge-region on the root element like the legacy layout does.

Privacy and security

No new PII and no change to what is collected: consent semantics are byte-for-byte parity with the legacy reporter (consent gates stable-ID persistence only, sending was never consent-gated), the stable-ID cookie contract is unchanged, and the Statsig SDK's own storage behavior is unchanged. The one behavioral tightening is bundle hygiene: the analytics subpath cannot drag the OneTrust provider or observability graph into consumer bundles.

🤖 Generated with Claude Code

[github-actions]

🖼️ Storybook Visual Comparison Report

✅ No Storybook eyes differences detected!