@bidkernel/analytics 0.12.0 → 0.17.0

package/dist/index.d.mts

@@ -23,21 +23,9 @@ interface BidTrace {
     creativeId?: string | undefined;
 }
 declare const BidTrace: MessageFns<BidTrace>;
-type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
-type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
-    [K in keyof T]?: DeepPartial<T[K]>;
-} : Partial<T>;
-type KeysOfUnion<T> = T extends T ? keyof T : never;
-type Exact<P, I extends P> = P extends Builtin ? P : P & {
-    [K in keyof P]: Exact<P[K], I[K]>;
-} & {
-    [K in Exclude<keyof I, KeysOfUnion<P>>]: never;
-};
 interface MessageFns<T> {
     encode(message: T, writer?: BinaryWriter): BinaryWriter;
     decode(input: BinaryReader | Uint8Array, length?: number): T;
-    create<I extends Exact<DeepPartial<T>, I>>(base?: I): T;
-    fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
 }
 
 interface AnalyticsConfig {
@@ -54,6 +42,13 @@ interface AnalyticsConfig {
     errorsEnabled?: boolean;
     /** Whether to enable client-side IAB viewability and time-in-view measurement. Defaults to true. */
     viewabilityEnabled?: boolean;
+    /**
+     * Whether identifiers may be written to localStorage (session id and its
+     * timestamp, exit batches). Defaults to true. Set false until storage
+     * consent is known, then flip with setStorageAllowed(true); events are
+     * always collected and sent regardless.
+     */
+    storageAllowed?: boolean;
     logLevel?: "DEBUG" | "INFO" | "WARN" | "ERROR";
     /** Window global holding the Prebid instance to attach to. Defaults to "pbjs". */
     pbjsGlobalName?: string;
@@ -76,24 +71,6 @@ interface SlotObserveOptions {
     refreshIndex?: number;
     emitRefreshEvent?: boolean;
 }
-interface VideoPlayerOptions {
-    /** The ad unit code / slot identifier for analytics reporting */
-    adUnitCode?: string;
-    slotId?: string;
-    auctionId?: string;
-    transactionId?: string;
-    bid?: any;
-    metadata?: Record<string, string>;
-    refreshIndex?: number;
-    /** Whether to automatically track IAB video viewability (2s continuous >=50% in-view) and Time-in-View. Defaults to true. */
-    trackViewability?: boolean;
-    /** Custom callback when impression is triggered */
-    onImpression?: (slotId: string, details: any) => void;
-    /** Custom callback when playback milestone reached (25%, 50%, 75%, 100%) */
-    onMilestone?: (milestone: "firstQuartile" | "midpoint" | "thirdQuartile" | "complete", slotId: string) => void;
-    /** Custom callback when render / playback error occurs */
-    onError?: (error: any) => void;
-}
 interface CachedWinningBid {
     bidTrace: BidTrace;
     auctionId: string;
@@ -108,6 +85,7 @@ interface SlotViewabilityState {
     timeInViewMs: number;
     refreshIndex: number;
 }
+declare const CACHED_BID_TTL_MS: number;
 /**
  * The ingest endpoint decides where auction telemetry -- CPMs, deal IDs,
  * advertiser domains, user and session IDs -- is shipped, and it arrives from
@@ -123,6 +101,15 @@ interface SlotViewabilityState {
  * registerPrebidAnalytics.
  */
 declare function isTrustedEndpoint(raw: string): boolean;
+/**
+ * The visitor's session id: a 30-minute rolling session persisted in
+ * localStorage when storage is allowed, kept in memory otherwise. A session
+ * begun in memory (before storage consent) is adopted and persisted the
+ * first time this runs with storage allowed, so consent never splits a
+ * session. Exported so an integration can report the same id the adapter
+ * stamps on its batches.
+ */
+declare function getOrCreateSessionId(): string;
 /**
  * Canonical duplicate-detection key for a Prebid event. Shared by the adapter
  * and the diagnostic extension so the two can never drift apart. Covers the
@@ -138,17 +125,16 @@ declare class PrebidEventDeduper {
     private seenKeys;
     isDuplicate(eventName: string, data: any): boolean;
 }
-/**
- * Hooks Google IMA SDK methods to automatically intercept AdsManager creation
- * across active BidkernelPrebidAnalytics instances without requiring manual
- * publisher calls to attachImaAdsManager.
- */
-declare function hookImaPrototype(ima: any): void;
-declare function initImaInterception(): void;
 declare class BidkernelPrebidAnalytics {
     private static activeInstances;
     static getActiveInstances(): Set<BidkernelPrebidAnalytics>;
-    static initImaInterception(): void;
+    /**
+     * 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: boolean): void;
+    static isStorageAllowed(): boolean;
     private config;
     private queue;
     private errorCount;
@@ -171,6 +157,10 @@ declare class BidkernelPrebidAnalytics {
     private slotRefreshIndices;
     private slotLastAuctionIds;
     private pendingThresholdListeners;
+    private pendingViewableListeners;
+    private slotElements;
+    private clickDetachCleanups;
+    private lastClickAt;
     private slotEmittedImpressionKeys;
     private cachedWinningBids;
     private videoDetachCleanups;
@@ -178,10 +168,48 @@ declare class BidkernelPrebidAnalytics {
     private logger;
     constructor(config: AnalyticsConfig);
     enable(): void;
+    /**
+     * 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(): boolean;
     disable(): void;
     private handleVisibilityChange;
     private handleIntersection;
     private handleDwellComplete;
+    private notifyViewable;
+    /**
+     * 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: string, element: HTMLElement): void;
+    /**
+     * 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: string, options?: {
+        metadata?: Record<string, string>;
+    }): boolean;
+    /**
+     * 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: HTMLElement, slotId: string): () => void;
+    onViewable(slotId: string, callback: (slotId: string) => void): () => void;
     private scheduleThresholdTimers;
     private checkThresholdListeners;
     private getCurrentTimeInView;
@@ -204,11 +232,6 @@ declare class BidkernelPrebidAnalytics {
      * consecutively, so eviction takes a whole bid's aliases together.
      */
     private pruneCachedWinningBids;
-    /**
-     * Searches cached winning bids for an entry matching the given filters (creativeId,
-     * adId, or mediaType), falling back to the most recent winning video bid.
-     */
-    private findCachedWinningBid;
     /** Records a dedup key, evicting oldest-first at the cap. */
     private addImpressionKey;
     /**
@@ -222,18 +245,6 @@ declare class BidkernelPrebidAnalytics {
     recordImpression(slotId: string, options?: SlotObserveOptions & {
         bid?: any;
     }): boolean;
-    /**
-     * Bridges Google IMA SDK AdsManager events to Bidkernel analytics.
-     * Defers IMPRESSION emission until AdEvent.STARTED (or IMPRESSION),
-     * tracks milestones (FIRST_QUARTILE, MIDPOINT, THIRD_QUARTILE, COMPLETE),
-     * and handles AD_ERROR.
-     */
-    attachImaAdsManager(adsManager: any, options?: VideoPlayerOptions): () => void;
-    /**
-     * Attaches render hooks and viewability tracking to a video player.
-     * Supports HTML5 <video> elements, container elements, or Google IMA AdsManager.
-     */
-    attachVideoPlayer(target: any, options?: VideoPlayerOptions): () => void;
     onTimeInViewThreshold(slotId: string, thresholdMs: number, callback: (slotId: string, durationMs: number) => void): () => void;
     getViewabilityState(slotId: string): SlotViewabilityState | undefined;
     /** The validated ingest endpoint in use, or "" when none passed validation. */
@@ -271,6 +282,69 @@ declare class BidkernelPrebidAnalytics {
 }
 declare function registerPrebidAnalytics(pbjsGlobalName?: string, defaults?: Partial<AnalyticsConfig>): void;
 
+/**
+ * Video and Google IMA support for the analytics adapter: render-triggered
+ * impressions from a video player or an IMA AdsManager, and the automatic
+ * IMA interception that hooks every AdsManager the page creates.
+ *
+ * Importing this module installs attachVideoPlayer and attachImaAdsManager
+ * on BidkernelPrebidAnalytics and starts the interception, so the package's
+ * public entry (index.ts) and the standalone bundle carry the full API. The
+ * display-only SDK imports the core module alone and ships none of this.
+ */
+interface VideoPlayerOptions {
+    /** The ad unit code / slot identifier for analytics reporting */
+    adUnitCode?: string;
+    slotId?: string;
+    auctionId?: string;
+    transactionId?: string;
+    bid?: any;
+    metadata?: Record<string, string>;
+    refreshIndex?: number;
+    /** Whether to automatically track IAB video viewability (2s continuous >=50% in-view) and Time-in-View. Defaults to true. */
+    trackViewability?: boolean;
+    /** Custom callback when impression is triggered */
+    onImpression?: (slotId: string, details: any) => void;
+    /** Custom callback when playback milestone reached (25%, 50%, 75%, 100%) */
+    onMilestone?: (milestone: "firstQuartile" | "midpoint" | "thirdQuartile" | "complete", slotId: string) => void;
+    /** Custom callback when render / playback error occurs */
+    onError?: (error: any) => void;
+}
+/**
+ * Hooks Google IMA SDK methods to automatically intercept AdsManager creation
+ * across active BidkernelPrebidAnalytics instances without requiring manual
+ * publisher calls to attachImaAdsManager.
+ */
+declare function hookImaPrototype(ima: any): void;
+declare function initImaInterception(): void;
+/**
+ * Bridges Google IMA SDK AdsManager events to Bidkernel analytics.
+ * Defers IMPRESSION emission until AdEvent.STARTED (or IMPRESSION),
+ * tracks milestones (FIRST_QUARTILE, MIDPOINT, THIRD_QUARTILE, COMPLETE),
+ * and handles AD_ERROR.
+ */
+declare function attachImaAdsManager(analytics: BidkernelPrebidAnalytics, adsManager: any, options?: VideoPlayerOptions): () => void;
+/**
+ * Attaches render hooks and viewability tracking to a video player.
+ * Supports HTML5 <video> elements, container elements, or Google IMA AdsManager.
+ */
+declare function attachVideoPlayer(analytics: BidkernelPrebidAnalytics, target: any, options?: VideoPlayerOptions): () => void;
+declare module "./prebid-analytics" {
+    interface BidkernelPrebidAnalytics {
+        /**
+         * Bridges Google IMA SDK AdsManager events to Bidkernel analytics: the
+         * IMPRESSION is deferred until AdEvent.STARTED (or IMPRESSION), quartile
+         * milestones are reported, and AD_ERROR becomes an adRenderFailed.
+         */
+        attachImaAdsManager(adsManager: any, options?: VideoPlayerOptions): () => void;
+        /**
+         * Attaches render hooks and viewability tracking to a video player: an
+         * HTML5 <video> element, a container element, or an IMA AdsManager.
+         */
+        attachVideoPlayer(target: any, options?: VideoPlayerOptions): () => void;
+    }
+}
+
 type SlotSize = [number, number];
 type SlotSizes = SlotSize[];
 interface SizeMapping {
@@ -337,4 +411,4 @@ interface AdsGlobal {
  */
 declare function getbidkernel(alias?: string): AdsGlobal;
 
-export { type AdsGlobal, type AnalyticsConfig, BidkernelPrebidAnalytics, type CachedWinningBid, PrebidEventDeduper, type SizeMapping, type SlotConfig, type SlotObserveOptions, type SlotSize, type SlotSizes, type SlotViewabilityState, type VideoPlayerOptions, getPrebidEventKey, getbidkernel, hookImaPrototype, initImaInterception, isTrustedEndpoint, registerPrebidAnalytics };
+export { type AdsGlobal, type AnalyticsConfig, BidkernelPrebidAnalytics, CACHED_BID_TTL_MS, type CachedWinningBid, PrebidEventDeduper, type SizeMapping, type SlotConfig, type SlotObserveOptions, type SlotSize, type SlotSizes, type SlotViewabilityState, type VideoPlayerOptions, attachImaAdsManager, attachVideoPlayer, getOrCreateSessionId, getPrebidEventKey, getbidkernel, hookImaPrototype, initImaInterception, isTrustedEndpoint, registerPrebidAnalytics };

package/dist/index.d.ts

@@ -23,21 +23,9 @@ interface BidTrace {
     creativeId?: string | undefined;
 }
 declare const BidTrace: MessageFns<BidTrace>;
-type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
-type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
-    [K in keyof T]?: DeepPartial<T[K]>;
-} : Partial<T>;
-type KeysOfUnion<T> = T extends T ? keyof T : never;
-type Exact<P, I extends P> = P extends Builtin ? P : P & {
-    [K in keyof P]: Exact<P[K], I[K]>;
-} & {
-    [K in Exclude<keyof I, KeysOfUnion<P>>]: never;
-};
 interface MessageFns<T> {
     encode(message: T, writer?: BinaryWriter): BinaryWriter;
     decode(input: BinaryReader | Uint8Array, length?: number): T;
-    create<I extends Exact<DeepPartial<T>, I>>(base?: I): T;
-    fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
 }
 
 interface AnalyticsConfig {
@@ -54,6 +42,13 @@ interface AnalyticsConfig {
     errorsEnabled?: boolean;
     /** Whether to enable client-side IAB viewability and time-in-view measurement. Defaults to true. */
     viewabilityEnabled?: boolean;
+    /**
+     * Whether identifiers may be written to localStorage (session id and its
+     * timestamp, exit batches). Defaults to true. Set false until storage
+     * consent is known, then flip with setStorageAllowed(true); events are
+     * always collected and sent regardless.
+     */
+    storageAllowed?: boolean;
     logLevel?: "DEBUG" | "INFO" | "WARN" | "ERROR";
     /** Window global holding the Prebid instance to attach to. Defaults to "pbjs". */
     pbjsGlobalName?: string;
@@ -76,24 +71,6 @@ interface SlotObserveOptions {
     refreshIndex?: number;
     emitRefreshEvent?: boolean;
 }
-interface VideoPlayerOptions {
-    /** The ad unit code / slot identifier for analytics reporting */
-    adUnitCode?: string;
-    slotId?: string;
-    auctionId?: string;
-    transactionId?: string;
-    bid?: any;
-    metadata?: Record<string, string>;
-    refreshIndex?: number;
-    /** Whether to automatically track IAB video viewability (2s continuous >=50% in-view) and Time-in-View. Defaults to true. */
-    trackViewability?: boolean;
-    /** Custom callback when impression is triggered */
-    onImpression?: (slotId: string, details: any) => void;
-    /** Custom callback when playback milestone reached (25%, 50%, 75%, 100%) */
-    onMilestone?: (milestone: "firstQuartile" | "midpoint" | "thirdQuartile" | "complete", slotId: string) => void;
-    /** Custom callback when render / playback error occurs */
-    onError?: (error: any) => void;
-}
 interface CachedWinningBid {
     bidTrace: BidTrace;
     auctionId: string;
@@ -108,6 +85,7 @@ interface SlotViewabilityState {
     timeInViewMs: number;
     refreshIndex: number;
 }
+declare const CACHED_BID_TTL_MS: number;
 /**
  * The ingest endpoint decides where auction telemetry -- CPMs, deal IDs,
  * advertiser domains, user and session IDs -- is shipped, and it arrives from
@@ -123,6 +101,15 @@ interface SlotViewabilityState {
  * registerPrebidAnalytics.
  */
 declare function isTrustedEndpoint(raw: string): boolean;
+/**
+ * The visitor's session id: a 30-minute rolling session persisted in
+ * localStorage when storage is allowed, kept in memory otherwise. A session
+ * begun in memory (before storage consent) is adopted and persisted the
+ * first time this runs with storage allowed, so consent never splits a
+ * session. Exported so an integration can report the same id the adapter
+ * stamps on its batches.
+ */
+declare function getOrCreateSessionId(): string;
 /**
  * Canonical duplicate-detection key for a Prebid event. Shared by the adapter
  * and the diagnostic extension so the two can never drift apart. Covers the
@@ -138,17 +125,16 @@ declare class PrebidEventDeduper {
     private seenKeys;
     isDuplicate(eventName: string, data: any): boolean;
 }
-/**
- * Hooks Google IMA SDK methods to automatically intercept AdsManager creation
- * across active BidkernelPrebidAnalytics instances without requiring manual
- * publisher calls to attachImaAdsManager.
- */
-declare function hookImaPrototype(ima: any): void;
-declare function initImaInterception(): void;
 declare class BidkernelPrebidAnalytics {
     private static activeInstances;
     static getActiveInstances(): Set<BidkernelPrebidAnalytics>;
-    static initImaInterception(): void;
+    /**
+     * 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: boolean): void;
+    static isStorageAllowed(): boolean;
     private config;
     private queue;
     private errorCount;
@@ -171,6 +157,10 @@ declare class BidkernelPrebidAnalytics {
     private slotRefreshIndices;
     private slotLastAuctionIds;
     private pendingThresholdListeners;
+    private pendingViewableListeners;
+    private slotElements;
+    private clickDetachCleanups;
+    private lastClickAt;
     private slotEmittedImpressionKeys;
     private cachedWinningBids;
     private videoDetachCleanups;
@@ -178,10 +168,48 @@ declare class BidkernelPrebidAnalytics {
     private logger;
     constructor(config: AnalyticsConfig);
     enable(): void;
+    /**
+     * 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(): boolean;
     disable(): void;
     private handleVisibilityChange;
     private handleIntersection;
     private handleDwellComplete;
+    private notifyViewable;
+    /**
+     * 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: string, element: HTMLElement): void;
+    /**
+     * 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: string, options?: {
+        metadata?: Record<string, string>;
+    }): boolean;
+    /**
+     * 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: HTMLElement, slotId: string): () => void;
+    onViewable(slotId: string, callback: (slotId: string) => void): () => void;
     private scheduleThresholdTimers;
     private checkThresholdListeners;
     private getCurrentTimeInView;
@@ -204,11 +232,6 @@ declare class BidkernelPrebidAnalytics {
      * consecutively, so eviction takes a whole bid's aliases together.
      */
     private pruneCachedWinningBids;
-    /**
-     * Searches cached winning bids for an entry matching the given filters (creativeId,
-     * adId, or mediaType), falling back to the most recent winning video bid.
-     */
-    private findCachedWinningBid;
     /** Records a dedup key, evicting oldest-first at the cap. */
     private addImpressionKey;
     /**
@@ -222,18 +245,6 @@ declare class BidkernelPrebidAnalytics {
     recordImpression(slotId: string, options?: SlotObserveOptions & {
         bid?: any;
     }): boolean;
-    /**
-     * Bridges Google IMA SDK AdsManager events to Bidkernel analytics.
-     * Defers IMPRESSION emission until AdEvent.STARTED (or IMPRESSION),
-     * tracks milestones (FIRST_QUARTILE, MIDPOINT, THIRD_QUARTILE, COMPLETE),
-     * and handles AD_ERROR.
-     */
-    attachImaAdsManager(adsManager: any, options?: VideoPlayerOptions): () => void;
-    /**
-     * Attaches render hooks and viewability tracking to a video player.
-     * Supports HTML5 <video> elements, container elements, or Google IMA AdsManager.
-     */
-    attachVideoPlayer(target: any, options?: VideoPlayerOptions): () => void;
     onTimeInViewThreshold(slotId: string, thresholdMs: number, callback: (slotId: string, durationMs: number) => void): () => void;
     getViewabilityState(slotId: string): SlotViewabilityState | undefined;
     /** The validated ingest endpoint in use, or "" when none passed validation. */
@@ -271,6 +282,69 @@ declare class BidkernelPrebidAnalytics {
 }
 declare function registerPrebidAnalytics(pbjsGlobalName?: string, defaults?: Partial<AnalyticsConfig>): void;
 
+/**
+ * Video and Google IMA support for the analytics adapter: render-triggered
+ * impressions from a video player or an IMA AdsManager, and the automatic
+ * IMA interception that hooks every AdsManager the page creates.
+ *
+ * Importing this module installs attachVideoPlayer and attachImaAdsManager
+ * on BidkernelPrebidAnalytics and starts the interception, so the package's
+ * public entry (index.ts) and the standalone bundle carry the full API. The
+ * display-only SDK imports the core module alone and ships none of this.
+ */
+interface VideoPlayerOptions {
+    /** The ad unit code / slot identifier for analytics reporting */
+    adUnitCode?: string;
+    slotId?: string;
+    auctionId?: string;
+    transactionId?: string;
+    bid?: any;
+    metadata?: Record<string, string>;
+    refreshIndex?: number;
+    /** Whether to automatically track IAB video viewability (2s continuous >=50% in-view) and Time-in-View. Defaults to true. */
+    trackViewability?: boolean;
+    /** Custom callback when impression is triggered */
+    onImpression?: (slotId: string, details: any) => void;
+    /** Custom callback when playback milestone reached (25%, 50%, 75%, 100%) */
+    onMilestone?: (milestone: "firstQuartile" | "midpoint" | "thirdQuartile" | "complete", slotId: string) => void;
+    /** Custom callback when render / playback error occurs */
+    onError?: (error: any) => void;
+}
+/**
+ * Hooks Google IMA SDK methods to automatically intercept AdsManager creation
+ * across active BidkernelPrebidAnalytics instances without requiring manual
+ * publisher calls to attachImaAdsManager.
+ */
+declare function hookImaPrototype(ima: any): void;
+declare function initImaInterception(): void;
+/**
+ * Bridges Google IMA SDK AdsManager events to Bidkernel analytics.
+ * Defers IMPRESSION emission until AdEvent.STARTED (or IMPRESSION),
+ * tracks milestones (FIRST_QUARTILE, MIDPOINT, THIRD_QUARTILE, COMPLETE),
+ * and handles AD_ERROR.
+ */
+declare function attachImaAdsManager(analytics: BidkernelPrebidAnalytics, adsManager: any, options?: VideoPlayerOptions): () => void;
+/**
+ * Attaches render hooks and viewability tracking to a video player.
+ * Supports HTML5 <video> elements, container elements, or Google IMA AdsManager.
+ */
+declare function attachVideoPlayer(analytics: BidkernelPrebidAnalytics, target: any, options?: VideoPlayerOptions): () => void;
+declare module "./prebid-analytics" {
+    interface BidkernelPrebidAnalytics {
+        /**
+         * Bridges Google IMA SDK AdsManager events to Bidkernel analytics: the
+         * IMPRESSION is deferred until AdEvent.STARTED (or IMPRESSION), quartile
+         * milestones are reported, and AD_ERROR becomes an adRenderFailed.
+         */
+        attachImaAdsManager(adsManager: any, options?: VideoPlayerOptions): () => void;
+        /**
+         * Attaches render hooks and viewability tracking to a video player: an
+         * HTML5 <video> element, a container element, or an IMA AdsManager.
+         */
+        attachVideoPlayer(target: any, options?: VideoPlayerOptions): () => void;
+    }
+}
+
 type SlotSize = [number, number];
 type SlotSizes = SlotSize[];
 interface SizeMapping {
@@ -337,4 +411,4 @@ interface AdsGlobal {
  */
 declare function getbidkernel(alias?: string): AdsGlobal;
 
-export { type AdsGlobal, type AnalyticsConfig, BidkernelPrebidAnalytics, type CachedWinningBid, PrebidEventDeduper, type SizeMapping, type SlotConfig, type SlotObserveOptions, type SlotSize, type SlotSizes, type SlotViewabilityState, type VideoPlayerOptions, getPrebidEventKey, getbidkernel, hookImaPrototype, initImaInterception, isTrustedEndpoint, registerPrebidAnalytics };
+export { type AdsGlobal, type AnalyticsConfig, BidkernelPrebidAnalytics, CACHED_BID_TTL_MS, type CachedWinningBid, PrebidEventDeduper, type SizeMapping, type SlotConfig, type SlotObserveOptions, type SlotSize, type SlotSizes, type SlotViewabilityState, type VideoPlayerOptions, attachImaAdsManager, attachVideoPlayer, getOrCreateSessionId, getPrebidEventKey, getbidkernel, hookImaPrototype, initImaInterception, isTrustedEndpoint, registerPrebidAnalytics };