Recording view analytics
When you share a completed video-room recording — for training, compliance, or a customer handoff — raw “link opened” counters tell you nothing useful. View analytics measure how the recording was actually watched: who watched, how far each viewer got, where the audience dropped off, and how many people are watching right now. It works like any viewership pipeline: your player widget reports lightweight playback events as a viewer watches, and Orbit rolls those events up into a live badge and a post-hoc engagement report. This guide shows you how to build the emit pattern on a player you own (an embedded widget, a portal page, or an internal tool) and how to read the results.This covers engagement on finalized video-room recordings — “who watched and how far.” It is distinct from session replay, which captures DOM-level interactions on a web page. The two solve different problems and you can use both independently.
Playback ingest
Your player reports one event at a time to the ingest endpoint:POST /api/v1/recordings/{id}/views
Each event carries the viewer’s current head position, the total recording duration, and the watch-time accrued since the last event. The same response returns the live unique-viewer and watching-now counts, so the player can render a “watching now” badge without a second call.
Response (in the envelope’s
data object):
Auth: an API key (
X-API-Key) or a session JWT with the video:write scope. Values are clamped server-side, so a buggy player build (NaN, negative, or runaway deltas) cannot poison the aggregate; only grossly malformed payloads get a 400.
Live monitor
The monitor answers “how many people have watched this recording, and how many are watching it right now”:GET /api/v1/recordings/{id}/views
Poll it on whatever cadence your dashboard or badge needs — it is a cheap read requiring the
video:read scope. The ingest POST already returns these two counts, so a player-side badge usually needs no live-endpoint polling at all.
Engagement report
The post-hoc report rolls everything up — the Wistia/Vimeo-style engagement graph for operators deciding whether the shared recording works:GET /api/v1/recordings/{id}/views/report
Read scope:
video:read. Use the curve to find drop-off moments, the per-viewer rows to see who actually finished, and the completion rate as the single health number.
Player integration recipe
Emit one event per player action with an opaque, player-mintedviewer_id — never an email, name, or account id. Send the play/pause/seek/ended events as they happen, and a heartbeat progress event every ~15 seconds while playing so the live badge stays warm. Measure watched_delta_seconds locally between emissions, and debounce high-frequency actions (scrubbing, rapid seek/restore-back) so a scrub gesture sends one seek event, not fifty.
Failure behaviour is fail-open
View analytics are best-effort by design. If the analytics backend is unavailable, the ingest and read endpoints answer503 (SERVICE_UNAVAILABLE) — never 500 — and nothing else about playback changes. Treat a 503 as “skip this event and keep playing,” exactly like the snippet above does. A player that gates rendering on a badge read should hide the badge, not the player, on a 503.
Limitations
- Scope: the endpoint family covers finalized video-room recording artefacts only — the recording id comes from the video-room recording lifecycle. Other recording families are out of scope for this surface.
- Tenant namespacing: all viewership state is namespaced by your organization, so a caller can only ever read their own tenant’s metrics.
- Retention: a recording’s viewership aggregate ages out 30 days after the last reported event, matching the maximum share-link lifetime.
- No PII by design: the opaque
viewer_idmeans the analytics carry no personal data — keep it that way and mint a fresh random id per session.
Example: read the report
completed_viewers of 18 out of 42 unique viewers is a 43% completion rate; the retention curve says 5% of the audience dropped before 10% and another 12% by the 20% mark, so the opening minutes lose the most viewers.
See also
- Recordings API — legal holds, integrity seals, and share links for finalized recordings
- Video channel — how video-room recordings are produced
- Session replay — DOM-level session capture, a different problem from recording engagement