Skip to main content

Epic 4 - Analytics & Metrics

To Be Done

Epic 4 implements analytics and metrics tracking for audio generations and QR code scans.

Objective​

Add analytics and metrics tracking to measure user engagement, QR code scans, and audio playback.

What You Track:

  • Total QR codes generated
  • Total scans per QR code
  • Total audio listens (direct URL and QR scans)
  • Geographic distribution of scans
  • Time-based usage patterns
  • Device types (mobile vs desktop)

What You Get:

  • Analytics dashboard
  • Real-time metrics
  • User engagement insights
  • Investor-ready reports
  • CSV/Excel exports
Building on Epic 1, 2 & 3

Epic 4 adds analytics to the complete system built in Epic 1 (audio), Epic 2 (QR codes), and Epic 3 (manual upload).

Priorities Covered​

  • P5: Basic Analytics (Scans/Listens)

Prerequisites:

  • Epic 1: Audio generation working
  • Epic 2: QR code generation working
  • Epic 3: Manual upload working

Features​

Analytics Dashboard​

Real-Time Metrics:

  • Total users registered
  • Total audio generations created
  • Total QR codes generated
  • Total scans across all QR codes
  • Total audio listens

User Dashboard:

  • Personal generation history
  • Scans per generation
  • Most popular content
  • Geographic scan distribution
  • Usage over time (charts)

Admin Dashboard:

  • Platform-wide metrics
  • Growth charts and trends
  • System health indicators
  • User engagement metrics
  • Error rates and alerts

Tracking Features​

QR Code Scan Tracking:

  • Track each scan via QR code
  • Capture device type
  • Capture location (city/country)
  • Capture timestamp
  • Link to specific generation

Audio Play Tracking:

  • Track direct URL plays
  • Track QR code plays
  • Capture listen duration
  • Capture completion rate
  • Identify repeat listeners

User Engagement:

  • Generation frequency
  • Average listens per generation
  • Peak usage times
  • Popular voice models
  • Content length patterns

Technical Details​

Data Storage​

Track the following metrics:

Scans Table:

  • Scan ID
  • Generation ID
  • Timestamp
  • Device type (mobile/desktop)
  • Location (city, country)
  • Referrer (QR scan vs direct link)

Plays Table:

  • Play ID
  • Generation ID
  • Timestamp
  • Duration listened
  • Completion percentage
  • Device type

Aggregated Metrics:

  • Total scans per generation
  • Total plays per generation
  • Average listen duration
  • Popular content
  • Geographic heatmap data

Analytics API​

Get Generation Analytics​

Endpoint: GET /api/v1/analytics/generation/{id}

Response:

{
  "success": true,
  "data": {
    "generationId": "550e8400-e29b-41d4-a716-446655440000",
    "totalScans": 127,
    "totalPlays": 98,
    "avgListenDuration": 12.5,
    "topLocations": [
      {"city": "New York", "country": "USA", "scans": 45},
      {"city": "London", "country": "UK", "scans": 32}
    ],
    "deviceBreakdown": {
      "mobile": 89,
      "desktop": 38
    },
    "scansByDay": [
      {"date": "2024-11-01", "scans": 23},
      {"date": "2024-11-02", "scans": 31}
    ]
  }
}

Get User Analytics​

Endpoint: GET /api/v1/analytics/user

Response:

{
  "success": true,
  "data": {
    "totalGenerations": 24,
    "totalScans": 450,
    "totalPlays": 367,
    "mostPopular": {
      "generationId": "550e8400...",
      "text": "Welcome to our restaurant...",
      "scans": 127
    },
    "recentActivity": [
      {"date": "2024-11-03", "generations": 3, "scans": 18}
    ]
  }
}

Success Criteria​

Epic 4 is complete when:

  1. ✅ QR code scans are tracked
  2. ✅ Audio plays are tracked
  3. ✅ Manual upload listens are tracked
  4. ✅ User dashboard shows personal analytics
  5. ✅ Admin dashboard shows platform metrics
  6. ✅ Geographic data is captured
  7. ✅ Device type is tracked
  8. ✅ CSV/Excel export works
  9. ✅ Real-time metrics update
  10. ✅ Manual testing completed and verified
  11. ✅ Deployed to production

Timeline​

Duration: 5 weeks

WeeksFocusDeliverables
Week 17Analytics InfrastructureTracking events implemented
Week 18Data Storage & APIAnalytics API endpoints
Week 19User DashboardPersonal analytics view
Week 20Admin DashboardPlatform-wide analytics
Week 21Reports & ExportCSV export and testing

Dashboard Mockup​

User Dashboard​

Personal Metrics:

  • Total Generations: 24
  • Total Scans: 450
  • Total Plays: 367
  • This Month: +15 generations

Top Performing Content:

  1. "Welcome to our restaurant..." - 127 scans
  2. "Special holiday menu..." - 89 scans
  3. "New summer menu items..." - 67 scans

Recent Activity Chart:

  • Line chart showing scans over the last 30 days
  • Bar chart showing plays by day of week

Admin Dashboard​

Platform Metrics:

  • Total Users: 342
  • Total Generations: 5,847
  • Total Scans: 45,231
  • Total Plays: 38,904
  • Growth: +23% this month

System Health:

  • API Response Time: 145ms avg
  • Error Rate: 0.02%
  • S3 Storage: 234 GB used
  • ElevenLabs Usage: 87% of quota

Export Formats​

CSV Export​

Generate CSV reports with:

  • Generation details (text, voice, date)
  • Scan counts per generation
  • Play counts per generation
  • Geographic breakdown
  • Date range filtering

Example CSV:

Generation ID,Text,Voice,Created,Scans,Plays,Top Location
550e8400...,Welcome to our restaurant,Rachel,2024-11-01,127,98,"New York, USA"
660e8400...,Special holiday menu,Adam,2024-11-02,89,72,"London, UK"

Excel Export​

Same data as CSV but with:

  • Multiple sheets (Overview, Scans, Plays, Locations)
  • Charts and visualizations
  • Formatted tables
  • Summary statistics