Add server-side ad template auctions with /ts-bids endpoint

Cargo.toml

@@ -65,6 +65,7 @@ fastly = "0.11.12"
 fern = "0.7.1"
 flate2 = "1.1"
 futures = "0.3"
+glob = "0.3"
 hex = "0.4.3"
 hmac = "0.12.1"
 http = "1.4.0"

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

@@ -31,12 +31,20 @@ interface GoogleTagSlot {
   getAdUnitPath(): string;
   getSlotElementId(): string;
   setTargeting(key: string, value: string | string[]): GoogleTagSlot;
+  getTargeting(key: string): string[];
+  addService(service: GoogleTagPubAdsService): GoogleTagSlot;
 }
 
 interface GoogleTagPubAdsService {
   setTargeting(key: string, value: string | string[]): GoogleTagPubAdsService;
   getTargeting(key: string): string[];
   enableSingleRequest(): void;
+  disableInitialLoad(): void;
+  addEventListener(
+    eventName: 'slotRenderEnded',
+    callback: (event: SlotRenderEndedEvent) => void
+  ): void;
+  refresh(slots?: GoogleTagSlot[]): void;
 }
 
 interface GoogleTag {
@@ -54,6 +62,38 @@ interface GoogleTag {
 
 type GptWindow = Window & {
   googletag?: Partial<GoogleTag>;
+  __ts_ad_slots?: TsAdSlot[];
+  __ts_request_id?: string;
+  __tsAdInit?: () => boolean;
+  __tsAdInitInstalled?: boolean;
+};
+
+type TsAdSlot = {
+  id?: string;
+  gam_unit_path?: string;
+  div_id?: string;
+  formats?: Array<number | number[]>;
+  targeting?: Record<string, string | string[]>;
+};
+
+type TsBidTargeting = {
+  hb_pb?: string;
+  hb_bidder?: string;
+  hb_adid?: string;
+  burl?: string;
+};
+
+type TsBidMap = Record<string, TsBidTargeting | undefined>;
+
+type DefinedTsSlot = {
+  descriptor: TsAdSlot;
+  slot: GoogleTagSlot;
+};
+
+type SlotRenderEndedEvent = {
+  slot?: {
+    getTargeting?: (key: string) => string[];
+  };
 };
 
 // ------------------------------------------------------------------
@@ -137,6 +177,155 @@ function patchCommandQueue(tag: Partial<GoogleTag>): void {
   log.debug('GPT shim: command queue patched', { pendingCommands: queue.length });
 }
 
+function readTsAdSlots(win: GptWindow): TsAdSlot[] {
+  return Array.isArray(win.__ts_ad_slots) ? win.__ts_ad_slots : [];
+}
+
+function fetchTsBids(win: GptWindow): Promise<TsBidMap> {
+  const rid = win.__ts_request_id;
+  if (!rid || typeof fetch !== 'function') {
+    return Promise.resolve({});
+  }
+
+  return fetch(`/ts-bids?rid=${encodeURIComponent(rid)}`, { credentials: 'omit' })
+    .then((response) => response.json() as Promise<TsBidMap>)
+    .catch(() => ({}));
+}
+
+function applyStaticTargeting(slot: GoogleTagSlot, targeting: TsAdSlot['targeting']): void {
+  for (const [key, value] of Object.entries(targeting ?? {})) {
+    slot.setTargeting(key, value);
+  }
+}
+
+function applyBidTargeting(slot: GoogleTagSlot, bid: TsBidTargeting): void {
+  for (const key of ['hb_pb', 'hb_bidder', 'hb_adid'] as const) {
+    const value = bid[key];
+    if (value != null) {
+      slot.setTargeting(key, String(value));
+    }
+  }
+}
+
+function installBurlListener(
+  pubads: GoogleTagPubAdsService,
+  bidsByAdId: Map<string, TsBidTargeting>
+): void {
+  if (typeof pubads.addEventListener !== 'function') {
+    return;
+  }
+
+  pubads.addEventListener('slotRenderEnded', (event) => {
+    const hbAdIds = event.slot?.getTargeting?.('hb_adid') ?? [];
+    const hbAdId = hbAdIds[0];
+    const bid = hbAdId ? bidsByAdId.get(hbAdId) : undefined;
+
+    if (
+      !bid?.burl ||
+      typeof navigator === 'undefined' ||
+      typeof navigator.sendBeacon !== 'function'
+    ) {
+      return;
+    }
+
+    navigator.sendBeacon(bid.burl);
+    bidsByAdId.delete(hbAdId);
+  });
+}
+
+function runTsAdInit(win: GptWindow): void {
+  const tag = win.googletag as GoogleTag | undefined;
+  const bidsPromise = fetchTsBids(win);
+  const slots = readTsAdSlots(win);
+  const definedSlots: DefinedTsSlot[] = [];
+  const bidsByAdId = new Map<string, TsBidTargeting>();
+
+  if (
+    !tag ||
+    typeof tag.defineSlot !== 'function' ||
+    typeof tag.pubads !== 'function' ||
+    typeof tag.enableServices !== 'function'
+  ) {
+    return;
+  }
+
+  const pubads = tag.pubads();
+  installBurlListener(pubads, bidsByAdId);
+
+  for (const descriptor of slots) {
+    if (!descriptor.gam_unit_path || !descriptor.div_id || !descriptor.id) {
+      continue;
+    }
+
+    const slot = tag.defineSlot(
+      descriptor.gam_unit_path,
+      descriptor.formats ?? [],
+      descriptor.div_id
+    );
+    if (!slot) {
+      continue;
+    }
+
+    if (typeof slot.addService === 'function') {
+      slot.addService(pubads);
+    }
+    applyStaticTargeting(slot, descriptor.targeting);
+    definedSlots.push({ descriptor, slot });
+  }
+
+  if (typeof pubads.disableInitialLoad === 'function') {
+    pubads.disableInitialLoad();
+  }
+  tag.enableServices();
+
+  for (const { descriptor } of definedSlots) {
+    if (typeof tag.display === 'function') {
+      tag.display(descriptor.div_id as string);
+    }
+  }
+
+  bidsPromise.then((bids) => {
+    for (const { descriptor, slot } of definedSlots) {
+      const bid = bids[descriptor.id as string];
+      if (!bid) {
+        continue;
+      }
+
+      applyBidTargeting(slot, bid);
+      if (bid.hb_adid) {
+        bidsByAdId.set(String(bid.hb_adid), bid);
+      }
+    }
+
+    if (typeof pubads.refresh === 'function') {
+      pubads.refresh(definedSlots.map(({ slot }) => slot));
+    }
+  });
+}
+
+/**
+ * Install the Trusted Server ad bootstrap for GPT slots.
+ *
+ * The bootstrap reads `window.__ts_ad_slots` and `window.__ts_request_id`,
+ * defines GPT slots immediately, then applies server-side bid targeting from
+ * `/ts-bids` before refreshing the slots.
+ */
+export function installTsAdInit(): boolean {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+
+  const win = window as GptWindow;
+  if (win.__tsAdInitInstalled) {
+    return true;
+  }
+
+  win.__tsAdInitInstalled = true;
+  const tag = ensureGoogleTagStub(win);
+  tag.cmd!.push(() => runTsAdInit(win));
+  return true;
+}
+
 /**
  * Install the GPT integration shim.
  *
@@ -156,6 +345,7 @@ export function installGptShim(): boolean {
 
   const tag = ensureGoogleTagStub(win);
   patchCommandQueue(tag);
+  installTsAdInit();
 
   log.info('GPT shim installed');
   return true;
@@ -170,9 +360,10 @@ export function installGptShim(): boolean {
 // regardless of script order, the module also checks for a pre-set enable flag
 // immediately after registering the function.
 if (typeof window !== 'undefined') {
-  const win = window as Record<string, unknown>;
+  const win = window as unknown as Record<string, unknown>;
 
   win.__tsjs_installGptShim = installGptShim;
+  win.__tsAdInit = installTsAdInit;
 
   if (win.__tsjs_gpt_enabled === true) {
     installGptShim();