astro-website/openspec/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
• a general click interaction event for all instrumented clickable items (per the site tracking taxonomy)

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

All tracked clickable items MUST emit events with a unique, consistent set of data elements as defined by the site tracking taxonomy, including at minimum target_id and placement.

The site MUST instrument tracked clickables using Umami's supported Track Events data-attribute method:

• data-umami-event="<event-name>"
• optional event data using data-umami-event-*

For content-related links (clickables representing a specific piece of content), the site MUST also provide the following Umami event data attributes:

• data-umami-event-title
• data-umami-event-type

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

Scenario: Emit general click event for any clickable

• WHEN a user clicks an instrumented navigation link
• THEN the system emits a click interaction event with target_id and placement

Scenario: Content click includes title and type

• WHEN a user clicks an instrumented content link (video, podcast episode, blog post/page)
• THEN the emitted Umami event includes title and type properties via data-umami-event-* attributes

Scenario: Uninstrumented clicks do not break the page

• WHEN a user clicks an element with no tracking metadata
• THEN the system does not throw and navigation/interaction proceeds normally

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