@streamlayer/feature-advertisement 1.1.0 → 1.1.1-rc.10.p6eb7304a

package/lib/units/ad-macros.js

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+export 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;
+    });
+};

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

@@ -1,8 +1,9 @@
+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';
-import { type PalNonceManager } from './gam';
-import { VastCreative } from './parse-vast-extensions';
+import { type PalNonceManager } from './gam.js';
+import { VastCreative } from './parse-vast-extensions.js';
 export type AdCompanion = {
     imageUrl?: string;
     clickUrl?: string;
@@ -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").FetcherStore<AdStore | undefined, any>;

package/lib/units/external-ad.js

@@ -7,8 +7,9 @@ import { createLogger } from '@streamlayer/sdk-web-logger';
 import { VASTClient, VASTParser, } from '@dailymotion/vast-client';
 import '@streamlayer/sdk-web-api';
 import VMAP from 'vmap';
-import { gam } from './gam';
-import { parseVastExtension } from './parse-vast-extensions';
+import { gam } from './gam.js';
+import { parseVastExtension } from './parse-vast-extensions.js';
+import { collectAssets, selectCardLogo } from './sponsor-logo.js';
 const log = createLogger('ui:gam-external-ad');
 /** Default budget for a single VAST resolution before it is treated as "no ad". */
 const VAST_FETCH_TIMEOUT_MS = 10_000;
@@ -38,7 +39,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
@@ -59,31 +60,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.
@@ -91,11 +71,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;
+export const selectCompanions = (companions) => {
+    const logo = companions.length > 1 ? companions.find((companion) => isLogoSized(companion)) : undefined;
     if (!logo) {
         return { logo: undefined, media: companions[0] };
     }
@@ -105,40 +92,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) => {
+export 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');
@@ -150,10 +123,47 @@ const buildAdData = (parsedVAST, order) => {
     const parsedExtension = parseVastExtension(extension);
     const creative = getCreative(validAd);
     const mediaFileUrl = getMediaFileUrl(creative);
-    const companions = getCompanions(validAd);
+    const images = 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 : 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,
@@ -169,6 +179,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');
@@ -178,6 +190,8 @@ const buildAdData = (parsedVAST, order) => {
         mediaFileUrl,
         companion: companions[0],
         logo,
+        cardLogo,
+        loneLogo,
         mediaCompanion,
         nonLinear,
         clickThrough,
@@ -206,8 +220,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) => {
+export const buildAuctionRequest = (url, adTagParams) => {
     const params = url.searchParams;
     const width = Number(params.get('w')) || 1920;
     const height = Number(params.get('h')) || 1080;
@@ -245,6 +263,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;
 };
 /**
@@ -252,11 +276,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}`);
@@ -309,13 +333,17 @@ export 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(adUrl);
+            const generateUrl = gam(adUrl, undefined, adTagParams);
             const generatedUrl = await generateUrl();
             const noncedLink = generatedUrl?.url;
             if (!noncedLink) {

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

@@ -7,6 +7,7 @@ import { eventBus } from '@streamlayer/sdk-web-interfaces';
 import { createLogger } from '@streamlayer/sdk-web-logger';
 import '@streamlayer/sdk-web-api';
 import { VASTClient } from '@dailymotion/vast-client';
+import { substituteAdTagMacros } from './ad-macros.js';
 const FULLBLEED_VIDEO_TEMPLATES = [
     'fullbleed-video',
     'fullbleed-video-center',
@@ -115,7 +116,12 @@ export const externalPauseAd = (instance) => {
             try {
                 // `resolveAll: true` follows every `VASTAdTagURI` wrapper chain and resolves all
                 // Ads (the default only resolves the first standalone Ad and stops at the wrapper).
-                const parsedVAST = await vastClient.get(adUrl, { resolveAll: true });
+                // Pause-ad tags do not go through `gam()`, so fill the macros here — with the host's values
+                // as they are NOW, since this fetcher re-runs on every pause. The store key stays the
+                // configured url: `ExposedPauseAd` compares against it.
+                const parsedVAST = await vastClient.get(substituteAdTagMacros(adUrl, instance.sdk.options.get().adTagParams), {
+                    resolveAll: true,
+                });
                 const template = options.template ?? 'default';
                 // `fullbleed-video` needs an ad that actually carries a usable linear MP4. With
                 // `resolveAll: true` the response can be a pod/wrapper chain, so prefer the first

package/lib/units/gam.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Google PAL nonce manager + ad-tag resolution for programmatic (GAM) VAST requests.
+ *
+ * Lives here because the VAST fetcher (`units/external-ad.ts`) is its only consumer: this is the
+ * request side of an ad tag, not the promotion side. The *composition* of a tag URL from the proto
+ * (`processGamAdvertisement` / `selectGamOptions`) stays in `feature-gamification`, next to the
+ * `$store` bridge that is its only consumer — so the two feature packages share no code and
+ * neither depends on the other.
+ */
+import type { AdTagParams } from '@streamlayer/sdk-web-core';
 export type PalNonceManager = {
     getNonce: () => string;
     sendAdClick: () => void;
@@ -8,7 +18,7 @@ export type GamNonceResult = {
     url: URL;
     manager?: PalNonceManager;
 };
-export declare const gam: (url: string, adContainer?: HTMLDivElement) => (() => Promise<{
+export declare const gam: (rawUrl: string, adContainer?: HTMLDivElement, adTagParams?: AdTagParams) => (() => Promise<{
     url: URL;
 }>) | (() => Promise<{
     url: URL;

package/lib/units/gam.js

@@ -1,18 +1,67 @@
-/**
- * Google PAL nonce manager + ad-tag resolution for programmatic (GAM) VAST requests.
- *
- * Lives here because the VAST fetcher (`units/external-ad.ts`) is its only consumer: this is the
- * request side of an ad tag, not the promotion side. The *composition* of a tag URL from the proto
- * (`processGamAdvertisement` / `selectGamOptions`) stays in `feature-gamification`, next to the
- * `$store` bridge that is its only consumer — so the two feature packages share no code and
- * neither depends on the other.
- */
 import { safeLocalStorage, safeSessionStorage } from '@streamlayer/sdk-web-storage';
 import { validate as uuidValidate, v5 as uuid5, v4 as uuid4 } from 'uuid';
+import { substituteAdTagMacros } from './ad-macros.js';
 const urlIsNotGam = (url) => {
     return url.origin !== 'https://pubads.g.doubleclick.net';
 };
-export const gam = (url, adContainer) => {
+const palScriptUrl = 'https://imasdk.googleapis.com/pal/sdkloader/pal.js';
+const getPal = () => {
+    // @ts-expect-error Google PAL is supplied by the host or the script loader below.
+    return typeof goog === 'undefined' ? undefined : goog.pal;
+};
+let palReady;
+const ensurePal = async () => {
+    if (getPal()) {
+        return;
+    }
+    if (!palReady) {
+        palReady = new Promise((resolve, reject) => {
+            if (typeof document === 'undefined') {
+                reject(new Error('Google PAL requires a browser document'));
+                return;
+            }
+            const existing = document.querySelector(`script[src="${palScriptUrl}"]`);
+            const script = existing || document.createElement('script');
+            const finish = (error) => {
+                clearTimeout(timeout);
+                script.removeEventListener('load', onLoad);
+                script.removeEventListener('error', onError);
+                if (error) {
+                    if (!existing) {
+                        script.remove();
+                    }
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            };
+            const onLoad = () => finish(getPal() ? undefined : new Error('Google PAL did not initialize'));
+            const onError = () => finish(new Error('Google PAL failed to load'));
+            const timeout = setTimeout(() => finish(new Error('Google PAL loading timed out')), 10000);
+            script.addEventListener('load', onLoad);
+            script.addEventListener('error', onError);
+            if (!existing) {
+                script.async = true;
+                script.src = palScriptUrl;
+                document.head.appendChild(script);
+            }
+        }).catch((error) => {
+            palReady = undefined;
+            throw error;
+        });
+    }
+    await palReady;
+    palReady = undefined;
+};
+export const gam = (rawUrl, adContainer, adTagParams) => {
+    // Every VAST/VMAP tag funnels through here, so this is where the macros get filled — for GAM and
+    // for any other vendor alike. Studio stores a programmatic tag verbatim, so an unexpanded
+    // `[timestamp]` / `[clickmacro]` / `${GDPR}` would otherwise reach the ad server literal, and a
+    // literal macro comes back copied into the vendor's click-through. `adTagParams` are the host's
+    // consent and click values, read by the caller at request time. The GAM `[placeholder]` tokens
+    // are left alone here and filled per parameter below.
+    const url = substituteAdTagMacros(rawUrl, adTagParams);
     const parsedUrl = (() => {
         try {
             const parsedUrl = new URL(url);
@@ -32,20 +81,19 @@ export const gam = (url, adContainer) => {
             return { url: parsedUrl };
         };
     }
-    // @ts-expect-error goog is injected by the externally-loaded Google PAL SDK
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const pal = (typeof goog === 'undefined' ? undefined : goog.pal);
-    if (!pal || !parsedUrl) {
+    if (!parsedUrl) {
         // eslint-disable-next-line require-await
         return async () => {
             return undefined;
         };
     }
-    const consentSettings = new pal.ConsentSettings();
-    consentSettings.allowStorage = false;
-    const nonceLoader = new pal.NonceLoader(consentSettings);
     const generateUrl = async () => {
         try {
+            await ensurePal();
+            const pal = getPal();
+            const consentSettings = new pal.ConsentSettings();
+            consentSettings.allowStorage = false;
+            const nonceLoader = new pal.NonceLoader(consentSettings);
             const parsedUrl = new URL(url);
             const request = new pal.NonceRequest();
             let deviceId = safeLocalStorage().getItem('sl-device-id') || uuid4();

package/lib/units/parse-vast-extensions.d.ts

@@ -1,7 +1,16 @@
 import { AdType } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
 export interface VastCreative {
     adName: string;
-    adType: AdType;
+    /**
+     * The placement this extension NAMES, or `undefined` when its root element is not one we map.
+     *
+     * Deliberately not defaulted here. An unrecognised extension means "this tag says nothing about
+     * placement", which must not outrank a placement the promotion proto already stated — defaulting
+     * it to `SIDE_BY_SIDE` at this layer silently re-routed a configured Sidebar/L-Bar, because the
+     * consumers join with `extension?.adType ?? placement`. The default now lives in
+     * `resolveExternalAdType`, applied only after the proto placement has had its turn.
+     */
+    adType?: AdType;
     landscapeBackground?: string;
     portraitBackground?: string;
     sponsorLogo?: string;

package/lib/units/parse-vast-extensions.js

@@ -1,4 +1,8 @@
 import { AdType } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
+/**
+ * Extension root element name → the placement it names. Only `DoubleBox` is defined by the
+ * StreamLayer extension schema today; anything else is a vendor extension we do not interpret.
+ */
 const MAP_EXTENSION_NAME_AD_TYPE = {
     DoubleBox: AdType.SIDE_BY_SIDE,
 };
@@ -38,7 +42,7 @@ export function parseVastExtension(root) {
     };
     return {
         adName,
-        adType: MAP_EXTENSION_NAME_AD_TYPE[root.name] || AdType.SIDE_BY_SIDE,
+        adType: MAP_EXTENSION_NAME_AD_TYPE[root.name],
         landscapeBackground: backgrounds.find((b) => b.orientation === 'landscape')?.url,
         portraitBackground: backgrounds.find((b) => b.orientation === 'portrait')?.url,
         sponsorLogo: logos.find((l) => l.role === 'header')?.url,

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

@@ -1,7 +1,7 @@
 import { createSingleStore, StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
 import '@streamlayer/sdk-web-api';
 import '@streamlayer/sdk-web-core/store';
-import { type PauseAdCard } from './pause-ad-card';
+import { type PauseAdCard } from './pause-ad-card.js';
 export type PauseAdListOptions = {
     refetchInterval: number;
     $enabled: boolean;

package/lib/units/pause-ad.js

@@ -3,7 +3,7 @@ import { atom } from 'nanostores';
 import '@streamlayer/sdk-web-api';
 import '@streamlayer/sdk-web-core/store';
 import { Feed } from '@streamlayer/sl-eslib/interactive/feed/interactive.feed_pb';
-import { parsePauseAdCards } from './pause-ad-card';
+import { parsePauseAdCards } from './pause-ad-card.js';
 const log = createLogger('advertisement:pause-ad');
 export const pauseAdListStore = (instance) => {
     const $slStreamId = instance.stores.slStreamId.getAtomStore();