Conversion Surfaces

What Are Conversion Surfaces?

Conversion Surfaces are configurable promotional units — modals, banners, slide-in panels, sticky notifications, and inline embeds — that appear on the Reader Portal to nudge readers toward a desired action: creating a free account, subscribing to a paid plan, joining the newsletter, redeeming a coupon, or visiting a campaign, event, or product page.

They are not random pop-ups. Each surface is created and tuned in the Admin Console by the marketing team, stored centrally in PostgreSQL, and then served to the Reader Portal where a targeting engine decides — per reader, per page, per visit — whether the surface is eligible, when it should fire, and how often it may reappear. Every display and interaction is tracked so the team can measure exactly which surfaces convert.

A single surface knows:

• Who to show to — anonymous visitors, registered (free) readers, paid subscribers, newsletter segments
• Where to show — which page types, devices, URLs, content sections/tags, and traffic sources (UTM)
• When to fire — on page load, after time on page, at a scroll depth, on exit intent, after N page views, or after an article is read
• How often — a frequency cap per session/day/week/month, plus dismiss and conversion suppression
• What to say — title, subtitle, body, image, theme, primary/secondary CTAs
• What to offer — a linked coupon (auto-applied at checkout), subscription plan, campaign, event, product, or newsletter

The primary process flow, from authoring to measurement, looks like this.

Business Objectives

How It Works (Behind the Scenes)

A conversion surface lives in three tiers. The Admin Console (:3000) is where it is authored, stored, and reported. PostgreSQL/Prisma is the single source of truth (conversion_surfaces and conversion_events tables). The Reader Portal (:3002) fetches eligible surfaces, evaluates client-side triggers and frequency caps, renders the winning surface, and posts events back.

Server vs. client responsibilities

Lifecycle cron

A background job (/api/cron/conversion-surface-lifecycle) runs on a schedule and performs two updateMany operations:

1. status = scheduled AND startsAt <= now → active
2. status = active AND endsAt < now (endsAt not null) → expired

So a scheduled surface goes live, and an active surface expires, within one cron interval (~15 minutes) of its boundary time.

Reader Portal component architecture

RootLayout
  └─ GlobalConversionSurfaces            (detects page type from URL, applies page suppression)
       └─ ConversionSurfaceProvider      (fetches eligible surfaces from the API)
            └─ ConversionSurfaceRenderer (evaluates triggers + frequency, picks the winner)
                 ├─ ModalSurface
                 ├─ StickyNotificationSurface
                 ├─ SlideInSurface
                 ├─ BannerSurface         (top_full / bottom_full)
                 └─ InlineEmbedSurface

Concepts: Surface Types, Targeting & Analytics

Surface types and placements

The surfaceType enum has six values, and placement is a separate enum controlling on-screen position.

Valid placement values: center, bottom_right, bottom_left, top_right, top_left, top_full, bottom_full, inline.

Conversion goals

Each surface has exactly one goal, which defines what counts as a conversion.

The targeting model

Targeting lives in a single targetingRules JSON column. Every dimension is optional — an omitted or empty array means "match all" for that dimension. Logic is AND between dimensions and OR within a dimension. A reader must satisfy all present dimensions to be eligible. The server evaluates these in /api/public/conversion-surfaces/eligible.

After targeting, the server sorts eligible surfaces by priority descending. The Reader Portal then applies client-side trigger and frequency/suppression checks. The full evaluation funnel:

Triggers (when a surface fires)

The trigger lives in the trigger enum plus three flat numeric columns. Eligibility is server-side; trigger firing is client-side.

Frequency, suppression & the event funnel

Each surface caps how often a reader sees it. Suppression is checked before frequency, in this order: conversion suppression → dismiss suppression → frequency cap.

The event funnel recorded for every surface: impression → click / coupon_copied → conversion, with dismiss as the negative outcome. Frequency state for anonymous readers lives in localStorage (cs_freq_*, cs_dismiss_*, cs_converted_*); for authenticated readers it is also checked server-side against conversion_events.

Adjacent Conversion Entry Points

The Admin-authored surfaces above are not the only conversion touchpoints on the Reader Portal. Three first-party, code-driven entry points sit alongside them and share the same goal — moving a reader from prompt to account or subscription. They are not configured under Marketing → Conversion Surfaces and are not tracked in conversion_events; they are part of the reader experience itself. They are documented here so QA and Customer Success know the full conversion picture.

The paywall overlay

When a reader hits a gated article (registration wall, free-article limit, or a metered allowance), the Reader Portal renders the PaywallOverlay — the single most important conversion surface that is not a marketing surface. Its copy and CTAs adapt to the gate the reader hit:

The metered overlay copy and CTA use the brand voice: the headline reads "We'll keep this page bookmarked.", the body is the line above, and the default CTA label is "Subscribe". The subscription/metered branch has a single Subscribe button and no secondary "View subscription plans" link (the primary Subscribe button already goes there). When a specific bucket is exhausted, the headline becomes bucket-specific (e.g. "You've used all N of your premium articles"). Admin-configured subscribeCtaText / subscribeCtaUrl always win over these defaults. See Paywall & Access for how gates are decided.

The reader sign-in dialog and the terms-acceptance gate

The overlay's auth CTA opens a shared sign-in dialog (AuthFlow). The dialog enforces an explicit terms-acceptance gate — the reader must tick "I agree to the Terms of Service and Privacy Policy" before they can proceed:

• On the email step, the "Continue with Google" button is disabled until the terms checkbox is checked. The gate is an explicit, required checkbox rather than a passive notice.
• On the account-creation (OTP) step, the Create-account / Sign-in submit button is disabled until the terms checkbox is ticked. A separate, optional newsletter opt-in checkbox sits above it.
• The gate also appears on the sign-in step for returning readers who lack a recorded termsAcceptedAt (e.g. bulk-created accounts), so consent is captured before they continue.

Consent is recorded with the account, so a reader is asked only until they have accepted. This means a conversion driven by any surface whose goal is register/login lands on a dialog that cannot complete without explicit consent.

The gated /start route (email CTAs)

Email welcome and onboarding CTAs ("Start Reading", verify-email follow-ups) link to /start rather than the bare homepage. /start is a server-side redirect with no rendered UI:

• Signed in → redirect to the homepage to start reading.
• Not signed in → redirect to /login?callbackUrl=/ (sign in first, then land on the homepage).

This ensures a reader who opens an email on a device where they are not authenticated is funnelled through sign-in instead of silently landing on the public homepage with no prompt — closing a conversion leak between email and the portal. The route is marked noindex so it never surfaces in search.

Configuration Reference

Every field on the Create/Edit form. UI path prefix: Admin Console → Marketing → Conversion Surfaces → New / Edit. Roles refer to the permission required to set the field (all editing requires MARKETING_CONVERSION_SURFACES_CREATE or _UPDATE).

Basic information

Content & call-to-action

Entity links

Targeting (all optional — empty = match all)

Trigger, frequency & scheduling

Status lifecycle

Transitions: draft → active/scheduled/archived · scheduled → active/draft/archived · active → paused/archived · paused → active/archived · expired → archived · archived → (none).

Coupon integration

When a coupon is linked, the eligible API validates it server-side and only ships it if it is active (isActive = true), not expired (validTo >= now or null), and not exhausted (usedCount < maxUses when maxUses is set). If any check fails the surface still renders, but without the coupon. The reader sees the code with a Copy Code button (fires a coupon_copied event), and for checkout/subscribe CTAs the code is appended as ?coupon=CODE for auto-apply.

UTM attribution

Internal/same-origin CTA URLs are auto-enriched: utm_source=conversion_surface, utm_medium=promo, utm_campaign=cs_{goal}_{surfaceId}. Existing UTM params on the URL are never overwritten, so downstream conversions attribute back to the originating surface.

RBAC

The public Reader Portal endpoints (/api/public/conversion-surfaces/eligible and /event) require no admin auth — they optionally detect a reader token for audience/suppression accuracy.

Analytics & Tracking

Every interaction is written to the conversion_events table (ConversionEventType: impression, click, dismiss, conversion, coupon_copied) with reader context (readerId?, sessionId), page context (pageUrl, pageType, deviceType), UTM context, and metadata. Internal events are recorded regardless of analytics consent; GA4 events fire only with consent.

The surface row keeps denormalized counters incremented in the same write path: impressionCount, clickCount, dismissCount, conversionCount. Note: coupon_copied is intentionally not mapped to a counter — it is captured as an event row only.

Derived metrics in the stats API: CTR (clickCount/impressionCount), dismiss rate, conversion rate, and engagement rate ((clicks + conversions)/impressions). The admin stats view breaks these down by device, page type, and UTM source, with a daily/weekly/monthly time series.

GA4 events mirror the funnel: conversion_surface_impression, conversion_surface_click, conversion_surface_dismiss, conversion_surface_conversion, coupon_copied, plus goal-specific newsletter_signup and registration_start.

Dependencies & Impact

Conversion Surfaces sit at the intersection of several modules.

Operational dependencies: the lifecycle cron must run for scheduled activation/expiration; GA4 + consent gating governs external analytics; linked coupons/plans/campaigns/events/products must stay valid or the eligible API silently drops them; the Reader Portal renders surfaces globally except on suppressed pages (/login, /register, /account/*, /subscribe/*, maintenance, preview).

Impact when changed: activating a high-priority surface can suppress lower-priority ones (one overlay per page load); editing targeting changes who sees it on the next eligibility fetch (not retroactively); archiving preserves history but removes the surface from readers immediately.

Known Limitations

FAQ