This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-10
|
||||
@@ -0,0 +1,73 @@
|
||||
## 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.
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
## Why
|
||||
|
||||
We need clear, consistent measurement of what users click on the website and where they go, so we can evaluate acquisition and conversion performance and iterate quickly.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Standardize click tracking across the entire site so every clickable item emits a custom event with a unique, consistent set of data properties.
|
||||
- Align event naming and properties with Umami custom event tracking conventions (see Umami "Track events" documentation).
|
||||
- Ensure tracking works without breaking navigation/UX, and remains safe when analytics is disabled or misconfigured.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `interaction-tracking-taxonomy`: Define a site-wide event taxonomy for clickable items (required properties, naming conventions, uniqueness rules, and allowed values) and document how new links/buttons must be instrumented.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `analytics-umami`: Expand custom event support beyond the current CTA/outbound tracking to cover all clickable items and their unique data properties.
|
||||
- `conversion-ctas`: Ensure all CTAs conform to the taxonomy (unique identifiers/properties per placement) and remain measurable in Umami with consistent segmentation.
|
||||
|
||||
## Impact
|
||||
|
||||
- Frontend code: add/standardize data attributes (or equivalent wiring) for all clickable elements (nav links, content cards, CTAs, external links) and update the central tracking hook.
|
||||
- Analytics: define and maintain an event/property contract; dashboards/filters in Umami will depend on stable names.
|
||||
- QA: verify in staging that events are emitted as expected and that disabling analytics does not cause client errors.
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Umami pageview tracking
|
||||
When Umami is enabled by configuration, the site MUST load Umami tracking on all indexable pages and MUST record pageviews.
|
||||
|
||||
When Umami is disabled or not configured, the site MUST still function and MUST NOT error in the browser due to missing analytics.
|
||||
|
||||
#### Scenario: Umami enabled
|
||||
- **WHEN** Umami is enabled by configuration
|
||||
- **THEN** the site includes the Umami script on `/`, `/videos`, `/podcast`, and `/about`
|
||||
|
||||
#### Scenario: Umami disabled
|
||||
- **WHEN** Umami is not configured
|
||||
- **THEN** the site renders normally and no analytics script is required
|
||||
|
||||
### 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`.
|
||||
|
||||
#### 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
|
||||
|
||||
### Requirement: Environment configuration
|
||||
The site MUST support configuration of Umami parameters (at minimum: website ID and script URL) without requiring code changes.
|
||||
|
||||
#### Scenario: Configure Umami via environment
|
||||
- **WHEN** Umami configuration values are provided via environment or config file
|
||||
- **THEN** the site uses those values to initialize analytics without modifying source code
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Reusable CTA component
|
||||
The site MUST implement CTAs as a reusable component that can render at least the following actions:
|
||||
- YouTube subscribe action (linking to the channel)
|
||||
- Instagram follow action (linking to the profile)
|
||||
- Podcast listen action (linking to a designated destination)
|
||||
|
||||
Each CTA MUST be configurable with:
|
||||
- `platform` (`youtube`, `instagram`, `podcast`)
|
||||
- `placement` (e.g., `hero`, `module_header`, `footer`)
|
||||
- destination `url`
|
||||
|
||||
#### Scenario: Rendering a YouTube subscribe CTA
|
||||
- **WHEN** the homepage includes a CTA with `platform: youtube`
|
||||
- **THEN** the site renders a visible action that links to the configured YouTube channel destination URL
|
||||
|
||||
### Requirement: Trackable outbound links
|
||||
CTA outbound links MUST support appending UTM parameters so traffic can be attributed in downstream analytics.
|
||||
|
||||
#### Scenario: UTM parameters applied
|
||||
- **WHEN** a CTA is configured with UTM parameters
|
||||
- **THEN** the rendered outbound link includes the UTM query parameters in its URL
|
||||
|
||||
### Requirement: CTA click event emission
|
||||
CTA clicks MUST emit an analytics event with at least:
|
||||
- event name `cta_click`
|
||||
- `platform`
|
||||
- `placement`
|
||||
- `target` (destination URL or a stable identifier)
|
||||
|
||||
In addition, CTA clicks MUST conform to the site click tracking taxonomy and MUST include a stable, unique identifier (`target_id`) for the CTA instance (so multiple CTAs with the same destination can be measured independently).
|
||||
|
||||
#### Scenario: User clicks CTA
|
||||
- **WHEN** a user clicks an Instagram follow CTA in the hero placement
|
||||
- **THEN** the system emits a `cta_click` event with `platform=instagram` and `placement=hero`
|
||||
|
||||
#### Scenario: Two CTAs to the same destination
|
||||
- **WHEN** two CTAs link to the same destination but appear in different placements
|
||||
- **THEN** their emitted events contain different `target_id` values
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Standard click tracking taxonomy
|
||||
The system MUST define and follow a standard taxonomy for tracking user interactions (clicks) across the website.
|
||||
|
||||
The taxonomy MUST define:
|
||||
- required event name(s)
|
||||
- required event properties
|
||||
- allowed values for categorical properties (where applicable)
|
||||
- uniqueness rules for identifiers
|
||||
|
||||
#### Scenario: Adding a new tracked link
|
||||
- **WHEN** a new link is added to any page/component
|
||||
- **THEN** it is instrumented according to the taxonomy (required event name and required properties) without additional bespoke tracking code
|
||||
|
||||
### 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.
|
||||
|
||||
#### 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
|
||||
|
||||
### 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)
|
||||
|
||||
#### 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`
|
||||
|
||||
### Requirement: No PII in event properties
|
||||
The taxonomy MUST prohibit including personally identifiable information (PII) in event names or event properties.
|
||||
|
||||
#### Scenario: Tracking includes only categorical metadata
|
||||
- **WHEN** tracking metadata is defined for a clickable item
|
||||
- **THEN** it contains only categorical identifiers (ids, placements, domains) and does not include user-provided content
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
## 1. Taxonomy Definition
|
||||
|
||||
- [x] 1.1 Define the canonical event name(s) and required properties for click tracking (target_id, placement, target_url for links)
|
||||
- [x] 1.2 Document uniqueness rules and naming conventions for `target_id` (including namespaces for nav/cta/cards)
|
||||
- [x] 1.3 Add a short "instrumentation checklist" section for developers when adding new clickables
|
||||
|
||||
## 2. Core Tracking Implementation
|
||||
|
||||
- [x] 2.1 Extend the centralized click handler to emit a general click interaction event for all instrumented clickables
|
||||
- [x] 2.2 Add support for required taxonomy properties (`target_id`, `placement`, `target_url`) on emitted events
|
||||
- [x] 2.3 Ensure uninstrumented clicks do not emit events and never throw (analytics disabled safe-path)
|
||||
- [x] 2.4 Keep existing `cta_click` and `outbound_click` semantics but align emitted properties with the taxonomy
|
||||
|
||||
## 3. Instrument All Clickables
|
||||
|
||||
- [x] 3.1 Instrument nav links with taxonomy attributes (unique `target_id`, `placement=nav`)
|
||||
- [x] 3.2 Instrument content cards (newest/high-performing/podcast) with taxonomy attributes (unique ids per source + placement)
|
||||
- [x] 3.3 Instrument all CTA links to include stable unique `target_id` values per placement
|
||||
- [x] 3.4 Instrument other outbound links (section headers, buttons) with taxonomy attributes and `outbound_click` where applicable
|
||||
|
||||
## 4. Verification
|
||||
|
||||
- [x] 4.1 Add/extend tests to validate taxonomy mapping (data attributes -> emitted event payload) for at least nav, CTA, and content-card clicks
|
||||
- [x] 4.2 Verify in staging Umami that click events show up with expected properties and are segmentable by placement and target_id
|
||||
Reference in New Issue
Block a user