better tracking
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-10
|
||||
@@ -0,0 +1,56 @@
|
||||
## 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.
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
## Why
|
||||
|
||||
Umami click tracking is currently limited to `target_id`/`placement`, which makes it harder to understand *which* specific content items (by title/type) users engage with most. Adding lightweight content metadata to click events enables clearer measurement and reporting.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Extend Umami click event instrumentation so content-related links include additional event data:
|
||||
- `data-umami-event-title`: the content title (e.g., post/video/episode/page title)
|
||||
- `data-umami-event-type`: the content type (e.g., `blog_post`, `blog_page`, `video`, `podcast_episode`)
|
||||
- Apply the above consistently across all instrumented content links (cards, lists, navigation items that represent a specific piece of content).
|
||||
- Ensure the metadata is additive and does not replace the existing deterministic identifiers:
|
||||
- keep `data-umami-event-target_id`
|
||||
- keep `data-umami-event-placement`
|
||||
- keep `data-umami-event-target_url` for links
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- (none)
|
||||
|
||||
### Modified Capabilities
|
||||
- `interaction-tracking-taxonomy`: add/standardize optional content metadata fields (`title`, `type`) for tracked click events, and define allowed values for `type`.
|
||||
- `analytics-umami`: require Umami Track Events data-attribute instrumentation to support the above additional `data-umami-event-*` properties on content-related clickables.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected code: shared link/card components and content listing/detail pages (videos, podcast, blog posts/pages, and any other instrumented content surfaces).
|
||||
- Data: Umami event payloads will include two additional string fields for content links; dashboards/reports can segment by `type` and view top-clicked items by `title`.
|
||||
@@ -0,0 +1,36 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Custom event tracking
|
||||
When Umami is enabled, the site MUST support custom event emission for:
|
||||
- `cta_click`
|
||||
- `outbound_click`
|
||||
- a general click interaction event for all instrumented clickable items (per the site tracking taxonomy)
|
||||
|
||||
Each emitted event MUST include enough properties to segment reports by platform and placement when applicable.
|
||||
|
||||
All tracked clickable items MUST emit events with a unique, consistent set of data elements as defined by the site tracking taxonomy, including at minimum `target_id` and `placement`.
|
||||
|
||||
The site MUST instrument tracked clickables using Umami’s supported Track Events data-attribute method:
|
||||
- `data-umami-event="<event-name>"`
|
||||
- optional event data using `data-umami-event-*`
|
||||
|
||||
For content-related links (clickables representing a specific piece of content), the site MUST also provide the following Umami event data attributes:
|
||||
- `data-umami-event-title`
|
||||
- `data-umami-event-type`
|
||||
|
||||
#### Scenario: Emit outbound click event
|
||||
- **WHEN** a user clicks a non-CTA outbound link from the homepage
|
||||
- **THEN** the system emits an `outbound_click` event with a property identifying the destination domain
|
||||
|
||||
#### Scenario: Emit general click event for any clickable
|
||||
- **WHEN** a user clicks an instrumented navigation link
|
||||
- **THEN** the system emits a click interaction event with `target_id` and `placement`
|
||||
|
||||
#### Scenario: Content click includes title and type
|
||||
- **WHEN** a user clicks an instrumented content link (video, podcast episode, blog post/page)
|
||||
- **THEN** the emitted Umami event includes `title` and `type` properties via `data-umami-event-*` attributes
|
||||
|
||||
#### Scenario: Uninstrumented clicks do not break the page
|
||||
- **WHEN** a user clicks an element with no tracking metadata
|
||||
- **THEN** the system does not throw and navigation/interaction proceeds normally
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Minimum required properties
|
||||
Every tracked click event MUST include, at minimum:
|
||||
- `target_id`
|
||||
- `placement`
|
||||
|
||||
For links, the event MUST also include:
|
||||
- `target_url` (or a stable target identifier that can be mapped to a URL)
|
||||
|
||||
For content-related links (clickables representing a specific piece of content), the event MUST also include:
|
||||
- `title` (human-readable content title)
|
||||
- `type` (content type identifier)
|
||||
|
||||
The `type` value MUST be one of:
|
||||
- `video`
|
||||
- `podcast_episode`
|
||||
- `blog_post`
|
||||
- `blog_page`
|
||||
|
||||
#### Scenario: Tracking a content card click
|
||||
- **WHEN** a user clicks a content card link
|
||||
- **THEN** the emitted event includes `target_id`, `placement`, and `target_url`
|
||||
|
||||
#### Scenario: Tracking a content link includes title and type
|
||||
- **WHEN** a user clicks a content-related link that represents a specific content item
|
||||
- **THEN** the emitted event includes `target_id`, `placement`, `target_url`, `title`, and `type`
|
||||
|
||||
15
openspec/changes/archive/2026-02-10-better-tracking/tasks.md
Normal file
15
openspec/changes/archive/2026-02-10-better-tracking/tasks.md
Normal file
@@ -0,0 +1,15 @@
|
||||
## 1. Update Tracking Taxonomy
|
||||
|
||||
- [x] 1.1 Update shared Umami instrumentation patterns to support optional `title` and `type` event data for content links (without breaking existing events)
|
||||
- [x] 1.2 Ensure content `type` values are normalized (`video`, `podcast_episode`, `blog_post`, `blog_page`) and do not include PII
|
||||
|
||||
## 2. Instrument Content Surfaces
|
||||
|
||||
- [x] 2.1 Add `data-umami-event-title` and `data-umami-event-type` to video clickables (listing cards and detail navigation where applicable)
|
||||
- [x] 2.2 Add `data-umami-event-title` and `data-umami-event-type` to podcast clickables (listing cards and episode links)
|
||||
- [x] 2.3 Add `data-umami-event-title` and `data-umami-event-type` to blog clickables that represent specific content items (post cards, pages list links)
|
||||
|
||||
## 3. Verify
|
||||
|
||||
- [x] 3.1 Add/update tests to assert content clickables include `data-umami-event-title` and `data-umami-event-type` where required
|
||||
- [x] 3.2 Build the site and confirm representative pages render the new data attributes (videos listing, podcast listing, blog listing)
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-10
|
||||
44
openspec/changes/archive/2026-02-10-blog-umami-fix/design.md
Normal file
44
openspec/changes/archive/2026-02-10-blog-umami-fix/design.md
Normal file
@@ -0,0 +1,44 @@
|
||||
## 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.
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
## Why
|
||||
|
||||
The Blog section’s click tracking is not firing reliably in Umami, which prevents measuring what users do in `/blog` and where they go next.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Update the Blog section UI so every clickable element uses Umami’s data-attribute event tracking format:
|
||||
- `data-umami-event="<event-name>"`
|
||||
- `data-umami-event-*` attributes for event data
|
||||
- Ensure every tracked clickable item has a unique, deterministic set of event data elements (especially `target_id`, `placement`, `target_url`) so clicks can be measured independently.
|
||||
- Add verification/tests to ensure Blog clickables are instrumented and follow the same taxonomy as the rest of the site.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- (none)
|
||||
|
||||
### Modified Capabilities
|
||||
- `blog-section-surface`: instrument blog clickables (post cards, post/page links, category secondary nav, blog header link) using Umami `data-umami-event` attributes.
|
||||
- `interaction-tracking-taxonomy`: extend/clarify tracking rules to cover blog-specific UI elements and namespaces for `target_id`.
|
||||
- `analytics-umami`: ensure the implementation adheres to Umami’s Track Events specification for data attributes.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected UI/components: blog pages and components under `site/src/pages/blog/` and `site/src/components/` (cards and secondary nav), plus any shared navigation link to `/blog`.
|
||||
- Testing: add/update tests to assert required Umami data attributes exist and are unique per clickable element in blog surfaces.
|
||||
@@ -0,0 +1,28 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Custom event tracking
|
||||
When Umami is enabled, the site MUST support custom event emission for:
|
||||
- `cta_click`
|
||||
- `outbound_click`
|
||||
- a general click interaction event for all instrumented clickable items (per the site tracking taxonomy)
|
||||
|
||||
Each emitted event MUST include enough properties to segment reports by platform and placement when applicable.
|
||||
|
||||
All tracked clickable items MUST emit events with a unique, consistent set of data elements as defined by the site tracking taxonomy, including at minimum `target_id` and `placement`.
|
||||
|
||||
The site MUST instrument tracked clickables using Umami’s supported Track Events data-attribute method:
|
||||
- `data-umami-event="<event-name>"`
|
||||
- optional event data using `data-umami-event-*`
|
||||
|
||||
#### Scenario: Emit outbound click event
|
||||
- **WHEN** a user clicks a non-CTA outbound link from the homepage
|
||||
- **THEN** the system emits an `outbound_click` event with a property identifying the destination domain
|
||||
|
||||
#### Scenario: Emit general click event for any clickable
|
||||
- **WHEN** a user clicks an instrumented navigation link
|
||||
- **THEN** the system emits a click interaction event with `target_id` and `placement`
|
||||
|
||||
#### Scenario: Uninstrumented clicks do not break the page
|
||||
- **WHEN** a user clicks an element with no tracking metadata
|
||||
- **THEN** the system does not throw and navigation/interaction proceeds normally
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Blog index listing (posts)
|
||||
The site MUST provide a blog index page at `/blog` that lists WordPress posts as cards containing:
|
||||
- featured image (when available)
|
||||
- title
|
||||
- excerpt/summary
|
||||
|
||||
The listing MUST be ordered by publish date descending (newest first).
|
||||
|
||||
Each post card MUST be instrumented with Umami Track Events data attributes and MUST include at minimum:
|
||||
- `data-umami-event`
|
||||
- `data-umami-event-target_id`
|
||||
- `data-umami-event-placement`
|
||||
- `data-umami-event-target_url`
|
||||
|
||||
#### Scenario: Blog index lists posts
|
||||
- **WHEN** the cached WordPress dataset contains posts
|
||||
- **THEN** `/blog` renders a list of post cards ordered by publish date descending
|
||||
|
||||
#### Scenario: Blog post card click is tracked
|
||||
- **WHEN** a user clicks a blog post card on `/blog`
|
||||
- **THEN** the click emits an Umami event with `target_id`, `placement`, and `target_url`
|
||||
|
||||
### Requirement: Category-based secondary navigation
|
||||
The blog section MUST render a secondary navigation under the header derived from the cached WordPress categories.
|
||||
|
||||
Selecting a category MUST navigate to a category listing page showing only posts in that category.
|
||||
|
||||
Each secondary navigation link MUST be instrumented with Umami Track Events data attributes and MUST include at minimum:
|
||||
- `data-umami-event`
|
||||
- `data-umami-event-target_id`
|
||||
- `data-umami-event-placement`
|
||||
- `data-umami-event-target_url`
|
||||
|
||||
#### Scenario: Category nav present
|
||||
- **WHEN** the cached WordPress dataset contains categories
|
||||
- **THEN** the blog section shows a secondary navigation with those categories
|
||||
|
||||
#### Scenario: Category listing filters posts
|
||||
- **WHEN** a user navigates to a category listing page
|
||||
- **THEN** only posts assigned to that category are listed
|
||||
|
||||
#### Scenario: Category nav click is tracked
|
||||
- **WHEN** a user clicks a category link in the blog secondary navigation
|
||||
- **THEN** the click emits an Umami event with `target_id`, `placement`, and `target_url`
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Unique identifier for every clickable item
|
||||
Every clickable item that is tracked MUST have a stable identifier (`target_id`) that is unique across the site (or unique within a documented namespace).
|
||||
|
||||
The identifier MUST be deterministic across builds for the same element and placement.
|
||||
|
||||
The taxonomy MUST define namespaces for repeated UI surfaces. For the blog surface, the following namespaces MUST be used:
|
||||
- `blog.subnav.*` for secondary navigation links
|
||||
- `blog.card.post.<slug>` for blog post cards
|
||||
- `blog.pages.link.<slug>` for blog page listing links
|
||||
- `blog.post.*` / `blog.page.*` for detail page chrome links (e.g., back links)
|
||||
|
||||
#### Scenario: Two links in different placements
|
||||
- **WHEN** two links point to the same destination but appear in different placements
|
||||
- **THEN** their `target_id` values are different so their clicks can be measured independently
|
||||
|
||||
15
openspec/changes/archive/2026-02-10-blog-umami-fix/tasks.md
Normal file
15
openspec/changes/archive/2026-02-10-blog-umami-fix/tasks.md
Normal file
@@ -0,0 +1,15 @@
|
||||
## 1. Audit Blog Clickables
|
||||
|
||||
- [x] 1.1 Inventory blog clickables (`site/src/pages/blog/**`, `site/src/components/Blog*`) that should emit Umami events (post cards, category subnav, pages list links, detail chrome links)
|
||||
- [x] 1.2 Confirm each clickable has the required Umami attributes and a deterministic unique `target_id` per taxonomy
|
||||
|
||||
## 2. Implement Umami Attributes
|
||||
|
||||
- [x] 2.1 Instrument blog secondary navigation links with `data-umami-event` and required event data (`target_id`, `placement`, `target_url`)
|
||||
- [x] 2.2 Instrument blog post cards and any inline links in listing UIs with `data-umami-event` and required event data
|
||||
- [x] 2.3 Instrument blog detail page chrome links (e.g., Back) and pages listing links with required Umami attributes
|
||||
|
||||
## 3. Verify
|
||||
|
||||
- [x] 3.1 Add/update tests to assert blog components/pages contain Umami `data-umami-event` attributes (and key properties like `target_id`, `placement`, `target_url`)
|
||||
- [x] 3.2 Build the site and confirm `/blog` and a blog detail page render with instrumented clickables
|
||||
Reference in New Issue
Block a user