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
• media_preview
• media_preview_close
• theme_switch
• 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 interactions that are triggered programmatically (e.g., modal close events where the close method must be recorded), the site MAY use Umami's JavaScript API (umami.track()) instead of data attributes when data attributes cannot express the required properties.

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

Scenario: Media preview event emitted on card click

• WHEN a user clicks a video or podcast content card that opens a media modal
• THEN the system emits a media_preview event with target_id, placement, title, type, and source

Scenario: Media preview close event emitted

• WHEN a user closes the media modal
• THEN the system emits a media_preview_close event with the target_id of the content that was previewed and the close_method used

Scenario: Modal CTA click emitted

• WHEN a user clicks a CTA inside the media modal (e.g., "View on YouTube")
• THEN the system emits a cta_click event with target_id, placement=media_modal, platform, and target_url

Requirement: Theme switch tracking event

When Umami is enabled, the site MUST emit a custom event when the user changes theme via the theme switcher UI.

The site MUST emit the event using Umami's JavaScript API (umami.track(...)) so runtime properties can be included.

The event name MUST be theme_switch.

The emitted event MUST include, at minimum:

• target_id
• placement
• theme

Scenario: Theme switch emits event

• WHEN a user selects high-contrast in the theme switcher notch
• THEN the site emits a theme_switch event with theme=high-contrast and a stable target_id

Scenario: Missing Umami does not break switching

• WHEN Umami is not configured or the Umami script is not present
• THEN theme switching and persistence still work and no browser error is thrown

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