@oddin-gg/havik-player 2.8.0 → 2.9.1

package/README.md

@@ -207,6 +207,29 @@ A ready-to-host template lives in the repo at [`embed/index.html`](embed/index.h
 > which is what havik-streams matches against; there is no `Origin` header on a
 > top-level iframe nav.
 
+The injected config also takes `analytics`, forwarded to the managed player.
+Set it when `baseUrl` is not a `feed` host, or QoE beacons stay off. See
+[Analytics](#analytics-qoe-beacons).
+
+```js
+window.HAVIK_EMBED_CONFIG = {
+  baseUrl: 'https://cdn.example.com',
+  matchUrn: 'od:match:1234',
+  apiKey: 'pk_test_…',
+  parentOrigin: 'https://your-site.example',
+  analytics: { endpoint: 'https://beacons.oddin-video.gg' },
+};
+```
+
+`analytics` is read from the injected config only. It names a telemetry sink,
+so the query string is not allowed to set one.
+
+That has a consequence worth knowing before you pick a Mode C path.
+`mountEmbed` passes its config to the embed page as query parameters, so it
+cannot carry `analytics` either. If your `baseUrl` is not a `feed` host and
+you need beacons, host the embed page yourself and inject the config. A
+`mountEmbed` integration on a non-feed base has no way to turn analytics on.
+
 ---
 
 ## Live pickup (`waitForLive`)
@@ -322,6 +345,44 @@ suspended (OS sleep, a frozen tab) for that long. The suspension gap never
 goes below five minutes, whatever `idleMs` is. The next `play()` reloads the
 stream as a fresh session.
 
+### If your `baseUrl` is not a `feed` host, set `analytics.endpoint`
+
+By default the beacons host is derived from `baseUrl` by hostname convention:
+`feed.<domain>` becomes `beacons.<domain>`, and `feed-dev.<domain>` becomes
+`beacons-dev.<domain>`. The rule is deliberately narrow. It maps only hosts
+whose first label is `feed` or `feed-*`. **Any other `baseUrl` derives nothing,
+and beacons are disabled.** This usually happens when your own CDN or gateway
+hostname fronts the streams API:
+
+```js
+// No beacons: 'cdn.example.com' is not a feed host, so there is
+// nothing to derive and no endpoint was given. Playback is unaffected.
+createPlayer({
+  video,
+  baseUrl: 'https://cdn.example.com',
+  matchUrn: 'od:match:1234',
+  credential: { apiKey: 'pk_test_…' },
+});
+
+// Beacons flow: name the host the derivation cannot guess.
+createPlayer({
+  video,
+  baseUrl: 'https://cdn.example.com',
+  matchUrn: 'od:match:1234',
+  credential: { apiKey: 'pk_test_…' },
+  analytics: { endpoint: 'https://beacons.oddin-video.gg' },
+});
+```
+
+Playback is unaffected, so nothing on screen changes. Only the analytics plane
+stays empty. The SDK therefore says so instead of failing quietly. It prints a
+`console.warn` naming the offending host, once per host per page. It also emits
+a non-fatal [`warning`](docs/API.md#player-events) event carrying the same
+sentence, so you can alert on it without watching a browser console.
+
+Ask Oddin for the beacons host that matches your deployment. A guessed host
+delivers nothing, just as quietly.
+
 ## Privacy
 
 The SDK persists a random per-device id in `localStorage` and sends it as