@oddin-gg/havik-player 2.11.1 → 2.12.0

package/dist/index.d.cts

@@ -142,8 +142,10 @@ export declare interface CreatePlayerOptions {
      * fronting the streams API, the CN plane, or a pinned build that must
      * outlive a domain change.
      *
-     * Note that a base which is not a `feed[-dev].<domain>` host derives no QoE
-     * beacons endpoint, so pair it with `analytics: { endpoint }`.
+     * QoE beacons: havik-streams v0.10.0+ names the beacons host itself, so any
+     * base works. Against an older server, a base which is not a
+     * `feed[-dev].<domain>` host derives no beacons endpoint, so pair it with
+     * `analytics: { endpoint }`.
      */
     baseUrl?: string;
     matchUrn: string;
@@ -308,13 +310,17 @@ export declare interface CreatePlayerOptions {
     /**
      * QoE beacons + CMCD session attribution. Active only when the playback
      * response carries an analytics sid (the server-side flag) — without one
-     * this option does nothing. Default: true, with the beacons endpoint
-     * derived from {@link baseUrl} by hostname convention (`feed[-dev].…` →
-     * `beacons[-dev].…`). Pass `false` to opt out entirely, or
-     * `{ endpoint }` to point at a non-conventional beacons host.
+     * this option does nothing. Default: true. Pass `false` to opt out entirely.
      *
-     * 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
+     * Where beacons go: havik-streams v0.10.0+ names the beacons host in the
+     * playback response, and that host is used whatever {@link baseUrl} is —
+     * including a CDN or gateway fronting the streams API. It also wins over
+     * `{ endpoint }` (a differing value is ignored with one `console.warn`).
+     *
+     * Against an older server that names none, the endpoint is `{ endpoint }`
+     * if given, else derived from {@link baseUrl} by hostname convention
+     * (`feed[-dev].…` → `beacons[-dev].…`). If {@link baseUrl} is NOT a
+     * `feed[-dev].<domain>` host, 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 }`.
      *
@@ -421,9 +427,11 @@ export declare interface EmbedConfig {
      * 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
+     * way to say it. Against a server that does not name the beacons host
+     * (havik-streams before v0.10.0), 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. A server
+     * that names it needs no option here. 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.
      *
@@ -763,10 +771,12 @@ export declare interface MountEmbedOptions {
     /**
      * 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
+     * ⚠️ QoE beacons: havik-streams v0.10.0+ names the beacons host in the
+     * playback response, so any base works. Against an older server the
+     * endpoint is derived from this host by convention (`feed[-dev].<domain>` →
+     * `beacons[-dev].<domain>`). There, if your base is NOT a feed host,
+     * nothing derives and analytics is off — and `mountEmbed` CANNOT fix it,
+     * because the only client-side 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
@@ -1061,9 +1071,17 @@ export declare interface StreamDescriptor {
      * id — non-secret by design (DRM remains the access gate) — echoed in CMCD
      * query params on CDN requests and carried by QoE beacons. It lives only in
      * memory for the duration of the session and is never persisted.
+     *
+     * `endpoint` is the QoE beacons origin the server names for this session
+     * (e.g. `https://beacons.oddin-video.gg`; beacons POST to
+     * `<endpoint>/v1/beacons`). Present only alongside a sid, and only from a
+     * server new enough to send it; the SDK keeps it only when it is a bare
+     * https origin. It takes precedence over the `analytics.endpoint` option and
+     * over deriving a host from `baseUrl`.
      */
     analytics?: {
         sid?: string;
+        endpoint?: string;
     };
     /** Any unrecognized top-level fields from the playback response (forward-compat). */
     extensions?: Record<string, unknown>;

package/dist/index.d.ts

@@ -142,8 +142,10 @@ export declare interface CreatePlayerOptions {
      * fronting the streams API, the CN plane, or a pinned build that must
      * outlive a domain change.
      *
-     * Note that a base which is not a `feed[-dev].<domain>` host derives no QoE
-     * beacons endpoint, so pair it with `analytics: { endpoint }`.
+     * QoE beacons: havik-streams v0.10.0+ names the beacons host itself, so any
+     * base works. Against an older server, a base which is not a
+     * `feed[-dev].<domain>` host derives no beacons endpoint, so pair it with
+     * `analytics: { endpoint }`.
      */
     baseUrl?: string;
     matchUrn: string;
@@ -308,13 +310,17 @@ export declare interface CreatePlayerOptions {
     /**
      * QoE beacons + CMCD session attribution. Active only when the playback
      * response carries an analytics sid (the server-side flag) — without one
-     * this option does nothing. Default: true, with the beacons endpoint
-     * derived from {@link baseUrl} by hostname convention (`feed[-dev].…` →
-     * `beacons[-dev].…`). Pass `false` to opt out entirely, or
-     * `{ endpoint }` to point at a non-conventional beacons host.
+     * this option does nothing. Default: true. Pass `false` to opt out entirely.
      *
-     * 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
+     * Where beacons go: havik-streams v0.10.0+ names the beacons host in the
+     * playback response, and that host is used whatever {@link baseUrl} is —
+     * including a CDN or gateway fronting the streams API. It also wins over
+     * `{ endpoint }` (a differing value is ignored with one `console.warn`).
+     *
+     * Against an older server that names none, the endpoint is `{ endpoint }`
+     * if given, else derived from {@link baseUrl} by hostname convention
+     * (`feed[-dev].…` → `beacons[-dev].…`). If {@link baseUrl} is NOT a
+     * `feed[-dev].<domain>` host, 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 }`.
      *
@@ -421,9 +427,11 @@ export declare interface EmbedConfig {
      * 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
+     * way to say it. Against a server that does not name the beacons host
+     * (havik-streams before v0.10.0), 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. A server
+     * that names it needs no option here. 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.
      *
@@ -763,10 +771,12 @@ export declare interface MountEmbedOptions {
     /**
      * 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
+     * ⚠️ QoE beacons: havik-streams v0.10.0+ names the beacons host in the
+     * playback response, so any base works. Against an older server the
+     * endpoint is derived from this host by convention (`feed[-dev].<domain>` →
+     * `beacons[-dev].<domain>`). There, if your base is NOT a feed host,
+     * nothing derives and analytics is off — and `mountEmbed` CANNOT fix it,
+     * because the only client-side 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
@@ -1061,9 +1071,17 @@ export declare interface StreamDescriptor {
      * id — non-secret by design (DRM remains the access gate) — echoed in CMCD
      * query params on CDN requests and carried by QoE beacons. It lives only in
      * memory for the duration of the session and is never persisted.
+     *
+     * `endpoint` is the QoE beacons origin the server names for this session
+     * (e.g. `https://beacons.oddin-video.gg`; beacons POST to
+     * `<endpoint>/v1/beacons`). Present only alongside a sid, and only from a
+     * server new enough to send it; the SDK keeps it only when it is a bare
+     * https origin. It takes precedence over the `analytics.endpoint` option and
+     * over deriving a host from `baseUrl`.
      */
     analytics?: {
         sid?: string;
+        endpoint?: string;
     };
     /** Any unrecognized top-level fields from the playback response (forward-compat). */
     extensions?: Record<string, unknown>;