@bidkernel/analytics 0.11.0 → 0.16.0

package/dist/index.mjs

@@ -1042,7 +1042,8 @@ var EVENT_NAME_TO_TYPE = {
   timeInView: TraceEventType.TIME_IN_VIEW,
   viewable: TraceEventType.VIEWABLE
 };
-var IMMEDIATE_FLUSH_TYPES = /* @__PURE__ */ new Set([
+var REVENUE_FLUSH_DELAY_MS = 3e3;
+var REVENUE_FLUSH_TYPES = /* @__PURE__ */ new Set([
   TraceEventType.IMPRESSION,
   TraceEventType.BID_WIN,
   TraceEventType.CLICK
@@ -1051,11 +1052,13 @@ var CACHED_BID_TTL_MS = 30 * 60 * 1e3;
 var MAX_CACHED_BID_KEYS = 200;
 var MAX_IMPRESSION_KEYS = 1e3;
 var MAX_TRACKED_AUCTIONS = 50;
+var CLICK_DEDUP_MS = 1e3;
 var SESSION_KEY = "_bidkernel_session";
 var SESSION_TS_KEY = "_bidkernel_session_ts";
 var THIRTY_MINUTES_MS = 30 * 60 * 1e3;
 var inMemorySessionId = null;
 var inMemorySessionTs = 0;
+var storageAllowed = true;
 function generateUUID() {
   if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
     return crypto.randomUUID();
@@ -1125,6 +1128,7 @@ function sameEndpointOrigin(a, b) {
 function extendSession() {
   const now = Date.now();
   inMemorySessionTs = now;
+  if (!storageAllowed) return;
   try {
     if (typeof localStorage !== "undefined") {
       localStorage.setItem(SESSION_TS_KEY, now.toString());
@@ -1134,18 +1138,23 @@ function extendSession() {
 }
 function getOrCreateSessionId() {
   const now = Date.now();
+  const memoryFresh = !!inMemorySessionId && !!inMemorySessionTs && now - inMemorySessionTs <= THIRTY_MINUTES_MS;
   try {
-    if (typeof localStorage !== "undefined") {
+    if (storageAllowed && typeof localStorage !== "undefined") {
       const storedId = localStorage.getItem(SESSION_KEY);
       const tsStr = localStorage.getItem(SESSION_TS_KEY);
       const storedTs = tsStr ? parseInt(tsStr, 10) || 0 : 0;
       if (storedId && storedTs && now - storedTs <= THIRTY_MINUTES_MS) {
         localStorage.setItem(SESSION_TS_KEY, now.toString());
+        inMemorySessionId = storedId;
+        inMemorySessionTs = now;
         return storedId;
       }
-      const newId = generateUUID();
+      const newId = memoryFresh ? inMemorySessionId : generateUUID();
       localStorage.setItem(SESSION_KEY, newId);
       localStorage.setItem(SESSION_TS_KEY, now.toString());
+      inMemorySessionId = newId;
+      inMemorySessionTs = now;
       return newId;
     }
   } catch {
@@ -1511,6 +1520,17 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
   static initImaInterception() {
     initImaInterception();
   }
+  /**
+   * Allows or forbids localStorage writes for every instance on the page.
+   * Collection and delivery are unaffected: only the persisted session id,
+   * its timestamp and exit batches are gated.
+   */
+  static setStorageAllowed(allowed) {
+    storageAllowed = allowed;
+  }
+  static isStorageAllowed() {
+    return storageAllowed;
+  }
   config;
   queue = [];
   errorCount = 0;
@@ -1526,7 +1546,7 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
   consecutiveSendFailures = 0;
   nextSendAllowedAt = 0;
   replayedEventCount = 0;
-  immediateFlushScheduled = false;
+  revenueFlushTimer = null;
   // localStorage keys of exit batches this instance persisted, so a page that
   // survives its own pagehide/hidden (bfcache restore, tab re-focus) can
   // remove them instead of leaving them for a duplicate resend.
@@ -1539,6 +1559,12 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
   slotRefreshIndices = /* @__PURE__ */ new Map();
   slotLastAuctionIds = /* @__PURE__ */ new Map();
   pendingThresholdListeners = /* @__PURE__ */ new Map();
+  pendingViewableListeners = /* @__PURE__ */ new Map();
+  // Element a subscriber named for a slot (a sticky bar or interstitial that
+  // renders outside the slot element); wins over document.getElementById.
+  slotElements = /* @__PURE__ */ new Map();
+  clickDetachCleanups = /* @__PURE__ */ new Set();
+  lastClickAt = /* @__PURE__ */ new Map();
   // Impression deduplication per slot and refresh cycle (strictly 1 impression per cycle)
   slotEmittedImpressionKeys = /* @__PURE__ */ new Set();
   // Winning bid cache from bidWon to marry with subsequent render triggers (adRenderSucceeded, video, etc.)
@@ -1549,6 +1575,9 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
   auctionBidderOutcomes = /* @__PURE__ */ new Map();
   logger;
   constructor(config) {
+    if (config.storageAllowed !== void 0) {
+      _BidkernelPrebidAnalytics.setStorageAllowed(config.storageAllowed);
+    }
     const requestedEndpoint = config.endpoint || "";
     const endpoint = !requestedEndpoint || isTrustedEndpoint(requestedEndpoint) ? requestedEndpoint : "";
     this.config = {
@@ -1564,9 +1593,11 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       warningsEnabled: config.warningsEnabled ?? true,
       errorsEnabled: config.errorsEnabled ?? true,
       viewabilityEnabled: config.viewabilityEnabled ?? true,
+      storageAllowed: config.storageAllowed ?? true,
       logLevel: config.logLevel || "INFO",
       pbjsGlobalName: config.pbjsGlobalName || "pbjs",
-      attachPbjsListeners: config.attachPbjsListeners ?? true
+      attachPbjsListeners: config.attachPbjsListeners ?? true,
+      revenueFlushDelayMs: Number.isFinite(config.revenueFlushDelayMs) && config.revenueFlushDelayMs >= 0 ? config.revenueFlushDelayMs : REVENUE_FLUSH_DELAY_MS
     };
     this.logger = createLogger({
       prefix: "[bidkernel][prebid-analytics]",
@@ -1605,65 +1636,7 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       }
     }
     if (this.config.attachPbjsListeners) {
-      const win = typeof window !== "undefined" ? window : {};
-      const pbjs = win[this.config.pbjsGlobalName] || {};
-      if (typeof pbjs.onEvent === "function") {
-        this.log("DEBUG", "Attaching event listeners to pbjs");
-        const events = [
-          ["auctionInit", this.handleAuctionInit.bind(this)],
-          ["auctionEnd", this.handleAuctionEnd.bind(this)],
-          ["bidRequested", this.handleBidRequested.bind(this)],
-          ["bidResponse", this.handleBidResponse.bind(this)],
-          ["bidTimeout", this.handleBidTimeout.bind(this)],
-          ["bidWon", this.handleBidWon.bind(this)],
-          ["noBid", this.handleNoBid.bind(this)],
-          ["adRenderFailed", this.handleAdRenderFailed.bind(this)],
-          ["adRenderSucceeded", this.handleAdRenderSucceeded.bind(this)]
-        ];
-        for (const [name, fn] of events) {
-          pbjs.onEvent(name, fn);
-          this.boundPbjsHandlers.push({ event: name, handler: fn });
-        }
-      } else {
-        this.log("WARN", "pbjs.onEvent is not defined. Prebid analytics will not function.");
-      }
-      if (typeof pbjs.getEvents === "function") {
-        try {
-          const pastEvents = pbjs.getEvents();
-          if (Array.isArray(pastEvents)) {
-            const newPastEvents = pastEvents.slice(this.replayedEventCount);
-            this.replayedEventCount = pastEvents.length;
-            if (newPastEvents.length > 0) {
-              this.log(
-                "DEBUG",
-                `Replaying ${newPastEvents.length} historical events from pbjs.getEvents()`
-              );
-              const handlerMap = {
-                auctionInit: this.handleAuctionInit.bind(this),
-                auctionEnd: this.handleAuctionEnd.bind(this),
-                bidRequested: this.handleBidRequested.bind(this),
-                bidResponse: this.handleBidResponse.bind(this),
-                bidTimeout: this.handleBidTimeout.bind(this),
-                bidWon: this.handleBidWon.bind(this),
-                noBid: this.handleNoBid.bind(this),
-                adRenderFailed: this.handleAdRenderFailed.bind(this),
-                adRenderSucceeded: this.handleAdRenderSucceeded.bind(this)
-              };
-              for (const ev of newPastEvents) {
-                if (!ev) continue;
-                const eventType = ev.eventType || ev.event || ev.name;
-                const args = ev.args !== void 0 ? ev.args : ev.data !== void 0 ? ev.data : ev;
-                const handler = handlerMap[eventType];
-                if (handler) {
-                  handler(args);
-                }
-              }
-            }
-          }
-        } catch (e) {
-          this.log("WARN", "Failed to replay historical events from pbjs.getEvents()", e);
-        }
-      }
+      this.attachPbjs();
     }
     if (typeof window !== "undefined") {
       if (!this.pageUrl) {
@@ -1686,6 +1659,68 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       }
     }
   }
+  /**
+   * Binds the Prebid event handlers on the configured global and replays
+   * pbjs.getEvents() history. enable() calls this when attachPbjsListeners is
+   * true. An integration that loads Prebid lazily constructs the instance with
+   * attachPbjsListeners=false and calls this once pbjs exists; disable() (and
+   * therefore navigate()) drops the handlers, so call it again after either.
+   * Idempotent. Returns true when handlers are bound after the call, false
+   * when the instance is disabled or pbjs.onEvent is not available yet.
+   */
+  attachPbjs() {
+    if (!this.isEnabled) return false;
+    if (this.boundPbjsHandlers.length > 0) return true;
+    const win = typeof window !== "undefined" ? window : {};
+    const pbjs = win[this.config.pbjsGlobalName] || {};
+    if (typeof pbjs.onEvent !== "function") {
+      this.log("WARN", "pbjs.onEvent is not defined. Prebid analytics will not function.");
+      return false;
+    }
+    this.log("DEBUG", "Attaching event listeners to pbjs");
+    const handlerMap = {
+      auctionInit: this.handleAuctionInit.bind(this),
+      auctionEnd: this.handleAuctionEnd.bind(this),
+      bidRequested: this.handleBidRequested.bind(this),
+      bidResponse: this.handleBidResponse.bind(this),
+      bidTimeout: this.handleBidTimeout.bind(this),
+      bidWon: this.handleBidWon.bind(this),
+      noBid: this.handleNoBid.bind(this),
+      adRenderFailed: this.handleAdRenderFailed.bind(this),
+      adRenderSucceeded: this.handleAdRenderSucceeded.bind(this)
+    };
+    for (const [name, fn] of Object.entries(handlerMap)) {
+      pbjs.onEvent(name, fn);
+      this.boundPbjsHandlers.push({ event: name, handler: fn });
+    }
+    if (typeof pbjs.getEvents === "function") {
+      try {
+        const pastEvents = pbjs.getEvents();
+        if (Array.isArray(pastEvents)) {
+          const newPastEvents = pastEvents.slice(this.replayedEventCount);
+          this.replayedEventCount = pastEvents.length;
+          if (newPastEvents.length > 0) {
+            this.log(
+              "DEBUG",
+              `Replaying ${newPastEvents.length} historical events from pbjs.getEvents()`
+            );
+            for (const ev of newPastEvents) {
+              if (!ev) continue;
+              const eventType = ev.eventType || ev.event || ev.name;
+              const args = ev.args !== void 0 ? ev.args : ev.data !== void 0 ? ev.data : ev;
+              const handler = handlerMap[eventType];
+              if (handler) {
+                handler(args);
+              }
+            }
+          }
+        }
+      } catch (e) {
+        this.log("WARN", "Failed to replay historical events from pbjs.getEvents()", e);
+      }
+    }
+    return true;
+  }
   disable() {
     if (!this.isEnabled) return;
     this.flushAllSlotsTimeInView();
@@ -1717,6 +1752,14 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       }
     }
     this.videoDetachCleanups.clear();
+    for (const cleanup of Array.from(this.clickDetachCleanups)) {
+      try {
+        cleanup();
+      } catch {
+      }
+    }
+    this.clickDetachCleanups.clear();
+    this.slotElements.clear();
     this.cachedWinningBids.clear();
     this.slotEmittedImpressionKeys.clear();
     this.slotLastAuctionIds.clear();
@@ -1725,6 +1768,10 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       clearInterval(this.flushTimer);
       this.flushTimer = null;
     }
+    if (this.revenueFlushTimer) {
+      clearTimeout(this.revenueFlushTimer);
+      this.revenueFlushTimer = null;
+    }
     if (this.persistedCleanupTimer) {
       clearTimeout(this.persistedCleanupTimer);
       this.persistedCleanupTimer = null;
@@ -1874,6 +1921,105 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
         }
       });
     }
+    this.notifyViewable(record);
+  }
+  notifyViewable(record) {
+    if (!record.viewableFired) return;
+    for (const listener of record.viewableListeners) {
+      if (listener.firedForIndex === record.refreshIndex) continue;
+      listener.firedForIndex = record.refreshIndex;
+      try {
+        listener.callback(record.slotId);
+      } catch (e) {
+        this.log("ERROR", "Error in viewable listener callback", e);
+      }
+    }
+  }
+  /**
+   * Calls back once per render cycle when the slot has met the IAB viewable
+   * standard this adapter measures (immediately if it already has). Works
+   * before the slot is observed: the listener waits for observeSlot. Returns
+   * an unsubscribe function.
+   */
+  /**
+   * Names the element to measure for a slot when the creative renders
+   * somewhere other than the slot element (a sticky bar, an interstitial).
+   * Applies to the current cycle at once and to every later render.
+   */
+  setSlotElement(slotId, element) {
+    this.slotElements.set(slotId, element);
+    const record = this.slotViewabilityRecords.get(slotId);
+    if (record && record.element !== element) {
+      this.observeSlot(element, slotId, {
+        refreshIndex: record.refreshIndex,
+        emitRefreshEvent: false
+      });
+    }
+  }
+  /**
+   * Records a click on the slot's current creative, attributed to the cached
+   * winning bid. Repeats within one second are one click. Returns whether a
+   * CLICK was recorded.
+   */
+  recordClick(slotId, options) {
+    if (!this.isEnabled || !slotId) return false;
+    const now = Date.now();
+    if (now - (this.lastClickAt.get(slotId) || 0) < CLICK_DEDUP_MS) return false;
+    this.lastClickAt.set(slotId, now);
+    const cached = this.getCachedBid(slotId);
+    this.enqueue(TraceEventType.CLICK, "click", {
+      auctionId: cached?.auctionId || "",
+      transactionId: cached?.transactionId || "",
+      adUnitCode: slotId,
+      bid: cached?.bidTrace,
+      metadata: {
+        ...options?.metadata,
+        refresh_index: String(this.getRefreshIndex(slotId))
+      }
+    });
+    return true;
+  }
+  /**
+   * Detects clicks into a cross-origin creative frame: a click inside an
+   * iframe moves focus into it and blurs the window. Returns a detach
+   * function; every tracker is detached on disable().
+   */
+  attachClickTracker(element, slotId) {
+    if (typeof window === "undefined") return () => {
+    };
+    const onBlur = () => {
+      setTimeout(() => {
+        const active = document.activeElement;
+        if (active && (active === element || element.contains(active))) {
+          this.recordClick(slotId, { metadata: { source: "blur" } });
+          window.focus();
+        }
+      }, 0);
+    };
+    window.addEventListener("blur", onBlur);
+    const cleanup = () => {
+      window.removeEventListener("blur", onBlur);
+      this.clickDetachCleanups.delete(cleanup);
+    };
+    this.clickDetachCleanups.add(cleanup);
+    return cleanup;
+  }
+  onViewable(slotId, callback) {
+    const listener = { callback, firedForIndex: -1 };
+    const record = this.slotViewabilityRecords.get(slotId);
+    if (record) {
+      record.viewableListeners.add(listener);
+      this.notifyViewable(record);
+    } else {
+      if (!this.pendingViewableListeners.has(slotId)) {
+        this.pendingViewableListeners.set(slotId, /* @__PURE__ */ new Set());
+      }
+      this.pendingViewableListeners.get(slotId).add(listener);
+    }
+    return () => {
+      this.slotViewabilityRecords.get(slotId)?.viewableListeners.delete(listener);
+      this.pendingViewableListeners.get(slotId)?.delete(listener);
+    };
   }
   scheduleThresholdTimers(record) {
     if (!record.inView || typeof document !== "undefined" && document.visibilityState === "hidden") {
@@ -2063,6 +2209,8 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       }
       const listeners = this.pendingThresholdListeners.get(resolvedSlotId) || /* @__PURE__ */ new Set();
       this.pendingThresholdListeners.delete(resolvedSlotId);
+      const viewableListeners = this.pendingViewableListeners.get(resolvedSlotId) || /* @__PURE__ */ new Set();
+      this.pendingViewableListeners.delete(resolvedSlotId);
       const record = {
         slotId: resolvedSlotId,
         element: el,
@@ -2079,7 +2227,8 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
         viewableFired: false,
         dwellTimer: null,
         dwellStartedAt: null,
-        thresholdListeners: listeners
+        thresholdListeners: listeners,
+        viewableListeners
       };
       this.slotViewabilityRecords.set(resolvedSlotId, record);
       if (el) {
@@ -2104,6 +2253,7 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       }
     }
     record.thresholdListeners = /* @__PURE__ */ new Set();
+    record.viewableListeners = /* @__PURE__ */ new Set();
     if (record.element && this.intersectionObserver) {
       this.intersectionObserver.unobserve(record.element);
       this.elementToSlotId.delete(record.element);
@@ -2118,6 +2268,7 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
     this.slotRefreshIndices.delete(slotId);
     this.slotLastAuctionIds.delete(slotId);
     this.pendingThresholdListeners.delete(slotId);
+    this.pendingViewableListeners.delete(slotId);
     const prefix = `${escapeKeyPart(slotId)}:`;
     for (const key of Array.from(this.slotEmittedImpressionKeys)) {
       if (key === slotId || key.startsWith(prefix)) {
@@ -2392,19 +2543,21 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
     if (!adsManager.__bidkernelAttachedInstances) {
       try {
         Object.defineProperty(adsManager, "__bidkernelAttachedInstances", {
-          value: /* @__PURE__ */ new Set(),
+          value: /* @__PURE__ */ new Map(),
           configurable: true,
           writable: true
         });
       } catch {
-        adsManager.__bidkernelAttachedInstances = /* @__PURE__ */ new Set();
+        adsManager.__bidkernelAttachedInstances = /* @__PURE__ */ new Map();
       }
     }
-    if (adsManager.__bidkernelAttachedInstances.has(this)) {
-      return () => {
+    const attached = adsManager.__bidkernelAttachedInstances;
+    const previous = attached.get(this);
+    if (previous) {
+      if (!options) return () => {
       };
+      previous();
     }
-    adsManager.__bidkernelAttachedInstances.add(this);
     const slotId = options?.slotId || options?.adUnitCode || "video";
     const adUnitCode = options?.adUnitCode || slotId;
     const auctionId = options?.auctionId || "";
@@ -2552,7 +2705,7 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       }
     }
     const cleanup = () => {
-      adsManager.__bidkernelAttachedInstances?.delete(this);
+      attached.delete(this);
       for (const { type, handler } of listeners) {
         try {
           adsManager.removeEventListener(type, handler);
@@ -2561,6 +2714,7 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       }
       this.videoDetachCleanups.delete(cleanup);
     };
+    attached.set(this, cleanup);
     this.videoDetachCleanups.add(cleanup);
     return cleanup;
   }
@@ -3188,9 +3342,9 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       );
     }
     if (this.config.viewabilityEnabled && typeof document !== "undefined") {
-      let el = null;
+      let el = adUnitCode && this.slotElements.get(adUnitCode) || null;
       const targetId = adUnitCode || data.adId || bid.adId;
-      if (targetId) {
+      if (!el && targetId) {
         el = document.getElementById(targetId);
       }
       if (!el && typeof window !== "undefined" && window.googletag?.pubads) {
@@ -3289,12 +3443,11 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
     }
     if (this.queue.length >= BATCH_SIZE) {
       this.flush();
-    } else if (IMMEDIATE_FLUSH_TYPES.has(type) && !this.immediateFlushScheduled) {
-      this.immediateFlushScheduled = true;
-      setTimeout(() => {
-        this.immediateFlushScheduled = false;
+    } else if (REVENUE_FLUSH_TYPES.has(type) && this.revenueFlushTimer === null) {
+      this.revenueFlushTimer = setTimeout(() => {
+        this.revenueFlushTimer = null;
         this.flush();
-      }, 0);
+      }, this.config.revenueFlushDelayMs);
     }
   }
   shouldSample(type, level) {
@@ -3452,6 +3605,7 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
     return `${PENDING_BATCH_KEY_PREFIX}${encodeURIComponent(this.config.propertyId)}_`;
   }
   persistBatch(encoded) {
+    if (!storageAllowed) return null;
     try {
       if (typeof localStorage === "undefined") return null;
       if (!this.config.propertyId) return null;
@@ -3703,6 +3857,7 @@ function getbidkernel(alias = "bidkernel") {
 export {
   BidkernelPrebidAnalytics,
   PrebidEventDeduper,
+  getOrCreateSessionId,
   getPrebidEventKey,
   getbidkernel,
   hookImaPrototype,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bidkernel/analytics",
-  "version": "0.11.0",
+  "version": "0.16.0",
   "description": "Bidkernel auction analytics: a standalone Prebid.js analytics adapter, plus TypeScript bindings for the Bidkernel ad SDK.",
   "keywords": [
     "advertising",