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

Context

The site uses Umami custom events via data attributes on clickables (e.g., navigation, CTAs, outbound links). Today, most tracked links include stable identifiers like target_id, placement, and (for links) target_url.

This is sufficient to measure where users clicked, but it is limited for content discovery because it does not capture content metadata (e.g., which specific video/post title was clicked). Umami supports adding additional event data via data-umami-event-* attributes, which are recorded as strings.

Goals / Non-Goals

Goals:

• Add content metadata fields to Umami click tracking for content-related links:
  • title (human-readable title)
  • type (content type)
• Apply consistently across content surfaces (videos, podcast, blog).
• Keep existing taxonomy constraints intact:
  • stable deterministic target_id
  • placement
  • target_url for links
• Avoid tracking PII.

Non-Goals:

• Introducing JavaScript-based window.umami.track calls (continue using Umami data-attribute tracking).
• Tracking clicks inside arbitrary WordPress-rendered HTML bodies (future enhancement if needed).
• Changing Umami initialization or environment configuration.

Decisions

• Decision: Use Option 1 (separate title and type fields).

  • Rationale: Makes reporting and filtering easier (segment by type, then list top title). Avoids parsing concatenated strings in analytics.
  • Alternative: Option 2 (single title field formatted as [type]-[title]). Rejected for reduced queryability.

• Decision: Only apply title/type to content-related links (not all links).

  • Rationale: Many links do not map cleanly to a single content item (e.g., category nav, pagination, generic navigation).

• Decision: Normalize type values.

  • Rationale: Stable type values enable dashboards to be reused over time.
  • Proposed set (from specs): video, podcast_episode, blog_post, blog_page.

• Decision: Prefer shared components to propagate tracking fields.

  • Rationale: Centralize logic and reduce missed clickables.
  • Approach:
    • Extend existing link/card components (where applicable) to accept optional umamiTitle and umamiType props.
    • For pages that render raw <a> tags directly, add attributes inline.

Risks / Trade-offs

• [Risk] Title values can change over time (content edits) which may reduce longitudinal stability.

  • Mitigation: Keep target_id deterministic and stable; use title for reporting convenience only.

• [Risk] Very long titles.

  • Mitigation: Truncate title values to a reasonable length (e.g., 120-160 chars) at instrumentation time if needed.

• [Risk] Inconsistent application across surfaces.

  • Mitigation: Add tests that assert content clickables include data-umami-event-title and data-umami-event-type where applicable.