playerHeartbeat

POST

/api/v1/player/heartbeat

curl --request POST \
  --url https://example.com/api/v1/player/heartbeat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "playerFamily": "example", "playerArchitecture": "example", "browser": { "browserName": "chrome", "browserMajorVersion": 1, "displayMode": "browser_tab", "fullscreenActive": true, "audioUnlocked": true, "wakeLock": "active", "storagePersistence": "persistent", "storageUsageBytes": 1, "storageQuotaBytes": 1, "offlineContent": "ready", "serviceWorker": "controlling", "serviceWorkerVersion": "example", "wasDiscarded": true } }'

Accepts the authenticated Player heartbeat. Optional Linux Display Control fields report detected providers, independent capabilities, display power observations, and policy state. They do not determine Player online status; command acknowledgement and display state confirmation remain separate.

Players released with the retired Noise Meter plugin may still send a noiseMeter object. The server accepts it and ignores it, so the rest of the heartbeat is recorded.

Authorizations

• deviceBearer

Request Body

Media typeapplication/json

The Player status document. Only the release family fields are described here; the remaining fields are the existing heartbeat contract and are additive.

object

playerFamily

android, electron-linux, edge, windows or browser. The server keeps only these values; another value is recorded as absent.

string

playerArchitecture

x86_64 or aarch64, kept only with playerFamily: edge or playerFamily: windows. An Edge or Windows screen without a known architecture is incompatible for its family’s deployments.

string

browser

Facts only a Browser Player can measure. A Browser Player also reports the generic reliability fields where their meaning matches: foregroundState (foreground, background, frozen or recovering), immersiveModeActive (the effective unattended presentation: fullscreen or an installed app), keepScreenOn, activeHoursState (active or off_hours) and cachedFallbackAvailable. Every value is a measurement. The server draws the health conclusions. The Browser Player sends no identifier that could single out one browser.

object

browserName

string

Allowed values: chrome edge chromium other

browserMajorVersion

integer

<= 9999

displayMode

standalone_pwa when the page runs as an installed app, otherwise browser_tab.

string

Allowed values: browser_tab standalone_pwa

fullscreenActive

boolean

audioUnlocked

Whether the browser allows audible playback now.

boolean

wakeLock

string

Allowed values: active released denied unsupported

storagePersistence

persistent only when the browser said so. best_effort means the browser may remove downloaded content under storage pressure.

string

Allowed values: persistent best_effort unknown

storageUsageBytes

integer format: int64

storageQuotaBytes

integer format: int64

offlineContent

string

Allowed values: ready repairing not_prepared

serviceWorker

string

Allowed values: controlling update_waiting installing unavailable

serviceWorkerVersion

string

<= 64 characters

wasDiscarded

True when the browser discarded this page and the Player restarted it.

boolean

Responses

200

Heartbeat accepted. data.ignoredFields names optional playback identifiers that were malformed and therefore dropped.

Media typeapplication/json

object

data

required

object

accepted

required

boolean

ignoredFields

Optional playback identifiers that were malformed and therefore dropped.

Array<string>

Example^generated

{
  "data": {
    "accepted": true,
    "ignoredFields": [
      "example"
    ]
  }
}

400

Heartbeat body rejected

401

Credential invalid or revoked

403

Screen disabled