Player SDK

Playback telemetry

Report buffering, bitrate switches and playback errors from a client back to the edge node serving the stream.

v1 Stable since 4.0 eu-central

Overview

Player SDKs emit telemetry events during playback. Events are collected client-side and sent to the same edge node that serves the media, so telemetry never crosses a region boundary and adds no extra DNS resolution to the playback path.

The endpoint accepts a single event or a small batch. It is intentionally cheap: no body parsing, no authentication round trip, and a fixed-size response that players discard.

Endpoint

GET /api/v1/metrics/analytics/

GET is used rather than POST so that events survive restrictive middleboxes and proxy configurations that reject request bodies on non-idempotent methods. Payloads are carried in the query string and in request headers.

The trailing slash is required. Requests to the path without it are redirected, which costs the player a round trip.

Parameters

Name		Description
sid	required	Playback session identifier. Generated by the SDK when playback starts and held for the lifetime of the session.
seq	required	Monotonic event counter within the session. Lets the collector detect and discard duplicates without deduplicating on payload.
ev	required	Event type: `buffer`, `bitrate`, `seek`, `error` or `heartbeat`.
_dc	optional	Cache buster. Ignored by the server, but prevents intermediate caches from collapsing identical requests. SDKs set it on every call.

Headers

X-Cache — set by the SDK on outbound calls; carries the encoded event payload for clients that cannot extend the query string.
X-Real-IP — added by the edge, not by the client.

Example

# report a buffering stall
curl 'https://static.zabg.site/api/v1/metrics/analytics/?sid=8f21c4&seq=147&ev=buffer&_dc=1757260'

{
  "accepted": 1,
  "seq": 147,
  "next": 250
}

The next field is a hint, in milliseconds, for when the SDK should flush again. Players that ignore it fall back to their local flush interval.

Batching

The SDK does not send one request per event. Events are buffered and flushed on a short interval, which keeps request volume proportional to session count rather than to event count.

Default flush interval is 250 ms during active playback.
Heartbeats continue at a reduced rate while playback is paused.
A session that produces no events for 30 s is closed by the collector.

A busy node therefore sees a high, steady rate of small requests on this path. That is expected and is not rate limited per session.

Errors

Status		Meaning
400		Missing `sid`, `seq` or `ev`.
410		Session already closed by the collector. The SDK should start a new session.
413		Encoded payload exceeded the header size limit. Reduce the batch size and retry.

Telemetry failures never interrupt playback. The SDK drops events it cannot deliver and continues.