analytics-and-monitoring

Analytics & Monitoring

Work with the GA4 analytics and Sentry error-monitoring integrations in this project. Use when adding events, capturing errors, configuring user identity, managing consent, or troubleshooting the integration.

Architecture overview

Both integrations follow the adapter pattern: a thin typed wrapper in src/lib/ owns the SDK, and all other code uses the adapter (or the React hooks) — never the raw SDK.

src/lib/analytics.ts    → GA4 gtag.js adapter
src/lib/monitoring.ts   → Sentry adapter (also re-exports ErrorBoundary)
src/types/analytics.ts  → Typed event definitions
src/types/monitoring.ts → Error context / user / breadcrumb types
src/hooks/useAnalytics.ts     → React hook (route-aware)
src/hooks/useMonitoring.ts    → React hook
src/hooks/usePageTracking.ts  → Auto page-view on route change
src/components/ErrorFallback.tsx → Fallback UI for SentryErrorBoundary

GA4 — Adding a new tracked event

1. Define the event shape in src/types/analytics.ts:

   export type FeatureUsedEvent = {
     name: 'feature_used'
     params: { feature: string; duration_ms?: number }
   }
   

2. Add it to the AnalyticsEvent union in the same file.

3. Track it from feature code:

   import { analytics } from '@/lib/analytics'
   analytics.track({ name: 'feature_used', params: { feature: 'export' } })
   

   Or via the hook:

   const { track } = useAnalytics()
   track({ name: 'feature_used', params: { feature: 'export' } })
   

Event naming rules (GA4)

• Use snake_case, max 40 characters.
• Avoid GA4 reserved names: click, error, first_visit, page_view, scroll, session_start, user_engagement.
• Prefer recommended events (login, sign_up, search, share, select_content, exception) when they fit — GA4 provides enhanced reporting for these.

User identification (GA4)

analytics.setUserId(user.id)                    // after login — internal ID only, no PII
analytics.setUserProperties({ plan: 'pro' })    // user-scoped custom dimensions
analytics.clearUserId()                          // on logout