Event Reporting Protocol - Analytics

Event Reporting Protocol

Session Management

Each playback session requires a unique analytics session ID. The analytics session is separate from the Kaltura Session (KS):

• KS — Authentication token for API calls
• Analytics session — Unique identifier linking all events from one playback session

Generate a unique analytics session ID per player instance / playback session. Use a UUID or timestamp-based identifier.

Event Ordering

Fire events in the correct lifecycle order:

1. WIDGET_LOADED (player ready)
2. MEDIA_LOADED (media metadata available)
3. PLAY (playback begins)
4. PLAY_REACHED_25 → PLAY_REACHED_50 → PLAY_REACHED_75 → PLAY_REACHED_100 (as playback progresses)
5. PAUSE, SEEK, BUFFER_START/BUFFER_END (during playback as they occur)
6. REPLAY (if user replays)

Quartile Calculation

Calculate quartile events based on the actual content duration:

• Fire each quartile event only once per playback session
• Base quartile positions on total content duration (excluding ads)
• If the user seeks past a quartile position, do not retroactively fire the skipped quartile — fire it only during natural forward playback

Batching and Timing

• Fire events as they occur rather than batching — real-time analytics depend on timely delivery
• Include accurate eventTimestamp values (Unix seconds)
• If the client goes offline temporarily, queue events and send them in order when connectivity resumes