santhoshj/astro-website
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

better tracking

Browse Source
This commit is contained in:
Santhosh Janardhanan
2026-02-10 01:52:41 -05:00
parent c1ab51a149
commit b63c62a732
23 changed files with 302 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
openspec/changes/archive/2026-02-10-blog-umami-fix/.openspec.yaml Normal file
View File

@@ -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
View 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.

26
openspec/changes/archive/2026-02-10-blog-umami-fix/proposal.md Normal file
View File

@@ -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.

28
openspec/changes/archive/2026-02-10-blog-umami-fix/specs/analytics-umami/spec.md Normal file
View File

@@ -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

47
openspec/changes/archive/2026-02-10-blog-umami-fix/specs/blog-section-surface/spec.md Normal file
View File

@@ -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`

17
openspec/changes/archive/2026-02-10-blog-umami-fix/specs/interaction-tracking-taxonomy/spec.md Normal file
View File

@@ -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
View 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