astro-website/openspec/changes/archive/2026-02-10-dynamic-homepage-social-acquisition/specs/analytics-umami/spec.md

ADDED Requirements

Requirement: Umami pageview tracking

When Umami is enabled by configuration, the site MUST load Umami tracking on all indexable pages and MUST record pageviews.

When Umami is disabled or not configured, the site MUST still function and MUST NOT error in the browser due to missing analytics.

Scenario: Umami enabled

• WHEN Umami is enabled by configuration
• THEN the site includes the Umami script on /, /videos, /podcast, and /about

Scenario: Umami disabled

• WHEN Umami is not configured
• THEN the site renders normally and no analytics script is required

Requirement: Custom event tracking

When Umami is enabled, the site MUST support custom event emission for:

• cta_click
• outbound_click

Each emitted event MUST include enough properties to segment reports by platform and placement when applicable.

Scenario: Emit outbound click event

• WHEN a user clicks a non-CTA outbound link from the homepage
• THEN the system emits an outbound_click event with a property identifying the destination domain

Requirement: Environment configuration

The site MUST support configuration of Umami parameters (at minimum: website ID and script URL) without requiring code changes.

Scenario: Configure Umami via environment

• WHEN Umami configuration values are provided via environment or config file
• THEN the site uses those values to initialize analytics without modifying source code