Analytics

Track video plays, watch time, and viewer engagement with Redis-first event ingestion.

Architecture

text

Browser/SDK                Redis              PostgreSQL
    │                       │                    │
    │── POST /events ─────▶│ (buffer)           │
    │                       │                    │
    │                       │── flush every 60s ▶│
    │                       │                    │
API ◀── GET /summary ───────────────────────────│

Events are written to Redis first for high throughput (handles thousands of concurrent viewers), then flushed to PostgreSQL every 60 seconds via a cron job for permanent storage and querying.

Ingest Events

This endpoint is public (no authentication required) — it's called by video players in browsers:

bash

curl -X POST /api/analytics/events \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": 1,
    "event_type": "play",
    "session_id": "unique-viewer-session",
    "watch_duration": 45.5,
    "user_agent": "Mozilla/5.0...",
    "referrer": "https://your-site.com/blog/post-1"
  }'

Event Types

Type	When
play	Video starts playing
pause	Video is paused
ended	Video finishes playing
seek	Viewer seeks to a position
quality_change	Quality tier changes

Query Analytics

Workspace Summary

bash

curl /api/analytics/summary \
  -H "Authorization: Bearer TOKEN"

Response

{
  "data": {
    "asset_count": 42,
    "total_plays_today": 156,
    "total_plays_week": 1023,
    "total_plays_month": 4521,
    "top_videos": [
      { "asset_id": 1, "title": "Getting Started", "plays": 342 },
      { "asset_id": 5, "title": "Advanced Tutorial", "plays": 187 }
    ]
  }
}

Per-Video Stats

bash

curl /api/analytics/videos/1 \
  -H "Authorization: Bearer TOKEN"

Automatic Tracking

The React SDK and embed script automatically send analytics events — no extra setup needed. If you build a custom player, call POST /api/analytics/events on play/pause/end events.

← Next.js + Go Guide Webhooks