57 lines
2.8 KiB
Markdown
57 lines
2.8 KiB
Markdown
## 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.
|
|
|