@dolby-optiview/ads-sdk-core 1.2.1 → 1.4.0

package/dist/session/SsbSwitch.d.ts

@@ -0,0 +1,55 @@
+import type { ExternalPlaybackAllowedTrigger } from '../services/ExternalPlaybackGate';
+import type { BreakManifest } from '../types/BreakManifest';
+import type { SessionConfig } from '../types/OptiViewAdsConfig';
+import type { SessionStarterDeps } from './SessionStarterDeps';
+import type { SessionState } from './SessionState';
+/** How long the receiver gets to take the stream once it is ready to play. */
+export declare const SSB_ACTIVE_TIMEOUT_MS = 1500;
+/** Cap on loading the SSB stream (a cold DAI session needs a couple of seconds). */
+export declare const SSB_LOAD_TIMEOUT_MS = 15000;
+export declare const SSB_RECEIVER_PAUSE_WINDOW_MS = 3000;
+export declare const SSB_RESTORE_PLAYING_BACKSTOP_MS = 10000;
+export declare const SSB_RESTORE_ATTEMPTS = 2;
+/** The session re-entry points the restore reuses from the channel-switch code. */
+export interface SsbSessionStarter {
+    switchToSgai(manifest: BreakManifest, config: SessionConfig, generation: number, preserveSchedulerLedgers: boolean): Promise<void>;
+    switchToSteeredSsai(manifest: BreakManifest, config: SessionConfig, preserveSchedulerLedgers: boolean): Promise<boolean>;
+    applyPendingChannelSwitch(): void;
+}
+type SwitchTrigger = ExternalPlaybackAllowedTrigger;
+/**
+ * Plays the channel's SSB stream on the AirPlay receiver and brings the original content back
+ * when AirPlay ends: switch behind the closed gate, open it, verify the receiver took the
+ * stream, restore the previous source and delivery mode afterwards.
+ */
+export declare class SsbSwitchController {
+    private readonly state;
+    private readonly starter;
+    private readonly deps;
+    private timers;
+    private runtimeParams;
+    private sessionMacros;
+    private previousPaused;
+    private streamReady;
+    constructor(state: SessionState, starter: SsbSessionStarter, deps: SessionStarterDeps);
+    /** True from the switch until the restore completes; the session's other content handlers stand down. */
+    get isActive(): boolean;
+    /** The `ExternalPlaybackGate` allowed hook. */
+    onAllowed: (trigger: SwitchTrigger) => void;
+    dispose(): void;
+    /** The session ended: forget the switch without touching the player. */
+    reset(): void;
+    private readonly onExternalPlaybackChange;
+    private readonly onPause;
+    private markActive;
+    private fail;
+    private restoreFromSsb;
+    private restoreSgai;
+    private reloadPrevious;
+    private waitForPlaying;
+    private rollSession;
+    private emitChange;
+    private later;
+    private clearTimers;
+}
+export {};

package/dist/session/SsbSwitch.js

@@ -0,0 +1 @@
+import{buildAssetParameterMacroTable as e}from"../services/assetParameterMacroTable";import{resolveSsbStream as s}from"../services/resolveGamVendorConfiguration";import{resolveSsbRestoreChange as t}from"../services/ssbSwitchSignals";import{buildSsbStreamUrl as i,resolveSsbRestorePosition as r}from"../services/ssbStream";export const SSB_ACTIVE_TIMEOUT_MS=1500;export const SSB_LOAD_TIMEOUT_MS=15e3;export const SSB_RECEIVER_PAUSE_WINDOW_MS=3e3;export const SSB_RESTORE_PLAYING_BACKSTOP_MS=1e4;export const SSB_RESTORE_ATTEMPTS=2;export class SsbSwitchController{constructor(t,r,a){this.state=t,this.starter=r,this.deps=a,this.timers=new Set,this.previousPaused=!1,this.streamReady=!1,this.onAllowed=t=>{const{state:r}=this,{player:a}=this.deps,o=r.effectiveSessionManifest??r.sessionManifest,n=o?s(o.vendorConfiguration):null,l=r.sessionConfig;if(!r.sessionActive||r.ssb||!o||!n||!l)return;const c=a.sourceUrl;if("string"!=typeof c||""===c.trim())return void this.deps.diagnose("DA-SSB-SWITCH-FAILED","The content adapter reports no source to restore; AirPlay stays on the device.",{reason:"no-restore-source",trigger:t});const h=this.deps.adPlayerController;this.runtimeParams=h?.updatedAssetParameters,this.sessionMacros=h?.sessionAssetParameterMacros,this.previousPaused=a.paused;const d=r.sessionDeliveryMode??"sgai";r.ssb={previousMode:d,previousSource:c,previousPosition:a.currentTime,previousLive:a.isLive??!Number.isFinite(a.duration),switchedAt:Date.now(),trigger:t,phase:"switching",activeAt:null,announced:!1},h?.stopActiveBreak(),h?.releaseContentHold(),h?.endGamSession(),r.steeredSsaiActive&&(r.ssaiController?.stop(),delete r.ssaiController,r.steeredSsaiActive=!1),this.deps.breakScheduler?.suspend(),this.deps.pauseAdController?.reset(),r.sessionDeliveryMode="ssb",this.deps.diagnose("DA-DELIVERY-MODE-RESOLVED","AirPlay started: playing the SSB stream",{mode:"ssb",source:"external-playback",previousMode:d,trigger:t}),this.rollSession(o);const p=i(n,{manifest:n.assetParameters,session:l.assetParameters,runtime:this.runtimeParams},e({customerMacros:h?.sessionAssetParameterMacros??{},element:null,breakDurationSec:void 0})),u=r.ssb;this.streamReady=!1;const m=()=>r.ssb===u&&"switching"===u.phase,S=()=>{this.streamReady=!0,m()&&("active"!==a.externalPlaybackState?this.later(()=>{m()&&("active"===a.externalPlaybackState?this.markActive(u):this.fail("external-not-active",t,p))},1500):this.markActive(u))};a.load(p).then(()=>(S(),this.previousPaused||r.ssb!==u||"restoring"===u.phase?void 0:a.play())).catch(e=>this.fail("load-error",t,p,e)),a.setExternalPlaybackAllowed?.(!0),this.later(()=>{m()&&!this.streamReady&&this.fail("load-timeout",t,p)},15e3)},this.onExternalPlaybackChange=e=>{const{state:s}=this,t=s.ssb,i=e;t&&("active"===i?.state&&"switching"===t.phase&&this.streamReady?this.markActive(t):"inactive"===i?.state&&"restoring"!==t.phase&&this.restoreFromSsb("external-playback-ended"))},this.onPause=()=>{const e=this.state.ssb;"active"===e?.phase&&null!==e.activeAt&&Date.now()-e.activeAt<=3e3&&this.fail("receiver-paused",e.trigger)},a.player.on("externalplaybackchange",this.onExternalPlaybackChange),a.player.on("pause",this.onPause)}get isActive(){return null!==this.state.ssb}dispose(){this.clearTimers(),this.state.ssb=null,this.deps.player.off("externalplaybackchange",this.onExternalPlaybackChange),this.deps.player.off("pause",this.onPause)}reset(){this.clearTimers(),this.streamReady=!1,this.state.ssb=null}markActive(e){this.clearTimers(),e.phase="active",e.activeAt=Date.now(),this.later(()=>{this.state.ssb===e&&"active"===e.phase&&(e.announced=!0,this.emitChange(e.previousMode,"ssb"),this.deps.adBreakStatusTracker.refreshDeliveryMode())},3e3)}fail(e,s,t,i){this.state.ssb&&"restoring"!==this.state.ssb.phase&&(this.deps.diagnose("DA-SSB-SWITCH-FAILED",`The SSB stream switch failed: ${e}`,{reason:e,uri:t,trigger:s,...void 0===i?{}:{message:i instanceof Error?i.message:String(i)}}),this.restoreFromSsb("switch-failed"))}async restoreFromSsb(e){const{state:s}=this,{player:i}=this.deps,r=s.ssb,a=s.effectiveSessionManifest??s.sessionManifest,o=s.sessionConfig,{starter:n}=this;if(!(r&&"restoring"!==r.phase&&a&&o&&n))return;r.phase="restoring",this.clearTimers(),i.setExternalPlaybackAllowed?.(!1);const l=s.sessionGeneration,c=this.deps.breakScheduler;c?.setContentReloading(!0);let h=!1;if("ssai"===r.previousMode&&(h=await n.switchToSteeredSsai(a,o,!0)),h||(h=await this.restoreSgai(r,a,o,n,l)),s.ssb!==r)return;if(!h)return r.phase="failed",void c?.setContentReloading(!1);if(await this.waitForPlaying(),s.ssb!==r)return;c?.setContentReloading(!1),c?.skipPendingBreaksDueBy("played-by-ssb"),c?.resume();const d="ssai"===r.previousMode&&s.steeredSsaiActive?"ssai":"sgai";s.sessionDeliveryMode=d,s.ssb=null,this.deps.diagnose("DA-DELIVERY-MODE-RESOLVED","AirPlay ended: content restored",{mode:d,source:"external-playback-ended",cause:e}),this.rollSession(a);const p=t(r.announced,d);p&&this.emitChange(p.previousDeliveryMode,p.deliveryMode),this.deps.adBreakStatusTracker.refreshDeliveryMode(),n.applyPendingChannelSwitch()}async restoreSgai(e,s,t,i,a){const{player:o}=this.deps,{state:n}=this;if(!await this.reloadPrevious(e.previousSource))return!1;if(n.ssb!==e)return!0;const l=Number.isFinite(o.duration)?o.duration:null,c=r({live:e.previousLive,recordedPosition:e.previousPosition,duration:l});null!==c&&o.seek(c),this.previousPaused||await o.play().catch(()=>{}),await i.switchToSgai(s,t,a,!0);const h=this.deps.adPlayerController;return this.sessionMacros&&h?.setSessionAssetParameterMacros(this.sessionMacros),this.runtimeParams&&h?.updateAssetParameters(this.runtimeParams),!0}async reloadPrevious(e){let s;for(let t=1;t<=2;t++)try{return await this.deps.player.load(e),!0}catch(e){s=e}return this.deps.diagnose("DA-SSB-RESTORE-FAILED","The previous content source could not be reloaded.",{attempt:2,reason:"load-error",source:e,message:s instanceof Error?s.message:String(s)}),!1}waitForPlaying(){return new Promise(e=>{const s=()=>{this.deps.player.off("playing",s),e()};this.deps.player.on("playing",s),this.later(s,1e4)})}rollSession(e){this.deps.cmcdAdReporter.onSessionEnd(),this.deps.cmcdAdReporter.onSessionStart(e),this.deps.lensReporter.endSession(),this.deps.lensReporter.startSession()}emitChange(e,s){const{state:t}=this,i=t.effectiveSessionManifest??t.sessionManifest,r=i?.channelId??null;this.deps.emit("adchannelchange",{type:"adchannelchange",timestamp:Date.now(),previousChannelId:r,channelId:r,eventId:t.activeEventId,reason:"external-playback",manifestUrl:t.sessionConfig?.manifestUrl??"",previousDeliveryMode:e,deliveryMode:s})}later(e,s){const t=setTimeout(()=>{this.timers.delete(t),e()},s);this.timers.add(t)}clearTimers(){for(const e of this.timers)clearTimeout(e);this.timers.clear()}}

package/dist/session/breakMeasurement.d.ts

@@ -0,0 +1,16 @@
+import { BreakTransitionTimer } from '../services/BreakTransitionTimer';
+import { BreakChainRecorder } from '../services/BreakChainRecorder';
+import type { KnownDiagnosticCode } from '../diagnostics/errorCodes';
+type Diagnose = (code: KnownDiagnosticCode, message: string, context?: Record<string, unknown>) => void;
+/**
+ * The transition timer (each transition a `DA-BREAK-TRANSITION`) and the chain recorder (each
+ * chain a `DA-BREAK-CHAIN`) it feeds, so transition cost is comparable across preload modes and devices.
+ */
+export declare function createBreakMeasurement(diagnose: Diagnose, modes: {
+    adPreload: string;
+    adInsertion: string;
+}): {
+    timer: BreakTransitionTimer;
+    recorder: BreakChainRecorder;
+};
+export {};

package/dist/session/breakMeasurement.js

@@ -0,0 +1 @@
+import{BreakTransitionTimer as e}from"../services/BreakTransitionTimer";import{BreakChainRecorder as a}from"../services/BreakChainRecorder";export function createBreakMeasurement(r,n){const s=new a(e=>{r("DA-BREAK-CHAIN",`Chain ${e.chainId}: ${e.breaks.length} break(s) in ${e.totalMs}ms`,{breakId:e.chainId,...e})});return{timer:new e(e=>{r("DA-BREAK-TRANSITION",`Transition ${e.kind} took ${e.durationMs}ms`,{transition:e.kind,durationMs:e.durationMs,breakId:e.breakId,adPreload:n.adPreload,adInsertion:n.adInsertion,...e.phases?{phases:e.phases}:{},...e.path?{path:e.path}:{},...void 0!==e.leadMs?{leadMs:e.leadMs}:{}}),s.transitionMeasured(e)}),recorder:s}}

package/dist/session/contentSnapback.d.ts

@@ -0,0 +1,13 @@
+import type { PlayerAdapter } from '../interfaces/PlayerAdapter';
+import type { Break } from '../types/BreakManifest';
+import type { SessionState } from './SessionState';
+export interface SnapbackDeps {
+    player: PlayerAdapter;
+    state: Pick<SessionState, 'snapbackSeekInFlight'>;
+    activeBreak(): Break | null | undefined;
+    /** A viewer seek (not our own corrective one) landed. */
+    onViewerSeek(): void;
+    log(...args: unknown[]): void;
+}
+/** The content `seeked` handler: snaps a viewer seek back to the break start while the break locks it. */
+export declare function createSnapbackHandler(deps: SnapbackDeps): () => void;

package/dist/session/contentSnapback.js

@@ -0,0 +1 @@
+export function createSnapbackHandler(e){return()=>{if(e.state.snapbackSeekInFlight)return void(e.state.snapbackSeekInFlight=!1);e.onViewerSeek();const t=e.activeBreak();if(!t?.controls?.snapback)return;const a="number"==typeof t.start?t.start:e.player.currentTime;Math.abs(e.player.currentTime-a)<=.5||(e.log("Snapback: seek detected during locked break, snapping back to break start"),e.state.snapbackSeekInFlight=!0,e.player.seek(a))}}

package/dist/session/createExternalPlaybackGate.d.ts

@@ -0,0 +1,19 @@
+import type { PlayerAdapter } from '../interfaces/PlayerAdapter';
+import type { KnownDiagnosticCode } from '../diagnostics/errorCodes';
+import type { BreakScheduler } from '../services/BreakScheduler';
+import { ExternalPlaybackGate, type ExternalPlaybackAllowedTrigger } from '../services/ExternalPlaybackGate';
+import type { SsbSwitchPhase } from '../services/ssbSwitchSignals';
+import type { ExternalPlaybackConfig } from '../types/OptiViewAdsConfig';
+export declare const DEFAULT_EXTERNAL_PLAYBACK_BLOCK_BEFORE_BREAK_SEC = 5;
+/** Non-finite values fall back to the default; a negative window means "only during a break". */
+export declare function resolveBlockBeforeBreakSec(config: ExternalPlaybackConfig | undefined): number;
+export interface ExternalPlaybackGateWiring {
+    scheduler(): BreakScheduler | undefined;
+    diagnose(code: KnownDiagnosticCode, message: string, context?: Record<string, unknown>): void;
+    /** Runs after the allowed diagnostic; the SSB switch. */
+    onAllowed?(trigger: ExternalPlaybackAllowedTrigger): void;
+    /** The phase of the SSB switch in progress; defaults to none. */
+    ssbSwitchPhase?(): SsbSwitchPhase | null;
+}
+/** The session's AirPlay gate, fed by the break scheduler; the allowed hook only reports for now. */
+export declare function createExternalPlaybackGate(player: PlayerAdapter, config: ExternalPlaybackConfig | undefined, wiring: ExternalPlaybackGateWiring): ExternalPlaybackGate;

package/dist/session/createExternalPlaybackGate.js

@@ -0,0 +1 @@
+import{ExternalPlaybackGate as e}from"../services/ExternalPlaybackGate";export const DEFAULT_EXTERNAL_PLAYBACK_BLOCK_BEFORE_BREAK_SEC=5;export function resolveBlockBeforeBreakSec(e){const r=e?.blockBeforeBreakSec;return"number"==typeof r&&Number.isFinite(r)?Math.max(0,r):5}export function createExternalPlaybackGate(r,n,t){return new e({player:r,blockBeforeBreakSec:resolveBlockBeforeBreakSec(n),diagnose:t.diagnose,guardInput:()=>{const e=t.scheduler(),r=e?.getNextPendingBreak()??null;return{activeBreakId:e?.getActiveBreak()?.id??null,nextBreakId:r?.id??null,secondsUntilNextBreak:r?.secondsUntil??null}},ssbSwitchPhase:()=>t.ssbSwitchPhase?.()??null,onAllowed:e=>{t.diagnose("DA-EXTERNAL-PLAYBACK-ALLOWED",`AirPlay allowed (${e})`,{trigger:e}),t.onAllowed?.(e)}})}

package/dist/session/sessionTick.d.ts

@@ -0,0 +1,7 @@
+import type { AdBreakStatusTracker } from './AdBreakStatusTracker';
+import type { PauseAdController } from '../services/PauseAdController';
+/** The 250 ms session tick: advances the pause-ad timer and the AirPlay guard's `adbreakstatus`. */
+export declare function sessionTick(deps: {
+    pauseAdController?: PauseAdController | undefined;
+    adBreakStatusTracker: AdBreakStatusTracker;
+}): () => void;

package/dist/session/sessionTick.js

@@ -0,0 +1 @@
+export function sessionTick(r){return()=>{r.pauseAdController?.tick(),r.adBreakStatusTracker.refreshExternalPlayback()}}

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 */
@@ -25,13 +25,33 @@ export interface VendorConfigurationBase {
 }
 /** Session-level GAM configuration for pod-serving SGAI. @category Break Manifests & Ad Formats */
 export interface GamSgaiConfiguration {
+    /** The custom asset key of the channel's pod-serving stream. */
     customAssetKey: string;
+    /** Session-level ad tag parameters for pod requests. */
     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 {
+    /** The asset key of the full-service DAI livestream. */
     assetKey: string;
+    /** Session-level ad tag parameters for the stitched stream request. */
     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
@@ -54,9 +74,15 @@ export interface GamVendorConfiguration extends VendorConfigurationBase {
     sgai?: GamSgaiConfiguration[];
     ssai?: GamSsaiConfiguration[];
 }
+/**
+ * Ad parameters for a provider outside the SDK, read by the application with
+ * `getExternalVendorConfiguration()` or {@link OptiViewAdsExternalVendors}.
+ * @category Break Manifests & Ad Formats */
 export interface ExternalVendorConfigurationEntry extends VendorConfigurationBase {
     type: 'external';
+    /** The provider the parameters are for; the first valid entry per provider is used. */
     provider: string;
+    /** The provider's parameter template; values may contain `$NAME$` macros. */
     assetParameters: Record<string, string>;
 }
 /** Known vendor configuration entries, kept open to unrecognized vendors from newer manifests. @category Break Manifests & Ad Formats */
@@ -74,7 +100,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 +109,29 @@ 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 on a wallclock live stream and the session configuration in effect while it
+ * runs. Crossing its start or end emits `adchannelchange` with reason `event-boundary`.
+ * @category Break Manifests & Ad Formats */
+export interface ChannelEvent {
+    /** Identifier of the event, reported as the manifest's `eventId` while it runs. */
+    id: string;
+    /** Start of the event window (ISO-8601 wallclock). */
+    start: string;
+    /** End of the event window (ISO-8601 wallclock). */
+    end: string;
+    /** When set, replaces the manifest's {@link BreakManifest.adStartDelay} during the event. */
+    adStartDelay?: number;
+    /** When set, replaces the manifest's {@link BreakManifest.delivery} rules during the event. */
+    delivery?: DeliveryRule[];
+    /** When set, replaces the manifest's {@link BreakManifest.vendorConfiguration} during the event. */
+    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. */
@@ -178,7 +224,7 @@ export declare enum DeviceType {
     TABLET = "tablet",
     TV = "tv"
 }
-/** Platforms supported by manifest targeting (manifest spec v1.7.0). */
+/** Platforms supported by manifest targeting (manifest spec v1.7.0). @category Break Manifests & Ad Formats */
 export declare enum Platform {
     WEB = "web",
     ANDROID = "android",
@@ -186,7 +232,7 @@ export declare enum Platform {
     TVOS = "tvos",
     ROKU = "roku"
 }
-/** Operating systems supported by manifest targeting (manifest spec v1.8.0). */
+/** Operating systems supported by manifest targeting (manifest spec v1.8.0). @category Break Manifests & Ad Formats */
 export declare enum Os {
     ANDROID = "android",
     CHROMEOS = "chromeos",
@@ -202,9 +248,11 @@ export declare enum Os {
     WINDOWS = "windows",
     XBOX = "xbox"
 }
-/** Inclusive operating-system version bounds; each bound is dot-separated decimal integers. */
+/** Inclusive operating-system version bounds; each bound is dot-separated decimal integers. @category Break Manifests & Ad Formats */
 export interface OsVersionRange {
+    /** Lowest matching version, e.g. `"14"` or `"17.2"`. */
     min?: string;
+    /** Highest matching version, e.g. `"18.1"`. */
     max?: string;
 }
 /** Targeting criteria for break variants. @category Break Manifests & Ad Formats */
@@ -324,6 +372,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,17 +231,20 @@ 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 {
     type: 'externalvendorconfigurationchange';
+    /** The provider whose template changed; read its new configuration with `getExternalVendorConfiguration(provider)`. */
     provider: string;
 }
 /** Union type of all SDK events. @category Events */

package/dist/types/ExternalVendorConfiguration.d.ts

@@ -1,5 +1,7 @@
-/** Resolved parameters for an external provider declared in the break manifest. */
+/** Resolved parameters for an external provider declared in the break manifest. @category Manifest Customization */
 export interface ExternalVendorConfiguration {
+    /** The provider, as declared by the manifest's `external` vendor configuration entry. */
     provider: string;
+    /** The provider's parameters after merging application parameters and resolving macros. */
     assetParameters: Record<string, string>;
 }

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.1",
+  "version": "1.4.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"