Conversion Surfaces

1. What Are Conversion Surfaces?

Conversion Surfaces are promotional overlays that appear on the Reader Portal to encourage readers to take a desired action — like registering for a free account, subscribing to a paid plan, signing up for the newsletter, or visiting a campaign page.

Think of them as smart, configurable pop-ups that know:

• Who to show to (anonymous visitors, registered readers, subscribers)
• Where to show (which pages, which device types)
• When to show (after scrolling, after time on page, on exit intent)
• How often to show (once per session, once per day, once per week)
• What to say (custom title, description, image, call-to-action buttons)
• What to offer (linked coupon code, specific subscription plan)

They are NOT random pop-ups. Each surface is a deliberately crafted, targeted touchpoint in the reader's journey, designed to convert at the right moment without disrupting the reading experience.

2. Business Objectives

3. Key Concepts & Terminology

4. Surface Types — What Readers See

4.1 Modal

A centered overlay that appears on top of the page content with a semi-transparent backdrop.

When to use: When you want to demand attention. The reader must interact with it (click CTA or dismiss) before continuing.

4.2 Sticky Notification

A small, persistent card that appears at a corner of the screen.

When to use: When you want to be present but not intrusive. The reader can continue reading while seeing the notification.

4.3 Slide-In Panel

A full-height panel that slides in from the right side of the screen.

When to use: When you need more space to present an offer or detailed information without navigating away from the current page.

4.4 Top Banner

A full-width strip at the top of the page.

When to use: When you want maximum visibility with minimum disruption. Good for announcements that every reader should notice.

4.5 Bottom Banner

Same as top banner but fixed to the bottom of the viewport.

When to use: When you want presence without competing with the header navigation area.

4.6 Inline Embed

An embedded card that appears within the page content flow (between sections or after article content).

When to use: When you want the promotion to feel native to the page, not like an interruption.

5. Conversion Goals — What You Want Readers to Do

Each surface must be assigned one conversion goal. This determines what action counts as a "conversion."

6. Targeting Rules — Who Sees a Surface

Targeting rules are the first layer of filtering. A reader must match ALL the targeting criteria to be considered eligible.

6.1 Audience Targeting

Rule: If the surface targets ["anonymous", "registered"], it will show to both anonymous visitors AND logged-in free readers, but NOT to paid subscribers.

Important: If the audience list is empty [], the surface matches ALL audiences (no audience restriction).

6.2 Page Type Targeting

Restrict which types of pages the surface appears on:

Rule: If the page type list is empty, the surface matches ALL page types.

6.3 Device Type Targeting

Rule: If the device list is empty, the surface matches ALL devices.

6.4 Content Targeting (Advanced)

For article pages, surfaces can target based on content attributes:

6.5 URL Targeting (Advanced)

6.6 UTM Targeting (Advanced)

7. Trigger Rules — When a Surface Appears

After a reader is deemed eligible (passes all targeting rules), the trigger determines the exact moment the surface appears.

Important: Exit intent only works on desktop. On mobile, the system falls back to scroll_depth (75%) as an equivalent signal.

8. Frequency & Suppression — How Often a Surface Appears

8.1 Frequency Capping

Each surface has a frequency limit that controls how many times a reader sees it within a time window.

Examples:

• frequencyLimit: 1, frequencyUnit: day = Show at most once per day
• frequencyLimit: 3, frequencyUnit: week = Show up to 3 times per week
• frequencyLimit: 1, frequencyUnit: session = Show once per browser session

8.2 Dismissal Suppression

When a reader dismisses (closes) a surface, you can configure how long before they see it again:

8.3 Conversion Suppression

Example: A "Register" surface with suppressIfConverted: true will never show to a reader who is already logged in, even if they've never seen this specific surface before.

8.4 How Frequency State Is Tracked

• Anonymous readers: Frequency state is tracked in the browser's localStorage. Clearing browser data resets the frequency state.
• Authenticated readers: Frequency state is tracked both in localStorage (for speed) and in the ConversionEvent table on the server (for cross-device accuracy). Server-side checks are performed for authenticated readers during the eligible API call.

9. Scheduling & Lifecycle — When a Surface Is Active

9.1 Status Lifecycle

Every surface goes through a lifecycle of statuses:

                                    (cron: startsAt reached)
    draft -------> scheduled --------------------------> active
      |                |                                   |
      |                |                                   | (manual)
      v                v                                   v
   archived         archived                             paused
                                                           |
                      (cron: endsAt passed)                | (manual)
                    active ---------> expired               v
                                        |                active
                                        v
                                     archived

9.2 Allowed Status Transitions

9.3 Automatic Transitions (Cron Job)

A background cron job runs every 15 minutes and:

1. Activates surfaces where status = scheduled AND startsAt <= now
2. Expires surfaces where status = active AND endsAt < now

This means:

• A scheduled surface will go live within ~15 minutes of its start time
• An active surface will expire within ~15 minutes of its end time

9.4 Immediate Activation

If you don't set a startsAt date and change the status directly from draft to active, the surface starts showing to readers immediately.

10. Priority & Conflict Resolution — Which Surface Wins

When multiple surfaces are eligible for the same reader on the same page, only one is shown. The system resolves conflicts using priority ordering:

1. Surfaces are ranked by priority (higher number = higher priority)
2. If two surfaces have the same priority, the more recently created one wins
3. Only one overlay surface (modal, slide-in, banner, sticky) is shown per page load
4. Inline embed surfaces are an exception — they render within the content and do not compete with overlay surfaces

Example: If both a modal (priority 15) and a sticky notification (priority 10) are eligible, only the modal appears.

Best practice: Set subscription-focused surfaces at priority 15-20, registration surfaces at 10-15, and informational surfaces at 1-10.

11. Coupon Integration — Promo Codes on Surfaces

Surfaces can be linked to a discount coupon from the platform's coupon system.

What Happens When a Coupon Is Linked

1. Display: The surface shows the coupon code prominently with a "Copy Code" button
2. Copy tracking: When the reader clicks "Copy Code," a coupon_copied event is recorded in both the internal analytics and GA4
3. Auto-apply at checkout: If the surface CTA links to a checkout or subscribe page, the coupon code is automatically appended to the URL as ?coupon=CODE. The checkout page reads this parameter and auto-fills the promo code input field, applying the discount without the reader needing to type anything.
4. Validation: The eligible API checks that the coupon is:
   • Currently active (isActive = true)
   • Not expired (validTo >= now or validTo is null)
   • Not exhausted (usedCount < maxUses)
   • If any check fails, the coupon is NOT shown to the reader

Example Flow

1. Admin creates a surface with a coupon "SPRING20" (20% off) linked to the Premium Annual plan
2. Reader visits an article, scrolls to 50%, and the modal appears: "Subscribe and save 20%! Use code SPRING20"
3. Reader clicks "Copy Code" — code is copied to clipboard, coupon_copied GA4 event fires
4. Reader clicks "Subscribe Now" — redirected to /subscribe/checkout?plan=premium-annual&coupon=SPRING20
5. Checkout page auto-fills the promo code field with "SPRING20" and shows the discounted price

12. Entity Linking — Connecting Surfaces to Platform Entities

Surfaces can be linked to existing platform entities to provide context and ensure data consistency:

Important: When linked entities become inactive (e.g., a plan is deactivated, a coupon expires), the eligible API automatically excludes them from reader-facing responses.

13. Analytics & Tracking — Measuring Surface Performance

13.1 Internal Analytics (ConversionEvent Table)

Every interaction is recorded as a ConversionEvent with:

• Event type: impression, click, dismiss, conversion, coupon_copied
• Reader context: readerId (if authenticated), sessionId
• Page context: pageUrl, pageType, deviceType
• UTM context: utmSource, utmMedium, utmCampaign
• Metadata: trigger type, scroll percentage, and other event-specific data

13.2 Denormalized Counters

For quick access, each surface maintains running totals:

• impressionCount — total times the surface was displayed
• clickCount — total CTA clicks
• dismissCount — total times the surface was dismissed
• conversionCount — total successful conversions

These counters are updated atomically when events are recorded.

13.3 GA4 Events

The system fires the following Google Analytics 4 events:

13.4 Admin Stats Dashboard

The admin can view detailed analytics for each surface:

• Totals: Impressions, clicks, dismissals, conversions, coupons copied
• Rates: CTR (click-through rate), dismiss rate, conversion rate, engagement rate
• Time series: Daily/weekly/monthly breakdown of all metrics
• Breakdown by device: Desktop, mobile, tablet splits
• Breakdown by page type: Which pages drive the most conversions
• Breakdown by UTM source: Which traffic sources convert best

14. UTM Attribution — Tracking Marketing Source

All conversion surface CTA URLs are automatically enriched with UTM parameters:

Rules:

• UTM params are only added to internal URLs (relative paths or same-origin URLs)
• If the URL already has UTM parameters, they are NOT overwritten
• This allows GA4 to attribute downstream conversions (subscriptions, registrations) back to the specific surface that drove them

15. Reader Portal Rendering — How It All Works Together

15.1 Architecture

RootLayout
  |
  +-- GlobalConversionSurfaces
        |
        +-- ConversionSurfaceProvider (fetches eligible surfaces)
              |
              +-- ConversionSurfaceRenderer (evaluates triggers, renders surfaces)
                    |
                    +-- ModalSurface
                    +-- StickyNotificationSurface
                    +-- SlideInSurface
                    +-- BannerSurface (top or bottom)
                    +-- InlineEmbedSurface

15.2 Rendering Flow

1. Page navigation detected: GlobalConversionSurfaces detects the current page type from the URL
2. Eligibility fetch: ConversionSurfaceProvider calls the eligible API with page context (page type, URL, device type, session ID)
3. Server-side filtering: The API evaluates all active surfaces against targeting rules and returns eligible ones, sorted by priority
4. Client-side trigger evaluation: ConversionSurfaceRenderer listens for the configured trigger event (scroll, time, exit intent, etc.)
5. Frequency check: Before displaying, the renderer checks localStorage for frequency caps and suppression state
6. Surface display: The highest-priority eligible surface is rendered using the appropriate surface component
7. Event tracking: Impression event is recorded (both internal API and GA4)
8. Reader interaction: Click, dismiss, or conversion events are tracked as the reader interacts

15.3 Page Suppression

Conversion surfaces are automatically suppressed (never shown) on:

16. Admin Console — Managing Surfaces

16.1 Navigation

Admin Console > Marketing > Conversion Surfaces

16.2 List Page

Shows all conversion surfaces with:

• Name, type (icon), goal, status badge
• Priority, impression/click/conversion counts
• Date range (starts at - ends at)
• Filter by: status, surface type, conversion goal
• Sort by: name, status, priority, impressions, clicks, conversions, created date
• Search by name
• Actions: Edit, Duplicate, Archive

16.3 Create/Edit Form

The form is organized into 7 sections:

Section 1: Basic Information

• Name (internal label, not shown to readers)
• Surface Type (modal, banner, etc.)
• Conversion Goal
• Priority (1-100, higher = shown first)

Section 2: Content

• Title (required, shown to reader)
• Subtitle (optional)
• Body Text (optional, rich text)
• Image URL (optional)
• Background Color (optional)
• Theme (light, dark, brand)

Section 3: Call-to-Action

• Primary CTA Label (required, e.g., "Subscribe Now")
• Primary CTA URL (required, e.g., "/subscribe")
• Secondary CTA Label (optional, e.g., "Maybe Later")
• Secondary CTA URL (optional, or auto-dismiss action)

Section 4: Entity Links

• Linked Coupon (dropdown of active coupons)
• Linked Subscription Plan (dropdown of active plans)
• Linked Campaign, Event, Product, Newsletter (optional)

Section 5: Targeting

• Audience segments (multi-select)
• Page types (multi-select)
• Device types (multi-select)
• Content types, sections, tags (advanced)
• URL include/exclude patterns (advanced)
• UTM source/medium/campaign filters (advanced)

Section 6: Trigger

• Trigger type (dropdown)
• Trigger configuration (delay seconds, scroll %, page view count)

Section 7: Frequency & Scheduling

• Frequency limit + unit
• Suppress after dismiss (days)
• Suppress after conversion (boolean)
• Suppress if already converted (boolean)
• Start date (optional, for scheduling)
• End date (optional, for auto-expiration)

16.4 Permissions (RBAC)

17. Pre-Built Templates — Getting Started Quickly

The system includes 15 pre-built template surfaces covering all conversion goals. These are seeded via the /api/marketing/conversion-surfaces/seed endpoint and created in draft status so admins can customize them before activating.

18. Page Suppression — Where Surfaces Never Appear

19. User Stories

For Marketing Team

For Readers (Implicit)

For Editors/Content Team

20. Use Cases & Scenarios

Scenario 1: Converting Anonymous Visitors to Registered Readers

Setup: Create a modal surface with:

• Goal: register
• Audience: anonymous only
• Trigger: exit_intent (desktop) / scroll_depth 75% (mobile fallback)
• Frequency: Once per day
• Suppress after dismiss: 3 days
• Suppress if converted: Yes

Reader experience:

1. Anonymous reader visits the site and reads an article
2. When they move their mouse to close the browser tab, the modal appears
3. "Create your free account — Save articles, get personalized recommendations"
4. If they register, the modal never appears again
5. If they dismiss, it won't reappear for 3 days

Scenario 2: Subscription Conversion with Discount

Setup: Create a slide-in surface with:

• Goal: subscribe_paid
• Audience: anonymous, registered
• Trigger: after_article_read
• Linked coupon: "SAVE30" (30% off first year)
• Linked plan: Premium Annual
• Frequency: Once per week
• Suppress if converted: Yes

Reader experience:

1. Reader finishes reading an article
2. Slide-in appears: "Enjoyed this? Subscribe and save 30% — Use code SAVE30"
3. Reader clicks "Copy Code" — code copied, GA4 coupon_copied event fires
4. Reader clicks "Subscribe Now" — redirected to /subscribe/checkout?plan=premium-annual&coupon=SAVE30
5. Checkout page auto-fills "SAVE30" in the promo code field
6. Price updates to show 30% discount

Scenario 3: Time-Limited Campaign Promotion

Setup: Create a top banner surface with:

• Goal: view_campaign
• Audience: All
• Trigger: page_load
• Schedule: March 15 to April 1
• Linked campaign: "Spring Literary Festival"
• Frequency: Once per session
• Priority: 25 (high, to override other surfaces)

Lifecycle:

1. Admin creates the surface on March 10 with status draft
2. Admin reviews content and sets status to scheduled with startsAt = March 15
3. On March 15, the cron job detects startsAt has passed and sets status to active
4. Readers see the banner: "Spring Literary Festival starts now! Join 20+ sessions with leading authors"
5. On April 1, the cron job detects endsAt has passed and sets status to expired
6. Banner stops appearing automatically

Scenario 4: Newsletter Growth via Inline Embed

Setup: Create an inline embed surface with:

• Goal: subscribe_newsletter
• Audience: newsletter_unsubscribed
• Page types: article only
• Trigger: N/A (inline embeds render with the page)
• Frequency: Once per day

Reader experience:

1. Reader opens an article
2. After the article content, between the article body and related content, an inline card appears
3. "Enjoy stories like this? Get our weekly fiction digest in your inbox"
4. Reader clicks "Subscribe" — newsletter sign-up flow triggers
5. The embed doesn't appear again for 24 hours

Scenario 5: UTM-Targeted Social Media Promotion

Setup: Create a sticky notification with:

• Goal: subscribe_paid
• Audience: anonymous, registered
• UTM targeting: utmSource: ["facebook", "instagram"]
• Trigger: time_on_page (15 seconds)
• Linked coupon: "SOCIAL25" (25% off)

Reader experience:

1. Reader arrives from a Facebook ad (?utm_source=facebook)
2. After 15 seconds of reading, a small sticky notification appears in the bottom-right
3. "Welcome from Facebook! Get 25% off your subscription — SOCIAL25"
4. Reader clicks "Copy Code" and proceeds to subscribe
5. Readers arriving from Google, email, or direct visits never see this surface