SECTION 9 — ANALYTICS: LIVE

51. POST /analytics/live/session/start

Called when a user starts watching a live stream.

Request

POST /analytics/live/session/start
Content-Type: application/json
Authorization: Bearer <token>

Request Body

{
  "session_id": "sess_live_xyz001",
  "user_id": "user_123",
  "device_id": "device_abc123",
  "platform": "web",
  "app_version": "2.4.1",
  "stream": {
    "stream_id": "stream_abc123",
    "channel_id": "ch_101",
    "creator_id": "creator_001",
    "creator_name": "Chris Spencer"
  },
  "epg": {
    "current_program_id": "prog_002",
    "current_program_title": "Behind the Laughs",
    "program_position_seconds": 900
  },
  "playback": {
    "quality": "auto",
    "latency_mode": "low",
    "dvr_enabled": false
  },
  "device": {
    "type": "web",
    "os": "macOS",
    "os_version": "14.0",
    "browser": "Chrome",
    "browser_version": "119.0",
    "screen_resolution": "1920x1080",
    "connection_type": "wifi"
  },
  "geo": { "country": "US", "state": "Georgia", "city": "Atlanta", "timezone": "America/New_York" },
  "referrer": { "source": "creator_zone", "page": "/creators/chris-spencer", "section": "channel_live" },
  "timestamp": "2024-11-01T18:15:00Z"
}

Request Body Parameters (key fields)

Field	Type	Required	Description
session_id	string	Yes	Unique session ID
user_id	string	No	User ID (null for guests)
device_id	string	Yes	Device fingerprint
platform	string	Yes	web, ios, android, roku, firetv, appletv
stream.stream_id	string	Yes	Live stream ID
stream.channel_id	string	Yes	Channel ID
stream.creator_id	string	Yes	Creator ID
epg.current_program_id	string	Yes	Current program ID
playback.quality	string	Yes	Initial stream quality
playback.latency_mode	string	Yes	low, normal
playback.dvr_enabled	boolean	Yes	Whether DVR is on
device.connection_type	string	Yes	wifi, cellular, ethernet
geo.country	string	Yes	Country code
timestamp	string	Yes	ISO 8601 UTC

Response 200 OK

{
  "status": "success",
  "data": {
    "session_id": "sess_live_xyz001",
    "accepted": true,
    "heartbeat_interval_seconds": 30,
    "server_timestamp": "2024-11-01T18:15:00Z"
  }
}

52. POST /analytics/live/session/heartbeat

Called every 30 seconds during live viewing.

Request Body

Include session_id, user_id, device_id, stream_id, channel_id, creator_id, epg (current_program_id, current_program_title, program_elapsed_seconds, program_progress_percent), playback (is_playing, is_paused, is_buffering, quality, volume_level, dvr_offset_seconds), performance (buffer_health_seconds, rebuffer_count, bitrate_kbps, latency_ms), engagement, and timestamp.

Response 200 OK

{
  "status": "success",
  "data": {
    "session_id": "sess_live_xyz001",
    "accepted": true,
    "next_heartbeat_seconds": 30,
    "server_timestamp": "2024-11-01T18:15:30Z"
  }
}

53. POST /analytics/live/session/end

Called when user exits the live stream.

Request Body (key fields)

Field	Type	Required	Description
session_id	string	Yes	Session ID
watch_summary.total_watch_seconds	int	Yes	Total watch time
watch_summary.end_reason	string	Yes	user_exit, error, timeout, inactivity
watch_summary.programs_watched	array	Yes	Programs watched during session
performance.total_rebuffer_count	int	Yes	Total rebuffer events
performance.quality_switches	int	Yes	Quality changes
engagement.total_chat_messages_sent	int	Yes	Chat messages sent
engagement.total_reactions_sent	int	Yes	Reactions sent
timestamp	string	Yes	ISO 8601 UTC

Response 200 OK

{
  "status": "success",
  "data": {
    "session_id": "sess_live_xyz001",
    "accepted": true,
    "watch_summary": {
      "total_watch_seconds": 2340,
      "total_watch_formatted": "39:00",
      "end_reason": "user_exit"
    },
    "server_timestamp": "2024-11-01T18:54:00Z"
  }
}

54. POST /analytics/live/events

Post discrete live stream player events.

Request Body

Send session_id, user_id, device_id, stream_id, creator_id, and an events array. Each event has event_id, event_type, timestamp, and optional metadata.

Supported Live Event Types

Event Type	Description
stream_start	Live playback started
stream_buffer_start / stream_buffer_end	Buffering began/ended
stream_reconnect / stream_reconnect_success	Reconnection
stream_error	Stream error occurred
program_change	EPG program changed
quality_change	Stream quality changed
fullscreen_enter / fullscreen_exit	Fullscreen
mute / unmute	Audio muted/unmuted
dvr_seek	User seeked via DVR
dvr_resume_live	Returned to live from DVR
reaction	User sent reaction
share	User shared stream
follow	User followed during stream
subscribe	User subscribed during stream
tip	User tipped during stream

Response 200 OK

{
  "status": "success",
  "data": {
    "session_id": "sess_live_xyz001",
    "accepted_count": 5,
    "rejected_count": 0,
    "rejected_events": [],
    "server_timestamp": "2024-11-01T19:00:00Z"
  }
}