@bidkernel/analytics 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,3 +1,45 @@
+import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
+
+/**
+ * BidTrace captures per-bid metrics for the reporting warehouse.
+ * CPM is the raw gross value as reported by the bidder.
+ */
+interface BidTrace {
+    bidder?: string | undefined;
+    /** raw bidder CPM, falling back to converted CPM if original is absent */
+    cpm?: number | undefined;
+    /** raw bidder currency, falling back to converted currency if original is absent (default USD) */
+    currency?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    dealId?: string | undefined;
+    /** "banner" | "video" | "native" */
+    mediaType?: string | undefined;
+    /** time from bid request to response */
+    latencyMs?: number | undefined;
+    /** primary adomain from bid.meta.advertiserDomains */
+    advertiserDomain?: string | undefined;
+    /** from bid.creativeId (Prebid) or bid.crid (oRTB) */
+    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 {
     endpoint: string;
     propertyId: string;
@@ -28,6 +70,32 @@ 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;
+    transactionId: string;
+    adUnitCode: string;
+    rawBid?: any;
+    timestamp: number;
+}
 interface SlotViewabilityState {
     inView: boolean;
     viewable: boolean;
@@ -64,11 +132,18 @@ declare class BidkernelPrebidAnalytics {
     private consecutiveSendFailures;
     private nextSendAllowedAt;
     private replayedEventCount;
+    private immediateFlushScheduled;
+    private persistedBatchKeys;
+    private persistedCleanupTimer;
     private intersectionObserver;
     private slotViewabilityRecords;
     private elementToSlotId;
     private slotRefreshIndices;
+    private slotLastAuctionIds;
     private pendingThresholdListeners;
+    private slotEmittedImpressionKeys;
+    private cachedWinningBids;
+    private videoDetachCleanups;
     constructor(config: AnalyticsConfig);
     enable(): void;
     disable(): void;
@@ -83,6 +158,23 @@ declare class BidkernelPrebidAnalytics {
     observeSlot(element: HTMLElement | string, slotId?: string, options?: SlotObserveOptions): void;
     unobserveSlot(slotId: string): void;
     destroySlot(slotId: string): void;
+    hasImpressionEmitted(slotId: string, refreshIndex?: number, auctionId?: string, creativeId?: string): boolean;
+    private markImpressionEmitted;
+    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;
     getRefreshIndex(slotId: string): number;
@@ -109,6 +201,10 @@ declare class BidkernelPrebidAnalytics {
     private handleSendFailure;
     private flush;
     private flushBeacon;
+    private persistBatch;
+    private removePersistedBatch;
+    private schedulePersistedCleanup;
+    private resendPersistedBatches;
     private log;
 }
 declare function registerPrebidAnalytics(pbjsGlobalName?: string, defaults?: Partial<AnalyticsConfig>): void;
@@ -163,6 +259,12 @@ interface AdsGlobal {
     refreshAll?: () => void;
     /** Notify the SDK that an SPA route transition happened so analytics and tracking reset. */
     navigate?: (url?: string) => void;
+    /** Attach video player hooks (HTML5 <video> or Google IMA AdsManager) for render-triggered telemetry. */
+    attachVideoPlayer?: (target: any, options?: any) => () => void;
+    /** Attach Google IMA SDK AdsManager event bridge for video render-triggered telemetry. */
+    attachImaAdsManager?: (adsManager: any, options?: any) => () => void;
+    /** Manually record ad render / impression when using custom rendering pipelines. */
+    recordImpression?: (slotId: string, options?: any) => boolean;
 }
 /**
  * Returns the global bidkernel SDK object interface.
@@ -173,4 +275,4 @@ interface AdsGlobal {
  */
 declare function getbidkernel(alias?: string): AdsGlobal;
 
-export { type AdsGlobal, type AnalyticsConfig, BidkernelPrebidAnalytics, PrebidEventDeduper, type SizeMapping, type SlotConfig, type SlotObserveOptions, type SlotSize, type SlotSizes, type SlotViewabilityState, getPrebidEventKey, getbidkernel, registerPrebidAnalytics };
+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, registerPrebidAnalytics };