astro-website/openspec/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.

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

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

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