@streamlayer/feature-advertisement 0.4.3 → 1.1.0

package/lib/units/ssai-preload.d.ts

@@ -0,0 +1,20 @@
+import type { SsaiCreative } from './ssai-creative';
+/**
+ * How long the overlay is willing to wait for artwork. A slow or dead image host
+ * must never hold the bar back — the ad is already playing, and a bar that shows
+ * late is worse than one that shows without its logo (the logo is hidden on error
+ * anyway). Warming the browser cache is the goal; blocking is not.
+ */
+export declare const DEFAULT_PRELOAD_TIMEOUT_MS = 2000;
+/**
+ * Fetch images into the browser cache and resolve once they are all settled, or
+ * once `timeoutMs` elapses — whichever comes first. Never rejects: a creative
+ * whose artwork fails is still a creative worth showing.
+ */
+export declare const preloadImages: (urls: (string | undefined | null)[], timeoutMs?: number) => Promise<void>;
+/**
+ * Warm every image the creative carries — the overlay's brand logo, and the
+ * companion banner for hosts that render one — so the bar fades in complete
+ * rather than popping its artwork in a beat later.
+ */
+export declare const preloadCreativeAssets: (creative: SsaiCreative, timeoutMs?: number) => Promise<void>;

package/lib/units/ssai-preload.js

@@ -0,0 +1,55 @@
+import { createLogger } from '@streamlayer/sdk-web-logger';
+const log = createLogger('ssai:preload');
+/**
+ * How long the overlay is willing to wait for artwork. A slow or dead image host
+ * must never hold the bar back — the ad is already playing, and a bar that shows
+ * late is worse than one that shows without its logo (the logo is hidden on error
+ * anyway). Warming the browser cache is the goal; blocking is not.
+ */
+export const DEFAULT_PRELOAD_TIMEOUT_MS = 2000;
+/**
+ * Fetch images into the browser cache and resolve once they are all settled, or
+ * once `timeoutMs` elapses — whichever comes first. Never rejects: a creative
+ * whose artwork fails is still a creative worth showing.
+ */
+export const preloadImages = (urls, timeoutMs = DEFAULT_PRELOAD_TIMEOUT_MS) => {
+    const targets = urls.filter((url) => !!url);
+    // `Image` is absent in SSR/worker contexts; there is nothing to warm there.
+    if (targets.length === 0 || typeof Image === 'undefined') {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        let remaining = targets.length;
+        const finish = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            log.debug({ remaining }, 'ssai preload timed out, showing anyway');
+            finish();
+        }, timeoutMs);
+        const one = () => {
+            remaining -= 1;
+            if (remaining <= 0) {
+                finish();
+            }
+        };
+        for (const url of targets) {
+            const image = new Image();
+            image.onload = one;
+            image.onerror = one;
+            image.src = url;
+        }
+    });
+};
+/**
+ * Warm every image the creative carries — the overlay's brand logo, and the
+ * companion banner for hosts that render one — so the bar fades in complete
+ * rather than popping its artwork in a beat later.
+ */
+export const preloadCreativeAssets = (creative, timeoutMs) => preloadImages([creative.iconUrl, creative.companion?.staticResource], timeoutMs);

package/lib/units/ssai-providers.d.ts

@@ -0,0 +1,117 @@
+import type { SsaiCreative } from './ssai-creative';
+export declare const DEFAULT_CREATIVE_API_BASE = "https://hls.next.streamlayer.io/api/creatives/";
+/**
+ * A creative provider encapsulates everything that differs between ad sources:
+ * how a creativeId resolves to the normalized {@link SsaiCreative}, and how
+ * impressions (and, in the future, other tracking events) are fired. The overlay
+ * UI only ever sees the normalized shape, so it never learns about providers.
+ */
+export interface SsaiCreativeProvider {
+    /** Stable id for logging/diagnostics, e.g. 'streamlayer' | 'vast'. */
+    readonly id: string;
+    /** Resolve a creativeId (from EXT-X-DATERANGE) to the normalized SsaiCreative. */
+    resolve(creativeId: string, signal: AbortSignal): Promise<SsaiCreative>;
+    /**
+     * Fire an impression for a resolved creative. Provider-specific (URL shape,
+     * beacon vs pixel vs SDK call). Optional — falls back to the shared default
+     * (first trackingEvent named 'impression' via sendBeacon/fetch) when omitted.
+     */
+    fireImpression?(creative: SsaiCreative): void;
+    /** Optional hook for other tracking events (click, quartiles) — future-facing, no-op default. */
+    fireTracking?(creative: SsaiCreative, event: string): void;
+}
+/**
+ * Shared low-level beacon helper. Prefers `navigator.sendBeacon` and falls back
+ * to a no-cors `fetch`. Used by the default impression path and available to
+ * providers that fire URL-based tracking pixels.
+ */
+export declare const fireBeacon: (url: string) => void;
+/**
+ * Fire every tracking event with the given name, and report how many went out.
+ *
+ * ALL matches, not the first: the creative contract states that a creative may
+ * repeat an `event` value to carry several URLs, and that consumers must not
+ * assume uniqueness. Today's payloads carry one URL per event, so this is not a
+ * change in what goes on the wire — it just stops being wrong the day a server
+ * sends two.
+ */
+export declare const fireTrackingEvents: (creative: SsaiCreative, event: string) => number;
+/**
+ * Shared default impression behavior: fire the `impression` tracking events.
+ * Used by the StreamLayer provider and as the fallback in
+ * {@link SsaiCreativeCache} when a provider doesn't override `fireImpression`.
+ * Exported so both call sites share one definition.
+ */
+export declare const fireDefaultImpression: (creative: SsaiCreative) => void;
+export type StreamLayerProviderConfig = {
+    /** Base URL of the StreamLayer JSON creative metadata API. */
+    creativeApiBase?: string;
+};
+/**
+ * StreamLayer's internal creative provider. Resolves creatives from the JSON
+ * creative API (`GET {creativeApiBase}{encodeURIComponent(creativeId)}`) and
+ * fires impressions from the `'impression'` tracking event via `sendBeacon`.
+ */
+export declare const createStreamLayerProvider: (config?: StreamLayerProviderConfig) => SsaiCreativeProvider;
+export type QuortexProviderConfig = {
+    /**
+     * Full URL of the tenant's ad metadata endpoint, e.g.
+     * `https://ads.example.com/get_ad` or, with the tenant baked in,
+     * `https://ads.example.com/get_ad?TenantName=acme`. Required — this is
+     * customer infrastructure, so there is no sensible SDK-level default.
+     */
+    adApiBase?: string;
+    /**
+     * Tenant the ad ids belong to, appended as the `TenantName` query parameter.
+     * Optional: omit it when `adApiBase` already carries the tenant.
+     */
+    tenantName?: string;
+};
+/**
+ * Quortex / Synamedia DAI ad metadata provider.
+ *
+ * `GET {adApiBase}?TenantName={tenantName}&adID={adId}&info=1` (the `TenantName`
+ * part omitted when `adApiBase` already carries it) — the ad id comes
+ * from the manifest's `X-AD-ID` DATERANGE attribute (see `ssai-detector.ts`, which
+ * reconstructs the ad window from the tracking-marker burst those tags form).
+ *
+ * The response is byte-compatible with the StreamLayer creative API, so the same
+ * `mapApiResponse` normalizes both.
+ *
+ * Known limitation: impressions fire the `impression` tracking event from the API
+ * response, not the per-session beacon the manifest carries in `X-AD-URL`. The two
+ * differ in `trackingid`/`USERID`, so Quortex-side attribution will see the
+ * generic id rather than the viewer's session until the manifest beacons are
+ * plumbed through to the provider.
+ */
+export declare const createQuortexProvider: (config?: QuortexProviderConfig) => SsaiCreativeProvider;
+export type VastProviderConfig = Record<string, never>;
+/**
+ * Maps a VAST tag into the normalized SsaiCreative shape.
+ *
+ * Note: `fireImpression` is intentionally left to the shared default for now.
+ * Proper VAST impression/tracking wiring through `VASTTracker` is a documented
+ * follow-up; it requires retaining the parsed ad/tracker per creative.
+ */
+export declare const createVastProvider: (_config?: VastProviderConfig) => SsaiCreativeProvider;
+export type SsaiProviderName = 'streamlayer' | 'quortex' | 'vast';
+/** Union of every built-in provider's config; each factory reads its own keys. */
+export type SsaiProviderConfig = StreamLayerProviderConfig & QuortexProviderConfig;
+/** Built-in provider factories keyed by name. */
+export declare const BUILTIN_PROVIDERS: Record<SsaiProviderName, (config?: SsaiProviderConfig) => SsaiCreativeProvider>;
+export type SsaiProviderOption = 
+/** A ready provider instance (built-in or fully custom). */
+SsaiCreativeProvider
+/** A built-in provider selected by name. */
+ | SsaiProviderName
+/** A built-in provider selected by name with optional config. */
+ | {
+    name: SsaiProviderName;
+    config?: SsaiProviderConfig;
+};
+/**
+ * Resolve a {@link SsaiProviderOption} into a concrete {@link SsaiCreativeProvider}.
+ * Defaults to the StreamLayer provider (using `fallbackConfig`) when no option is
+ * supplied.
+ */
+export declare const resolveProvider: (option?: SsaiProviderOption, fallbackConfig?: SsaiProviderConfig) => SsaiCreativeProvider;

package/lib/units/ssai-providers.js

@@ -0,0 +1,250 @@
+import { createLogger } from '@streamlayer/sdk-web-logger';
+import { VASTClient } from '@dailymotion/vast-client';
+const log = createLogger('ssai:provider');
+export const DEFAULT_CREATIVE_API_BASE = 'https://hls.next.streamlayer.io/api/creatives/';
+/**
+ * Shared low-level beacon helper. Prefers `navigator.sendBeacon` and falls back
+ * to a no-cors `fetch`. Used by the default impression path and available to
+ * providers that fire URL-based tracking pixels.
+ */
+export const fireBeacon = (url) => {
+    try {
+        if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+            navigator.sendBeacon(url);
+        }
+        else {
+            void fetch(url, { mode: 'no-cors' }).catch((error) => {
+                log.warn(error, 'ssai beacon failed');
+            });
+        }
+    }
+    catch (error) {
+        log.warn(error, 'ssai beacon failed');
+    }
+};
+const resolveAdvertiser = (advertiser, title) => {
+    if (advertiser) {
+        return advertiser;
+    }
+    if (title) {
+        return title;
+    }
+    return 'Ad';
+};
+const buildCreativeUrl = (base, creativeId) => {
+    const normalizedBase = base.endsWith('/') ? base : `${base}/`;
+    return `${normalizedBase}${encodeURIComponent(creativeId)}`;
+};
+const mapApiResponse = (raw) => {
+    const trackingEvents = Array.isArray(raw.trackingEvents)
+        ? raw.trackingEvents
+            .filter((entry) => Boolean(entry?.event && entry?.url))
+            .map((entry) => ({ event: entry.event, url: entry.url }))
+        : [];
+    const rawCompanion = Array.isArray(raw.companions)
+        ? raw.companions.find((entry) => !!entry?.staticResource)
+        : undefined;
+    const companion = rawCompanion?.staticResource
+        ? {
+            staticResource: rawCompanion.staticResource,
+            width: Number(rawCompanion.width) || 0,
+            height: Number(rawCompanion.height) || 0,
+            clickThrough: rawCompanion.clickThrough,
+            clickTracking: Array.isArray(rawCompanion.clickTracking)
+                ? rawCompanion.clickTracking.filter((url) => typeof url === 'string' && !!url)
+                : [],
+        }
+        : undefined;
+    return {
+        creativeId: raw.creativeId,
+        advertiser: resolveAdvertiser(raw.advertiser, raw.title),
+        title: raw.title || resolveAdvertiser(raw.advertiser, raw.title),
+        iconUrl: raw.iconUrl || undefined,
+        clickThroughUrl: raw.clickThroughUrl || undefined,
+        trackingEvents,
+        companion,
+    };
+};
+/**
+ * Fire every tracking event with the given name, and report how many went out.
+ *
+ * ALL matches, not the first: the creative contract states that a creative may
+ * repeat an `event` value to carry several URLs, and that consumers must not
+ * assume uniqueness. Today's payloads carry one URL per event, so this is not a
+ * change in what goes on the wire — it just stops being wrong the day a server
+ * sends two.
+ */
+export const fireTrackingEvents = (creative, event) => {
+    const matches = creative.trackingEvents.filter((entry) => entry.event === event);
+    for (const match of matches) {
+        fireBeacon(match.url);
+    }
+    return matches.length;
+};
+/**
+ * Shared default impression behavior: fire the `impression` tracking events.
+ * Used by the StreamLayer provider and as the fallback in
+ * {@link SsaiCreativeCache} when a provider doesn't override `fireImpression`.
+ * Exported so both call sites share one definition.
+ */
+export const fireDefaultImpression = (creative) => {
+    fireTrackingEvents(creative, 'impression');
+};
+/**
+ * StreamLayer's internal creative provider. Resolves creatives from the JSON
+ * creative API (`GET {creativeApiBase}{encodeURIComponent(creativeId)}`) and
+ * fires impressions from the `'impression'` tracking event via `sendBeacon`.
+ */
+export const createStreamLayerProvider = (config = {}) => {
+    const creativeApiBase = config.creativeApiBase ?? DEFAULT_CREATIVE_API_BASE;
+    return {
+        id: 'streamlayer',
+        resolve: async (creativeId, signal) => {
+            const url = buildCreativeUrl(creativeApiBase, creativeId);
+            const response = await fetch(url, { signal });
+            if (!response.ok) {
+                throw new Error(`creative request failed: ${response.status}`);
+            }
+            const raw = (await response.json());
+            return mapApiResponse({ ...raw, creativeId: raw.creativeId || creativeId });
+        },
+        fireImpression: fireDefaultImpression,
+    };
+};
+const buildQuortexUrl = (base, tenantName, adId) => {
+    // Deliberately string concatenation rather than `URL`/`URLSearchParams`: this
+    // package ships to 2016-era TV engines (see the chrome-32 classic build).
+    const separator = base.indexOf('?') === -1 ? '?' : '&';
+    const tenant = tenantName ? `TenantName=${encodeURIComponent(tenantName)}&` : '';
+    return `${base}${separator}${tenant}adID=${encodeURIComponent(adId)}&info=1`;
+};
+/**
+ * Quortex / Synamedia DAI ad metadata provider.
+ *
+ * `GET {adApiBase}?TenantName={tenantName}&adID={adId}&info=1` (the `TenantName`
+ * part omitted when `adApiBase` already carries it) — the ad id comes
+ * from the manifest's `X-AD-ID` DATERANGE attribute (see `ssai-detector.ts`, which
+ * reconstructs the ad window from the tracking-marker burst those tags form).
+ *
+ * The response is byte-compatible with the StreamLayer creative API, so the same
+ * `mapApiResponse` normalizes both.
+ *
+ * Known limitation: impressions fire the `impression` tracking event from the API
+ * response, not the per-session beacon the manifest carries in `X-AD-URL`. The two
+ * differ in `trackingid`/`USERID`, so Quortex-side attribution will see the
+ * generic id rather than the viewer's session until the manifest beacons are
+ * plumbed through to the provider.
+ */
+export const createQuortexProvider = (config = {}) => {
+    const { adApiBase, tenantName } = config;
+    if (!adApiBase) {
+        // Loud, but not thrown: this runs inside the host's render effect via
+        // `startSsaiMonitoring`, and taking the app down over a config typo is worse
+        // than an overlay that never appears and says why.
+        log.error({ adApiBase, tenantName }, 'quortex provider requires `adApiBase`');
+    }
+    return {
+        id: 'quortex',
+        resolve: async (adId, signal) => {
+            if (!adApiBase) {
+                throw new Error('quortex provider is missing `adApiBase`');
+            }
+            const response = await fetch(buildQuortexUrl(adApiBase, tenantName, adId), { signal });
+            if (!response.ok) {
+                throw new Error(`quortex creative request failed: ${response.status}`);
+            }
+            const raw = (await response.json());
+            return mapApiResponse({ ...raw, creativeId: raw.creativeId || adId });
+        },
+        fireImpression: fireDefaultImpression,
+    };
+};
+// --- VAST provider ---------------------------------------------------------
+const mapVastResponse = async (creativeId, signal) => {
+    const vastClient = new VASTClient();
+    const parsedVAST = await vastClient.get(creativeId, { timeout: 8000 });
+    if (signal.aborted) {
+        throw new DOMException('aborted', 'AbortError');
+    }
+    const validAd = parsedVAST.ads.find((ad) => ad.creatives.length > 0);
+    if (!validAd) {
+        throw new Error('no_valid_ad');
+    }
+    const advertiserValue = Array.isArray(validAd.advertiser)
+        ? validAd.advertiser.find((entry) => !!entry?.value)?.value
+        : undefined;
+    const advertiser = resolveAdvertiser(advertiserValue, validAd.title || undefined);
+    let iconUrl;
+    let clickThroughUrl;
+    let companion;
+    for (const creative of validAd.creatives) {
+        if (creative.type === 'linear') {
+            const linear = creative;
+            iconUrl = iconUrl || linear.icons?.find((icon) => !!icon?.staticResource)?.staticResource || undefined;
+            clickThroughUrl = clickThroughUrl || linear.videoClickThroughURLTemplate?.url;
+        }
+        if (creative.type === 'companion') {
+            const variation = creative.variations?.[0];
+            const staticResource = variation?.staticResources?.[0]?.url;
+            if (staticResource && !companion) {
+                companion = {
+                    staticResource,
+                    width: Number(variation?.width) || 0,
+                    height: Number(variation?.height) || 0,
+                    clickThrough: variation?.companionClickThroughURLTemplate?.url,
+                    clickTracking: (variation?.companionClickTrackingURLTemplates ?? [])
+                        .map((entry) => entry?.url)
+                        .filter((url) => !!url),
+                };
+            }
+        }
+    }
+    return {
+        creativeId,
+        advertiser,
+        title: validAd.title || advertiser,
+        iconUrl,
+        clickThroughUrl,
+        trackingEvents: [],
+        companion,
+    };
+};
+/**
+ * Maps a VAST tag into the normalized SsaiCreative shape.
+ *
+ * Note: `fireImpression` is intentionally left to the shared default for now.
+ * Proper VAST impression/tracking wiring through `VASTTracker` is a documented
+ * follow-up; it requires retaining the parsed ad/tracker per creative.
+ */
+export const createVastProvider = (_config = {}) => {
+    return {
+        id: 'vast',
+        resolve: mapVastResponse,
+    };
+};
+/** Built-in provider factories keyed by name. */
+export const BUILTIN_PROVIDERS = {
+    streamlayer: (config) => createStreamLayerProvider(config),
+    quortex: (config) => createQuortexProvider(config),
+    vast: () => createVastProvider(),
+};
+const isProviderInstance = (option) => {
+    return typeof option === 'object' && typeof option.resolve === 'function';
+};
+/**
+ * Resolve a {@link SsaiProviderOption} into a concrete {@link SsaiCreativeProvider}.
+ * Defaults to the StreamLayer provider (using `fallbackConfig`) when no option is
+ * supplied.
+ */
+export const resolveProvider = (option, fallbackConfig) => {
+    if (!option) {
+        return createStreamLayerProvider(fallbackConfig);
+    }
+    if (typeof option === 'string') {
+        return BUILTIN_PROVIDERS[option](fallbackConfig);
+    }
+    if (isProviderInstance(option)) {
+        return option;
+    }
+    return BUILTIN_PROVIDERS[option.name](option.config ?? fallbackConfig);
+};

package/lib/units/vast-tracker.d.ts

@@ -0,0 +1,45 @@
+/**
+ * One place that constructs a `VASTTracker`.
+ *
+ * Every StreamLayer surface that reports VAST beacons — the GAM video player, both pause-ad
+ * renderers and the Standard Ad sidebar — needs the same `(ad, creative, variation)` triple, and
+ * each was assembling it by hand behind its own `@ts-ignore`. The parsed shapes those triples
+ * come from (`AdData` / `AdCompanion` / `AdNonLinear`) are defined in this package, so the
+ * mapping belongs here too.
+ *
+ * Deliberately *only* construction: when a beacon may fire, and how a surface de-duplicates its
+ * impression, stays with that surface. Those policies differ on purpose (per-ad-id in module
+ * scope for the sidebar, per component instance for the pause ads, per tracker identity for the
+ * player) and they are billing-visible, so collapsing them here would silently change counts.
+ */
+import { VASTTracker, VastAd, VastCompanionAd, VastCreativeCompanion, VastCreativeLinear, VastCreativeNonLinear, VastNonLinearAd } from '@dailymotion/vast-client';
+import type { AdCompanion, AdData } from './external-ad';
+/** The creative (and, for non-linear creatives, the variation) a tracker reports through. */
+export type VastTrackerTarget = {
+    ad: VastAd;
+    /** `<Linear>`, `<NonLinearAds>` or `<CompanionAds>` — whichever owns the `<TrackingEvents>`. */
+    creative: VastCreativeLinear | VastCreativeNonLinear | VastCreativeCompanion;
+    /**
+     * The `<NonLinear>` / `<Companion>` variation. Omitted for a linear creative; required for the
+     * others, since the variation is what owns their `creativeView`, click-through and click
+     * trackers.
+     */
+    variation?: VastNonLinearAd | VastCompanionAd;
+};
+export declare const createVastTracker: ({ ad, creative, variation }: VastTrackerTarget) => VASTTracker;
+/**
+ * A tracker for a single `<Companion>`. A `<CompanionAds>` creative has no creative-level
+ * `<TrackingEvents>` — each variation owns its own `creativeView` — so a companion is reported
+ * through its own tracker. `undefined` when the companion was parsed without them (nothing to
+ * report against).
+ */
+export declare const createCompanionTracker: (ad: VastAd, companion: AdCompanion) => VASTTracker | undefined;
+/**
+ * The creative a parsed ad reports its impression / playback beacons through, in the order the
+ * shells draw them: the `<Linear>` creative first, then the `<NonLinear>` still, then — for a tag
+ * whose only creative is `<CompanionAds>` — the companion that was actually drawn.
+ *
+ * `drawnCompanion` is a parameter rather than `adData.companion` because only the rendering shell
+ * knows which companion reached the screen, and reporting one that did not is a false view.
+ */
+export declare const resolveVastTrackerTarget: (adData: AdData, drawnCompanion?: AdCompanion) => VastTrackerTarget | undefined;

package/lib/units/vast-tracker.js

@@ -0,0 +1,57 @@
+/**
+ * One place that constructs a `VASTTracker`.
+ *
+ * Every StreamLayer surface that reports VAST beacons — the GAM video player, both pause-ad
+ * renderers and the Standard Ad sidebar — needs the same `(ad, creative, variation)` triple, and
+ * each was assembling it by hand behind its own `@ts-ignore`. The parsed shapes those triples
+ * come from (`AdData` / `AdCompanion` / `AdNonLinear`) are defined in this package, so the
+ * mapping belongs here too.
+ *
+ * Deliberately *only* construction: when a beacon may fire, and how a surface de-duplicates its
+ * impression, stays with that surface. Those policies differ on purpose (per-ad-id in module
+ * scope for the sidebar, per component instance for the pause ads, per tracker identity for the
+ * player) and they are billing-visible, so collapsing them here would silently change counts.
+ */
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="../module.d.ts" />
+import { VASTTracker, } from '@dailymotion/vast-client';
+export const createVastTracker = ({ ad, creative, variation }) => 
+// The first argument is the `VASTClient` the tracker may update; every surface here drives
+// playback itself and only wants the beacons, so it is always `null`.
+//
+// The type shim declares the 3rd argument as `VastCreativeLinear` and the 4th as another
+// *creative*. At runtime `vast-client` accepts any creative in the 3rd and expects the
+// `<Companion>` / `<NonLinear>` *variation* in the 4th. The casts encode that runtime contract
+// once here rather than at every call site.
+new VASTTracker(null, ad, creative, variation);
+/**
+ * A tracker for a single `<Companion>`. A `<CompanionAds>` creative has no creative-level
+ * `<TrackingEvents>` — each variation owns its own `creativeView` — so a companion is reported
+ * through its own tracker. `undefined` when the companion was parsed without them (nothing to
+ * report against).
+ */
+export const createCompanionTracker = (ad, companion) => companion.creative && companion.variation
+    ? createVastTracker({ ad, creative: companion.creative, variation: companion.variation })
+    : undefined;
+/**
+ * The creative a parsed ad reports its impression / playback beacons through, in the order the
+ * shells draw them: the `<Linear>` creative first, then the `<NonLinear>` still, then — for a tag
+ * whose only creative is `<CompanionAds>` — the companion that was actually drawn.
+ *
+ * `drawnCompanion` is a parameter rather than `adData.companion` because only the rendering shell
+ * knows which companion reached the screen, and reporting one that did not is a false view.
+ */
+export const resolveVastTrackerTarget = (adData, drawnCompanion) => {
+    // `AdData.creative` is not optional in the type but `getCreative` can return nothing: a
+    // programmatic tag does not have to carry a `<Linear>` creative.
+    if (adData.creative) {
+        return { ad: adData.ad, creative: adData.creative };
+    }
+    if (adData.nonLinear) {
+        return { ad: adData.ad, creative: adData.nonLinear.creative, variation: adData.nonLinear.variation };
+    }
+    if (drawnCompanion?.creative && drawnCompanion.variation) {
+        return { ad: adData.ad, creative: drawnCompanion.creative, variation: drawnCompanion.variation };
+    }
+    return undefined;
+};

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@streamlayer/feature-advertisement",
-  "version": "0.4.3",
+  "version": "1.1.0",
   "peerDependencies": {
-    "@dailymotion/vast-client": "^6.4.2",
-    "@streamlayer/sl-eslib": "^5.229.1",
+    "@dailymotion/vast-client": "^6.4.5",
+    "@streamlayer/sl-eslib": "^5.268.1",
+    "uuid": "^11.1.0",
     "nanostores": "^1.1.0",
-    "@streamlayer/sdk-web-core": "^1.22.6",
-    "@streamlayer/sdk-web-api": "^1.17.6",
-    "@streamlayer/sdk-web-interfaces": "^1.10.6",
-    "@streamlayer/sdk-web-logger": "^1.1.6",
-    "@streamlayer/sdk-web-types": "^1.18.6"
+    "@streamlayer/sdk-web-core": "^1.23.1",
+    "@streamlayer/sdk-web-api": "^1.18.1",
+    "@streamlayer/sdk-web-interfaces": "^1.11.1",
+    "@streamlayer/sdk-web-types": "^2.0.1",
+    "@streamlayer/sdk-web-logger": "^1.2.1",
+    "@streamlayer/sdk-web-storage": "^1.2.1"
   },
   "devDependencies": {
     "@types/vast-client": "^3.0.4"