frontend-observability

Define canonical event names as constants in a constants/analytics.ts file with a union type, then call track() with those constants from client components via a useAnalytics() hook. The union type makes event-name typos a compile error instead of silent data drift.

Wrap each provider adapter call in its own try/catch inside a single track() fan-out, and guard every adapter against missing window globals or unloaded scripts. A failing or absent provider then no-ops without throwing into the caller or blocking other providers.

Yes, one adapter shape covers both platforms because the web firebase/analytics SDK and @react-native-firebase/analytics share the same logEvent(name, params) contract. Resolve the platform variant by file extension so the taxonomy, fan-out, and consent gate stay unchanged.

Server Components cannot use the useAnalytics() hook, so wrap tracked elements in thin client components. The hook returns a no-op outside a provider or on the server, so instrumented components render safely anywhere including SSR trees.

Check consent once at the track() fan-out boundary rather than at every call site, defaulting consent to false where regulations require. No events, web vitals, or error reports with PII fire before opt-in, and event props should use ids and enums instead of emails or names.

Reporting real-user LCP, INP, and CLS through the same fan-out closes the lab/field loop with synthetic Lighthouse budgets using identical metrics and thresholds. A lab-green but field-poor result reveals gaps between test conditions and real devices or networks.