Telemetry from the player,
not a universal SDK claim.

Compatibility: Unverified

Documented contract

Verification evidence

Source-inspected implementation
The checked-in SDK and server-side Zod mirror define the telemetry envelope, event names, and payload fields shown on this page.
Basis
The local player-sdk sources and src/lib/contracts/telemetry.ts were inspected together.
Scope
createTelemetry, HTML video observation, optional hls.js quality-change wiring, and POST /api/v1/telemetry batching.
Reference
packages/player-sdk/src/events.ts · src/lib/contracts/telemetry.ts

The checked-in player SDK defines a telemetry handle, observes an HTML <video> element, optionally receives an hls.js instance, and sends typed event batches to POST /api/v1/telemetry. The fields and local implementation are documented here; distribution, broad compatibility, durable delivery, and production operation remain separate questions.

Read the web SDK reference Back to integrations

Supported scope

A narrow, inspectable player integration boundary.

This is the behavior represented by the checked-in sources. It describes a contract and adapter path, not a promise that every player or browser can produce every event.

Source-inspected shape — not a public install instruction

// Source-inspected shape; not a public install command.
const handle = createTelemetry({
  apiKey: '<controlled-evaluation key>',
  ingestUrl: '<configured-ingest-origin>/api/v1/telemetry',
  session: {
    contentId: '<content-id>',
    contentVersion: '<content-version>',
  },
});

const detach = handle.attach(videoElement, {
  hls: optionalHlsInstance,
  expectedContentVersion: '<expected-version>',
});

handle.emit({
  type: 'error',
  ts: new Date().toISOString(),
  payload: { code: 'example', fatal: false },
});

handle.end('ended');
detach();

What is represented

01
Session handlecreateTelemetry(config) returns sessionId, emit, attach, and end.
02
Player observationattach observes an HTML <video> element and can wire an optional hls.js instance for quality changes.
03
Bounded batchingBearer-authenticated batches post to /api/v1/telemetry. Defaults are 50 events or 10 seconds, whichever flushes first.

Documented contract

Eleven event types, one typed envelope.

The table below mirrors packages/player-sdk/src/events.ts and src/lib/contracts/telemetry.ts. A ? marks an optional field;from? may also be null. Field names and optionality are documented contract shape, not proof of universal player coverage.

Telemetry event envelope fields
Envelope field	Shape	Meaning
type	EventType	One of the eleven closed contract event names below.
ts	string	Timestamp carried with the event.
payload	type-specific object	The strict payload shape associated with `type`.

Telemetry event payload fields
Event type	Payload fields
playback_start	`positionMs`, `durationMs`?, `contentId`?
playback_pause	`positionMs`, `bufferedMs`?
playback_resume	`positionMs`, `bufferedMs`?
rebuffer_start	`positionMs`, `bufferedMs`?
rebuffer_end	`positionMs`, `bufferedMs`?
quality_change	`from`?, `to`, `bitrate`?
first_frame_decoded	`positionMs`, `startupLatencyMs`?, `contentId`?, `contentVersion`?, `recoveryRunId`?
content_freshness	`contentId`?, `contentVersion`?, `expectedContentVersion`?, `isFresh`?, `cacheAgeMs`?, `recoveryRunId`?
latency_sample	`startupLatencyMs`?, `segmentLatencyMs`?, `playerLatencyMs`?, `recoveryRunId`?
error	`code`?, `message`?, `fatal`?
session_end	`reason` (`ended` \| `unloaded` \| `error`), `durationMs`?

Evidence boundary

What the local contract does not establish.

Source inspection can establish the shape of an implementation. It cannot substitute for a distribution channel, a compatibility matrix, a durability policy, or an attributable production evaluation.

Distribution

Not verified here

The checked-in sources are present, but public npm, CDN, and GitHub distribution or a download channel is not established. This page provides no public install command.

Compatibility

Not verified here

The inspected paths cover an HTML video adapter and an optional hls.js peer path. Browser, player, and version coverage beyond those paths is unverified; no Shaka, ExoPlayer, AVPlayer, DASH, or universal-browser claim is made.

Data recovery

Not guaranteed

Network and 5xx failures retry with exponential backoff for at most three total attempts, then the batch is dropped. There is no durable client retry queue; 4xx failures are not retried, and the database schema does not establish an idempotency uniqueness constraint.

Production validation

Not evidenced

No production validation, customer deployment, audience-wide coverage, retention policy, or SLA is evidenced by this page.

Reference surfaces

Use the checked-in docs for a controlled evaluation.

The web SDK reference describes the local shape. API key documentation covers the bearer-authenticated credential flow, and the API reference describes the ingest endpoint. None of those links is a public package or a production-readiness claim.

Web SDK docs API keys API reference

CMCD is a separate integration surface. This page does not turn the older CMCD concept into part of the player telemetry event contract. View CMCD evidence.

Telemetry from the player,not a universal SDK claim.