astro-website/openspec/changes/archive/2026-02-10-custom-events-umami/specs/interaction-tracking-taxonomy/spec.md

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