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: Media preview event for in-page content views

The tracking taxonomy MUST define a media_preview event for content card clicks that open an in-page media modal instead of navigating outbound.

The media_preview event MUST include the following properties:

• target_id (stable unique identifier for the card, following the existing card.{placement}.{source}.{id} format)
• placement (the listing surface where the card appears, e.g., home.newest, videos.list, podcast.list)
• title (human-readable content title, truncated to max 160 characters)
• type (video or podcast_episode)
• source (youtube or podcast)

Scenario: Video card click emits media_preview

• WHEN a user clicks a YouTube video card on the videos listing page
• THEN the system emits a media_preview event with target_id=card.videos.list.youtube.{id}, placement=videos.list, type=video, and source=youtube

Scenario: Podcast card click emits media_preview on homepage

• WHEN a user clicks a podcast card in the homepage podcast section
• THEN the system emits a media_preview event with target_id=card.home.podcast.podcast.{id}, placement=home.podcast, type=podcast_episode, and source=podcast

Requirement: Media preview close event

The tracking taxonomy MUST define a media_preview_close event emitted when the media modal is dismissed.

The media_preview_close event MUST include:

• target_id (the same identifier as the media_preview event that opened the modal)
• close_method (one of: button, escape, backdrop)

Scenario: User closes modal via Escape key

• WHEN the user presses Escape to close the media modal that was opened from a video card
• THEN the system emits a media_preview_close event with the original target_id and close_method=escape

Scenario: User closes modal via close button

• WHEN the user clicks the close button on the media modal
• THEN the system emits a media_preview_close event with the original target_id and close_method=button

Scenario: User closes modal via backdrop click

• WHEN the user clicks the backdrop outside the modal content
• THEN the system emits a media_preview_close event with the original target_id and close_method=backdrop

Requirement: Modal CTA namespace

The tracking taxonomy MUST define a media_modal placement value for CTA interactions within the media modal.

Modal CTAs MUST use target_id values in the namespace modal.cta.{action}.{platform}.

The action value MUST be one of:

• subscribe (YouTube channel)
• view (YouTube video)
• follow (Spotify podcast profile)
• listen (Spotify episode)

Scenario: User clicks "View on YouTube" in modal

• WHEN the user clicks the "View on YouTube" CTA inside the media modal
• THEN the system emits a cta_click event with target_id=modal.cta.view.youtube, placement=media_modal, and platform=youtube

Scenario: User clicks "Subscribe on YouTube" in modal

• WHEN the user clicks the "Subscribe on YouTube" CTA inside the media modal
• THEN the system emits a cta_click event with target_id=modal.cta.subscribe.youtube, placement=media_modal, and platform=youtube

Scenario: User clicks "Follow on Spotify" in modal

• WHEN the user clicks the "Follow on Spotify" CTA inside the media modal
• THEN the system emits a cta_click event with target_id=modal.cta.follow.spotify, placement=media_modal, and platform=spotify

Scenario: User clicks "Listen on Spotify" in modal

• WHEN the user clicks the "Listen on Spotify" CTA inside the media modal
• THEN the system emits a cta_click event with target_id=modal.cta.listen.spotify, placement=media_modal, and platform=spotify

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

For non-link clickables that trigger in-page actions (e.g., modal openers), the event MUST also include:

• title (human-readable content title)
• type (content type identifier)
• source (content source identifier)

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

Scenario: Tracking a modal-trigger card includes title, type, and source

• WHEN a user clicks a content card that opens a media modal instead of navigating
• THEN the emitted event includes target_id, placement, title, type, and source (no target_url since the user stays on-page)

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

Requirement: Theme switch event taxonomy

The tracking taxonomy MUST define an event for theme switching.

The event name MUST be theme_switch.

The theme_switch event MUST include, at minimum:

• target_id
• placement
• theme

The event MUST include prev_theme when it is available.

The taxonomy MUST define the target_id namespace for theme switching as:

• theme.switch.<theme>

The taxonomy MUST define the placement value for the theme switcher notch as:

• theme_notch

Scenario: Theme switch target_id is deterministic

• WHEN a user selects light theme using the theme notch
• THEN the event is emitted with target_id=theme.switch.light and placement=theme_notch