Resolve server-side ad template review issues

Author: prk-Jr

.env.example

@@ -37,7 +37,7 @@ TRUSTED_SERVER__REQUEST_SIGNING__ENABLED=false
 
 # Prebid
 TRUSTED_SERVER__INTEGRATIONS__PREBID__ENABLED=false
-# TRUSTED_SERVER__INTEGRATIONS__PREBID__SERVER_URL=https://prebid-server.com/openrtb2/auction
+# TRUSTED_SERVER__INTEGRATIONS__PREBID__SERVER_URL=https://prebid-server.example.com/openrtb2/auction
 # TRUSTED_SERVER__INTEGRATIONS__PREBID__TIMEOUT_MS=1000
 # TRUSTED_SERVER__INTEGRATIONS__PREBID__BIDDERS=kargo,rubicon,appnexus
 # TRUSTED_SERVER__INTEGRATIONS__PREBID__BID_PARAM_OVERRIDES='{"bidder-name":{"param1":12345,"param2":"value"}}'

crates/js/lib/src/core/types.ts

@@ -98,6 +98,8 @@ export interface TsjsApi {
   servicesEnabled?: boolean;
   /** Maps actualDivId → slotId for slotRenderEnded billing lookup. */
   divToSlotId?: Record<string, string>;
+  /** Slot-level GPT targeting keys TS applied on the previous route. */
+  prevSlotTargetingKeys?: Record<string, string[]>;
   /** Guards SPA pushState hook installation. */
   spaHookInstalled?: boolean;
 }

crates/js/lib/src/integrations/gpt/index.ts

@@ -25,6 +25,14 @@ import { installGptGuard } from './script_guard';
  */
 
 const TS_INITIAL_TARGETING_KEY = 'ts_initial' as const;
+const TS_BID_TARGETING_KEYS = [
+  'hb_pb',
+  'hb_bidder',
+  'hb_adid',
+  'hb_cache_host',
+  'hb_cache_path',
+] as const;
+const TS_BASE_TARGETING_KEYS = [...TS_BID_TARGETING_KEYS, TS_INITIAL_TARGETING_KEY] as const;
 
 // ------------------------------------------------------------------
 // googletag type stubs (minimal surface needed by the shim)
@@ -34,6 +42,7 @@ interface GoogleTagSlot {
   getAdUnitPath(): string;
   getSlotElementId(): string;
   setTargeting(key: string, value: string | string[]): GoogleTagSlot;
+  clearTargeting?(key?: string): GoogleTagSlot;
   addService(service: GoogleTagPubAdsService): GoogleTagSlot;
   getTargeting?(key: string): string[];
 }
@@ -82,6 +91,14 @@ function messageSourceBelongsToConfiguredSlot(source: MessageEventSource | null)
   );
 }
 
+function clearTargetingKeys(slot: GoogleTagSlot, keys: Iterable<string>): void {
+  if (typeof slot.clearTargeting !== 'function') return;
+
+  for (const key of new Set(keys)) {
+    slot.clearTargeting(key);
+  }
+}
+
 interface GoogleTagPubAdsService {
   setTargeting(key: string, value: string | string[]): GoogleTagPubAdsService;
   getTargeting(key: string): string[];
@@ -333,6 +350,8 @@ export function installTsAdInit(): void {
       // All slots to refresh (TS-defined + publisher-owned reused).
       const slotsToRefresh: GoogleTagSlot[] = [];
       const divToSlotId: Record<string, string> = {};
+      const prevSlotTargetingKeys = ts.prevSlotTargetingKeys ?? {};
+      const nextSlotTargetingKeys: Record<string, string[]> = {};
 
       slots.forEach((slot) => {
         // Resolve actual div ID: exact match first, then prefix query.
@@ -363,19 +382,26 @@ export function installTsAdInit(): void {
           tsOwned = true;
         }
 
+        const slotDivId2 = gptSlot.getSlotElementId?.() ?? actualDivId;
+        clearTargetingKeys(gptSlot, [
+          ...TS_BASE_TARGETING_KEYS,
+          ...(prevSlotTargetingKeys[actualDivId] ?? []),
+          ...(prevSlotTargetingKeys[slotDivId2] ?? []),
+        ]);
+
         Object.entries(slot.targeting ?? {}).forEach(([k, v]) => gptSlot.setTargeting(k, v));
-        (['hb_pb', 'hb_bidder', 'hb_adid', 'hb_cache_host', 'hb_cache_path'] as const).forEach(
-          (key) => {
-            if (bid[key]) gptSlot.setTargeting(key, String(bid[key]!));
-          }
-        );
+        TS_BID_TARGETING_KEYS.forEach((key) => {
+          if (bid[key]) gptSlot.setTargeting(key, String(bid[key]!));
+        });
         gptSlot.setTargeting(TS_INITIAL_TARGETING_KEY, '1');
         // Map both inner div and container div → slot ID so slotRenderEnded
         // (which reports the GPT slot's div, i.e. slotDivId/container) can look up
         // the slot, while adm injection (which targets the inner div) also works.
         divToSlotId[actualDivId] = slot.id;
-        const slotDivId2 = gptSlot.getSlotElementId?.() ?? actualDivId;
         if (slotDivId2 !== actualDivId) divToSlotId[slotDivId2] = slot.id;
+        const slotTargetingKeys = Object.keys(slot.targeting ?? {});
+        nextSlotTargetingKeys[actualDivId] = slotTargetingKeys;
+        if (slotDivId2 !== actualDivId) nextSlotTargetingKeys[slotDivId2] = slotTargetingKeys;
         if (tsOwned) newSlots.push(gptSlot);
         slotsToRefresh.push(gptSlot);
 
@@ -391,6 +417,7 @@ export function installTsAdInit(): void {
       ts.prevGptSlots = newSlots as unknown[];
       // Replace (not merge) so destroyed slots from previous navigation don't linger.
       ts.divToSlotId = divToSlotId;
+      ts.prevSlotTargetingKeys = nextSlotTargetingKeys;
 
       // enableSingleRequest and enableServices must only be called once per page load.
       if (!ts.servicesEnabled) {

crates/js/lib/src/integrations/prebid/index.ts

@@ -39,6 +39,14 @@ import { DEFAULT_PREBID_USER_ID_MODULES, PREBID_USER_ID_MODULE_REGISTRY } from '
 const ADAPTER_CODE = 'trustedServer';
 const BIDDER_PARAMS_KEY = 'bidderParams';
 const ZONE_KEY = 'zone';
+const TS_REFRESH_TARGETING_KEYS = [
+  'ts_initial',
+  'hb_pb',
+  'hb_bidder',
+  'hb_adid',
+  'hb_cache_host',
+  'hb_cache_path',
+] as const;
 
 /** Configuration options for the Prebid integration. */
 export interface PrebidNpmConfig {
@@ -242,6 +250,7 @@ type PrebidUserIdEid = {
 type RefreshGptSlot = {
   getSlotElementId?: () => string;
   getTargeting?: (key: string) => string[];
+  clearTargeting?: (key?: string) => RefreshGptSlot;
   getSizes?: () => unknown[];
 };
 
@@ -333,6 +342,14 @@ function firstTargetingValue(values: string[] | undefined): string | undefined {
   return values?.find((value) => value.length > 0);
 }
 
+function clearRefreshTargeting(slot: RefreshGptSlot): void {
+  if (typeof slot.clearTargeting !== 'function') return;
+
+  for (const key of TS_REFRESH_TARGETING_KEYS) {
+    slot.clearTargeting(key);
+  }
+}
+
 function collectAuctionEids(): AuctionEid[] | undefined {
   if (typeof pbjs.getUserIdsAsEids !== 'function') {
     return undefined;
@@ -569,8 +586,9 @@ export function installPrebidNpm(config?: Partial<PrebidNpmConfig>): typeof pbjs
  * Wraps `googletag.pubads().refresh()` so that when the publisher's GPT
  * refresh policy fires (sticky anchor, viewability dwell, infinite scroll),
  * Prebid runs a fresh client-side auction for the refreshing slots before
- * the GAM call. TS-owned first-impression slots (`ts_initial=1`) are excluded
- * — they are managed server-side and should not re-auction client-side.
+ * the GAM call. TS-owned first-impression slots (`ts_initial=1`) are included
+ * on later publisher refreshes, but stale TS server-side targeting is cleared
+ * before fresh Prebid targeting is applied.
  *
  * Must be called after `installPrebidNpm()` and after GPT is loaded.
  * Idempotent: safe to call multiple times — wraps only once via a sentinel.
@@ -598,24 +616,20 @@ export function installRefreshHandler(timeoutMs = 1500): void {
     const originalRefresh = pubads.refresh.bind(pubads);
     pubads.refresh = function (slots?: unknown[], opts?: unknown) {
       // For bare refresh() calls (no slots arg), get all registered slots from GPT
-      // so we can filter out TS first-impression slots and auction the rest.
+      // so we can auction the same concrete slot list and avoid stale targeting.
       const targetSlots = (
         slots ??
         (pubads as { getSlots?: () => unknown[] }).getSlots?.() ??
         []
       ).filter((slot): slot is RefreshGptSlot => typeof slot === 'object' && slot !== null);
 
-      // Filter out TS first-impression slots — they don't need client-side refresh auctions.
-      const nonTsSlots = targetSlots.filter(
-        (slot) => !slot.getTargeting?.('ts_initial')?.includes('1')
-      );
-
-      if (!nonTsSlots.length) {
-        // All slots are TS-owned — pass through unchanged.
+      if (!targetSlots.length) {
         return originalRefresh(slots, opts);
       }
 
-      const adUnits = nonTsSlots.map((slot) => {
+      targetSlots.forEach(clearRefreshTargeting);
+
+      const adUnits = targetSlots.map((slot) => {
         const injectedSlot = findInjectedSlotForRefresh(slot);
         const zone =
           injectedSlot?.targeting?.[ZONE_KEY] ?? firstTargetingValue(slot.getTargeting?.(ZONE_KEY));
@@ -638,8 +652,7 @@ export function installRefreshHandler(timeoutMs = 1500): void {
         adUnits,
         bidsBackHandler: () => {
           pbjs.setTargetingForGPTAsync?.();
-          // Refresh only the non-TS slots (pass explicit list so TS slots are not re-refreshed).
-          originalRefresh(nonTsSlots, opts);
+          originalRefresh(targetSlots, opts);
         },
         timeout: timeoutMs,
       });

crates/js/lib/test/integrations/gpt/index.test.ts

@@ -216,6 +216,103 @@ describe('GPT – installSlimPrebidLoader', () => {
   });
 });
 
+describe('GPT – installTsAdInit', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    delete (window as any).tsjs;
+    delete (window as any).googletag;
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = '';
+    delete (window as any).tsjs;
+    delete (window as any).googletag;
+  });
+
+  it('clears stale TS-managed targeting before applying a new route to a reused GPT slot', async () => {
+    const { installTsAdInit } = await import('../../../src/integrations/gpt/index');
+    const slotTargeting = new Map<string, string[]>([
+      ['hb_pb', ['1.20']],
+      ['hb_bidder', ['kargo']],
+      ['hb_adid', ['old-ad']],
+      ['hb_cache_host', ['cache.example.com']],
+      ['hb_cache_path', ['/cache']],
+      ['ts_initial', ['1']],
+      ['pos', ['old-pos']],
+    ]);
+    const gptSlot: any = {
+      getSlotElementId: vi.fn(() => 'div-ad-homepage-header'),
+      getTargeting: vi.fn((key: string) => slotTargeting.get(key) ?? []),
+      setTargeting: vi.fn((key: string, value: string | string[]) => {
+        slotTargeting.set(key, Array.isArray(value) ? value : [value]);
+        return gptSlot;
+      }),
+      clearTargeting: vi.fn((key?: string) => {
+        if (key) {
+          slotTargeting.delete(key);
+        } else {
+          slotTargeting.clear();
+        }
+        return gptSlot;
+      }),
+    };
+    const pubads = {
+      getSlots: vi.fn(() => [gptSlot]),
+      enableSingleRequest: vi.fn(),
+      addEventListener: vi.fn(),
+      refresh: vi.fn(),
+    };
+    const cmd: Array<() => void> = [];
+    cmd.push = (...callbacks: Array<() => void>) => {
+      callbacks.forEach((callback) => callback());
+      return cmd.length;
+    };
+
+    document.body.innerHTML = '<div id="div-ad-homepage-header"></div>';
+    (window as any).googletag = {
+      cmd,
+      pubads: () => pubads,
+      defineSlot: vi.fn(),
+      destroySlots: vi.fn(),
+      enableServices: vi.fn(),
+    };
+    (window as any).tsjs = {
+      prevSlotTargetingKeys: {
+        'div-ad-homepage-header': ['pos'],
+      },
+      adSlots: [
+        {
+          id: 'homepage_header_ad',
+          gam_unit_path: '/123/homepage',
+          div_id: 'div-ad-homepage-header',
+          formats: [[728, 90]],
+          targeting: { zone: 'homepage' },
+        },
+      ],
+      bids: {},
+    };
+
+    installTsAdInit();
+    (window as any).tsjs.adInit();
+
+    expect(gptSlot.clearTargeting).toHaveBeenCalledWith('hb_pb');
+    expect(gptSlot.clearTargeting).toHaveBeenCalledWith('hb_bidder');
+    expect(gptSlot.clearTargeting).toHaveBeenCalledWith('hb_adid');
+    expect(gptSlot.clearTargeting).toHaveBeenCalledWith('hb_cache_host');
+    expect(gptSlot.clearTargeting).toHaveBeenCalledWith('hb_cache_path');
+    expect(gptSlot.clearTargeting).toHaveBeenCalledWith('ts_initial');
+    expect(gptSlot.clearTargeting).toHaveBeenCalledWith('pos');
+    expect(slotTargeting.get('hb_pb')).toBeUndefined();
+    expect(slotTargeting.get('hb_bidder')).toBeUndefined();
+    expect(slotTargeting.get('hb_adid')).toBeUndefined();
+    expect(slotTargeting.get('hb_cache_host')).toBeUndefined();
+    expect(slotTargeting.get('hb_cache_path')).toBeUndefined();
+    expect(slotTargeting.get('pos')).toBeUndefined();
+    expect(slotTargeting.get('zone')).toEqual(['homepage']);
+    expect(slotTargeting.get('ts_initial')).toEqual(['1']);
+  });
+});
+
 describe('GPT shim – runtime gating', () => {
   type GatedWindow = Window & {
     __tsjs_gpt_enabled?: boolean;

crates/js/lib/test/integrations/prebid/index.test.ts

@@ -769,6 +769,7 @@ describe('prebid/installPrebidNpm with server-injected config', () => {
 describe('prebid/installRefreshHandler', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    mockRequestBids.mockReset();
     mockPbjs.requestBids = mockRequestBids;
     mockPbjs.adUnits = [];
     (window as any).tsjs = undefined;
@@ -833,6 +834,85 @@ describe('prebid/installRefreshHandler', () => {
       })
     );
   });
+
+  it('auctions refreshed TS initial slots and clears stale TS targeting before refresh', () => {
+    const originalRefresh = vi.fn();
+    const clearTargeting = vi.fn();
+    const gptSlot = {
+      getSlotElementId: vi.fn(() => 'div-ad-homepage-header'),
+      getTargeting: vi.fn((key: string) => {
+        if (key === 'ts_initial') return ['1'];
+        if (key === 'zone') return ['homepage'];
+        return [];
+      }),
+      getSizes: vi.fn(() => [
+        { getWidth: () => 970, getHeight: () => 250 },
+        { getWidth: () => 728, getHeight: () => 90 },
+      ]),
+      clearTargeting,
+    };
+    const pubads = {
+      refresh: originalRefresh,
+      getSlots: vi.fn(() => [gptSlot]),
+    };
+    const setTargetingForGPTAsync = vi.fn();
+    (mockPbjs as any).setTargetingForGPTAsync = setTargetingForGPTAsync;
+    (window as any).googletag = {
+      cmd: { push: (fn: () => void) => fn() },
+      pubads: () => pubads,
+    };
+    (window as any).tsjs = {
+      adSlots: [
+        {
+          id: 'homepage_header_ad',
+          gam_unit_path: '/123/homepage',
+          div_id: 'div-ad-homepage-header',
+          formats: [
+            [970, 250],
+            [728, 90],
+          ],
+          targeting: { zone: 'homepage' },
+        },
+      ],
+    };
+
+    installRefreshHandler(750);
+    pubads.refresh([gptSlot]);
+
+    expect(mockRequestBids).toHaveBeenCalledWith(
+      expect.objectContaining({
+        timeout: 750,
+        adUnits: [
+          expect.objectContaining({
+            code: 'div-ad-homepage-header',
+            mediaTypes: {
+              banner: {
+                name: 'homepage',
+                sizes: [
+                  [970, 250],
+                  [728, 90],
+                ],
+              },
+            },
+            bids: [{ bidder: 'trustedServer', params: { zone: 'homepage' } }],
+          }),
+        ],
+      })
+    );
+    expect(clearTargeting).toHaveBeenCalledWith('ts_initial');
+    expect(clearTargeting).toHaveBeenCalledWith('hb_pb');
+    expect(clearTargeting).toHaveBeenCalledWith('hb_bidder');
+    expect(clearTargeting).toHaveBeenCalledWith('hb_adid');
+    expect(clearTargeting).toHaveBeenCalledWith('hb_cache_host');
+    expect(clearTargeting).toHaveBeenCalledWith('hb_cache_path');
+    expect(originalRefresh).not.toHaveBeenCalled();
+
+    const bidsBackHandler = mockRequestBids.mock.calls[0][0].bidsBackHandler;
+    bidsBackHandler();
+
+    expect(setTargetingForGPTAsync).toHaveBeenCalled();
+    expect(originalRefresh).toHaveBeenCalledWith([gptSlot], undefined);
+  });
 });
 
 describe('prebid/client-side bidders', () => {