Skip to main content

Umami Analytics Runbook

This runbook defines how IED uses Umami for the public web app and how to keep reporting clean.

Scope​

  • app: apps/web
  • tracking provider: Umami script (NEXT_PUBLIC_UMAMI_SCRIPT_URL)
  • website identifier: NEXT_PUBLIC_UMAMI_WEBSITE_ID

Configuration​

Required public env vars:

  • NEXT_PUBLIC_UMAMI_SCRIPT_URL
  • NEXT_PUBLIC_UMAMI_WEBSITE_ID

Current implementation:

  • Script is loaded in apps/web/src/core/analytics/web-analytics-tracker.tsx
  • Pageviews are manually tracked on SPA route transitions
  • First-load manual pageview is skipped to avoid duplicate initial hits

Event Taxonomy​

Behavioral events (code)​

  • assessment_start_view
  • assessment_postcode_unsupported
  • assessment_submitted
  • contact_page_view
  • contact_submit_success
  • contact_submit_failed
  • recommendation_results_view
  • next_step_view
  • next_step_selected_path
  • funnel_submission_success
  • funnel_submission_failed

CTA click events (data attributes)​

All declarative CTA clicks use:

  • data-umami-event="cta_click"
  • data-umami-event-id="..."
  • data-umami-event-position="..."

This keeps click reporting simple while preserving action context.

Umami Dashboard Setup​

Recommended funnels:

  1. assessment_start_view
  2. recommendation_results_view
  3. next_step_selected_path
  4. funnel_submission_success

Recommended saved filters:

  • by selectedPath
  • by batteryRecommendation
  • by technicalReason for failure diagnostics

Data Quality Rules​

  • Keep event names stable (snake_case)
  • Avoid renaming existing events without migration notes
  • Keep metadata small and predictable
  • Do not include raw personal data (email, full phone, full name) in event metadata

Verification Checklist​

  1. Open home page and navigate to /start, /results, /next-step, /confirmation
  2. Submit contact form once (success path)
  3. Confirm pageviews appear in Umami realtime
  4. Confirm custom events appear with expected metadata
  5. Confirm cta_click events include id and position dimensions

Troubleshooting​

No events appearing:

  • verify NEXT_PUBLIC_UMAMI_SCRIPT_URL
  • verify NEXT_PUBLIC_UMAMI_WEBSITE_ID
  • inspect network requests to Umami host
  • verify browser privacy/adblock rules are not blocking your self-hosted domain

Unexpected duplicate pageviews:

  • verify first-load skip logic in tracker is present
  • verify no duplicate script tags are rendered

Missing route transitions:

  • verify usePathname() updates and tracker component is mounted in root layout