astro-website/openspec/changes/archive/2026-02-10-better-tracking/proposal.md

Why

Umami click tracking is currently limited to target_id/placement, which makes it harder to understand which specific content items (by title/type) users engage with most. Adding lightweight content metadata to click events enables clearer measurement and reporting.

What Changes

• Extend Umami click event instrumentation so content-related links include additional event data:
  • data-umami-event-title: the content title (e.g., post/video/episode/page title)
  • data-umami-event-type: the content type (e.g., blog_post, blog_page, video, podcast_episode)
• Apply the above consistently across all instrumented content links (cards, lists, navigation items that represent a specific piece of content).
• Ensure the metadata is additive and does not replace the existing deterministic identifiers:
  • keep data-umami-event-target_id
  • keep data-umami-event-placement
  • keep data-umami-event-target_url for links

Capabilities

New Capabilities

• (none)

Modified Capabilities

• interaction-tracking-taxonomy: add/standardize optional content metadata fields (title, type) for tracked click events, and define allowed values for type.
• analytics-umami: require Umami Track Events data-attribute instrumentation to support the above additional data-umami-event-* properties on content-related clickables.

Impact

• Affected code: shared link/card components and content listing/detail pages (videos, podcast, blog posts/pages, and any other instrumented content surfaces).
• Data: Umami event payloads will include two additional string fields for content links; dashboards/reports can segment by type and view top-clicked items by title.