@bidkernel/analytics 0.24.0 → 0.26.0

package/dist/index.mjs

@@ -1277,11 +1277,26 @@ function parseBidDimensions(bid) {
     height: Number.isFinite(bid?.height) ? bid.height : 0
   };
 }
+var defaultLogger = createLogger({
+  prefix: "[analytics]",
+  logLevel: "INFO"
+});
 var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
   static activeInstances = /* @__PURE__ */ new Set();
+  static allInstances = /* @__PURE__ */ new Set();
   static getActiveInstances() {
     return _BidkernelPrebidAnalytics.activeInstances;
   }
+  static setLogLevel(level) {
+    const norm = normalizeLogLevel(level);
+    defaultLogger.setLevel(norm);
+    for (const inst of _BidkernelPrebidAnalytics.allInstances) {
+      inst.setLogLevel(norm);
+    }
+  }
+  static getLogLevel() {
+    return defaultLogger.getLevel();
+  }
   /**
    * Allows or forbids localStorage writes for every instance on the page.
    * Collection and delivery are unaffected: only the persisted session id,
@@ -1320,6 +1335,7 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
   slotViewabilityRecords = /* @__PURE__ */ new Map();
   elementToSlotId = /* @__PURE__ */ new Map();
   slotRefreshIndices = /* @__PURE__ */ new Map();
+  slotAdSessionCounters = /* @__PURE__ */ new Map();
   slotLastAuctionIds = /* @__PURE__ */ new Map();
   pendingThresholdListeners = /* @__PURE__ */ new Map();
   pendingViewableListeners = /* @__PURE__ */ new Map();
@@ -1363,11 +1379,12 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       errorsEnabled: config.errorsEnabled ?? true,
       viewabilityEnabled: config.viewabilityEnabled ?? true,
       storageAllowed: config.storageAllowed ?? true,
-      logLevel: config.logLevel || "INFO",
+      logLevel: config.logLevel ? normalizeLogLevel(config.logLevel) : defaultLogger.getLevel(),
       pbjsGlobalName: config.pbjsGlobalName || "pbjs",
       attachPbjsListeners: config.attachPbjsListeners ?? true,
       revenueFlushDelayMs: Number.isFinite(config.revenueFlushDelayMs) && config.revenueFlushDelayMs >= 0 ? config.revenueFlushDelayMs : REVENUE_FLUSH_DELAY_MS
     };
+    _BidkernelPrebidAnalytics.allInstances.add(this);
     this.logger = createLogger({
       prefix: "[analytics]",
       logLevel: this.config.logLevel
@@ -1387,6 +1404,15 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
     };
     this.boundVisibilityChange = () => this.handleVisibilityChange();
   }
+  setLogLevel(level) {
+    const norm = normalizeLogLevel(level);
+    this.config.logLevel = norm;
+    this.logger.setLevel(norm);
+    defaultLogger.setLevel(norm);
+  }
+  getLogLevel() {
+    return this.logger.getLevel();
+  }
   enable() {
     if (this.isEnabled) return;
     this.isEnabled = true;
@@ -2023,6 +2049,7 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
     this.unobserveSlot(slotId);
     this.slotViewabilityRecords.delete(slotId);
     this.slotRefreshIndices.delete(slotId);
+    this.slotAdSessionCounters.delete(slotId);
     this.slotLastAuctionIds.delete(slotId);
     this.pendingThresholdListeners.delete(slotId);
     this.pendingViewableListeners.delete(slotId);
@@ -2100,9 +2127,41 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
     }
     return auctionMap;
   }
-  hasImpressionEmitted(slotId, refreshIndex, auctionId, creativeId) {
+  nextSlotAdSession(slotId) {
+    const next = (this.slotAdSessionCounters.get(slotId) ?? 0) + 1;
+    this.slotAdSessionCounters.set(slotId, next);
+    return `ad-session-${next}`;
+  }
+  hasImpressionEmitted(slotId, refreshIndex, auctionId, creativeId, adId) {
     const rIndex = refreshIndex ?? this.slotRefreshIndices.get(slotId) ?? 0;
     const baseSlotKey = `${escapeKeyPart(slotId)}:${rIndex}`;
+    if (adId) {
+      if (auctionId) {
+        if (this.slotEmittedImpressionKeys.has(
+          `${baseSlotKey}:auc:${escapeKeyPart(auctionId)}:ad:${escapeKeyPart(adId)}`
+        ) || this.slotEmittedImpressionKeys.has(`${baseSlotKey}:ad:${escapeKeyPart(adId)}`) || // Compat: pre-0.26.0 adapters stored keys without :ad: prefix; release once all in-flight keys expire.
+        this.slotEmittedImpressionKeys.has(
+          `${baseSlotKey}:auc:${escapeKeyPart(auctionId)}:${escapeKeyPart(adId)}`
+        ) || this.slotEmittedImpressionKeys.has(`${baseSlotKey}:${escapeKeyPart(adId)}`)) {
+          return true;
+        }
+      } else if (this.slotEmittedImpressionKeys.has(`${baseSlotKey}:ad:${escapeKeyPart(adId)}`) || // Compat: pre-0.26.0 adapters stored keys without :ad: prefix; release once all in-flight keys expire.
+      this.slotEmittedImpressionKeys.has(`${baseSlotKey}:${escapeKeyPart(adId)}`)) {
+        return true;
+      }
+      if (creativeId && creativeId !== adId) {
+        if (auctionId) {
+          if (this.slotEmittedImpressionKeys.has(
+            `${baseSlotKey}:auc:${escapeKeyPart(auctionId)}:${escapeKeyPart(creativeId)}`
+          ) || this.slotEmittedImpressionKeys.has(`${baseSlotKey}:${escapeKeyPart(creativeId)}`)) {
+            return true;
+          }
+        } else if (this.slotEmittedImpressionKeys.has(`${baseSlotKey}:${escapeKeyPart(creativeId)}`)) {
+          return true;
+        }
+      }
+      return false;
+    }
     if (creativeId) {
       if (auctionId) {
         return this.slotEmittedImpressionKeys.has(
@@ -2116,18 +2175,37 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
     }
     return this.slotEmittedImpressionKeys.has(baseSlotKey);
   }
-  markImpressionEmitted(slotId, refreshIndex, auctionId, creativeId) {
+  markImpressionEmitted(slotId, refreshIndex, auctionId, creativeId, adId) {
     const baseSlotKey = `${escapeKeyPart(slotId)}:${refreshIndex}`;
-    this.addImpressionKey(baseSlotKey);
-    if (creativeId) {
-      this.addImpressionKey(`${baseSlotKey}:${escapeKeyPart(creativeId)}`);
-    }
-    if (auctionId) {
-      this.addImpressionKey(`${baseSlotKey}:auc:${escapeKeyPart(auctionId)}`);
-      if (creativeId) {
-        this.addImpressionKey(
-          `${baseSlotKey}:auc:${escapeKeyPart(auctionId)}:${escapeKeyPart(creativeId)}`
-        );
+    const hasIdentity = Boolean(adId || creativeId);
+    if (hasIdentity) {
+      if (adId) {
+        this.addImpressionKey(`${baseSlotKey}:ad:${escapeKeyPart(adId)}`);
+        this.addImpressionKey(`${baseSlotKey}:${escapeKeyPart(adId)}`);
+        if (auctionId) {
+          this.addImpressionKey(
+            `${baseSlotKey}:auc:${escapeKeyPart(auctionId)}:ad:${escapeKeyPart(adId)}`
+          );
+          this.addImpressionKey(
+            `${baseSlotKey}:auc:${escapeKeyPart(auctionId)}:${escapeKeyPart(adId)}`
+          );
+        }
+      }
+      if (creativeId && creativeId !== adId) {
+        this.addImpressionKey(`${baseSlotKey}:${escapeKeyPart(creativeId)}`);
+        if (auctionId) {
+          this.addImpressionKey(
+            `${baseSlotKey}:auc:${escapeKeyPart(auctionId)}:${escapeKeyPart(creativeId)}`
+          );
+        }
+      }
+      if (auctionId) {
+        this.addImpressionKey(`${baseSlotKey}:auc:${escapeKeyPart(auctionId)}`);
+      }
+    } else {
+      this.addImpressionKey(baseSlotKey);
+      if (auctionId) {
+        this.addImpressionKey(`${baseSlotKey}:auc:${escapeKeyPart(auctionId)}`);
       }
     }
   }
@@ -2140,6 +2218,7 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
     const auctionId = options?.auctionId || rawBid.auctionId || cached?.auctionId || "";
     const transactionId = options?.transactionId || rawBid.transactionId || cached?.transactionId || "";
     const creativeId = rawBid.creativeId || cached?.bidTrace?.creativeId || options?.bid?.creativeId || "";
+    const adId = options?.adId || rawBid.adId || options?.bid?.adId || "";
     const mediaType = options?.mediaType || rawBid.mediaType || cached?.bidTrace?.mediaType || "banner";
     const targetSlot = resolvedSlotId || adUnitCode;
     const rec = (resolvedSlotId ? this.slotViewabilityRecords.get(resolvedSlotId) : void 0) || (adUnitCode ? this.slotViewabilityRecords.get(adUnitCode) : void 0);
@@ -2180,7 +2259,13 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       }
     }
     const currentRefreshIndex = options?.refreshIndex ?? (resolvedSlotId ? this.slotRefreshIndices.get(resolvedSlotId) ?? (adUnitCode ? this.slotRefreshIndices.get(adUnitCode) : void 0) ?? (rec ? rec.refreshIndex : 0) : 0);
-    const alreadyEmitted = resolvedSlotId && this.hasImpressionEmitted(resolvedSlotId, currentRefreshIndex, auctionId, creativeId) || adUnitCode && adUnitCode !== resolvedSlotId && this.hasImpressionEmitted(adUnitCode, currentRefreshIndex, auctionId, creativeId);
+    const alreadyEmitted = resolvedSlotId && this.hasImpressionEmitted(
+      resolvedSlotId,
+      currentRefreshIndex,
+      auctionId,
+      creativeId,
+      adId
+    ) || adUnitCode && adUnitCode !== resolvedSlotId && this.hasImpressionEmitted(adUnitCode, currentRefreshIndex, auctionId, creativeId, adId);
     if (alreadyEmitted) {
       this.log(
         "DEBUG",
@@ -2189,9 +2274,9 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       return false;
     }
     if (resolvedSlotId)
-      this.markImpressionEmitted(resolvedSlotId, currentRefreshIndex, auctionId, creativeId);
+      this.markImpressionEmitted(resolvedSlotId, currentRefreshIndex, auctionId, creativeId, adId);
     if (adUnitCode && adUnitCode !== resolvedSlotId)
-      this.markImpressionEmitted(adUnitCode, currentRefreshIndex, auctionId, creativeId);
+      this.markImpressionEmitted(adUnitCode, currentRefreshIndex, auctionId, creativeId, adId);
     this.enqueue(TraceEventType.IMPRESSION, "impression", {
       auctionId,
       transactionId,
@@ -2330,6 +2415,7 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
   navigate(pageviewId, pageUrl) {
     this.disable();
     this.slotRefreshIndices.clear();
+    this.slotAdSessionCounters.clear();
     this.floorDecisions.clear();
     this.pendingThresholdListeners.clear();
     this.config.pageviewId = pageviewId || generateUUID();
@@ -3033,10 +3119,6 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
     this.logger.log(level, msg, ...args);
   }
 };
-var defaultLogger = createLogger({
-  prefix: "[analytics]",
-  logLevel: "INFO"
-});
 function extractAnalyticsOptions(config, allowProviderless = true) {
   if (!config) return null;
   if (Array.isArray(config)) {
@@ -3559,9 +3641,29 @@ function attachImaAdsManager(analytics, adsManager, options) {
     return cached;
   };
   let adStarted = false;
+  let activeAdSession = null;
+  const mintAdSession = (initialAd) => {
+    const nextSession = typeof self.nextSlotAdSession === "function" ? self.nextSlotAdSession(slotId) : `ad-session-${(self.slotAdSessionCounters?.get(slotId) ?? 0) + 1}`;
+    if (self.slotAdSessionCounters && typeof self.nextSlotAdSession !== "function") {
+      const c = (self.slotAdSessionCounters.get(slotId) ?? 0) + 1;
+      self.slotAdSessionCounters.set(slotId, c);
+    }
+    const adId = (typeof initialAd?.getAdId === "function" ? initialAd.getAdId() : initialAd?.adId ?? initialAd?.id) || "";
+    const creativeId = (typeof initialAd?.getCreativeId === "function" ? initialAd.getCreativeId() : initialAd?.creativeId) || "";
+    activeAdSession = {
+      sessionId: nextSession,
+      adId: adId || void 0,
+      creativeId: creativeId || void 0
+    };
+    return activeAdSession;
+  };
+  const onAdLoaded = (event) => {
+    const ad = typeof event?.getAd === "function" ? event.getAd() : event?.ad;
+    mintAdSession(ad);
+    self.log("DEBUG", "IMA AdEvent.LOADED received", { slotId, activeAdSession });
+  };
   const onAdStartedOrImpression = (event) => {
     adStarted = true;
-    self.log("DEBUG", "IMA AdEvent.STARTED / IMPRESSION received", event);
     const ad = typeof event?.getAd === "function" ? event.getAd() : event?.ad;
     const adData = {};
     if (ad) {
@@ -3571,15 +3673,28 @@ function attachImaAdsManager(analytics, adsManager, options) {
       adData.duration = typeof ad.getDuration === "function" ? ad.getDuration() : ad.duration;
       adData.advertiserName = typeof ad.getAdvertiserName === "function" ? ad.getAdvertiserName() : "";
     }
+    if (!activeAdSession || adData.adId && activeAdSession.adId && activeAdSession.adId !== adData.adId) {
+      mintAdSession(ad);
+    } else {
+      if (!activeAdSession.adId && adData.adId) {
+        activeAdSession.adId = adData.adId;
+      }
+      if (!activeAdSession.creativeId && adData.creativeId) {
+        activeAdSession.creativeId = adData.creativeId;
+      }
+    }
+    const session = activeAdSession || mintAdSession(ad);
     const cached = getWinningBid(adData);
     const resolvedSlotId = options?.slotId && options.slotId !== "video" ? options.slotId : options?.adUnitCode && options.adUnitCode !== "video" ? options.adUnitCode : cached?.adUnitCode || options?.slotId || options?.adUnitCode || "video";
     const resolvedAdUnitCode = options?.adUnitCode && options.adUnitCode !== "video" ? options.adUnitCode : cached?.adUnitCode || resolvedSlotId;
     const resolvedAuctionId = auctionId || cached?.auctionId || "";
     const resolvedTransactionId = transactionId || cached?.transactionId || "";
+    const creativeId = session.creativeId || adData.creativeId || cached?.bidTrace?.creativeId || options?.bid?.creativeId || "";
+    const stableAdIdentity = session.adId || adData.adId || creativeId || session.sessionId;
     const mergedBid = {
       ...cached?.rawBid || options?.bid,
       mediaType: "video",
-      creativeId: adData.creativeId || cached?.bidTrace?.creativeId || options?.bid?.creativeId || ""
+      creativeId
     };
     const emitted = self.recordImpression(resolvedSlotId, {
       adUnitCode: resolvedAdUnitCode,
@@ -3587,6 +3702,7 @@ function attachImaAdsManager(analytics, adsManager, options) {
       transactionId: resolvedTransactionId,
       mediaType: "video",
       bid: mergedBid,
+      adId: stableAdIdentity,
       metadata: {
         ...options?.metadata,
         media_type: "video",
@@ -3594,6 +3710,16 @@ function attachImaAdsManager(analytics, adsManager, options) {
         ...Number.isFinite(adData.duration) ? { ad_duration_s: String(adData.duration) } : {}
       }
     });
+    let rawType = typeof event?.type === "string" ? event.type : typeof event?.getType === "function" ? event.getType() : typeof event === "string" ? event : "";
+    if (rawType.toLowerCase().startsWith("adevent.")) {
+      rawType = rawType.slice(8);
+    }
+    const eventName = rawType ? rawType.toUpperCase() : "STARTED/IMPRESSION";
+    self.log(
+      "DEBUG",
+      `IMA AdEvent.${eventName} received${emitted ? "" : " (second event for this ad, already counted)"}`,
+      event
+    );
     if (emitted && options?.onImpression) {
       try {
         options.onImpression(resolvedSlotId, { ad, bid: mergedBid });
@@ -3628,6 +3754,7 @@ function attachImaAdsManager(analytics, adsManager, options) {
     });
   };
   const onAdError = (event) => {
+    activeAdSession = null;
     const cached = getWinningBid();
     const resolvedAdUnitCode = options?.adUnitCode && options.adUnitCode !== "video" ? options.adUnitCode : cached?.adUnitCode || slotId;
     const err = recordImaAdError(analytics, event, {
@@ -3650,6 +3777,7 @@ function attachImaAdsManager(analytics, adsManager, options) {
   const adEventType = googleIma?.AdEvent?.Type || {};
   const adErrorEventType = googleIma?.AdErrorEvent?.Type || {};
   const rawListeners = [
+    { type: adEventType.LOADED || "loaded", handler: onAdLoaded },
     { type: adEventType.STARTED || "started", handler: onAdStartedOrImpression },
     { type: adEventType.IMPRESSION || "impression", handler: onAdStartedOrImpression },
     {
@@ -3661,7 +3789,19 @@ function attachImaAdsManager(analytics, adsManager, options) {
       type: adEventType.THIRD_QUARTILE || "thirdQuartile",
       handler: () => onMilestone("thirdQuartile")
     },
-    { type: adEventType.COMPLETE || "complete", handler: () => onMilestone("complete") },
+    {
+      type: adEventType.COMPLETE || "complete",
+      handler: () => {
+        activeAdSession = null;
+        onMilestone("complete");
+      }
+    },
+    {
+      type: adEventType.ALL_ADS_COMPLETED || "allAdsCompleted",
+      handler: () => {
+        activeAdSession = null;
+      }
+    },
     { type: adEventType.CLICK || "click", handler: onAdClick },
     { type: adErrorEventType.AD_ERROR || "adError", handler: onAdError }
   ];
@@ -3680,6 +3820,7 @@ function attachImaAdsManager(analytics, adsManager, options) {
     }
   }
   const cleanup = () => {
+    activeAdSession = null;
     attached.delete(analytics);
     for (const { type, handler } of listeners) {
       try {
@@ -3946,6 +4087,8 @@ function normalizeImaEventName(name) {
       return "volumeChanged";
     case "loaded":
       return "loaded";
+    case "alladscompleted":
+      return "allAdsCompleted";
     case "aderror":
     case "error":
       return "adError";
@@ -4060,6 +4203,7 @@ export {
   BidkernelPrebidAnalytics,
   CACHED_BID_TTL_MS,
   ImaAdsManagerStub,
+  LogLevel,
   PrebidEventDeduper,
   attachImaAdsManager,
   attachVideoPlayer,
@@ -4071,6 +4215,7 @@ export {
   isSessionActive,
   isTrustedEndpoint,
   normalizeImaEventName,
+  normalizeLogLevel,
   onSessionResume,
   registerPrebidAnalytics
 };

package/package.json

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