4.0 KiB
Context
The site currently tracks a limited set of Umami custom events (CTAs and outbound links). This change expands measurement so every clickable item can be uniquely identified and analyzed in Umami, with a consistent set of event properties across pages.
We need this to understand what users do on the site (what they click, where they go) and to support iteration on acquisition/conversion.
Constraints:
- Tracking must be safe when analytics is disabled or misconfigured (no runtime errors).
- Tracking should not block navigation or degrade performance.
- We should avoid collecting PII; event properties should be categorical/structural (ids, placements, destinations).
Goals / Non-Goals
Goals:
- Define a site-wide click tracking taxonomy for unique identification of click targets.
- Ensure every clickable item (at minimum: links and buttons) emits a Umami custom event with a unique, consistent set of properties.
- Keep the instrumentation low-friction: adding a new clickable should require adding a small, predictable set of data attributes.
- Preserve existing CTA and outbound tracking semantics, but align them with the taxonomy so dashboards can segment consistently.
Non-Goals:
- Deep product analytics (funnels, sessions, heatmaps) beyond Umami custom events.
- Tracking form input content or any user-provided personal data.
- Implementing a server-side analytics proxy.
Decisions
1) Centralized click listener with data attributes
Decision: Keep a single document-level click handler (event delegation) that inspects the clicked element and its ancestors for tracking metadata (data attributes).
Rationale: Minimizes per-component JS and avoids hydration. It is robust for both static and dynamically inserted content and does not require wiring on every component.
Alternatives considered:
- Per-component tracking calls: more code duplication and higher chance of missed instrumentation.
- Framework-level router hooks: not applicable for a static-first site and does not cover outbound navigation.
2) Taxonomy: stable ids + placement + destination
Decision: Standardize on a minimal required property set for every tracked click:
action(event name or action type; e.g.,click)target_id(stable identifier for the clickable element; unique within the site)placement(where it appears; e.g.,nav,hero,section_header,content_card)target_url(destination URL for links; optional for buttons)- Optional:
target_domain,source(youtube/podcast/instagram for content cards),label
Rationale: This allows segmentation by page region and click target, and provides "where users are going" without needing full URL logging everywhere.
3) Event naming strategy
Decision: Use a primary generic event name for click tracking (e.g., click) and reserve specialized event names (e.g., cta_click) only when they provide value or already exist.
Rationale: A single event name makes dashboards simpler. Specialized names can be preserved for backwards compatibility, but taxonomy properties must be consistent either way.
4) Uniqueness rules
Decision: Require every clickable item to define a stable target_id that is unique across the site (or unique within a namespace) and deterministic between builds.
Rationale: Prevents ambiguous metrics and supports comparing performance over time.
5) Safety and performance
Decision: Tracking MUST be best-effort:
- Never throw errors if
window.umamiis missing - Never block navigation (no awaited network calls)
- Avoid attaching large payloads; keep properties small and categorical
Risks / Trade-offs
- [Over-instrumentation complexity] -> Provide a clear taxonomy and reusable helpers/components for common clickables.
- [Inconsistent ids] -> Document required id rules and add simple lint/test checks later (optional).
- [Umami limitations] -> Keep properties to a small set and ensure they map cleanly to Umami filters.
- [Privacy concerns] -> Prohibit PII in event properties; prefer domains/ids over full URLs where appropriate.