74 lines
4.0 KiB
Markdown
74 lines
4.0 KiB
Markdown
## 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.umami` is 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.
|
|
|