astro-website/openspec/specs/conversion-ctas/spec.md

ADDED 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

Requirement: Modal CTAs for YouTube and Spotify

The media modal MUST render two CTA actions:

• "Subscribe on YouTube" / "Follow on Spotify" — links to the channel/podcast profile page
• "View on YouTube" / "Listen on Spotify" — links to the specific content item URL

The CTA label and destination MUST be determined by the content source:

• For youtube source: "Subscribe on YouTube" links to the YouTube channel URL, "View on YouTube" links to the video URL
• For podcast source: "Follow on Spotify" links to the podcast profile URL, "Listen on Spotify" links to the episode URL

Each CTA MUST be rendered using the existing CtaLink component conventions (or equivalent markup) with UTM parameters appended.

Scenario: YouTube video modal shows YouTube CTAs

• WHEN the media modal is displaying a YouTube video
• THEN the modal renders "Subscribe on YouTube" (linking to the channel) and "View on YouTube" (linking to the video URL) as CTA actions

Scenario: Podcast episode modal shows Spotify CTAs

• WHEN the media modal is displaying a podcast episode
• THEN the modal renders "Follow on Spotify" (linking to the podcast profile) and "Listen on Spotify" (linking to the episode URL) as CTA actions

Requirement: Modal CTA tracking

Each CTA rendered inside the media modal MUST emit a cta_click event conforming to the existing CTA tracking requirements.

The modal CTAs MUST use:

• placement=media_modal
• target_id following the modal.cta.{action}.{platform} namespace
• platform set to youtube or spotify (mapped from content source)

Scenario: Modal CTA emits cta_click event

• WHEN a 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, platform=youtube, and target_url set to the YouTube channel URL

Scenario: Modal CTA emits cta_click event (secondary)

• WHEN a 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, platform=youtube, and target_url set to the video URL

Scenario: Modal CTA emits cta_click event (podcast)

• WHEN a 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, platform=spotify, and target_url set to the podcast profile URL

Scenario: Modal CTA emits cta_click event (podcast secondary)

• WHEN a 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, platform=spotify, and target_url set to the episode URL

Scenario: Modal CTA includes UTM parameters

• WHEN a modal CTA is rendered
• THEN the CTA link URL includes UTM parameters for attribution (utm_source, utm_medium, utm_campaign, utm_content)