Analytics & events
OGPlayer emits events on three surfaces, and all three are identical across Android, iOS and web — same names, same fields, same timing. This page is the complete inventory.
PlaybackListener — the app-facing callbacks
Section titled “PlaybackListener — the app-facing callbacks”Drive your UI and app logic from these (all optional):
| Callback | Fields | When |
|---|---|---|
onStateChanged | state | IDLE → BUFFERING → READY → ENDED |
onIsPlayingChanged | isPlaying | actual playing/not-playing flips |
onPlay | — | first start of the loaded item only |
onPause / onResume | — | explicit pauses only — stalls and ad-break handoffs are silent |
onProgress | positionMs, bufferedMs, durationMs | steady tick, 250 ms default (configurable) |
onSeekStarted | fromMs, toMs | seek begins |
onSeekCompleted | positionMs | seek lands |
onLiveEdgeChanged | atLiveEdge | viewer drifts behind / catches up to live |
onDrmSessionRenewed | reason | a license quietly renewed mid-session |
onPlaybackCompleted | — | content truly finished — waits for postrolls |
onError | OGPlayerError | terminal errors (stable codes) |
onCastStateChanged | state | Android · Chromecast connection: NO_DEVICES / NOT_CONNECTED / CONNECTING / CONNECTED |
On live streams, onProgress reports the position inside the DVR window and
the window length as the duration.
AnalyticsEvent — the measurement stream
Section titled “AnalyticsEvent — the measurement stream”One listener, eleven typed events, identical string formatting on every platform — feed them to your pipeline as-is:
| Event | Fields | When |
|---|---|---|
Play / Pause | — | transport changes (explicit; stalls are silent) |
Seek | fromMs, toMs | user or API seeks |
BufferStart / BufferEnd | — | rebuffering window |
BitrateChanged | bitrate, width, height, frameRate | ABR switches |
DroppedFrames | count, elapsedMs | render drops in the window |
QualitySnapshot | positionMs, bufferedMs, bandwidthEstimateBps, droppedFramesTotal | every 10 s while playing |
DrmKeysLoaded | — | license acquired |
Error | the OGPlayerError | terminal errors |
Complete | — | content finished |
player.addAnalyticsListener { event -> pipeline.track(event.toString()) }player.addAnalyticsListener(MyAnalytics()) // onEvent(_ event: AnalyticsEvent)player.addAnalyticsListener((event) => pipeline.track(event));AdListener — the full ad lifecycle
Section titled “AdListener — the full ad lifecycle”Everything about ads lives here — the analytics stream carries no ad events by design, so the two feeds stay cleanly separated:
| Callback | Fields | When |
|---|---|---|
onAdBreakStarted | breakType, totalAds | a PREROLL / MIDROLL / POSTROLL break begins |
onAdStarted | AdInfo (adId, pod position, duration, skippability…) | each ad begins |
onAdProgress | ad, positionMs, durationMs | steady tick during an ad (drives the countdown) |
onAdPaused / onAdResumed | ad | viewer pauses/resumes the ad |
onAdSkipped | ad | viewer skipped |
onAdCompleted | ad | ad finished |
onAdBreakCompleted | breakType | the break ended (its cue marker is removed) |
onAdSkippableStateChanged | ad, isSkippable, skipOffsetMs | an ad becomes skippable (slot providers) |
onAdError | OGAdError (code, phase, message) | ad problems — never fatal to content |
VMAP cue points are exposed separately via adCuePositionsMs and drawn as
markers on the scrubber.