@streamlayer/feature-advertisement 1.1.1-rc.1345 → 1.1.1-rc.2.pf58ff685

package/lib/advertisement.js

@@ -7,6 +7,7 @@ import { SsaiCreativeCache } from './units/ssai-creative.js';
 import { resolveProvider } from './units/ssai-providers.js';
 import { createSsaiDetector, } from './units/ssai-detector.js';
 import { createSsaiAdBreakStore } from './units/ssai-ad-break.js';
+import { ssaiq } from './units/ssai-log.js';
 import { preloadCreativeAssets } from './units/ssai-preload.js';
 export class Advertisement extends AbstractFeatureUnit {
     getExternalAd;
@@ -121,10 +122,25 @@ export class Advertisement extends AbstractFeatureUnit {
             const provider = resolveProvider(options.provider);
             const cache = new SsaiCreativeCache(provider);
             this.ssaiCache = cache;
+            /**
+             * Every beacon the SDK fires gets a line, with the URL it was fired at.
+             * The narrative log is read as a live trace of one ad, and "we called the
+             * ad server's own tracking URL" is as much of the story as the request
+             * that fetched the creative in the first place.
+             */
+            const logBeacon = (creativeId, event) => {
+                const url = cache.peek(creativeId)?.trackingEvents?.find((entry) => entry.event === event)?.url;
+                ssaiq.info({ creativeId, event, url }, `[beacon] ${event} fired — ${creativeId}`);
+            };
             this.fireSsaiImpression = (creativeId) => {
+                // The UI only calls this once the bar is actually rendered, so this is
+                // the moment the viewer saw the ad — not the moment it resolved.
+                ssaiq.info({ creativeId }, `[ad] ad on screen — ${cache.peek(creativeId)?.advertiser || creativeId}`);
+                logBeacon(creativeId, 'impression');
                 cache.fireImpressionById(creativeId);
             };
             this.fireSsaiTracking = (creativeId, event) => {
+                logBeacon(creativeId, event);
                 cache.fireTrackingById(creativeId, event);
             };
             this.fireSsaiCompanionClick = (creativeId) => {
@@ -144,12 +160,14 @@ export class Advertisement extends AbstractFeatureUnit {
             const prefetchCreative = (creativeId) => {
                 cache
                     .resolve(creativeId)
-                    .then((creative) => preloadCreativeAssets(creative))
-                    .then(() => {
+                    .then((creative) => preloadCreativeAssets(creative).then(() => creative))
+                    .then((creative) => {
                     preloadedIds.add(creativeId);
+                    ssaiq.info({ creativeId }, `[ad] creative ready — ${creative.advertiser} (artwork preloaded)`);
                 })
-                    .catch((error) => {
-                    this.log.debug(error, 'ssai creative prefetch failed');
+                    .catch(() => {
+                    // Already on `ssaiq` from the provider; the break may still be
+                    // minutes away, and `loadCreative` retries when it actually starts.
                 });
             };
             const publishReady = (range, creative) => {
@@ -214,11 +232,9 @@ export class Advertisement extends AbstractFeatureUnit {
                 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 },
@@ -226,7 +242,6 @@ export class Advertisement extends AbstractFeatureUnit {
                     loadCreative(range);
                 },
                 onCreativeChange: (range) => {
-                    this.log.debug({ creativeId: range.creativeId }, 'ssai creative change');
                     loadCreative(range);
                 },
                 onAdEnding: (range) => {
@@ -239,11 +254,11 @@ export class Advertisement extends AbstractFeatureUnit {
                     this.ssaiAdBreak.set({ ...current, status: 'ending' });
                 },
                 onProgress: (range, event) => {
-                    this.log.debug({ creativeId: range.creativeId, event }, 'ssai progress');
+                    // Logged by the detector as `progress:<event>` at the moment playback
+                    // crosses the marker; nothing to add here.
                     cache.fireTrackingById(range.creativeId, event);
                 },
                 onBreakEnd: () => {
-                    this.log.debug('ssai break end');
                     const current = this.ssaiAdBreak.get();
                     eventBus.emit('ssaiAdBreak', {
                         action: 'breakEnd',

package/lib/cjs/advertisement.js

@@ -9,6 +9,7 @@ var ssaiCreative = require('./units/ssai-creative.js');
 var ssaiProviders = require('./units/ssai-providers.js');
 var ssaiDetector = require('./units/ssai-detector.js');
 var ssaiAdBreak = require('./units/ssai-ad-break.js');
+var ssaiLog = require('./units/ssai-log.js');
 var ssaiPreload = require('./units/ssai-preload.js');
 
 class Advertisement extends sdkWebInterfaces.AbstractFeatureUnit {
@@ -124,10 +125,25 @@ class Advertisement extends sdkWebInterfaces.AbstractFeatureUnit {
             const provider = ssaiProviders.resolveProvider(options.provider);
             const cache = new ssaiCreative.SsaiCreativeCache(provider);
             this.ssaiCache = cache;
+            /**
+             * Every beacon the SDK fires gets a line, with the URL it was fired at.
+             * The narrative log is read as a live trace of one ad, and "we called the
+             * ad server's own tracking URL" is as much of the story as the request
+             * that fetched the creative in the first place.
+             */
+            const logBeacon = (creativeId, event) => {
+                const url = cache.peek(creativeId)?.trackingEvents?.find((entry) => entry.event === event)?.url;
+                ssaiLog.ssaiq.info({ creativeId, event, url }, `[beacon] ${event} fired — ${creativeId}`);
+            };
             this.fireSsaiImpression = (creativeId) => {
+                // The UI only calls this once the bar is actually rendered, so this is
+                // the moment the viewer saw the ad — not the moment it resolved.
+                ssaiLog.ssaiq.info({ creativeId }, `[ad] ad on screen — ${cache.peek(creativeId)?.advertiser || creativeId}`);
+                logBeacon(creativeId, 'impression');
                 cache.fireImpressionById(creativeId);
             };
             this.fireSsaiTracking = (creativeId, event) => {
+                logBeacon(creativeId, event);
                 cache.fireTrackingById(creativeId, event);
             };
             this.fireSsaiCompanionClick = (creativeId) => {
@@ -147,12 +163,14 @@ class Advertisement extends sdkWebInterfaces.AbstractFeatureUnit {
             const prefetchCreative = (creativeId) => {
                 cache
                     .resolve(creativeId)
-                    .then((creative) => ssaiPreload.preloadCreativeAssets(creative))
-                    .then(() => {
+                    .then((creative) => ssaiPreload.preloadCreativeAssets(creative).then(() => creative))
+                    .then((creative) => {
                     preloadedIds.add(creativeId);
+                    ssaiLog.ssaiq.info({ creativeId }, `[ad] creative ready — ${creative.advertiser} (artwork preloaded)`);
                 })
-                    .catch((error) => {
-                    this.log.debug(error, 'ssai creative prefetch failed');
+                    .catch(() => {
+                    // Already on `ssaiq` from the provider; the break may still be
+                    // minutes away, and `loadCreative` retries when it actually starts.
                 });
             };
             const publishReady = (range, creative) => {
@@ -217,11 +235,9 @@ class Advertisement extends sdkWebInterfaces.AbstractFeatureUnit {
                 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');
                     sdkWebInterfaces.eventBus.emit('ssaiAdBreak', {
                         action: 'breakStart',
                         payload: { creativeId: range.creativeId },
@@ -229,7 +245,6 @@ class Advertisement extends sdkWebInterfaces.AbstractFeatureUnit {
                     loadCreative(range);
                 },
                 onCreativeChange: (range) => {
-                    this.log.debug({ creativeId: range.creativeId }, 'ssai creative change');
                     loadCreative(range);
                 },
                 onAdEnding: (range) => {
@@ -242,11 +257,11 @@ class Advertisement extends sdkWebInterfaces.AbstractFeatureUnit {
                     this.ssaiAdBreak.set({ ...current, status: 'ending' });
                 },
                 onProgress: (range, event) => {
-                    this.log.debug({ creativeId: range.creativeId, event }, 'ssai progress');
+                    // Logged by the detector as `progress:<event>` at the moment playback
+                    // crosses the marker; nothing to add here.
                     cache.fireTrackingById(range.creativeId, event);
                 },
                 onBreakEnd: () => {
-                    this.log.debug('ssai break end');
                     const current = this.ssaiAdBreak.get();
                     sdkWebInterfaces.eventBus.emit('ssaiAdBreak', {
                         action: 'breakEnd',

package/lib/cjs/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="../vast-client.d.ts" />
 import { StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
 declare module '@streamlayer/sdk-web-interfaces' {
     interface StreamLayerSDK {
@@ -9,6 +10,7 @@ export { type GAMStaticCore, type PauseAdTemplate, isFullbleedVideoTemplate } fr
 export { INSIGHT_BODY_MAX_LENGTH, type PauseAdCard, type PauseAdKind, type PauseAdMediaMode, } from './units/pause-ad-card.js';
 export { type PauseAdStore } from './units/pause-ad.js';
 export { type AdStore, type AdData, type AdCompanion, type AdNonLinear } from './units/external-ad.js';
+export { selectSponsorLogo, type SponsorLogoAsset } from './units/sponsor-logo.js';
 export { gam, type GamNonceResult, type PalNonceManager } from './units/gam.js';
 export { createCompanionTracker, createVastTracker, resolveVastTrackerTarget, type VastTrackerTarget, } from './units/vast-tracker.js';
 export { type SsaiCreative, type SsaiTrackingEvent, type SsaiCompanion, type SsaiProgressEvent, DEFAULT_CREATIVE_API_BASE, } from './units/ssai-creative.js';

package/lib/cjs/index.js

@@ -3,6 +3,7 @@
 var advertisement$1 = require('./advertisement.js');
 var externalPauseAd = require('./units/external-pause-ad.js');
 var pauseAdCard = require('./units/pause-ad-card.js');
+var sponsorLogo = require('./units/sponsor-logo.js');
 var gam = require('./units/gam.js');
 var vastTracker = require('./units/vast-tracker.js');
 var ssaiProviders = require('./units/ssai-providers.js');
@@ -21,6 +22,7 @@ const advertisement = (instance, _opts, done) => {
 
 exports.isFullbleedVideoTemplate = externalPauseAd.isFullbleedVideoTemplate;
 exports.INSIGHT_BODY_MAX_LENGTH = pauseAdCard.INSIGHT_BODY_MAX_LENGTH;
+exports.selectSponsorLogo = sponsorLogo.selectSponsorLogo;
 exports.gam = gam.gam;
 exports.createCompanionTracker = vastTracker.createCompanionTracker;
 exports.createVastTracker = vastTracker.createVastTracker;

package/lib/cjs/units/ad-macros.d.ts

@@ -0,0 +1,7 @@
+import type { AdTagParams } from '@streamlayer/sdk-web-core';
+/**
+ * Fill the macros this SDK knows in an ad-tag URL. One timestamp per call, so a tag naming the macro
+ * twice stays self-consistent. `params` is read as given — the caller passes the host's CURRENT
+ * values at request time.
+ */
+export declare const substituteAdTagMacros: (url: string, params?: AdTagParams) => string;

package/lib/cjs/units/ad-macros.js

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * Ad-tag macro substitution, for every ad server — not just GAM.
+ *
+ * Studio stores a programmatic tag verbatim (`gamRawUrl`, returned untouched by
+ * `processGamAdvertisement`), so whatever macros the ad server's own tag builder emitted reach the
+ * SDK literal. `gam()` used to fill only the GAM `[placeholder]` token, and only for
+ * `pubads.g.doubleclick.net` — every other vendor's tag went out with its macros unexpanded.
+ *
+ * That is not inert. Measured against the ADITION tag on event 11089
+ * (`…/banner?…&ts=[timestamp]&clickurl=[clickmacro]`): ADITION prepends the value of `clickurl` to
+ * its own redi URL, so a literal `[clickmacro]` came back inside `<CompanionClickThrough>` as
+ * `[clickmacro]https%3A%2F%2Fad1…` — a broken click-through. Sending `clickurl=` empty answers with
+ * a valid redi URL.
+ *
+ * **Two sources.** The cache buster is the SDK's own. The consent family — `${GDPR}` and
+ * `${GDPR_CONSENT_<gvlid>}`, IAB TCF, where the id is the vendor's Global Vendor List entry (39 is
+ * ADITION / Virtual Minds) — and the click macro come from the host app (`AdTagParams`, set through
+ * the `adTagParams` option or `sdk.setAdTagParams`). The SDK never reads a CMP and never guesses
+ * consent: a value the host did not pass goes out EMPTY, which ad servers read as "unknown" — never
+ * as `gdpr=0`. Empty rather than literal because a literal is not inert either: ADITION copied
+ * `${GDPR}` into its own redirect URL (`gdpr%3D%24%7BGDPR%7D`). See
+ * `docs/wiki/programmatic-ads-macros.md`.
+ *
+ * An unknown macro is left exactly as configured, which is what keeps the GAM `[placeholder]`
+ * tokens for the PAL path (`gam.ts` fills those per parameter, not per token).
+ */
+/**
+ * All three spellings in the wild — `[NAME]` (IAB / SpotX), `${NAME}` (Google) and bare `{NAME}` —
+ * each with its delimiters either literal or PERCENT-ENCODED.
+ *
+ * Neither half of that is theoretical. ADITION emitted `[timestamp]` / `[clickmacro]` for the
+ * campaign on event 11089 and `{CACHEBUSTER}` / `{GDPR}` for the one on 6203 — same ad server, same
+ * advertiser, different tag builder. And Studio stores the 6203 tag as `ts=%7BCACHEBUSTER%7D`, so
+ * matching only literal braces made the whole substitution a silent no-op on it: an unexpanded
+ * macro raises no error and the ad server still answers 200. `searchParams.get()` decodes on read,
+ * which is what hides the encoding from anyone inspecting the parsed URL.
+ *
+ * The `$` is optional rather than a fourth branch — an unowned `${NAME}` still returns its full
+ * matched text, `$` included, so the brace forms cannot corrupt each other.
+ */
+const MACRO_PATTERN = /(?:\[|%5B)([a-z0-9_]+)(?:\]|%5D)|(?:\$|%24)?(?:\{|%7B)([a-z0-9_]+)(?:\}|%7D)/gi;
+/**
+ * Every host value lands inside a query-string VALUE, so it is encoded exactly once. That matters
+ * most for the click URL, which carries its own `?`/`&`: sent raw it re-opens the tag's query, the
+ * way the malformed 6203 tag did (`clickurl` truncated, every following parameter duplicated).
+ */
+const hostValue = (value) => (value ? encodeURIComponent(value) : '');
+const gdprConsent = ({ params }) => hostValue(params?.tcString);
+/**
+ * Macro name (lower-cased) → the value this SDK sends for it.
+ *
+ * `clickurl` / `clickmacro` take the host's click tracker, which the ad server PREPENDS to its own
+ * redirect — so the viewer's click passes host tracker → vendor redirect → landing page. The SDK
+ * does not fire that tracker itself; it would count the click twice. Without one it is empty, the
+ * documented "no player tracker" value. VAST click beacons are reported separately by
+ * `useSidebarVastTracker`.
+ */
+const MACRO_VALUES = {
+    // One family, one value: every name here means "make this request unique so nothing caches it".
+    // Epoch milliseconds satisfies that for all of them, and keeps the value already shipped for
+    // `timestamp` unchanged. (IAB defines `[CACHEBUSTING]` as a random 8-digit number and
+    // `[TIMESTAMP]` as ISO-8601, but those describe VAST *tracking* URLs; this substitution only
+    // ever touches the ad REQUEST url, where every ad server documents the parameter as a number.)
+    timestamp: ({ now }) => String(now),
+    cachebuster: ({ now }) => String(now),
+    cachebusting: ({ now }) => String(now),
+    clickmacro: ({ params }) => hostValue(params?.clickUrl),
+    clickurl: ({ params }) => hostValue(params?.clickUrl),
+    // `1` / `0` only from an explicit boolean — an absent value is unknown, not "does not apply".
+    gdpr: ({ params }) => (params?.gdprApplies === undefined ? '' : params.gdprApplies ? '1' : '0'),
+    gdpr_consent: gdprConsent,
+};
+/** `GDPR_CONSENT_<gvlid>`: the vendor id names whose tag this is; the value is the same TC string. */
+const GDPR_CONSENT_FOR_VENDOR = /^gdpr_consent_\d+$/;
+const resolveMacro = (name) => MACRO_VALUES[name] ?? (GDPR_CONSENT_FOR_VENDOR.test(name) ? gdprConsent : undefined);
+/**
+ * Fill the macros this SDK knows in an ad-tag URL. One timestamp per call, so a tag naming the macro
+ * twice stays self-consistent. `params` is read as given — the caller passes the host's CURRENT
+ * values at request time.
+ */
+const substituteAdTagMacros = (url, params) => {
+    const now = Date.now();
+    return url.replace(MACRO_PATTERN, (match, bracketed, braced) => {
+        const value = resolveMacro((bracketed ?? braced ?? '').toLowerCase());
+        return value ? value({ now, params }) : match;
+    });
+};
+
+exports.substituteAdTagMacros = substituteAdTagMacros;

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

@@ -1,3 +1,4 @@
+import type { AdTagParams } from '@streamlayer/sdk-web-core';
 import { StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
 import { VastAd, VastCompanionAd, VastCreativeCompanion, VastCreativeLinear, VastCreativeNonLinear, VastNonLinearAd, VastResponse } from '@dailymotion/vast-client';
 import '@streamlayer/sdk-web-api';
@@ -35,6 +36,23 @@ export type AdData = {
     companion?: AdCompanion;
     /** The 300x75 `<Companion>` — the sponsor logo. Only set for a companion pair. */
     logo?: AdCompanion;
+    /**
+     * The iOS `SLRVASTSlotRole.cardLogo` pick: companion-only, aspect-scored toward 1:1, and minus
+     * whatever the hero slot already claimed. Consumed **only** by the hero-card placements
+     * (Side-by-Side / Picture in Picture / Sponsor Frame) as a fallback for an otherwise empty
+     * header logo. `logo` is the SC-335 display rule and is unchanged; when it fires, this stays
+     * `undefined` because the display rule already won the slot.
+     */
+    cardLogo?: AdCompanion;
+    /**
+     * The tag's ONLY `<Companion>`, when it is exactly 300x75 and the hero is a Linear or a
+     * NonLinear — i.e. the companion is logo-sized and nothing else needs it. The pair rule behind
+     * `logo` exists to tell the logo from the media among companions; with the media coming from
+     * elsewhere there is nothing to tell apart, and iOS fills its logo from a single companion.
+     * Consumed only by the Standard Ad Sidebar (`createActiveAdFromVast`) as a header-logo fallback;
+     * a companion-only tag leaves it `undefined`, because there the companion IS the media.
+     */
+    loneLogo?: 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. */
@@ -55,4 +73,55 @@ export type AdStore = {
     muted: boolean;
     nonceManager?: PalNonceManager;
 };
+/**
+ * Split a `<CompanionAds>` creative's variations into the logo and media slots.
+ *
+ * The pair mapping activates only for a tag that ships an exact 300x75 companion next to at
+ * least one other. Deliberately conservative pending broader product sizes: on any other tag
+ * no companion is promoted to the logo slot and the first one stays the media/strip candidate.
+ *
+ * Both halves of that gate are load-bearing and neither is an aspect rule: a 320x80 companion is
+ * the same 4:1 shape as 300x75 and is still rejected, and a lone 300x75 companion is rejected too
+ * (the Standard Ad Sidebar recovers that one as `AdData.loneLogo` when a Linear / NonLinear is
+ * the media, so it is not needed here).
+ * This is **narrower than iOS**, which has no size rule at all and fills its logo slot from a
+ * single companion — see `docs/wiki/programmatic-ads-display-ios-parity.md`. Exported for
+ * `external-ad.spec.ts` only; `src/index.ts` re-exports names explicitly, so this stays out of the
+ * package's public API.
+ */
+export declare const selectCompanions: (companions: AdCompanion[]) => {
+    logo: undefined;
+    media: AdCompanion;
+} | {
+    logo: AdCompanion;
+    media: AdCompanion | undefined;
+};
+/**
+ * Map a parsed VAST response into our `AdData` shape. Shared by both acquisition
+ * paths — the GAM/VMAP tag flow and the Prebid auction flow — so the two always
+ * produce identical downstream data.
+ *
+ * Returns `undefined` for a no-ad, which is two distinct shapes: a response with no ad carrying
+ * creatives, and an ad whose creatives carry no RENDERABLE asset — no linear `<MediaFile>`, no
+ * `<NonLinear>` still and no `<Companion>` image. Both callers `filter(Boolean)` the result, so a
+ * no-ad leaves `ads: []` and the card keeps whatever the server configured for it.
+ *
+ * Exported for `vast-mapping.spec.ts`, which drives it over the same fixture corpus the iOS suite
+ * uses. `src/index.ts` re-exports names explicitly, so this stays out of the package's public API.
+ */
+export declare const buildAdData: (parsedVAST: VastResponse, order: number) => AdData | undefined;
+/**
+ * Build the OpenRTB request body for a single video auction. Placement config is
+ * carried on the Prebid link's query string so the consumer-facing interface stays a
+ * single URL string:
+ * - `configId` → `imp.ext.prebid.storedrequest.id` (production stored request).
+ * - `storedauctionresponse` → `imp.ext.prebid.storedauctionresponse.id` (staging mock).
+ * - `test=1` → top-level `test` flag.
+ * - `w` / `h` → video dimensions (default 1920×1080).
+ *
+ * The host's GDPR consent (`AdTagParams`) rides the OpenRTB 2.5 extension fields Prebid Server
+ * reads — `regs.ext.gdpr` and `user.ext.consent` — the same signal the `${GDPR}` /
+ * `${GDPR_CONSENT}` macros carry for a VAST tag. Each is sent only when the host passed it.
+ */
+export declare const buildAuctionRequest: (url: URL, adTagParams?: AdTagParams) => Record<string, unknown>;
 export declare const externalAd: (instance: StreamLayerContext) => (gamUrl: string) => import("@nanostores/query", { with: { "resolution-mode": "import" } }).FetcherStore<AdStore | undefined, any>;

package/lib/cjs/units/external-ad.js

@@ -6,6 +6,7 @@ require('@streamlayer/sdk-web-api');
 var VMAP = require('vmap');
 var gam = require('./gam.js');
 var parseVastExtensions = require('./parse-vast-extensions.js');
+var sponsorLogo = require('./sponsor-logo.js');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -45,7 +46,7 @@ const withTimeout = (promise, ms) => {
  * Get the first valid creative from an ad
  */
 const getCreative = (ad) => {
-    return ad.creatives.find((creative) => creative.mediaFiles);
+    return ad.creatives.find((creative) => getMediaFileUrl(creative));
 };
 /**
  * Get the URL of the first media file in the creative
@@ -66,31 +67,10 @@ const getClickThrough = (creative) => {
     // @ts-ignore — vast-client types `videoClickThroughURLTemplate` loosely
     return creative?.videoClickThroughURLTemplate?.url || undefined;
 };
-/**
- * Extract every `<Companion>` variation of the first `<CompanionAds>` creative that carries a
- * `<StaticResource>`, in document order. `width`/`height` are XML attributes (strings at
- * runtime), normalised to numbers so the size mapping can compare them.
- */
-const getCompanions = (ad) => {
-    const creative = ad.creatives.find((item) => item.type === 'companion');
-    return (creative?.variations || []).reduce((acc, variation) => {
-        const imageUrl = variation?.staticResources?.[0]?.url;
-        if (!imageUrl) {
-            return acc;
-        }
-        return acc.concat({
-            imageUrl,
-            clickUrl: variation.companionClickThroughURLTemplate ?? undefined,
-            width: Number(variation.width) || undefined,
-            height: Number(variation.height) || undefined,
-            creative,
-            variation,
-        });
-    }, []);
-};
 /** Product companion mapping: the 300x75 companion is the logo, the banner-sized one the media. */
 const LOGO_COMPANION_WIDTH = 300;
 const LOGO_COMPANION_HEIGHT = 75;
+const isLogoSized = (companion) => companion?.width === LOGO_COMPANION_WIDTH && companion?.height === LOGO_COMPANION_HEIGHT;
 const companionArea = (companion) => (companion.width || 0) * (companion.height || 0);
 /**
  * Split a `<CompanionAds>` creative's variations into the logo and media slots.
@@ -98,11 +78,18 @@ const companionArea = (companion) => (companion.width || 0) * (companion.height
  * The pair mapping activates only for a tag that ships an exact 300x75 companion next to at
  * least one other. Deliberately conservative pending broader product sizes: on any other tag
  * no companion is promoted to the logo slot and the first one stays the media/strip candidate.
+ *
+ * Both halves of that gate are load-bearing and neither is an aspect rule: a 320x80 companion is
+ * the same 4:1 shape as 300x75 and is still rejected, and a lone 300x75 companion is rejected too
+ * (the Standard Ad Sidebar recovers that one as `AdData.loneLogo` when a Linear / NonLinear is
+ * the media, so it is not needed here).
+ * This is **narrower than iOS**, which has no size rule at all and fills its logo slot from a
+ * single companion — see `docs/wiki/programmatic-ads-display-ios-parity.md`. Exported for
+ * `external-ad.spec.ts` only; `src/index.ts` re-exports names explicitly, so this stays out of the
+ * package's public API.
  */
 const selectCompanions = (companions) => {
-    const logo = companions.length > 1
-        ? companions.find((companion) => companion.width === LOGO_COMPANION_WIDTH && companion.height === LOGO_COMPANION_HEIGHT)
-        : undefined;
+    const logo = companions.length > 1 ? companions.find((companion) => isLogoSized(companion)) : undefined;
     if (!logo) {
         return { logo: undefined, media: companions[0] };
     }
@@ -112,40 +99,26 @@ const selectCompanions = (companions) => {
         .pop();
     return { logo, media };
 };
-/**
- * Extract the first `<NonLinearAds>` creative's static-image variation. Both the creative (which
- * owns the `<TrackingEvents>`) and the variation (which owns the click-through) are kept —
- * `VASTTracker` needs both.
- *
- * `@dailymotion/vast-client` 6.4.2 emits `nonlinearClickThroughURLTemplate` (lower-case `l`),
- * which the `@types/vast-client` shim declares as `nonLinearClickThroughURLTemplate` — the
- * runtime spelling is authoritative.
- */
-const getNonLinear = (ad) => {
-    const creative = ad.creatives.find((item) => item.type === 'nonlinear');
-    const variation = creative?.variations?.[0];
-    const imageUrl = variation?.staticResource;
-    if (!creative || !variation || !imageUrl) {
-        return undefined;
-    }
-    return {
-        imageUrl,
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore — see the runtime-vs-shim spelling note above
-        clickUrl: variation.nonlinearClickThroughURLTemplate ?? undefined,
-        width: Number(variation.width) || undefined,
-        height: Number(variation.height) || undefined,
-        creative,
-        variation,
-    };
-};
 /**
  * Map a parsed VAST response into our `AdData` shape. Shared by both acquisition
  * paths — the GAM/VMAP tag flow and the Prebid auction flow — so the two always
- * produce identical downstream data. Returns `undefined` when the response has no
- * ad carrying creatives.
+ * produce identical downstream data.
+ *
+ * Returns `undefined` for a no-ad, which is two distinct shapes: a response with no ad carrying
+ * creatives, and an ad whose creatives carry no RENDERABLE asset — no linear `<MediaFile>`, no
+ * `<NonLinear>` still and no `<Companion>` image. Both callers `filter(Boolean)` the result, so a
+ * no-ad leaves `ads: []` and the card keeps whatever the server configured for it.
+ *
+ * Exported for `vast-mapping.spec.ts`, which drives it over the same fixture corpus the iOS suite
+ * uses. `src/index.ts` re-exports names explicitly, so this stays out of the package's public API.
  */
 const buildAdData = (parsedVAST, order) => {
+    // Defensive, and unreachable through either production path: `@dailymotion/vast-client` discards
+    // an ad whose creatives all fail to parse (empty `<Linear>`, empty/missing `<Creatives>`, unknown
+    // creative element) before `parseVAST` resolves, so it never yields an Ad with zero creatives.
+    // Kept because it costs nothing and `buildAdData` is also reachable from tests with a hand-built
+    // response — see the `invalid_ad` case in `vast-mapping.spec.ts`, which pins the parser contract
+    // this relies on rather than pretending to exercise the guard.
     const validAd = parsedVAST.ads.find((ads) => ads.creatives.length > 0);
     if (!validAd) {
         log.warn({ order, ads: parsedVAST.ads.length }, 'vast response carries no ad with creatives — treated as no-ad');
@@ -157,10 +130,47 @@ const buildAdData = (parsedVAST, order) => {
     const parsedExtension = parseVastExtensions.parseVastExtension(extension);
     const creative = getCreative(validAd);
     const mediaFileUrl = getMediaFileUrl(creative);
-    const companions = getCompanions(validAd);
+    const images = sponsorLogo.collectAssets(validAd);
+    const companions = images.filter((asset) => asset.origin === 'companion');
+    const nonLinear = images.find((asset) => asset.origin === 'nonlinear');
+    // An ad the parser KEPT whose creatives carry nothing any shell can draw is a no-ad, exactly
+    // like a response with no ad at all. vast-client only discards a creative it cannot parse; a
+    // `<NonLinear>` or `<Companion>` whose `<StaticResource>` body is empty parses fine and just
+    // yields no url, so the guard above cannot catch it. Without this the fabricated promotion still
+    // took the slot and drew the ad's TEXT — title and description over an empty media box — which
+    // is a billable impression for a creative that does not exist.
+    //
+    // "Renderable" is the union of the three slots the shells can fill: a linear `<MediaFile>`, a
+    // `<NonLinear>` still, or a `<Companion>` image. `collectAssets` already drops the imageless
+    // ones, so a non-empty `companions` means at least one drawable image. A tag carrying only a
+    // `<Mezzanine>` never reaches here — the parser drops that Linear itself — but it lands in the
+    // same place either way.
+    if (!mediaFileUrl && !nonLinear && companions.length === 0) {
+        log.warn({ order, adId: validAd.id, creatives: validAd.creatives.length }, 'vast ad carries no renderable asset (no media file, no nonlinear, no companion) — treated as no-ad');
+        return undefined;
+    }
     const { logo, media: mediaCompanion } = selectCompanions(companions);
-    const nonLinear = getNonLinear(validAd);
     const clickThrough = getClickThrough(creative) || nonLinear?.clickUrl || mediaCompanion?.clickUrl;
+    // Mirror iOS's greedy `pool.select([hero, .cardLogo])`: the hero claims first and a claimed
+    // asset is gone for later roles. Web's hero precedence (`createActiveAdFromVast`) is linear
+    // video → pair media companion (unreachable here: a `logo` short-circuits the whole selection)
+    // → NonLinear still → lone companion, so a companion is only unavailable to the logo slot when
+    // it IS the hero, i.e. when the tag ships neither. `selectCardLogo` already filters to companion
+    // origins, so the NonLinear never needs excluding.
+    //
+    // Excluding `companions[0]` (which is what `mediaCompanion` is when there is no `logo`) rather
+    // than the largest-area asset is a deliberate difference from iOS's `areaDominant` hero: web's
+    // content slot draws the FIRST companion in document order, so document order is the correct
+    // criterion for "what the hero already claimed" on this platform.
+    const companionIsHero = !mediaFileUrl && !nonLinear;
+    const cardLogoAsset = logo ? undefined : sponsorLogo.selectCardLogo(validAd, companionIsHero ? [mediaCompanion] : []);
+    // Share the selected resource wrapper so drawn-companion identity remains stable.
+    const cardLogo = cardLogoAsset
+        ? companions.find((item) => item.variation === cardLogoAsset.variation && item.imageUrl === cardLogoAsset.imageUrl)
+        : undefined;
+    // Same collected instance as `companion` (identity matters to `drawnCompanions`). A lone
+    // companion never satisfies the pair rule, so this can only fill a slot `logo` left empty.
+    const loneLogo = companions.length === 1 && !companionIsHero && isLogoSized(companions[0]) ? companions[0] : undefined;
     log.info({
         order,
         adId: validAd.id,
@@ -176,6 +186,8 @@ const buildAdData = (parsedVAST, order) => {
             media: mediaCompanion
                 ? { size: `${mediaCompanion.width}x${mediaCompanion.height}`, url: mediaCompanion.imageUrl }
                 : undefined,
+            cardLogo: cardLogo ? { size: `${cardLogo.width}x${cardLogo.height}`, url: cardLogo.imageUrl } : undefined,
+            loneLogo: loneLogo ? { size: `${loneLogo.width}x${loneLogo.height}`, url: loneLogo.imageUrl } : undefined,
             clickThrough: !!clickThrough,
         },
     }, 'vast ad parsed');
@@ -185,6 +197,8 @@ const buildAdData = (parsedVAST, order) => {
         mediaFileUrl,
         companion: companions[0],
         logo,
+        cardLogo,
+        loneLogo,
         mediaCompanion,
         nonLinear,
         clickThrough,
@@ -213,8 +227,12 @@ const createRequestId = () => `sl-web-${Date.now().toString(36)}-${Math.random()
  * - `storedauctionresponse` → `imp.ext.prebid.storedauctionresponse.id` (staging mock).
  * - `test=1` → top-level `test` flag.
  * - `w` / `h` → video dimensions (default 1920×1080).
+ *
+ * The host's GDPR consent (`AdTagParams`) rides the OpenRTB 2.5 extension fields Prebid Server
+ * reads — `regs.ext.gdpr` and `user.ext.consent` — the same signal the `${GDPR}` /
+ * `${GDPR_CONSENT}` macros carry for a VAST tag. Each is sent only when the host passed it.
  */
-const buildAuctionRequest = (url) => {
+const buildAuctionRequest = (url, adTagParams) => {
     const params = url.searchParams;
     const width = Number(params.get('w')) || 1920;
     const height = Number(params.get('h')) || 1080;
@@ -252,6 +270,12 @@ const buildAuctionRequest = (url) => {
     if (params.get('test') === '1') {
         request.test = 1;
     }
+    if (adTagParams?.gdprApplies !== undefined) {
+        request.regs = { ext: { gdpr: adTagParams.gdprApplies ? 1 : 0 } };
+    }
+    if (adTagParams?.tcString) {
+        request.user = { ext: { consent: adTagParams.tcString } };
+    }
     return request;
 };
 /**
@@ -259,11 +283,11 @@ const buildAuctionRequest = (url) => {
  * Every bid's `adm` is inline VAST XML (no URL to fetch); bids are ordered by price
  * so the winner plays first (RFC §2). A single bad bid must not drop the batch.
  */
-const fetchPrebidAds = async (prebidUrl) => {
+const fetchPrebidAds = async (prebidUrl, adTagParams) => {
     const response = await fetch(prebidUrl.toString(), {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(buildAuctionRequest(prebidUrl)),
+        body: JSON.stringify(buildAuctionRequest(prebidUrl, adTagParams)),
     });
     if (!response.ok) {
         throw new Error(`prebid auction failed with status ${response.status}`);
@@ -316,13 +340,17 @@ const externalAd = (instance) => {
                     return undefined;
                 }
             })();
+            // The host's CURRENT macro values, read per request rather than baked into the store: the
+            // store is cached by url for the session, and consent routinely arrives after the SDK
+            // starts (a CMP answers asynchronously) or changes mid-session.
+            const adTagParams = instance.sdk.options.get().adTagParams;
             // Prebid links hit our Prebid Server auction endpoint instead of a VAST tag.
             // Run the OpenRTB auction and parse the winning bid's inline VAST (`adm`) into
             // the same `AdStore` shape the GAM/VMAP path returns. See rfcs/prebid.
             if (parsedAdUrl && isPrebidUrl(parsedAdUrl)) {
-                return fetchPrebidAds(parsedAdUrl);
+                return fetchPrebidAds(parsedAdUrl, adTagParams);
             }
-            const generateUrl = gam.gam(adUrl);
+            const generateUrl = gam.gam(adUrl, undefined, adTagParams);
             const generatedUrl = await generateUrl();
             const noncedLink = generatedUrl?.url;
             if (!noncedLink) {
@@ -387,4 +415,7 @@ const externalAd = (instance) => {
     });
 };
 
+exports.buildAdData = buildAdData;
+exports.buildAuctionRequest = buildAuctionRequest;
 exports.externalAd = externalAd;
+exports.selectCompanions = selectCompanions;