astro-website/openspec/changes/archive/2026-02-10-reduce-bounce-rate/specs/interaction-tracking-taxonomy/spec.md

ADDED Requirements

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

MODIFIED Requirements

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)