astro-website/openspec/changes/reduce-bounce-rate/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
• media_preview
• media_preview_close
• 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