astro-website/openspec/changes/archive/2026-02-10-better-tracking/specs/analytics-umami/spec.md

MODIFIED Requirements

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