Analytics Feature Description

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.

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?