@bidkernel/analytics 0.24.0 → 0.27.0

package/dist/index.mjs

@@ -304,6 +304,14 @@ var TraceEventType = {
   CLICK: 12,
   /** AD_RENDER_FAILED - Prebid failed to render the winning ad */
   AD_RENDER_FAILED: 13,
+  /**
+   * WARN - A wrapper condition worth reporting that is not a failure: a slot with no
+   * fitting sizes, a video load the watchdog cut short. Carries its own
+   * event_name, like ERROR. Publishers gate these with warnings_enabled;
+   * ERROR is never gated. Before this type these events reached the adapter
+   * and were dropped for want of one, so warnings_enabled controlled nothing.
+   */
+  WARN: 17,
   UNRECOGNIZED: -1
 };
 var BidderOutcome = {
@@ -1010,6 +1018,14 @@ var EVENT_NAME_TO_TYPE = {
   timeInView: TraceEventType.TIME_IN_VIEW,
   viewable: TraceEventType.VIEWABLE
 };
+var LEVEL_TO_TYPE = {
+  WARN: TraceEventType.WARN,
+  ERROR: TraceEventType.ERROR
+};
+var SELF_NAMING_TYPES = /* @__PURE__ */ new Set([
+  TraceEventType.ERROR,
+  TraceEventType.WARN
+]);
 var REVENUE_FLUSH_DELAY_MS = 3e3;
 var REVENUE_FLUSH_TYPES = /* @__PURE__ */ new Set([
   TraceEventType.IMPRESSION,
@@ -1277,11 +1293,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 +1351,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 +1395,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 +1420,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 +2065,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 +2143,37 @@ 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)}`)) {
+          return true;
+        }
+      } else if (this.slotEmittedImpressionKeys.has(`${baseSlotKey}:ad:${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 +2187,33 @@ 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)}`);
+        if (auctionId) {
+          this.addImpressionKey(
+            `${baseSlotKey}:auc:${escapeKeyPart(auctionId)}:ad:${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 +2226,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 +2267,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 +2282,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,
@@ -2289,9 +2382,9 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
     }
   }
   trackRawEvent(level, eventName, data) {
-    const eventType = EVENT_NAME_TO_TYPE[eventName] ?? (level === "ERROR" ? TraceEventType.ERROR : void 0);
+    const eventType = LEVEL_TO_TYPE[level] ?? EVENT_NAME_TO_TYPE[eventName];
     if (eventType === void 0) return;
-    this.enqueue(eventType, eventName, data, level);
+    this.enqueue(eventType, eventName, data);
   }
   /**
    * Record the wrapper's Live Floors decision for an auction and ad unit,
@@ -2330,6 +2423,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();
@@ -2680,9 +2774,9 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
   isDuplicate(eventName, data) {
     return this.deduper.isDuplicate(eventName, data);
   }
-  enqueue(type, eventName, data, level) {
+  enqueue(type, eventName, data) {
     if (!this.isEnabled) return;
-    if (!this.shouldSample(type, level)) return;
+    if (!this.shouldSample(type)) return;
     if (this.managesSessionId && sessionNeedsSync()) {
       this.config.sessionId = getOrCreateSessionId();
     }
@@ -2691,8 +2785,8 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       timestampMs: Date.now(),
       type,
       // Typed events have a fixed name that ingest derives from `type`; only
-      // ERROR events carry theirs, which names the failure.
-      eventName: type === TraceEventType.ERROR ? eventName : "",
+      // ERROR and WARN carry theirs, which names the failure or condition.
+      eventName: SELF_NAMING_TYPES.has(type) ? eventName : "",
       auctionId: idToBytes(String(data.auctionId || "")),
       transactionId: idToBytes(String(data.transactionId || "")),
       adUnitCode: data.adUnitCode || data.elementId || "",
@@ -2772,13 +2866,12 @@ var BidkernelPrebidAnalytics = class _BidkernelPrebidAnalytics {
       }, this.config.revenueFlushDelayMs);
     }
   }
-  shouldSample(type, level) {
+  shouldSample(type) {
     if (type === TraceEventType.ERROR) {
       this.errorCount++;
-      if (this.errorCount > MAX_ERRORS_PER_SESSION) return false;
-      return this.config.errorsEnabled;
+      return this.errorCount <= MAX_ERRORS_PER_SESSION;
     }
-    if (level === "WARN") {
+    if (type === TraceEventType.WARN) {
       return this.config.warningsEnabled;
     }
     return this.config.auctionEnabled;
@@ -3033,10 +3126,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 +3648,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 +3680,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 +3709,7 @@ function attachImaAdsManager(analytics, adsManager, options) {
       transactionId: resolvedTransactionId,
       mediaType: "video",
       bid: mergedBid,
+      adId: stableAdIdentity,
       metadata: {
         ...options?.metadata,
         media_type: "video",
@@ -3594,6 +3717,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 +3761,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 +3784,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 +3796,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 +3827,7 @@ function attachImaAdsManager(analytics, adsManager, options) {
     }
   }
   const cleanup = () => {
+    activeAdSession = null;
     attached.delete(analytics);
     for (const { type, handler } of listeners) {
       try {
@@ -3946,6 +4094,8 @@ function normalizeImaEventName(name) {
       return "volumeChanged";
     case "loaded":
       return "loaded";
+    case "alladscompleted":
+      return "allAdsCompleted";
     case "aderror":
     case "error":
       return "adError";
@@ -4060,6 +4210,7 @@ export {
   BidkernelPrebidAnalytics,
   CACHED_BID_TTL_MS,
   ImaAdsManagerStub,
+  LogLevel,
   PrebidEventDeduper,
   attachImaAdsManager,
   attachVideoPlayer,
@@ -4071,6 +4222,7 @@ export {
   isSessionActive,
   isTrustedEndpoint,
   normalizeImaEventName,
+  normalizeLogLevel,
   onSessionResume,
   registerPrebidAnalytics
 };

package/package.json

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