@streamlayer/feature-advertisement 0.4.3 → 1.1.0

package/lib/advertisement.d.ts

@@ -1,19 +1,62 @@
 import { AbstractFeatureUnit, StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
-import { externalAd, type ExternalAdOptions } from './units/external-ad';
+import { externalAd } from './units/external-ad';
 import { externalPauseAd, type ExternalPauseAdOptions } from './units/external-pause-ad';
 import { type PauseAdListOptions, type PauseAdStore } from './units/pause-ad';
+import { type SsaiProviderOption } from './units/ssai-providers';
+import { type HlsLike, type SsaiDebugSnapshot } from './units/ssai-detector';
+import { type SsaiAdBreakStore } from './units/ssai-ad-break';
 export type ExternalAdStore = ReturnType<ReturnType<typeof externalAd>>;
 export type ExternalPauseAdStore = ReturnType<ReturnType<typeof externalPauseAd>>;
+export type SsaiMonitorOptions = {
+    player?: HlsLike;
+    videoRef?: HTMLVideoElement;
+    manifestUrl?: string;
+    /** Creative provider: a ready instance, a built-in name, or `{ name, config }`. Defaults to `streamlayer`. */
+    provider?: SsaiProviderOption;
+};
 export declare class Advertisement extends AbstractFeatureUnit {
-    getExternalAd: (adUrl: string, options: ExternalAdOptions) => [ExternalAdStore, string];
+    getExternalAd: (adUrl?: string) => [ExternalAdStore, string];
     getExternalPauseAd: (adUrl: string, options: ExternalPauseAdOptions) => [ExternalPauseAdStore, string];
     getPauseAdList: (options: PauseAdListOptions) => PauseAdStore;
+    readonly ssaiAdBreak: SsaiAdBreakStore;
+    startSsaiMonitoring: (options: SsaiMonitorOptions) => void;
+    stopSsaiMonitoring: () => void;
+    /**
+     * Fire the impression tracking pixel for a creative. Called by the UI the
+     * moment the bar actually renders the creative, so "impression" means the
+     * viewer saw it (not merely that metadata resolved).
+     */
+    fireSsaiImpression: (creativeId: string) => void;
+    /**
+     * Fire a named tracking beacon for a creative (`clickThrough`, or any event
+     * the creative carries). Lifecycle beacons — `start`, the quartiles and
+     * `complete` — are fired automatically by the detector as playback crosses
+     * them; this is for the ones only the UI knows about.
+     */
+    fireSsaiTracking: (creativeId: string, event: string) => void;
+    /**
+     * Fire the companion's `clickTracking` beacons. Exposed for hosts that render
+     * the companion banner themselves — the TV overlay has no companion surface,
+     * so nothing in this SDK calls it.
+     */
+    fireSsaiCompanionClick: (creativeId: string) => void;
+    /**
+     * User-dismissed the current break: hide the bar now and keep it hidden for
+     * the rest of this break (a later break/creative shows again).
+     */
+    dismissSsaiBreak: () => void;
+    /**
+     * Read-only timing introspection of the running SSAI monitor (null while no
+     * monitor runs). Feeds the demo app's SSAI debug window; safe to poll.
+     */
+    getSsaiDebugSnapshot: () => SsaiDebugSnapshot | null;
     private externalAdStores;
-    private externalAdEnabled;
     private externalPauseAdStores;
     private externalPauseAdEnabled;
     private pauseAdStore;
     private pauseAdEnabled;
+    private ssaiDetector;
+    private ssaiCache;
     private log;
     constructor(instance: StreamLayerContext);
     connect: () => void;

package/lib/advertisement.js

@@ -1,18 +1,56 @@
-import { AbstractFeatureUnit, createSingleStore } from '@streamlayer/sdk-web-interfaces';
+import { AbstractFeatureUnit, createSingleStore, eventBus } from '@streamlayer/sdk-web-interfaces';
 import { createLogger } from '@streamlayer/sdk-web-logger';
 import { externalAd } from './units/external-ad';
 import { externalPauseAd } from './units/external-pause-ad';
 import { pauseAdListStore } from './units/pause-ad';
+import { SsaiCreativeCache } from './units/ssai-creative';
+import { resolveProvider } from './units/ssai-providers';
+import { createSsaiDetector, } from './units/ssai-detector';
+import { createSsaiAdBreakStore } from './units/ssai-ad-break';
+import { preloadCreativeAssets } from './units/ssai-preload';
 export class Advertisement extends AbstractFeatureUnit {
     getExternalAd;
     getExternalPauseAd;
     getPauseAdList;
+    ssaiAdBreak = createSsaiAdBreakStore();
+    startSsaiMonitoring;
+    stopSsaiMonitoring;
+    /**
+     * Fire the impression tracking pixel for a creative. Called by the UI the
+     * moment the bar actually renders the creative, so "impression" means the
+     * viewer saw it (not merely that metadata resolved).
+     */
+    fireSsaiImpression;
+    /**
+     * Fire a named tracking beacon for a creative (`clickThrough`, or any event
+     * the creative carries). Lifecycle beacons — `start`, the quartiles and
+     * `complete` — are fired automatically by the detector as playback crosses
+     * them; this is for the ones only the UI knows about.
+     */
+    fireSsaiTracking;
+    /**
+     * Fire the companion's `clickTracking` beacons. Exposed for hosts that render
+     * the companion banner themselves — the TV overlay has no companion surface,
+     * so nothing in this SDK calls it.
+     */
+    fireSsaiCompanionClick;
+    /**
+     * User-dismissed the current break: hide the bar now and keep it hidden for
+     * the rest of this break (a later break/creative shows again).
+     */
+    dismissSsaiBreak;
+    /**
+     * Read-only timing introspection of the running SSAI monitor (null while no
+     * monitor runs). Feeds the demo app's SSAI debug window; safe to poll.
+     */
+    getSsaiDebugSnapshot;
     externalAdStores = new Map();
-    externalAdEnabled = new Map();
     externalPauseAdStores = new Map();
     externalPauseAdEnabled = new Map();
     pauseAdStore = null;
     pauseAdEnabled = null;
+    ssaiDetector = null;
+    ssaiCache = null;
     log;
     constructor(instance) {
         super();
@@ -20,6 +58,12 @@ export class Advertisement extends AbstractFeatureUnit {
         const externalAdGenerator = externalAd(instance);
         const externalPauseAdGenerator = externalPauseAd(instance);
         const pauseAdGenerator = pauseAdListStore(instance);
+        this.fireSsaiImpression = () => undefined;
+        this.fireSsaiTracking = () => undefined;
+        this.fireSsaiCompanionClick = () => undefined;
+        this.dismissSsaiBreak = () => undefined;
+        // Stable across start/stop cycles — always answers from the CURRENT detector.
+        this.getSsaiDebugSnapshot = () => this.ssaiDetector?.getDebugSnapshot() ?? null;
         this.getPauseAdList = (options) => {
             if (this.pauseAdStore) {
                 const $enabled = this.pauseAdEnabled;
@@ -38,29 +82,23 @@ export class Advertisement extends AbstractFeatureUnit {
             this.pauseAdStore = pauseAdGenerator($enabled, options);
             return this.pauseAdStore;
         };
-        this.getExternalAd = (adUrl, options) => {
+        this.getExternalAd = (adUrl = '') => {
             if (this.externalAdStores.has(adUrl)) {
-                const $enabled = this.externalAdEnabled.get(adUrl);
                 const $store = this.externalAdStores.get(adUrl);
-                const shouldRevalidate = $enabled.get() === false && options.$enabled === true;
-                $enabled.set(options.$enabled);
-                if (shouldRevalidate) {
-                    window.requestAnimationFrame(() => {
-                        $store.revalidate();
-                    });
-                }
                 return [$store, adUrl];
             }
-            const $enabled = createSingleStore(options.$enabled);
-            const store = externalAdGenerator(adUrl, $enabled, options);
-            this.externalAdEnabled.set(adUrl, $enabled);
+            const store = externalAdGenerator(adUrl);
             this.externalAdStores.set(adUrl, store);
             return [store, adUrl];
         };
         this.getExternalPauseAd = (adUrl, options) => {
-            if (this.externalPauseAdStores.has(adUrl)) {
-                const $enabled = this.externalPauseAdEnabled.get(adUrl);
-                const $store = this.externalPauseAdStores.get(adUrl);
+            // Store identity is (template, url): the template selects a DIFFERENT creative
+            // from the SAME tag, so the two must not share a store. Required because the
+            // cache-hit branch below applies only `$enabled` and drops the rest of `options`.
+            const storeKey = `${options.template ?? 'default'}::${adUrl}`;
+            if (this.externalPauseAdStores.has(storeKey)) {
+                const $enabled = this.externalPauseAdEnabled.get(storeKey);
+                const $store = this.externalPauseAdStores.get(storeKey);
                 const shouldRevalidate = $enabled.get() === false && options.$enabled === true;
                 $enabled.set(options.$enabled);
                 if (shouldRevalidate) {
@@ -68,27 +106,182 @@ export class Advertisement extends AbstractFeatureUnit {
                         $store.revalidate();
                     });
                 }
+                // The 2nd element MUST stay the BARE url — `ExposedPauseAd` compares it to
+                // `vastUrlRef.current` (index.tsx:121) to scope store errors to the selected tag.
                 return [$store, adUrl];
             }
             const $enabled = createSingleStore(options.$enabled);
             const store = externalPauseAdGenerator(adUrl, $enabled, options);
-            this.externalPauseAdEnabled.set(adUrl, $enabled);
-            this.externalPauseAdStores.set(adUrl, store);
+            this.externalPauseAdEnabled.set(storeKey, $enabled);
+            this.externalPauseAdStores.set(storeKey, store);
             return [store, adUrl];
         };
+        this.startSsaiMonitoring = (options) => {
+            this.stopSsaiMonitoring();
+            const provider = resolveProvider(options.provider);
+            const cache = new SsaiCreativeCache(provider);
+            this.ssaiCache = cache;
+            this.fireSsaiImpression = (creativeId) => {
+                cache.fireImpressionById(creativeId);
+            };
+            this.fireSsaiTracking = (creativeId, event) => {
+                cache.fireTrackingById(creativeId, event);
+            };
+            this.fireSsaiCompanionClick = (creativeId) => {
+                cache.fireCompanionClickById(creativeId);
+            };
+            // Creative ids whose artwork preload has completed. Tracked apart from the
+            // cache: `peek` alone would let the bar show with a logo still in flight.
+            const preloadedIds = new Set();
+            /**
+             * Resolve + warm a creative the moment its id shows up in the manifest —
+             * typically seconds before its break starts, since the playhead trails the
+             * live edge. By break start the sync fast-path in `loadCreative` then flips
+             * the store straight to 'ready'. Failure here is only a debug note: the
+             * break may still be minutes away, and `loadCreative` retries (and warns)
+             * when the ad actually starts.
+             */
+            const prefetchCreative = (creativeId) => {
+                cache
+                    .resolve(creativeId)
+                    .then((creative) => preloadCreativeAssets(creative))
+                    .then(() => {
+                    preloadedIds.add(creativeId);
+                })
+                    .catch((error) => {
+                    this.log.debug(error, 'ssai creative prefetch failed');
+                });
+            };
+            const publishReady = (range, creative) => {
+                this.ssaiAdBreak.set({
+                    creativeId: range.creativeId,
+                    creative,
+                    status: 'ready',
+                    startMs: range.startMs,
+                    durationSec: range.durationSec,
+                });
+                // "loaded" = metadata resolved. Impression (eventBus + pixel) fires
+                // from the UI when the bar is actually rendered, not here.
+                eventBus.emit('ssaiAdBreak', {
+                    action: 'vastLoaded',
+                    payload: {
+                        creativeId: creative.creativeId,
+                        advertiser: creative.advertiser,
+                        clickThroughUrl: creative.clickThroughUrl,
+                    },
+                });
+            };
+            const loadCreative = (range) => {
+                // Fast path: prefetched at discovery, artwork warm — go straight to
+                // 'ready'. Skipping the 'detecting' hop matters for pods in particular:
+                // it momentarily empties the store, which the UI renders as the bar
+                // starting to close between two back-to-back ads.
+                const prefetched = cache.peek(range.creativeId);
+                if (prefetched && preloadedIds.has(range.creativeId)) {
+                    publishReady(range, prefetched);
+                    return;
+                }
+                this.ssaiAdBreak.set({
+                    creativeId: range.creativeId,
+                    status: 'detecting',
+                    startMs: range.startMs,
+                    durationSec: range.durationSec,
+                });
+                cache
+                    .resolve(range.creativeId)
+                    // Warm the artwork BEFORE flipping to 'ready', so the bar fades in with
+                    // its logo already decoded instead of popping it in mid-animation. Capped
+                    // internally, so a slow image host delays nothing.
+                    .then((creative) => preloadCreativeAssets(creative).then(() => {
+                    preloadedIds.add(range.creativeId);
+                    return creative;
+                }))
+                    .then((creative) => {
+                    const current = this.ssaiAdBreak.get();
+                    // Re-checked after the preload as well as the fetch: the break can end
+                    // while either is in flight.
+                    if (!current || current.creativeId !== range.creativeId) {
+                        return;
+                    }
+                    publishReady(range, creative);
+                })
+                    .catch((error) => {
+                    this.log.warn(error, 'ssai creative resolution failed');
+                });
+            };
+            this.ssaiDetector = createSsaiDetector({
+                player: options.player,
+                videoRef: options.videoRef,
+                manifestUrl: options.manifestUrl,
+                onAdDiscovered: (creativeId) => {
+                    this.log.debug({ creativeId }, 'ssai ad discovered, prefetching creative');
+                    prefetchCreative(creativeId);
+                },
+                onBreakStart: (range) => {
+                    this.log.debug({ creativeId: range.creativeId }, 'ssai break start');
+                    eventBus.emit('ssaiAdBreak', {
+                        action: 'breakStart',
+                        payload: { creativeId: range.creativeId },
+                    });
+                    loadCreative(range);
+                },
+                onCreativeChange: (range) => {
+                    this.log.debug({ creativeId: range.creativeId }, 'ssai creative change');
+                    loadCreative(range);
+                },
+                onAdEnding: (range) => {
+                    const current = this.ssaiAdBreak.get();
+                    // Only a bar currently showing this creative has anything to wind
+                    // down — a dismissed or still-resolving break stays as it is.
+                    if (!current || current.creativeId !== range.creativeId || current.status !== 'ready') {
+                        return;
+                    }
+                    this.ssaiAdBreak.set({ ...current, status: 'ending' });
+                },
+                onProgress: (range, event) => {
+                    this.log.debug({ creativeId: range.creativeId, event }, 'ssai progress');
+                    cache.fireTrackingById(range.creativeId, event);
+                },
+                onBreakEnd: () => {
+                    this.log.debug('ssai break end');
+                    const current = this.ssaiAdBreak.get();
+                    eventBus.emit('ssaiAdBreak', {
+                        action: 'breakEnd',
+                        payload: { creativeId: current?.creativeId },
+                    });
+                    this.ssaiAdBreak.set(null);
+                },
+            });
+            this.dismissSsaiBreak = () => {
+                this.ssaiDetector?.dismissActiveBreak();
+                this.ssaiAdBreak.set(null);
+            };
+        };
+        this.stopSsaiMonitoring = () => {
+            if (this.ssaiDetector) {
+                this.ssaiDetector.destroy();
+                this.ssaiDetector = null;
+            }
+            if (this.ssaiCache) {
+                this.ssaiCache.destroy();
+                this.ssaiCache = null;
+            }
+            this.fireSsaiImpression = () => undefined;
+            this.fireSsaiTracking = () => undefined;
+            this.fireSsaiCompanionClick = () => undefined;
+            this.dismissSsaiBreak = () => undefined;
+            this.ssaiAdBreak.set(null);
+        };
     }
     connect = () => {
         this.log.debug('connect');
     };
     disconnect = () => {
         this.log.debug('disconnect');
+        this.stopSsaiMonitoring();
         this.externalAdStores.forEach((store) => {
             store.off();
         });
-        this.externalAdEnabled.forEach((enabled) => {
-            enabled.off();
-        });
-        this.externalAdEnabled.clear();
         this.externalAdStores.clear();
         this.externalPauseAdStores.forEach((store) => {
             store.off();

package/lib/index.d.ts

@@ -4,8 +4,16 @@ declare module '@streamlayer/sdk-web-interfaces' {
         advertisement: import('./advertisement').Advertisement;
     }
 }
-export { type ExternalAdStore, type ExternalPauseAdStore } from './advertisement';
-export { type GAMStaticAdCore } from './units/external-ad';
-export { type GAMStaticCore } from './units/external-pause-ad';
-export { type PauseAdCard, type PauseAdStore } from './units/pause-ad';
+export { type ExternalAdStore, type ExternalPauseAdStore, type SsaiMonitorOptions } from './advertisement';
+export { type GAMStaticCore, type PauseAdTemplate, isFullbleedVideoTemplate } from './units/external-pause-ad';
+export { INSIGHT_BODY_MAX_LENGTH, type PauseAdCard, type PauseAdKind, type PauseAdMediaMode, } from './units/pause-ad-card';
+export { type PauseAdStore } from './units/pause-ad';
+export { type AdStore, type AdData, type AdCompanion, type AdNonLinear } from './units/external-ad';
+export { gam, type GamNonceResult, type PalNonceManager } from './units/gam';
+export { createCompanionTracker, createVastTracker, resolveVastTrackerTarget, type VastTrackerTarget, } from './units/vast-tracker';
+export { type SsaiCreative, type SsaiTrackingEvent, type SsaiCompanion, type SsaiProgressEvent, DEFAULT_CREATIVE_API_BASE, } from './units/ssai-creative';
+export { type SsaiCreativeProvider, type SsaiProviderOption, type SsaiProviderName, type SsaiProviderConfig, type StreamLayerProviderConfig, type QuortexProviderConfig, createStreamLayerProvider, createQuortexProvider, createVastProvider, resolveProvider, fireBeacon, fireTrackingEvents, BUILTIN_PROVIDERS, } from './units/ssai-providers';
+export { type SsaiDateRange, type SsaiTrackingMarker, type HlsLike, type SsaiClockSource, type SsaiDebugEvent, type SsaiDebugRange, type SsaiDebugSnapshot, } from './units/ssai-detector';
+export { preloadImages, preloadCreativeAssets, DEFAULT_PRELOAD_TIMEOUT_MS } from './units/ssai-preload';
+export { type SsaiAdBreakState, type SsaiAdBreakStatus, type SsaiAdBreakStore } from './units/ssai-ad-break';
 export declare const advertisement: (instance: StreamLayerContext, _opts: unknown, done: () => void) => void;

package/lib/index.js

@@ -1,4 +1,16 @@
 import { Advertisement } from './advertisement';
+export { isFullbleedVideoTemplate } from './units/external-pause-ad';
+// Card shapes come straight from the pure module rather than through `units/pause-ad`. NOT a bundle
+// guarantee for barrel consumers — this file value-imports `Advertisement` on line 3, which imports
+// the store module anyway, and the package declares no `sideEffects: false`. What it does buy: the
+// unit spec and any deep importer get the card shapes without the store, and dropping the
+// `export *` keeps `units/pause-ad` from silently re-exporting `parsePauseAdCards`.
+export { INSIGHT_BODY_MAX_LENGTH, } from './units/pause-ad-card';
+export { gam } from './units/gam';
+export { createCompanionTracker, createVastTracker, resolveVastTrackerTarget, } from './units/vast-tracker';
+export { DEFAULT_CREATIVE_API_BASE, } from './units/ssai-creative';
+export { createStreamLayerProvider, createQuortexProvider, createVastProvider, resolveProvider, fireBeacon, fireTrackingEvents, BUILTIN_PROVIDERS, } from './units/ssai-providers';
+export { preloadImages, preloadCreativeAssets, DEFAULT_PRELOAD_TIMEOUT_MS } from './units/ssai-preload';
 export const advertisement = (instance, _opts, done) => {
     instance.sdk.advertisement = new Advertisement(instance);
     instance.sdk.onMount({ name: 'advertisement' }, () => {

package/lib/units/external-ad.d.ts

@@ -1,19 +1,58 @@
-import { createSingleStore, StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
+import { StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
+import { VastAd, VastCompanionAd, VastCreativeCompanion, VastCreativeLinear, VastCreativeNonLinear, VastNonLinearAd, VastResponse } from '@dailymotion/vast-client';
 import '@streamlayer/sdk-web-api';
-export type GAMStaticAdCore = {
-    id: string;
-    parentId: string;
-    url: string;
-    imageSrc?: string;
-    videoSrc?: string;
-    sponsorSrc?: string;
+import { type PalNonceManager } from './gam';
+import { VastCreative } from './parse-vast-extensions';
+export type AdCompanion = {
+    imageUrl?: string;
+    clickUrl?: string;
+    width?: number;
+    height?: number;
+    /** The `<CompanionAds>` creative — the `VASTTracker` 3rd argument. */
+    creative?: VastCreativeCompanion;
+    /** The `<Companion>` variation — the 4th argument; carries this companion's own `creativeView`. */
+    variation?: VastCompanionAd;
+};
+/**
+ * First `<NonLinear>` variation of a `<NonLinearAds>` creative. Tags that ship this instead of a
+ * `<Linear>` creative make it the ad's main media, not a companion strip.
+ */
+export type AdNonLinear = {
+    imageUrl: string;
+    clickUrl?: string;
+    width?: number;
+    height?: number;
+    /** The `<NonLinearAds>` creative — carries the creative-level `<TrackingEvents>`. */
+    creative: VastCreativeNonLinear;
+    /** The `<NonLinear>` variation — the `VASTTracker` 4th argument (click-through + its trackers). */
+    variation: VastNonLinearAd;
+};
+export type AdData = {
+    creative: VastCreativeLinear;
+    order: number;
+    mediaFileUrl?: string;
+    /** First companion creative (static image + click-through) — sources the L-Bar banner strip. */
+    companion?: AdCompanion;
+    /** The 300x75 `<Companion>` — the sponsor logo. Only set for a companion pair. */
+    logo?: AdCompanion;
+    /** Banner-sized `<Companion>` (468x60 class) — the sidebar media for companion-pair tags. */
+    mediaCompanion?: AdCompanion;
+    /** NonLinear (image-only) creative — present when the tag has no `<Linear>` media. */
+    nonLinear?: AdNonLinear;
+    /** VAST `<AdTitle>`. */
     title?: string;
+    /** VAST `<Description>`. */
     description?: string;
-    adUrl?: string;
+    /** Linear `<ClickThrough>`, else `<NonLinearClickThrough>`, else `<CompanionClickThrough>`. */
+    clickThrough?: string;
+    ad: VastAd;
+    extension?: VastCreative;
+    raw: VastResponse;
 };
-export type ExternalAdOptions = {
-    refetchInterval: number;
-    prefetch: boolean;
-    $enabled: boolean;
+export type AdStore = {
+    ads: AdData[];
+    autoplay: boolean;
+    muted: boolean;
+    nonceManager?: PalNonceManager;
 };
-export declare const externalAd: (instance: StreamLayerContext) => (gamUrl: string, $enabled: ReturnType<typeof createSingleStore<boolean>>, options: ExternalAdOptions) => import("@nanostores/query").FetcherStore<GAMStaticAdCore | undefined, any>;
+export declare const externalAd: (instance: StreamLayerContext) => (gamUrl: string) => import("@nanostores/query").FetcherStore<AdStore | undefined, any>;