@oddin-gg/havik-player 2.8.0 → 2.9.1

package/dist/index.d.cts

@@ -275,6 +275,11 @@ export declare interface CreatePlayerOptions {
      * `beacons[-dev].…`). Pass `false` to opt out entirely, or
      * `{ endpoint }` to point at a non-conventional beacons host.
      *
+     * If {@link baseUrl} is NOT a `feed[-dev].<domain>` host — a CDN or gateway
+     * fronting the streams API, say — nothing can be derived and beacons are
+     * disabled. That is reported, not silent: a `console.warn` naming the host
+     * (once per host) plus a non-fatal `warning` event. Supply `{ endpoint }`.
+     *
      * Privacy: the sid is an opaque per-session id, held in memory only and
      * never persisted. Beacons carry playback QoE numbers plus the session's
      * environment (form factor, device model and OS version where the browser
@@ -373,6 +378,23 @@ export declare interface EmbedConfig {
     autoplay?: boolean;
     muted?: boolean;
     waitForLive?: WaitForLive;
+    /**
+     * QoE beacons, forwarded verbatim to {@link createPlayer}. Same meaning as
+     * there: `false` opts out, `{ endpoint }` names a beacons host.
+     *
+     * Mode C needs this for the same reason Mode A does, and until now had no
+     * way to say it. An embed whose `baseUrl` is not a `feed[-dev].<domain>`
+     * host — a CDN or gateway fronting the streams API — derives no beacons
+     * endpoint, so analytics is off and stays off. Without this option the
+     * only remedy was to move `baseUrl` back onto a feed host, which is not a
+     * choice an integrator who fronts the API deliberately can make.
+     *
+     * INJECTED CONFIG ONLY: unlike every other field here, this is not read
+     * from the query string. See {@link readConfig}.
+     */
+    analytics?: boolean | {
+        endpoint?: string;
+    };
 }
 
 export declare interface EmbedHandle {
@@ -673,6 +695,18 @@ export declare interface MountEmbedOptions {
     container: HTMLElement;
     /** URL of the hosted embed page, e.g. `https://player-dev.oddin-video.gg/embed/`. */
     src: string;
+    /**
+     * API base URL, forwarded to the embed page as a query parameter.
+     *
+     * ⚠️ QoE beacons: the beacons endpoint is derived from this host by
+     * convention (`feed[-dev].<domain>` → `beacons[-dev].<domain>`). If your
+     * base is NOT a feed host, nothing derives and analytics is off — and
+     * `mountEmbed` CANNOT fix it, because the only way to name an endpoint is
+     * {@link EmbedConfig.analytics}, which the embed page reads from injected
+     * config and deliberately never from the query string (a link must not be
+     * able to redirect a session's telemetry). Host the embed page yourself
+     * and inject `window.HAVIK_EMBED_CONFIG` with `analytics: { endpoint }`.
+     */
     baseUrl: string;
     matchUrn: string;
     /**

package/dist/index.d.ts

@@ -275,6 +275,11 @@ export declare interface CreatePlayerOptions {
      * `beacons[-dev].…`). Pass `false` to opt out entirely, or
      * `{ endpoint }` to point at a non-conventional beacons host.
      *
+     * If {@link baseUrl} is NOT a `feed[-dev].<domain>` host — a CDN or gateway
+     * fronting the streams API, say — nothing can be derived and beacons are
+     * disabled. That is reported, not silent: a `console.warn` naming the host
+     * (once per host) plus a non-fatal `warning` event. Supply `{ endpoint }`.
+     *
      * Privacy: the sid is an opaque per-session id, held in memory only and
      * never persisted. Beacons carry playback QoE numbers plus the session's
      * environment (form factor, device model and OS version where the browser
@@ -373,6 +378,23 @@ export declare interface EmbedConfig {
     autoplay?: boolean;
     muted?: boolean;
     waitForLive?: WaitForLive;
+    /**
+     * QoE beacons, forwarded verbatim to {@link createPlayer}. Same meaning as
+     * there: `false` opts out, `{ endpoint }` names a beacons host.
+     *
+     * Mode C needs this for the same reason Mode A does, and until now had no
+     * way to say it. An embed whose `baseUrl` is not a `feed[-dev].<domain>`
+     * host — a CDN or gateway fronting the streams API — derives no beacons
+     * endpoint, so analytics is off and stays off. Without this option the
+     * only remedy was to move `baseUrl` back onto a feed host, which is not a
+     * choice an integrator who fronts the API deliberately can make.
+     *
+     * INJECTED CONFIG ONLY: unlike every other field here, this is not read
+     * from the query string. See {@link readConfig}.
+     */
+    analytics?: boolean | {
+        endpoint?: string;
+    };
 }
 
 export declare interface EmbedHandle {
@@ -673,6 +695,18 @@ export declare interface MountEmbedOptions {
     container: HTMLElement;
     /** URL of the hosted embed page, e.g. `https://player-dev.oddin-video.gg/embed/`. */
     src: string;
+    /**
+     * API base URL, forwarded to the embed page as a query parameter.
+     *
+     * ⚠️ QoE beacons: the beacons endpoint is derived from this host by
+     * convention (`feed[-dev].<domain>` → `beacons[-dev].<domain>`). If your
+     * base is NOT a feed host, nothing derives and analytics is off — and
+     * `mountEmbed` CANNOT fix it, because the only way to name an endpoint is
+     * {@link EmbedConfig.analytics}, which the embed page reads from injected
+     * config and deliberately never from the query string (a link must not be
+     * able to redirect a session's telemetry). Host the embed page yourself
+     * and inject `window.HAVIK_EMBED_CONFIG` with `analytics: { endpoint }`.
+     */
     baseUrl: string;
     matchUrn: string;
     /**