Skip to main content
Ant Media Server provides built-in analytics capabilities to track viewer behavior, stream performance, and player events. This guide covers analytics collection, event types, and implementation.

Analytics Overview

The analytics system collects events from both server-side and client-side sources to provide comprehensive insights into streaming performance and viewer engagement.

Event Sources

  • Server-side: Automatically generated by Ant Media Server
  • Client-side: Sent from player applications via REST API

Analytics Logger

The AnalyticEventLogger (src/main/java/io/antmedia/analytic/AnalyticEventLogger.java) processes all analytics events through dedicated REST endpoints.

Player Analytics Events

Play Events

Track when viewers start, pause, and stop playback:

Event Types

playStartedFirstTime
  • Triggered once when user first starts playing
  • Useful for counting unique views
  • Sent from client player
playStarted
  • Triggered when playback starts or resumes
  • Generated on both server and client side
  • Applies to WebRTC, HLS, and VoD
playPaused
  • Triggered when viewer pauses playback
  • Client-side event only
playEnded
  • Triggered when playback ends
  • Generated on both server and client side

Send Play Events

Watch Time Events

Track how long viewers watch and which parts of content they consume:

Watch Time Metrics

  • watchTimeMs: Duration viewer watched (in milliseconds)
  • startTimeMs: Position in video where watching started
  • timeMs: Unix timestamp when event occurred

Understanding Watch Time

If you receive:
This means: User watched for 5 seconds, covering the 10-15 second segment of the video.

Send Watch Time Events

Periodic Watch Time Tracking

Implement periodic tracking in your player:

Securing Analytics Endpoints

Protect analytics endpoints from abuse:

Enable JWT Authentication

Configure in Application Settings:

Generate JWT Token

Analytics Event Structure

Base Event Fields

All analytics events (src/main/java/io/antmedia/analytic/model/AnalyticEvent.java) include:
  • event: Event type identifier
  • timeMs: Unix timestamp in milliseconds (auto-set if not provided)
  • app: Application name (auto-set by server)
  • streamId: Stream identifier
  • logSource: “client” or “server”
  • token: JWT token for secured endpoints
  • subscriberId: Unique viewer/subscriber identifier

Play Event Fields

Additional fields for play events (src/main/java/io/antmedia/analytic/model/PlayEvent.java):
  • protocol: Streaming protocol (webrtc, hls, dash, rtmp)
  • clientIP: Client IP address (auto-set by server)

Watch Time Event Fields

Additional fields for watch time events (src/main/java/io/antmedia/analytic/model/WatchTimeEvent.java):
  • watchTimeMs: Duration of watch session in milliseconds
  • startTimeMs: Video position where viewing started

Server-Side Analytics Events

Ant Media Server automatically generates these events:

Publish Events

publishStarted
  • When a stream starts publishing
  • Includes stream metadata
  • Logged automatically
publishEnded
  • When a stream stops publishing
  • Includes stream duration
  • Logged automatically
publishStats
  • Periodic publishing statistics
  • Bitrate, resolution, codec info
  • Logged during active streams

Viewer Count Events

viewerCount
  • Periodic viewer count snapshots
  • Per-stream viewer metrics
  • Broken down by protocol type

Key Frame Events

keyFrameStats
  • Key frame interval statistics
  • Important for ABR and streaming quality

Analytics Data Storage

Analytics events are logged and can be:

File-based Logging

Events are logged to application log files:

Custom Analytics Processing

To process analytics events:
  1. Parse Log Files: Extract analytics JSON from logs
  2. Kafka Integration: Stream analytics to Kafka for processing
  3. Database Storage: Store events in your analytics database
  4. Real-time Processing: Process events as they arrive

Implementing Analytics in Players

WebRTC Player Example

HLS Player Example

Analytics Best Practices

  1. Use Subscriber IDs: Assign unique IDs to track individual viewer behavior
  2. Secure Endpoints: Enable JWT authentication in production
  3. Report Periodically: Send watch time events every 10-30 seconds
  4. Handle Errors: Implement retry logic for failed analytics requests
  5. Track First Plays: Use playStartedFirstTime for unique view counts
  6. Include Protocol: Always specify the streaming protocol
  7. Batch Events: Consider batching events in high-volume scenarios
  8. Privacy Compliance: Ensure analytics collection complies with privacy regulations

Analytics Queries and Reporting

Common Analytics Questions

Total Unique Views
Average Watch Time
Concurrent Viewers
Most Watched Segments
  • Aggregate startTimeMs values from watch time events
  • Create histogram of video positions
  • Identify popular segments

Integration with Analytics Platforms

Google Analytics

Forward events to Google Analytics:

Custom Analytics Pipeline

  1. Collect: Gather events via REST API
  2. Process: Parse and normalize event data
  3. Store: Save to time-series database (InfluxDB, TimescaleDB)
  4. Visualize: Create dashboards (Grafana, Kibana)
  5. Alert: Set up alerts on metrics (viewer drops, error rates)