@oddin-gg/havik-player 1.16.0 → 1.17.0

package/README.md

@@ -13,7 +13,7 @@ integration modes:
 Widevine (Chrome/Firefox/Edge/Android) is fully supported. Safari/iOS plays via
 native passthrough; full FairPlay EME is a tracked fast-follow. See [Limitations](#limitations).
 
-> 📖 **Hosted docs & embed page:** [player-dev.oddin-video.gg](https://player-dev.oddin-video.gg) · **Full API reference:** [docs/API.md](docs/API.md) · **Examples** (vanilla / React / Vue): [examples/](examples/) · **API stability & versioning:** [docs/STABILITY.md](docs/STABILITY.md) · **Service status & endpoint directory:** [status-dev.oddin-video.gg](https://status-dev.oddin-video.gg)
+> 📖 **Hosted docs & embed page:** [player-dev.oddin-video.gg](https://player-dev.oddin-video.gg) (source: [havik-player-site](https://github.com/oddin-gg/havik-player-site) — the site pins and bundles this SDK's released npm package) · **Full API reference:** [docs/API.md](docs/API.md) · **Examples** (vanilla / React / Vue): [examples/](examples/) · **API stability & versioning:** [docs/STABILITY.md](docs/STABILITY.md) · **Service status & endpoint directory:** [status-dev.oddin-video.gg](https://status-dev.oddin-video.gg)
 
 > ⚠️ **Before you integrate — a server-side prerequisite that is out of your code's hands:**
 > the api-key's **AllowedOrigins** (and, for iframes, **AllowedIframeParents**) **and** the
@@ -196,15 +196,16 @@ channel directly.
 
 All API errors are a typed `PlaybackError` with `{ code, httpStatus, retryAfterMs?, requestId? }`:
 
-| code                         | HTTP      | meaning                                             | retry?            |
-| ---------------------------- | --------- | --------------------------------------------------- | ----------------- |
-| `INVALID_URN`                | 400       | malformed URN                                       | no                |
-| `NOT_FOUND`                  | 404       | unknown URN **or** not entitled (indistinguishable) | no                |
-| `GONE`                       | 410       | ended past catchup window                           | no                |
-| `TOO_EARLY`                  | 425       | upcoming, not live yet                              | yes (waitForLive) |
-| `UNAVAILABLE`                | 503       | should-be-live, origin warming up                   | yes               |
-| `UNAUTHORIZED` / `FORBIDDEN` | 401 / 403 | bad key / origin not allowed / DRM rejected         | no                |
-| `RATE_LIMITED`               | 429       | per-IP limiter                                      | back off          |
+| code                         | HTTP                | meaning                                                                                                                                       | retry?                                                     |
+| ---------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `INVALID_URN`                | 400                 | malformed URN                                                                                                                                 | no                                                         |
+| `NOT_FOUND`                  | 404                 | unknown URN **or** not entitled (indistinguishable)                                                                                           | no                                                         |
+| `GONE`                       | 410                 | ended past catchup window                                                                                                                     | no                                                         |
+| `TOO_EARLY`                  | 425                 | upcoming, not live yet                                                                                                                        | yes (waitForLive)                                          |
+| `UNAVAILABLE`                | 503                 | should-be-live, origin warming up                                                                                                             | yes                                                        |
+| `UNAUTHORIZED` / `FORBIDDEN` | 401 / 403           | bad key / origin not allowed / DRM rejected **server-side**                                                                                   | no                                                         |
+| `DRM_CLIENT`                 | 0 or license status | **client-side** DRM failure — key system unusable on this platform, CDM/EME error, or license transport exhausted (not an entitlement denial) | sometimes — the control bar offers retry (see docs/API.md) |
+| `RATE_LIMITED`               | 429                 | per-IP limiter                                                                                                                                | back off                                                   |
 
 ---
 
@@ -256,16 +257,29 @@ The key's `AllowedOrigins` must include `http://localhost:5173`.
   fast-follow.
 - **HLS only** (no DASH); **Widevine + FairPlay** key systems (no PlayReady — Edge
   uses Widevine). Container CMAF/fMP4, encryption cbcs.
-- hls.js is pinned to `1.7.0-beta.1` (the first version that plays this LL-HLS+DRM
-  content; 1.6.x has a fatal sourceBuffer bug). Pin to `1.7.0` stable when released.
+- hls.js is pinned exactly (see `package.json` for the current version).
+  LL-HLS+DRM playback is sensitive to hls.js regressions, so bumps are
+  deliberate and tested, never automatic.
+
+## Analytics (QoE beacons)
+
+Mode A emits anonymous QoE beacons (startup time, heartbeat byte/quality deltas,
+state changes, errors, session end) to the Havik analytics plane, correlated with
+CDN logs via a server-minted CMCD session id (`sid`). The `sid` lives **only in
+JS memory** — never in storage or cookies — and dies with the player. Opt out or
+redirect with the `analytics` option on `createPlayer`
+(`analytics: false | { endpoint?: string }`); without a server-minted `sid` the
+emitter is inert.
 
 ## Privacy
 
 The SDK persists a random per-device id in `localStorage` and sends it as
 `X-Device-Id` on every DRM license request (required by the license server). It is a
 stable cross-session identifier — disclose it in your privacy policy and offer a reset
-via [`clearDeviceId()`](docs/API.md#getdeviceid--cleardeviceid). No other personal
-data is collected by the SDK.
+via [`clearDeviceId()`](docs/API.md#getdeviceid--cleardeviceid). The QoE beacons
+above are anonymous (no IP is stored and the user agent is minimized on arrival;
+the in-memory `sid` is not a cross-session identifier). No other personal data is
+collected by the SDK.
 
 ## Browser & runtime support