45 lines
2.7 KiB
Markdown
45 lines
2.7 KiB
Markdown
## Context
|
||
|
||
The site uses Umami for analytics. Most site clickables are instrumented using Umami’s data-attribute method (`data-umami-event` and optional `data-umami-event-*` properties) so events are recorded automatically on click.
|
||
|
||
The Blog section was added recently and its clickables (post cards, category nav, page links) are not consistently emitting Umami events. This creates a measurement blind spot for the `/blog` surface.
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
- Ensure all blog clickables emit Umami events using the documented data-attribute method.
|
||
- Ensure every tracked clickable has a deterministic, unique `target_id` and includes at minimum `placement` and `target_url` per taxonomy.
|
||
- Keep event names within Umami limits (<= 50 chars) and avoid sending event data without an event name.
|
||
- Add tests to prevent regressions (blog pages/components should contain required Umami attributes).
|
||
|
||
**Non-Goals:**
|
||
- Introducing custom JavaScript tracking (`window.umami.track`) for v1; we will use Umami’s data-attribute method.
|
||
- Adding new analytics providers or changing Umami initialization.
|
||
- Tracking PII or user-generated content in event properties.
|
||
|
||
## Decisions
|
||
|
||
- **Decision: Use Umami-native data attributes on every blog clickable.**
|
||
- Rationale: Aligns with Umami’s “Track events” docs and the rest of the site’s tracking approach; avoids adding JS listeners that can interfere with other handlers.
|
||
|
||
- **Decision: Use consistent event names by clickable type.**
|
||
- Rationale: Keeps reporting clean while still allowing segmentation via event properties.
|
||
- Proposed:
|
||
- `click` for internal navigation links (including blog category navigation)
|
||
- `outbound_click` for external links (if any in blog chrome)
|
||
|
||
- **Decision: Add a deterministic `target_id` namespace for blog elements.**
|
||
- Rationale: Blog has many repeated elements; we need unique IDs that remain stable across builds.
|
||
- Proposed conventions:
|
||
- Blog header link: `nav.blog`
|
||
- Blog secondary nav: `blog.subnav.all`, `blog.subnav.pages`, `blog.subnav.category.<slug>`
|
||
- Blog post card: `blog.card.post.<slug>` (placement `blog.index` or `blog.category.<slug>`)
|
||
- Blog post detail back link: `blog.post.back`
|
||
- Blog page list links: `blog.pages.link.<slug>`
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- [Risk] Some blog content areas render raw HTML from WordPress; links inside content are not instrumented. -> Mitigation: Track the blog chrome (cards/nav/back links) first; consider JS-based delegated tracking for content-body links in a future change if needed.
|
||
- [Risk] Over-instrumentation adds noisy events. -> Mitigation: Keep event names simple, rely on `target_id` + `placement` for segmentation, and avoid tracking non-clickable elements.
|
||
|