@oddin-gg/havik-player 2.7.0 → 2.9.0

package/README.md

@@ -61,7 +61,7 @@ import { createPlayer } from '@oddin-gg/havik-player';
 
 const player = await createPlayer({
   video: document.querySelector('video')!,
-  baseUrl: 'https://feed-dev.oddin-video.gg',
+  env: 'integration', // or 'production'
   matchUrn: 'od:match:1234',
   credential: { apiKey: 'pk_test_…' },
   autoplay: true,
@@ -81,6 +81,39 @@ player.destroy();
 The managed player handles `425 TOO_EARLY` retries (honoring `Retry-After`),
 buffering recovery, and silent DRM **license-URL refresh** for long sessions.
 
+### Choosing an environment
+
+`env` names the stack: `integration` is the shared pre-production environment,
+`production` is the production one. They are separate deployments, not
+aliases. Prefer `env` over a hand-written `baseUrl`. The API host is then
+correct by construction, and so is every host derived from it, including the
+QoE beacons endpoint.
+
+Pass `baseUrl` instead when the named environments do not cover your
+deployment:
+
+- your own CDN or gateway in front of the streams API
+- the CN plane, whose host is not under this domain
+- a pinned build that has to outlive a domain change
+
+`baseUrl` is not deprecated and is not going away. Pass exactly one of the
+two. In TypeScript, passing both or neither is a compile error. In JavaScript
+it throws at `createPlayer`, because the two disagreeing is the
+misconfiguration worth refusing.
+
+Modes B and C still take a `baseUrl`. Use `baseUrlForEnv` there rather than
+copying a hostname into your own config:
+
+```ts
+import { baseUrlForEnv, resolveStream } from '@oddin-gg/havik-player';
+
+const stream = await resolveStream({
+  baseUrl: baseUrlForEnv('production'),
+  matchUrn: 'od:match:1234',
+  credential: { apiKey: 'pk_live_…' },
+});
+```
+
 ### Controls & skinning
 
 By default, Mode A renders a **branded, fully skinnable control bar**. It covers
@@ -174,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`)