Conversion Flow --- Analytics & Metrics (MAI-23)

Last updated: May 6, 2026Section: Monetization & growth

Conversion Flow --- Analytics & Metrics (MAI-23)

This document pairs with conversion-flow{.interpreted-text role="doc"}. It defines event taxonomy, KPI formulas, and a baseline instrumentation checklist for measuring User → Customer conversion. Implementation may use GA4 (existing gtag hooks in the web app), server-side events, or both---names below are canonical product identifiers; map them to provider-specific event names in engineering specs.

Existing web instrumentation (reference)

  • Client route page_view --- apps/web/src/components/analytics/ga-page-view.tsx
  • CTA clicks --- apps/web/src/components/analytics/trackable-link.tsx (cta_click)

Add dedicated conversion events (below) with consistent parameters so funnels are not inferred only from page paths.

Event dictionary

Use snake_case event names and stable parameter keys. Include locale, plan_tier (when known), project_uid (hashed or omitted if PII-sensitive), and surface (e.g. dashboard, pricing, paywall_modal).

Event name When it fires Required parameters (minimum)

view_pricing Pricing page or pricing modal becomes visible (not only route prefetch). surface, audience (anonymous | free | trialing | paid)

hit_limit User crosses soft warning threshold or hard quota (API or UI). limit_type, current_value, threshold, hard_or_soft

paywall_shown Paywall UI displayed (modal, sheet, or blocking inline). trigger_family (usage | gate | trial), trigger_id, surface

paywall_dismissed User closes paywall without checkout. trigger_id, surface, dismiss_method (x | backdrop | cta)

trial_started Trial entitlement begins (user or system initiated). trial_days, plan_target, source_surface

checkout_started Checkout session created or user lands on provider-hosted payment. plan_id, price_id (if applicable), billing_period

purchase_success Webhook or server confirms payment; entitlements updated. plan_id, subscription_id (opaque id), is_trial_conversion

purchase_failed Terminal failure after checkout attempt. reason_code (provider-normalized), recoverable (bool)

entitlements_activated Post-webhook state applied; user can use paid features. plan_id, latency_ms (checkout → active, optional)

Engagement for retention (examples): dashboard_session_start, message_created, campaign_sent --- define one primary weekly active proxy per persona for D7/D30 (see KPIs).

Core KPIs and formulas

Definitions use cohorts keyed by signup week or first value-moment week (product to choose one primary key and stick to it).

Stage conversion rates

  • visit_to_activate = users with Activate / users with Visit (same window, e.g. 7 days from first visit).
  • activate_to_value = users with value-moment event / users activated (14-day window recommended).
  • value_to_paywall = users with paywall_shown / users with value moment (ever or within 30 days---document choice).
  • paywall_to_checkout = checkout_started / paywall_shown (dedupe users per 7-day window).
  • checkout_to_purchase = purchase_success / checkout_started.

Trial and paywall quality

  • trial_to_paid = purchase_success where is_trial_conversion=true / users with trial_started (cohort by trial start week).
  • paywall_dismiss_to_later_upgrade = users with purchase_success who had paywall_dismissed earlier (same account; attribution window e.g. 30 days).

Revenue health (if amounts available server-side)

  • Optional: arpu, expansion_rate --- out of scope for minimal baseline; add when billing data exists.

Retention

  • retained_d7_paid = users with purchase_success and at least one primary weekly active event on day 1--7 after purchase / paid cohort.
  • retained_d30_paid = same for days 1--30.

Anti-annoyance proxy

  • paywall_shown_per_active_week --- distribution per user; target downward while paywall_to_checkout holds or improves.

Baseline collection checklist

  1. Single source of truth for user_id (and optional project_uid) on every client and server event.
  2. Dedupe checkout and purchase: one purchase_success per invoice or subscription id.
  3. Clock skew: attribute purchase_success to checkout cohort by checkout_started timestamp, not only webhook arrival.
  4. Consent: fire marketing-sensitive events only when analytics consent allows (see app consent banner behavior).
  5. Debug mode: staging project in GA4 (or equivalent) with parameter environment=staging excluded from production dashboards.
  6. Dashboard slices: one board per funnel stage + one "trial cohort" board.

Rollout phases (measurement)

  • Phase 1: view_pricing, hit_limit, paywall_shown, dismissed, checkout_started, purchase_success + page views.
  • Phase 2: trial_started, entitlements_activated, retention composite, paywall frequency distribution.
  • conversion-flow{.interpreted-text role="doc"} --- UX, paywall rules, checkout states
📚