@dolby-optiview/ads-sdk-core 1.2.0 → 1.3.0

package/dist/types/BreakManifest.d.ts

@@ -1,4 +1,4 @@
-/** Break Manifest types, per https://github.com/Dolby-OptiView/optiview-ads-manifest-spec/blob/v1.4.0/spec.md. */
+/** Break Manifest types, per https://github.com/Dolby-OptiView/optiview-ads-manifest-spec/blob/v1.9.0/spec.md. */
 /** Which 'time' reference break start times use. @category Break Manifests & Ad Formats */
 export declare enum Timebase {
     /** An absolute ISO-8601 timestamp */
@@ -28,10 +28,26 @@ export interface GamSgaiConfiguration {
     customAssetKey: string;
     assetParameters?: Record<string, string>;
 }
+/**
+ * Server-side beaconing (SSB) stream the channel offers next to the DAI livestream (manifest spec
+ * 1.9.0 draft). While present, the SDK keeps the content player off AirPlay around ad breaks.
+ * @category Break Manifests & Ad Formats */
+export interface GamSsbConfiguration {
+    /** The SSB stream URL. */
+    uri: string;
+    /** The stream format, e.g. `hls`. */
+    format?: string;
+    /** Stream request parameters. */
+    assetParameters?: Record<string, string>;
+    /** DRM configuration, passed through untouched. */
+    drm?: Record<string, unknown>;
+}
 /** Session-level GAM configuration for full-service DAI SSAI. @category Break Manifests & Ad Formats */
 export interface GamSsaiConfiguration {
     assetKey: string;
     assetParameters?: Record<string, string>;
+    /** The channel's server-side beaconing stream, when it has one. */
+    ssb?: GamSsbConfiguration;
 }
 /**
  * The GAM identity needed to create the IMA/DAI stream session. Must agree with the per-asset
@@ -74,7 +90,7 @@ export interface BreakManifest {
     /** Identifier of the channel the stream belongs to. */
     channelId?: string;
     /** Identifier of the event being streamed. */
-    eventId?: string;
+    eventId?: string | null;
     /** Determines how often the manifest should be refreshed */
     polling?: Polling;
     /** Ordered delivery-steering rules (first match wins), evaluated once on the first fetch; absent means sgai. */
@@ -83,9 +99,20 @@ export interface BreakManifest {
     adStartDelay?: number;
     /** Session-level configuration per vendor integration (spec 1.1.0). */
     vendorConfiguration?: VendorConfiguration[];
+    /** Event-specific configuration windows on a wallclock live stream. */
+    events?: ChannelEvent[];
     /** The available breaks */
     breaks: Break[];
 }
+/** An event window and the session configuration in effect while it runs. */
+export interface ChannelEvent {
+    id: string;
+    start: string;
+    end: string;
+    adStartDelay?: number;
+    delivery?: DeliveryRule[];
+    vendorConfiguration?: VendorConfiguration[];
+}
 /** Delivery architecture selected by a {@link DeliveryRule}. @category Break Manifests & Ad Formats */
 export declare enum DeliveryMode {
     /** Server-Guided Ad Insertion — the SDK schedules and renders breaks client-side. */
@@ -324,6 +351,11 @@ export interface StaticAsset extends BaseAsset {
     type: AssetType.STATIC;
     /** The resource URL or array of URLs with targeting */
     uri: string | AssetUri[];
+    /**
+     * Query parameters the player appends to the resource URL (for HLS or DASH, only the
+     * master playlist or MPD request). Values may be `$NAME$` macros.
+     */
+    assetParameters?: Record<string, string>;
 }
 /** VAST asset, played by Google IMA as CSAI. SGAI only, linear formats only (single, double, lshape_ad). @category Break Manifests & Ad Formats */
 export interface VastAsset extends BaseAsset {

package/dist/types/Events.d.ts

@@ -1,5 +1,5 @@
 import { Break, Asset, BreakFormat } from './BreakManifest';
-import type { OptiViewAdsMode } from './OptiViewAdsConfig';
+import type { SessionDeliveryMode } from './OptiViewAdsConfig';
 /**
  * Lifecycle phase reported by {@link AdBreakStatus}.
  * - `idle`: no break is upcoming or active.
@@ -8,7 +8,7 @@ import type { OptiViewAdsMode } from './OptiViewAdsConfig';
  * @category Events */
 export type AdBreakPhase = 'idle' | 'upcoming' | 'active' | 'complete';
 /** Why a scheduled ad break was refused before it began (`adbreakskipped` event). @category Events */
-export type AdBreakSkipReason = 'late' | 'not-ready' | 'preparation-failed' | 'unsupported' | 'overlap' | 'start-delay' | 'removed' | 'insufficient-remaining' | 'resource-limit';
+export type AdBreakSkipReason = 'late' | 'not-ready' | 'preparation-failed' | 'unsupported' | 'overlap' | 'start-delay' | 'removed' | 'insufficient-remaining' | 'resource-limit' | 'played-by-ssb';
 export interface AdBreakSkippedEvent extends OptiViewAdsEvent {
     type: 'adbreakskipped';
     break: Break;
@@ -37,6 +37,14 @@ export interface AdBreakStatus {
     ticking: boolean;
     /** The configured warning second that was crossed, when a pre-break warning triggered this status. */
     warningSec?: number | undefined;
+    /**
+     * Whether the content player may start AirPlay right now: `false` during a break and in the
+     * seconds before one. Present only when the SDK manages the AirPlay gate (the manifest carries a
+     * server-side beaconing stream and the adapter can gate external playback).
+     */
+    externalPlaybackAllowed?: boolean | undefined;
+    /** Delivery mode of the active session; `ssb` while AirPlay plays the server-side beaconing stream. Absent between sessions. */
+    deliveryMode?: SessionDeliveryMode | undefined;
 }
 /** Event types emitted by the OptiViewAds SDK. @category Events */
 export type OptiViewAdsEventType = 'adbreakbegin' | 'adbreakend' | 'adbreakskipped' | 'adbegin' | 'adend' | 'aderror' | 'adfirstquartile' | 'admidpoint' | 'adthirdquartile' | 'adtimeupdate' | 'adbreakstatus' | 'adclick' | 'waiting' | 'playing' | 'volumechange' | 'adchannelchange' | 'externalvendorconfigurationchange';
@@ -209,13 +217,13 @@ export interface AdClickEvent extends OptiViewAdsEvent {
     asset: Asset;
     clickThrough?: string | undefined;
 }
-/** Why the SDK rebuilt its ad setup from a polled manifest; see {@link AdChannelChangeEvent}. @category Events */
-export type AdChannelChangeReason = 'channel-id-changed' | 'channel-id-added' | 'channel-id-removed' | 'vendor-configuration-changed' | 'timebase-changed';
+/** Why the SDK re-aligned ad configuration after a polled channel or event change; see {@link AdChannelChangeEvent}. @category Events */
+export type AdChannelChangeReason = 'channel-id-changed' | 'channel-id-added' | 'channel-id-removed' | 'vendor-configuration-changed' | 'timebase-changed' | 'event-boundary' | 'external-playback';
 /**
- * Emitted when a polled manifest describes a different ads channel than the one the session
- * was started on. During an active break, the event is emitted after that break finishes and
- * the latest polled manifest is applied. Before playback starts, the new manifest's
- * `adStartDelay` applies; after playback starts, the delay in effect is unchanged.
+ * Emitted when a polled manifest changes the ads channel or playback crosses a channel-event
+ * boundary. Event-boundary changes use reason `event-boundary` and identify the active event
+ * with `eventId` (or `null` when no event is active). During an active break, the event is
+ * emitted after that break finishes and the latest manifest is applied.
  * @category Events */
 export interface AdChannelChangeEvent extends OptiViewAdsEvent {
     type: 'adchannelchange';
@@ -223,13 +231,15 @@ export interface AdChannelChangeEvent extends OptiViewAdsEvent {
     previousChannelId: string | null;
     /** `channelId` of the manifest the session is aligned to now; `null` when it has none. */
     channelId: string | null;
+    /** Event id in effect after the boundary, or null when no event is active. */
+    eventId: string | null;
     reason: AdChannelChangeReason;
     /** The polled manifest URL (unchanged by the switch). */
     manifestUrl: string;
     /** Delivery mode in effect before the switch. */
-    previousDeliveryMode: OptiViewAdsMode;
+    previousDeliveryMode: SessionDeliveryMode;
     /** Delivery mode in effect after the switch. */
-    deliveryMode: OptiViewAdsMode;
+    deliveryMode: SessionDeliveryMode;
 }
 /** An external provider's manifest parameter template was added, changed, or removed. @category Events */
 export interface ExternalVendorConfigurationChangeEvent extends OptiViewAdsEvent {

package/dist/types/OptiViewAdsConfig.d.ts

@@ -112,8 +112,8 @@ export type AdInsertionType = 'replacement' | 'insertion';
 /** Initial live-playback distance from the reported edge. @category Configuration */
 export interface LiveStartPushbackConfig {
     /**
-     * Apply once per session/channel. When omitted, it follows `ptsSource`: on for `'anvatoCue'`,
-     * off for `'mediaTime'`. An explicit value always wins.
+     * Apply once per session/channel. Off unless set to `true`, for every `ptsSource`.
+     * @default false
      */
     enabled?: boolean;
     /** Minimum total distance in target durations, not an additional rewind. @default 5 */
@@ -127,6 +127,8 @@ export interface LiveStartPushbackConfig {
  *   stream, loads the stitched master, forwards timed metadata to IMA and re-emits ad events.
  * @category Configuration */
 export type OptiViewAdsMode = 'sgai' | 'ssai';
+/** The delivery mode a session runs in: `ssb` while AirPlay plays the channel's server-side beaconing stream. @category SDK & Sessions */
+export type SessionDeliveryMode = OptiViewAdsMode | 'ssb';
 /** How a PTS-timebase break's `start` value is resolved. @category Configuration */
 export type PtsSource = 'mediaTime' | 'anvatoCue';
 /** Default ad insertion architecture. */
@@ -245,6 +247,14 @@ export interface DiagnosticsConfig {
      */
     bufferSize?: number;
 }
+/** AirPlay guard settings. @category Configuration */
+export interface ExternalPlaybackConfig {
+    /**
+     * Seconds before a scheduled break during which AirPlay may not start; `0` blocks only during a break.
+     * @default 5
+     */
+    blockBeforeBreakSec?: number;
+}
 /** SDK instance configuration, fixed for its lifetime (org-level). @category Configuration */
 export interface OptiViewAdsConfig {
     /**
@@ -348,7 +358,12 @@ export interface OptiViewAdsConfig {
      */
     continueContentDuringBreak?: boolean;
     /**
-     * Live startup adjustment, on by default with `ptsSource: 'anvatoCue'`; does not change later
+     * AirPlay (external playback) guard, active only when the manifest carries a server-side
+     * beaconing (`ssb`) stream and the content adapter can gate external playback.
+     */
+    externalPlayback?: ExternalPlaybackConfig;
+    /**
+     * Live startup adjustment, off unless `liveStartPushback.enabled` is `true`; does not change later
      * break-resume policy.
      */
     liveStartPushback?: LiveStartPushbackConfig;
@@ -418,11 +433,12 @@ export interface SessionConfig {
      * manifest / session / update value is replaced when the ad request is built,
      * so `"$OPTIVIEW_PLAYER_WIDTH$x$OPTIVIEW_PLAYER_HEIGHT$"` becomes `"1920x1080"`.
      * Customer macros are consulted before the built-in `$OPTIVIEW_*` set, so a built-in can be
-     * overridden. A string replaces the token. `null` omits the parameter; for GAM `cust_params`,
-     * only the containing pair is dropped and the key is omitted if no pair remains. For VAST,
-     * the whole `cust_params` parameter is omitted. `undefined` leaves an unresolved token literal
-     * and sends the parameter. `DA-ASSET-MACRO-UNKNOWN` reports
-     * unresolved built-in or registered macros; `DA-ASSET-PARAMETER-OMITTED` reports null omissions.
+     * overridden. A string replaces the token. `""`, `null`, or a registered callback's `undefined`
+     * result omits the parameter, or only the containing pair when its value has a literal `&`;
+     * `DA-ASSET-PARAMETER-OMITTED` reports the omission. An `undefined` map entry is not registered.
+     * `updateAssetParameterMacros` uses `undefined` to unregister a name. A throwing callback warns
+     * and is unresolved, falling back to a built-in when one exists. `DA-ASSET-MACRO-UNKNOWN` reports
+     * unresolved built-in or registered macros.
      * Other unresolved `$NAME$` tokens stay literal without a diagnostic. `$` without a closing `$`
      * is unchanged.
      * Callbacks are evaluated per ad request and cleared when the session ends.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dolby-optiview/ads-sdk-core",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "OptiView Ads SDK Core - Player-agnostic ad insertion",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,6 +17,10 @@
       "types": "./dist/id3/index.d.ts",
       "default": "./dist/id3/index.js"
     },
+    "./external-playback": {
+      "types": "./dist/external-playback/index.d.ts",
+      "default": "./dist/external-playback/index.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "default": "./dist/server/index.js"