Analytics Feature Description

0. Overview — What This Guide Covers

This is the deep-dive reference for two specific analytics surfaces:

1. Content Performance Analytics — how individual articles and sections are performing (page views, active users, engagement time, scroll depth).
2. Subscription & Revenue Metrics — the business-health view (MRR, ARR, churn, growth, revenue by plan and by month).

For the dashboard overview, the full GA4 event catalog, traffic sources, device/browser, institutional usage, social, and export workflows, see the companion Analytics guide. This document focuses on how the two feature areas above are computed end-to-end and what every field means, so you can trust the numbers and debug them when they look wrong.

The single most important rule to internalise: content performance is sourced from Google Analytics 4 (GA4); subscription and revenue metrics are sourced from the platform's own PostgreSQL database (Prisma). They never cross over. GA4 is never used for money; the database is never used for traffic.

1. What Is the Analytics & Reporting System?

The Analytics & Reporting system tracks, measures, and visualizes how readers interact with the Hyphen publishing platform. It combines two data sources:

1. Google Analytics 4 (GA4) — Tracks real-time reader behavior on the Reader Portal: page views, scroll depth, article reading time, paywall interactions, device types, geographic data, and traffic sources.

2. Internal Platform Data (PostgreSQL/Prisma) — Tracks subscription metrics, revenue, reader registrations, institutional usage, content moderation, and social media performance from the platform's own database.

Together, these provide a complete picture across the entire reader lifecycle: from first visit to content consumption to subscription conversion to long-term retention.

How It Works (Behind the Scenes)

The two feature areas this guide covers have two completely separate pipelines. Understanding the difference is the key to trusting and debugging the numbers.

Content Performance pipeline (GA4)

1. The Reader Portal loads gtag.js (subject to cookie consent). GA4 records page_view events automatically and scroll events via GA4 enhanced measurement (the native percent_scrolled parameter at 90% by default, plus the platform's own article_scroll_depth milestones).
2. GA4 ingests and aggregates this server-side in the Google Analytics property.
3. The Admin Console calls GET /api/analytics/content-performance?days=N. That route authenticates to the GA4 Data API — with a service-account JWT when GA4_SERVICE_ACCOUNT_KEY is set, or via Application Default Credentials (ADC) from a VM-attached service account when it is not — and runs three runReport queries:
   • Top articles — dimensions pagePath + pageTitle, metrics averageSessionDuration, screenPageViews, activeUsers, filtered to paths beginning with /articles/, ordered by engagement time (limit 20).
   • Scroll-depth distribution — dimension percentScrolled, metric eventCount, filtered to eventName = scroll; counts are bucketed into 25/50/75/100 and converted to percentages of total scroll events.
   • Engagement by section — dimension contentGroup, metrics averageSessionDuration, screenPageViews, activeUsers (limit 15; (not set) rows dropped).
4. If GA4 is not configured, the route returns { configured: false } with empty arrays — the page renders an empty state rather than erroring.

Subscription & Revenue pipeline (Prisma)

1. Real subscription lifecycle events (create, renew, cancel) and successful Payment rows accumulate in PostgreSQL as readers transact.
2. The Admin Console calls GET /api/analytics/subscription-metrics, which queries Prisma directly and derives MRR, ARR, churn, growth, revenue-by-month (12 buckets) and revenue-by-plan in real time.
3. In parallel, an hourly cron (POST /api/cron/snapshot-analytics) computes the current-period subscription/revenue figures and upserts one row per calendar day into daily_analytics_snapshots. This snapshot table backs fast dashboard loads and powers trend/alerting without re-running heavy aggregates on every request.

Naming caution — doc_activity_events is NOT a content-analytics table. Despite the name, the doc_activity_events model records Google Drive document editing activity (edits, comments, suggestions on Drive docs) for the Editorial Workflow — see Editorial. It does not feed content-performance views. Article-level performance comes from GA4; per-reader reading progress comes from ReadingHistory; article ratings come from article_ratings.

Concepts: Content Performance & Subscription Metrics

Source-of-truth matrix (the two areas in this guide)

How content-performance metrics are derived

Each row in the Top Content table is one GA4 page path under /articles/. There is no separate "reads" or "completion" column computed server-side here — completion is inferred from the scroll-depth distribution (% of scroll events that reached 100%). "Dwell" is GA4's averageSessionDuration surfaced as Avg. Engagement Time.

How subscription metrics are derived

The subscription-metrics route computes everything from Prisma in one request:

• MRR = sum of Payment.amount where status = SUCCEEDED and createdAt >= start of current month. (The hourly snapshot cron uses a more stable plan-price-based MRR — summing active subscriptions' plan prices — so the snapshot doesn't swing with payment timing.)
• ARR = MRR × 12.
• Churn rate = subscriptions CANCELED this month ÷ subscriptions ACTIVE at the start of the month, as a percentage.
• Growth = (new subs this month − new subs last month) ÷ new subs last month × 100 (or 100% if there were none last month).
• Revenue by month = 12 monthly buckets, each the sum of SUCCEEDED Payment.amount in that calendar month.
• Revenue by plan = successful payments in the trailing 12 months grouped by the subscription's plan, with per-plan revenue and subscriber count.
• Total active = count of Subscription where status = ACTIVE.

Configuration Reference

There is very little to configure on these surfaces — most controls are read-only views over upstream data. The table below lists every metric and control, what it means, whether it is a UI control or backend-derived value, and the role required.

Content-performance metrics & controls

Subscription & revenue metrics

Export & access controls

Dependencies & Impact

These two feature areas sit at a crossroads of several modules. Changes upstream ripple into the numbers shown here.

• Analytics — the dashboard overview, full GA4 event catalog, traffic sources, device/browser, institutional usage, and export workflows. This guide is the deep-dive companion; the overview is the canonical reference for everything not covered here.
• Editorial — owns doc_activity_events (Drive editing activity) and contentGroup / section tagging that feeds engagement by section. Mis-tagged sections show up as Uncategorised.
• Subscriptions — the source of every financial number. Subscription status transitions and Payment rows directly drive MRR, ARR, churn, and growth. Plan price/config changes shift the snapshot's plan-price-based MRR.
• Reader Management — ReadingHistory (per-reader progress) and article_ratings live here; they complement (but do not feed) GA4 content performance.
• Marketing — campaigns and conversion surfaces add UTM-tagged traffic that appears in GA4 acquisition reports and influences the funnels referenced from the overview guide.

Impact notes:

• Cookie-consent declines suppress GA4 events, so content-performance numbers under-count real traffic. Subscription metrics are unaffected (authenticated DB writes).
• If the GA4 service account (key-based or ADC) loses access, content-performance silently returns the empty state — subscription metrics keep working.
• The hourly snapshot cron must run for trend/alerting accuracy; a stalled cron leaves daily_analytics_snapshots stale even though the live subscription-metrics endpoint stays correct.

2. Business Objectives & KPIs

Primary KPIs Tracked

Business Questions the System Answers

3. System Architecture — Where Data Comes From

Reader Portal (Next.js)                      Admin Console (Next.js)
+---------------------------+                +---------------------------+
|                           |                |                           |
|  GoogleAnalytics.tsx      |   GA4 Data     |  Analytics Page           |
|  (gtag.js script)   -----+---API---------->  /api/analytics/*         |
|                           |                |  (ga4-data-client.ts)     |
|  analytics.ts             |                |                           |
|  (custom events)          |   Custom       |  Dashboard Page            |
|  - paywall_view           |   Events       |  /api/stats/dashboard     |
|  - article_scroll_depth   |                |                           |
|  - subscribe_start        |                |  /api/analytics/          |
|  - shop_add_to_cart       |                |   - traffic-sources       |
|  - conversion_surface_*   |                |   - content-performance   |
|  - newsletter_*           |                |   - subscription-metrics  |
|  etc.                     |                |   - paywall-funnel        |
|                           |                |   - registration-funnel   |
|  CookieConsent.tsx        |                |   - device-browser        |
|  (consent gating)         |   Prisma       |   - institutional-usage   |
|                           |   DB Data      |   - author-stats          |
|  ReadingTracker.tsx       +---API---------->   - export                |
|  (progress to backend)    |                |                           |
|                           |                |  /api/stats/subscribers   |
+---------------------------+                +---------------------------+
         |                                              |
         v                                              v
   Google Analytics 4                          PostgreSQL Database
   (GA4 Property)                              (Prisma Models)
   - pageview events                           - Subscription
   - custom events                             - Payment
   - real-time data                            - Reader
   - audience data                             - ReadingHistory
   - acquisition data                          - Institution
                                               - InstitutionUser
                                               - Comment
                                               - ArticleRating
                                               - ConversionEvent

Data Source Mapping

4. GA4 Event Catalog — Every Event the Platform Fires

4.1 Automatic Events (fired by gtag.js)

4.2 Article Engagement Events

4.3 Paywall Events

4.4 Subscription Events

4.5 E-Commerce / Shop Events

4.6 Conversion Surface Events

4.7 Newsletter Events

4.8 Registration Events

Event Flow Summary

Reader Journey:
  Visit site -----> page_view (automatic)
  Browse article -> article_view
  Scroll reading -> article_scroll_depth (25%, 50%, 75%)
  Finish article -> article_scroll_depth (100%) + article_read_complete
  Hit paywall ----> paywall_view
  Click Subscribe > paywall_click_subscribe
  Start checkout -> subscribe_start
  Complete payment> subscribe_complete

  Browse shop ----> shop_product_view
  Add to cart ----> shop_add_to_cart
  Checkout -------> shop_checkout_start

  See promo modal > conversion_surface_impression
  Click CTA ------> conversion_surface_click
  Copy coupon ----> coupon_copied
  Complete action > conversion_surface_conversion

5. Admin Dashboard — Quick Daily Snapshot

Location

Admin Console > Dashboard (landing page after login)

What It Shows

4 Primary Stat Cards:

6 Status Cards:

3-Column Section:

• Most Popular articles (by view count)
• Under Review articles (pending editorial review)
• Quick Actions (New Article, Moderation, Analytics)

Social Overview Widget:

• Scheduled Today / This Week / Failed post counts
• Quick links to Compose Post and Social Analytics

Recently Published:

• Last 6 published articles with views, comments, shares

6. Analytics Overview Page — Deep Metrics

Location

Admin Console > Analytics

Controls

• Date Range Picker: 7d, 30d (default), 90d, 12m, Custom
• Refresh Button: Reloads all data
• Export Button: Downloads CSV report (requires ANALYTICS_EXPORT permission)

Section Layout

7. Paywall Conversion Funnel

What It Tracks

The paywall funnel measures the step-by-step conversion journey from seeing a paywall to completing a paid subscription.

How to Read the Funnel

• The conversion rate shown at each stage is relative to the top of the funnel (stage 1)
• A healthy paywall funnel converts 2-5% of paywall views to completed subscriptions
• Large drop-offs between stages indicate friction points:
  • Big drop between "Viewed" and "Clicked Subscribe" = paywall messaging isn't compelling
  • Big drop between "Started" and "Completed" = checkout friction (price, payment method, UX)

Data Source

GA4 Data API -- server-side query aggregating custom event counts over the selected date range.

8. Registration Funnel

What It Tracks

The registration funnel measures how effectively the platform converts anonymous visitors to active subscribers.

API Endpoint

GET /api/analytics/registration-funnel?days=30

9. Subscription & Revenue Metrics

Metrics Displayed

Revenue by Plan Breakdown

Shows subscriber distribution and revenue contribution per plan (e.g., "Digital Only: 45%, Print+Digital: 30%, Annual: 25%").

Revenue Trend

Monthly time-series chart of revenue, showing growth trajectory.

API Endpoint

GET /api/analytics/subscription-metrics

10. Content Performance Analytics

Metrics Per Article

Top Content Table

Ranked list showing the highest-performing articles by page views, with time-on-page, shares, and comments.

Author Statistics

GET /api/analytics/author-stats — Per-author metrics for editorial performance review.

API Endpoint

GET /api/analytics/content-performance

11. Traffic Source Analysis

Channels Tracked

UTM Attribution from Conversion Surfaces

When readers click a conversion surface CTA, the URL is automatically tagged with:

• utm_source=conversion_surface
• utm_medium=promo
• utm_campaign=cs_{goal}_{surfaceId}

This appears in GA4 traffic source reports, allowing you to measure the direct impact of conversion surfaces on subscriptions.

API Endpoint

GET /api/analytics/traffic-sources

12. Device & Browser Analytics

Device Categories

• Desktop (screen > 1024px)
• Mobile (screen < 768px)
• Tablet (768-1024px)

Browser Distribution

Top browsers by usage (Chrome, Safari, Firefox, Edge, etc.)

Operating Systems

Distribution across Windows, macOS, iOS, Android, Linux.

API Endpoint

GET /api/analytics/device-browser

13. Institutional Usage Reporting

What It Tracks

For each institution with an active subscription:

Use Case

Sales and customer success teams use this data to:

• Identify underutilized institutional accounts for engagement outreach
• Prepare usage reports for institutional renewal conversations
• Upsell additional seats to institutions with high utilization

API Endpoint

GET /api/analytics/institutional-usage

14. Social Media Analytics

Location

Admin Console > Social > Analytics

Tabs

1. Performance -- Impressions, Reach, Engagements, Engagement Rate, Posts Published, Likes, Comments, Clicks
2. Content -- Per-post performance breakdown
3. Growth -- Follower growth trends
4. Best Times -- Optimal posting time recommendations based on engagement data
5. Executive -- Summary view for leadership (requires SOCIAL_EXECUTIVE_READ permission)

Metrics

15. Data Export & Reporting

Export Formats

• CSV -- Comma-separated values for spreadsheet analysis
• JSON -- Machine-readable format for programmatic use

Available Exports

How to Export

1. Navigate to Analytics page
2. Set the desired date range
3. Click the Export button (top-right)
4. CSV file downloads automatically

Permission Required

ANALYTICS_EXPORT permission

API Endpoint

GET /api/analytics/export?type=subscriptions&format=csv&days=30

16. Cookie Consent & Privacy

How It Works

1. GoogleAnalytics component loads with analytics_storage: denied by default
2. CookieConsent component shows a banner asking the reader to accept cookies
3. If reader accepts, consent is stored in localStorage as hyphen_cookie_consent: accepted
4. On subsequent visits, analytics_storage is set to granted based on stored consent
5. If reader does not accept, GA4 events are still queued but not sent to Google

Impact on Analytics

• Readers who decline cookies will NOT generate GA4 data
• This means page views, scroll depth, and all custom events from those readers are invisible
• Internal platform data (subscriptions, reading history, bookmarks) is NOT affected by cookie consent -- it's recorded via authenticated API calls

Privacy Compliance

• Cookie consent follows GDPR principles
• No tracking cookies set before consent
• Consent status persisted only in localStorage (not server-side)

17. Scroll Depth & Reading Engagement Tracking

How Scroll Tracking Works

The observeScrollDepth() function in the Reader Portal:

1. Attaches a passive scroll event listener when an article page mounts
2. Calculates scroll percentage: (window.scrollY / (scrollHeight - windowHeight)) * 100
3. Fires article_scroll_depth at each milestone (25%, 50%, 75%, 100%)
4. Each milestone fires exactly once per page load
5. At 100%, also fires article_read_complete with total read time in seconds

What the Admin Sees

In the Analytics Overview page, the Scroll Depth Distribution section shows estimated percentages:

• % of readers who scrolled to 25%
• % of readers who scrolled to 50%
• % of readers who scrolled to 75%
• % of readers who scrolled to 100% (completed reading)

Reading Progress (Internal Tracking)

Separately from GA4, the ReadingTracker component:

• POSTs reading progress to /api/account/history/[articleId] at milestones (0/25/50/75/100%)
• Tracks progress, scrollPosition, timeSpentSec
• Records startedAt, lastReadAt, completedAt in the ReadingHistory table
• This powers the reader's Reading History page and the Implicit Preference Learning system

18. Conversion Surface Analytics

See the dedicated Conversion Surfaces Feature Description for full details.

Summary of analytics integration:

• 5 GA4 events: impression, click, dismiss, conversion, coupon_copied
• Internal ConversionEvent table: every interaction recorded with reader context
• Denormalized counters on each surface: impressionCount, clickCount, dismissCount, conversionCount
• Admin stats dashboard: totals, rates, time-series, device breakdown, top pages, UTM source breakdown
• UTM attribution: all CTA URLs auto-tagged for GA4 campaign tracking

19. User Stories

For Editors

For Product Managers

For Marketing

For Sales / Customer Success

For QA

20. Use Cases & Scenarios

Scenario 1: Monitoring a New Issue Launch

Context: New magazine issue published this week. Editor wants to measure reader response.

Steps:

1. Open Dashboard -- check "Published (7d)" card for the new issue's articles
2. Open Analytics -- set date range to "7d"
3. Check Key Metrics -- expect a spike in Page Views and Unique Visitors
4. Check Top Content -- new issue's articles should appear in the top 10
5. Check Scroll Depth -- look for high completion rates (75-100%) indicating engaged readers
6. Check Paywall Funnel -- if issue articles are premium, expect funnel activity

Scenario 2: Evaluating a Marketing Campaign

Context: Marketing ran a Facebook campaign to drive subscriptions.

Steps:

1. Open Analytics -- set date range to cover the campaign period
2. Check Traffic Sources -- "Social" percentage should be higher than baseline
3. Open GA4 directly -- filter by utm_source=facebook to see campaign-specific metrics
4. Check Subscription Metrics -- look for a spike in "New Subscribers"
5. If conversion surfaces were used, check their stats for UTM attribution (utm_campaign=cs_subscribe_paid_*)

Scenario 3: Institutional Renewal Preparation

Context: Sales team preparing for an institutional subscription renewal meeting.

Steps:

1. Open Analytics > Institutional Usage
2. Find the institution by name
3. Note: seats used vs total, utilization rate, most active users
4. Export the data as CSV for the renewal proposal
5. If utilization is low, recommend engagement strategies; if high, propose additional seats

Scenario 4: Diagnosing a Conversion Drop

Context: MRR has dropped this month. Need to diagnose why.

Steps:

1. Open Analytics -- compare 30d vs previous 30d
2. Check Subscription Metrics -- is churn rate up, or are new subscribers down?
3. Check Paywall Funnel -- are fewer people seeing paywalls (traffic drop)? Or is the funnel leaking?
4. Check Traffic Sources -- has any channel dropped significantly?
5. Check Top Content -- is popular content shifting away from premium articles?
6. Check Device Breakdown -- is a mobile issue causing bounce rate increases?

Known Limitations

FAQ