@bidkernel/analytics 0.6.0 → 0.9.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,12 +70,53 @@ 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;
     timeInViewMs: number;
     refreshIndex: number;
 }
+/**
+ * The ingest endpoint decides where auction telemetry -- CPMs, deal IDs,
+ * advertiser domains, user and session IDs -- is shipped, and it arrives from
+ * page context (enableAnalytics options, or the _bidkernelAnalyticsConfig
+ * global). Anything running in the page can reach that, including a banner
+ * creative rendered into a same-origin Prebid friendly iframe, so the value is
+ * validated rather than trusted: HTTPS only, absolute, no credentials in the
+ * URL. Plain HTTP is allowed only for loopback so local development works.
+ *
+ * This deliberately does not allowlist hosts: properties on branded ingest
+ * domains legitimately point at their own. Hijacking a live instance to a
+ * different origin is prevented separately, by pinning in
+ * registerPrebidAnalytics.
+ */
+declare function isTrustedEndpoint(raw: string): boolean;
 /**
  * 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
@@ -71,7 +154,12 @@ declare class BidkernelPrebidAnalytics {
     private slotViewabilityRecords;
     private elementToSlotId;
     private slotRefreshIndices;
+    private slotLastAuctionIds;
     private pendingThresholdListeners;
+    private slotEmittedImpressionKeys;
+    private cachedWinningBids;
+    private videoDetachCleanups;
+    private auctionBidderOutcomes;
     constructor(config: AnalyticsConfig);
     enable(): void;
     disable(): void;
@@ -86,8 +174,49 @@ declare class BidkernelPrebidAnalytics {
     observeSlot(element: HTMLElement | string, slotId?: string, options?: SlotObserveOptions): void;
     unobserveSlot(slotId: string): void;
     destroySlot(slotId: string): void;
+    /**
+     * Reads a cached winning bid, treating an entry past CACHED_BID_TTL_MS as
+     * absent and dropping it. Every read goes through here so a stale bid can
+     * never be married to a much later render.
+     */
+    private getCachedBid;
+    /** Removes every alias pointing at one entry. Aliases are stored by identity. */
+    private deleteCachedBidEntry;
+    /**
+     * Drops expired entries, then evicts oldest-first until the key cap holds.
+     * Map iterates in insertion order and one win's aliases are written
+     * consecutively, so eviction takes a whole bid's aliases together.
+     */
+    private pruneCachedWinningBids;
+    /** Records a dedup key, evicting oldest-first at the cap. */
+    private addImpressionKey;
+    /**
+     * The bidder-outcome map for an auction, creating it if absent. Evicts the
+     * oldest auction at the cap: without this, any auction whose auctionEnd never
+     * fires (abandoned, navigated away from mid-flight) leaks its map forever.
+     */
+    private getOrCreateAuctionOutcomes;
+    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;
+    /** The validated ingest endpoint in use, or "" when none passed validation. */
+    getEndpoint(): string;
     getRefreshIndex(slotId: string): number;
     triggerSlotRefresh(slotId: string, options?: SlotObserveOptions): void;
     trackRawEvent(level: string, eventName: string, data: any): void;
@@ -112,6 +241,7 @@ declare class BidkernelPrebidAnalytics {
     private handleSendFailure;
     private flush;
     private flushBeacon;
+    private pendingKeyPrefix;
     private persistBatch;
     private removePersistedBatch;
     private schedulePersistedCleanup;
@@ -170,6 +300,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.
@@ -180,4 +316,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, isTrustedEndpoint, registerPrebidAnalytics };