@bidspark/analytics 0.0.0-stage → 0.43.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +15 -0
- package/README.md +122 -2
- package/dist/analytics.global.js +1 -0
- package/dist/index.d.mts +661 -0
- package/dist/index.d.ts +661 -0
- package/dist/index.js +4805 -0
- package/dist/index.mjs +4753 -0
- package/package.json +54 -4
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,661 @@
|
|
|
1
|
+
import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
|
|
2
|
+
|
|
3
|
+
declare const LogLevel: {
|
|
4
|
+
readonly DEBUG: "DEBUG";
|
|
5
|
+
readonly INFO: "INFO";
|
|
6
|
+
readonly WARN: "WARN";
|
|
7
|
+
readonly ERROR: "ERROR";
|
|
8
|
+
};
|
|
9
|
+
type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
|
|
10
|
+
/** Normalizes case-insensitive log level string to canonical LogLevel. */
|
|
11
|
+
declare function normalizeLogLevel(level?: unknown): LogLevel;
|
|
12
|
+
|
|
13
|
+
declare const TraceEventType: {
|
|
14
|
+
readonly TRACE_EVENT_TYPE_UNSPECIFIED: 0;
|
|
15
|
+
readonly AUCTION_START: 1;
|
|
16
|
+
readonly AUCTION_END: 2;
|
|
17
|
+
readonly BID_WIN: 4;
|
|
18
|
+
/** IMPRESSION - Ad rendered into DOM */
|
|
19
|
+
readonly IMPRESSION: 5;
|
|
20
|
+
/** VIEWABLE - IAB viewability met (once per render cycle) */
|
|
21
|
+
readonly VIEWABLE: 6;
|
|
22
|
+
/** TIME_IN_VIEW - Accumulated in-viewport duration (fired at render cycle end) */
|
|
23
|
+
readonly TIME_IN_VIEW: 7;
|
|
24
|
+
readonly ERROR: 9;
|
|
25
|
+
readonly SLOT_DEFINED: 10;
|
|
26
|
+
readonly SLOT_DESTROYED: 11;
|
|
27
|
+
/** CLICK - Ad click-through */
|
|
28
|
+
readonly CLICK: 12;
|
|
29
|
+
/** AD_RENDER_FAILED - Prebid failed to render winning ad */
|
|
30
|
+
readonly AD_RENDER_FAILED: 13;
|
|
31
|
+
/**
|
|
32
|
+
* WARN - Non-fatal wrapper condition (e.g. no fitting sizes, video watchdog timeout).
|
|
33
|
+
* Uses custom event_name; gated by tracker.warnings_enabled.
|
|
34
|
+
*/
|
|
35
|
+
readonly WARN: 17;
|
|
36
|
+
/**
|
|
37
|
+
* CONSENT - Visitor consent decision (granted or denied). Metadata holds flattened CMP details:
|
|
38
|
+
* regime, action, strings (tc, ac, gpp, usp), vendor/purpose counts, and flags.
|
|
39
|
+
*/
|
|
40
|
+
readonly CONSENT: 19;
|
|
41
|
+
/**
|
|
42
|
+
* RECOVERY - Ad block recovery funnel. Metadata: state (detected|shown|allow_click|support_click|dismissed|verified|recovered),
|
|
43
|
+
* first ("1" on first detected/recovered), mode (ask|metered|wall), shown_as (soft|wall on shown),
|
|
44
|
+
* signals (bitmask), sdk_loaded, device (mobile|desktop), browser, forced ("1" on forced show).
|
|
45
|
+
*/
|
|
46
|
+
readonly RECOVERY: 20;
|
|
47
|
+
readonly UNRECOGNIZED: -1;
|
|
48
|
+
};
|
|
49
|
+
type TraceEventType = typeof TraceEventType[keyof typeof TraceEventType];
|
|
50
|
+
declare namespace TraceEventType {
|
|
51
|
+
type TRACE_EVENT_TYPE_UNSPECIFIED = typeof TraceEventType.TRACE_EVENT_TYPE_UNSPECIFIED;
|
|
52
|
+
type AUCTION_START = typeof TraceEventType.AUCTION_START;
|
|
53
|
+
type AUCTION_END = typeof TraceEventType.AUCTION_END;
|
|
54
|
+
type BID_WIN = typeof TraceEventType.BID_WIN;
|
|
55
|
+
type IMPRESSION = typeof TraceEventType.IMPRESSION;
|
|
56
|
+
type VIEWABLE = typeof TraceEventType.VIEWABLE;
|
|
57
|
+
type TIME_IN_VIEW = typeof TraceEventType.TIME_IN_VIEW;
|
|
58
|
+
type ERROR = typeof TraceEventType.ERROR;
|
|
59
|
+
type SLOT_DEFINED = typeof TraceEventType.SLOT_DEFINED;
|
|
60
|
+
type SLOT_DESTROYED = typeof TraceEventType.SLOT_DESTROYED;
|
|
61
|
+
type CLICK = typeof TraceEventType.CLICK;
|
|
62
|
+
type AD_RENDER_FAILED = typeof TraceEventType.AD_RENDER_FAILED;
|
|
63
|
+
type WARN = typeof TraceEventType.WARN;
|
|
64
|
+
type CONSENT = typeof TraceEventType.CONSENT;
|
|
65
|
+
type RECOVERY = typeof TraceEventType.RECOVERY;
|
|
66
|
+
type UNRECOGNIZED = typeof TraceEventType.UNRECOGNIZED;
|
|
67
|
+
}
|
|
68
|
+
/** Per-bid metrics for reporting warehouse. CPM is gross value reported by bidder. */
|
|
69
|
+
interface BidTrace {
|
|
70
|
+
bidder?: string | undefined;
|
|
71
|
+
/** Raw CPM; falls back to converted CPM if absent */
|
|
72
|
+
cpm?: number | undefined;
|
|
73
|
+
/** Raw currency; falls back to converted currency (default "USD") */
|
|
74
|
+
currency?: string | undefined;
|
|
75
|
+
width?: number | undefined;
|
|
76
|
+
height?: number | undefined;
|
|
77
|
+
dealId?: string | undefined;
|
|
78
|
+
/** "banner" | "video" | "native" */
|
|
79
|
+
mediaType?: string | undefined;
|
|
80
|
+
/** Request to response duration in ms */
|
|
81
|
+
latencyMs?: number | undefined;
|
|
82
|
+
/** Primary domain from bid.meta.advertiserDomains */
|
|
83
|
+
advertiserDomain?: string | undefined;
|
|
84
|
+
/** bid.creativeId (Prebid) or bid.crid (oRTB) */
|
|
85
|
+
creativeId?: string | undefined;
|
|
86
|
+
}
|
|
87
|
+
declare const BidTrace: MessageFns$1<BidTrace>;
|
|
88
|
+
interface MessageFns$1<T> {
|
|
89
|
+
encode(message: T, writer?: BinaryWriter): BinaryWriter;
|
|
90
|
+
decode(input: BinaryReader | Uint8Array, length?: number): T;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Identifier wire encoding (proto/trace_event.proto).
|
|
95
|
+
*
|
|
96
|
+
* Wire fields are `bytes`. Lowercase canonical UUID travels as 16 raw bytes;
|
|
97
|
+
* other identifiers travel as UTF-8. Exact round-trip: ingest formats 16 bytes
|
|
98
|
+
* back to lowercase UUID string and takes other byte lengths verbatim as text.
|
|
99
|
+
*/
|
|
100
|
+
/** Encodes ID to wire bytes: 16 bytes for canonical UUID, UTF-8 otherwise. */
|
|
101
|
+
declare function idToBytes(id: string | undefined): Uint8Array;
|
|
102
|
+
/** Decodes wire bytes to ID: 16 bytes format to canonical lowercase UUID. */
|
|
103
|
+
declare function idToString(bytes: Uint8Array | undefined): string;
|
|
104
|
+
/** Normalizes a telemetry sample rate to (0, 1], defaulting invalid or unset values to 1 (100%). */
|
|
105
|
+
declare function normalizeSampleRate(rate?: number): number;
|
|
106
|
+
/**
|
|
107
|
+
* Deterministic 32-bit FNV-1a visitor roll in [0, 1).
|
|
108
|
+
* The same visitor key maps to the same uniform bucket across pageviews and sessions.
|
|
109
|
+
*/
|
|
110
|
+
declare function isVisitorSampled(visitorKey: string, sampleRate?: number): boolean;
|
|
111
|
+
|
|
112
|
+
interface AnalyticsConfig {
|
|
113
|
+
endpoint: string;
|
|
114
|
+
/** Usage endpoint origin (e.g. "https://by.bidspark.io/u"). */
|
|
115
|
+
usageEndpoint?: string;
|
|
116
|
+
propertyId: string;
|
|
117
|
+
pageviewId?: string;
|
|
118
|
+
sessionId?: string;
|
|
119
|
+
userId?: string;
|
|
120
|
+
/** In-memory visitor key for deterministic sampling before storage consent grants userId. */
|
|
121
|
+
visitorId?: string;
|
|
122
|
+
deviceType?: string;
|
|
123
|
+
country?: string;
|
|
124
|
+
region?: string;
|
|
125
|
+
auctionEnabled?: boolean;
|
|
126
|
+
warningsEnabled?: boolean;
|
|
127
|
+
/** Deterministic visitor sample rate in (0, 1]. Defaults to 1 (100%). */
|
|
128
|
+
sampleRate?: number;
|
|
129
|
+
/** Track IAB viewability and time-in-view. Defaults to true. */
|
|
130
|
+
viewabilityEnabled?: boolean;
|
|
131
|
+
/**
|
|
132
|
+
* Allows localStorage writes (session ID, timestamp, exit batches).
|
|
133
|
+
* Defaults to true. Set false until storage consent is confirmed;
|
|
134
|
+
* event collection and delivery continue regardless.
|
|
135
|
+
*/
|
|
136
|
+
storageAllowed?: boolean;
|
|
137
|
+
logLevel?: LogLevel | "DEBUG" | "INFO" | "WARN" | "ERROR" | string;
|
|
138
|
+
/** Window global holding Prebid instance. Defaults to "pbjs". */
|
|
139
|
+
pbjsGlobalName?: string;
|
|
140
|
+
/** Attach pbjs.onEvent listeners. Defaults to true; set false for manual SDK tracking. */
|
|
141
|
+
attachPbjsListeners?: boolean;
|
|
142
|
+
/**
|
|
143
|
+
* Batching delay (ms) for revenue events (impression, win, click) to combine
|
|
144
|
+
* render cycle events in one POST. 0 sends next tick. Defaults to 3000.
|
|
145
|
+
*/
|
|
146
|
+
revenueFlushDelayMs?: number;
|
|
147
|
+
/** Window global alias for CMP instance. Defaults to "ads". */
|
|
148
|
+
alias?: string;
|
|
149
|
+
}
|
|
150
|
+
/** Canonical consent record shape from CMP. */
|
|
151
|
+
interface ConsentRecord {
|
|
152
|
+
regime: "tcf" | "us";
|
|
153
|
+
action: "accept_all" | "reject_all" | "save" | "withdraw" | "replay" | "opt_out" | "opt_in" | "gpc";
|
|
154
|
+
cmpId: number;
|
|
155
|
+
cmpVersion: number;
|
|
156
|
+
gvlVersion?: number;
|
|
157
|
+
tcString?: string | null;
|
|
158
|
+
acString?: string | null;
|
|
159
|
+
gppString?: string | null;
|
|
160
|
+
uspString?: string | null;
|
|
161
|
+
purposesConsented?: number[];
|
|
162
|
+
vendorsConsented?: number;
|
|
163
|
+
vendorsTotal?: number;
|
|
164
|
+
language?: string;
|
|
165
|
+
optOut?: boolean;
|
|
166
|
+
gpc?: boolean;
|
|
167
|
+
}
|
|
168
|
+
interface SlotObserveOptions {
|
|
169
|
+
adUnitCode?: string;
|
|
170
|
+
auctionId?: string;
|
|
171
|
+
transactionId?: string;
|
|
172
|
+
mediaType?: string;
|
|
173
|
+
bid?: any;
|
|
174
|
+
metadata?: Record<string, string>;
|
|
175
|
+
refreshIndex?: number;
|
|
176
|
+
adId?: string;
|
|
177
|
+
isRefresh?: boolean;
|
|
178
|
+
}
|
|
179
|
+
interface CachedWinningBid {
|
|
180
|
+
bidTrace: BidTrace;
|
|
181
|
+
auctionId: string;
|
|
182
|
+
transactionId: string;
|
|
183
|
+
adUnitCode: string;
|
|
184
|
+
rawBid?: any;
|
|
185
|
+
timestamp: number;
|
|
186
|
+
}
|
|
187
|
+
interface SlotViewabilityState {
|
|
188
|
+
inView: boolean;
|
|
189
|
+
viewable: boolean;
|
|
190
|
+
timeInViewMs: number;
|
|
191
|
+
refreshIndex: number;
|
|
192
|
+
}
|
|
193
|
+
declare const DEFAULT_ALIAS = "ads";
|
|
194
|
+
declare const CACHED_BID_TTL_MS: number;
|
|
195
|
+
/** Live Floors pricing decision for an auction and ad unit. */
|
|
196
|
+
interface FloorDecision {
|
|
197
|
+
/** Applied floor for primary size in integer cents. */
|
|
198
|
+
floorCents?: number;
|
|
199
|
+
/** Floor term source. */
|
|
200
|
+
source: "static" | "pool" | "none";
|
|
201
|
+
/** Pageview variance multiplier (two decimals). */
|
|
202
|
+
treatment: number;
|
|
203
|
+
}
|
|
204
|
+
/**
|
|
205
|
+
* Validates ingest endpoint: HTTPS only (or loopback HTTP), absolute, credentials forbidden.
|
|
206
|
+
* Prevents malicious creative frames from exfiltrating telemetry to third-party domains.
|
|
207
|
+
* Live instances pin their origin on first registration.
|
|
208
|
+
*/
|
|
209
|
+
declare function isTrustedEndpoint(raw: string): boolean;
|
|
210
|
+
/** True if visitor activity occurred within past 30 minutes. Used by SDK to gate refresh. */
|
|
211
|
+
declare function isSessionActive(now?: number): boolean;
|
|
212
|
+
/** Subscribes to session resumption after 30 idle minutes. Returns unsubscribe function. */
|
|
213
|
+
declare function onSessionResume(listener: () => void): () => void;
|
|
214
|
+
/**
|
|
215
|
+
* Returns current 30-minute session ID. Stored in localStorage when allowed,
|
|
216
|
+
* memory otherwise. Adopts in-memory ID upon storage consent without session split.
|
|
217
|
+
*/
|
|
218
|
+
declare function getOrCreateSessionId(): string;
|
|
219
|
+
/**
|
|
220
|
+
* Reports whether this page load started the visit: true when the session id was
|
|
221
|
+
* created on this page, false when it continues a stored session from an earlier page.
|
|
222
|
+
* Read it after the consent decision; before storage is allowed every page looks new.
|
|
223
|
+
*/
|
|
224
|
+
declare function sessionStarted(): boolean;
|
|
225
|
+
/**
|
|
226
|
+
* Removes the stored session keys (storage consent withdrawn). The in-memory
|
|
227
|
+
* session continues, so the session ID does not split.
|
|
228
|
+
*/
|
|
229
|
+
declare function clearStoredSession(): void;
|
|
230
|
+
declare function getOrCreateUserId(): string;
|
|
231
|
+
declare function clearStoredUserId(): void;
|
|
232
|
+
declare function resetTcfListener(): void;
|
|
233
|
+
/**
|
|
234
|
+
* Canonical duplicate-detection key for a Prebid event. Shared by the adapter
|
|
235
|
+
* and the diagnostic extension so the two can never drift apart. Covers the
|
|
236
|
+
* events the adapter forwards plus display-only events the extension shows.
|
|
237
|
+
*/
|
|
238
|
+
declare function getPrebidEventKey(eventName: string, data: any): string;
|
|
239
|
+
/**
|
|
240
|
+
* Tracks Prebid events already seen, by object identity and semantic key across replay and live streams.
|
|
241
|
+
*/
|
|
242
|
+
declare class PrebidEventDeduper {
|
|
243
|
+
private seenObjects;
|
|
244
|
+
private seenKeys;
|
|
245
|
+
isDuplicate(eventName: string, data: any): boolean;
|
|
246
|
+
}
|
|
247
|
+
declare class BidsparkPrebidAnalytics {
|
|
248
|
+
private static activeInstances;
|
|
249
|
+
private static allInstances;
|
|
250
|
+
static getActiveInstances(): Set<BidsparkPrebidAnalytics>;
|
|
251
|
+
static setLogLevel(level: LogLevel | string): void;
|
|
252
|
+
static getLogLevel(): LogLevel;
|
|
253
|
+
/** Sets page-wide localStorage permission. Telemetry collection and delivery remain active. */
|
|
254
|
+
static setStorageAllowed(allowed: boolean): void;
|
|
255
|
+
static isStorageAllowed(): boolean;
|
|
256
|
+
private config;
|
|
257
|
+
private usageRecorder;
|
|
258
|
+
private queue;
|
|
259
|
+
private errorCount;
|
|
260
|
+
private flushTimer;
|
|
261
|
+
private boundFlushBeacon;
|
|
262
|
+
private boundVisibilityChange;
|
|
263
|
+
private isEnabled;
|
|
264
|
+
private boundPbjsHandlers;
|
|
265
|
+
private pageUrl;
|
|
266
|
+
private deduper;
|
|
267
|
+
private consecutiveSendFailures;
|
|
268
|
+
private nextSendAllowedAt;
|
|
269
|
+
private replayedEventCount;
|
|
270
|
+
private revenueFlushTimer;
|
|
271
|
+
private persistedBatchKeys;
|
|
272
|
+
private persistedCleanupTimer;
|
|
273
|
+
private intersectionObserver;
|
|
274
|
+
private slotViewabilityRecords;
|
|
275
|
+
private elementToSlotId;
|
|
276
|
+
private slotRefreshIndices;
|
|
277
|
+
/** Configured slot name per ad unit code, stamped on that unit's events. */
|
|
278
|
+
private slotNames;
|
|
279
|
+
private slotAdSessionCounters;
|
|
280
|
+
private slotLastAuctionIds;
|
|
281
|
+
private pendingViewableListeners;
|
|
282
|
+
private slotElements;
|
|
283
|
+
private clickDetachCleanups;
|
|
284
|
+
private lastClickAt;
|
|
285
|
+
private slotEmittedImpressionKeys;
|
|
286
|
+
private cachedWinningBids;
|
|
287
|
+
private videoDetachCleanups;
|
|
288
|
+
private auctionBidderOutcomes;
|
|
289
|
+
private floorDecisions;
|
|
290
|
+
private recordedConsentKeys;
|
|
291
|
+
private consentCount;
|
|
292
|
+
private cmpDetach;
|
|
293
|
+
private logger;
|
|
294
|
+
private managesSessionId;
|
|
295
|
+
constructor(config: AnalyticsConfig);
|
|
296
|
+
setLogLevel(level: LogLevel | string): void;
|
|
297
|
+
getLogLevel(): LogLevel;
|
|
298
|
+
enable(): void;
|
|
299
|
+
/**
|
|
300
|
+
* Binds Prebid event listeners and replays historical pbjs.getEvents().
|
|
301
|
+
* Idempotent. Returns true if handlers successfully attached.
|
|
302
|
+
*/
|
|
303
|
+
attachPbjs(): boolean;
|
|
304
|
+
disable(): void;
|
|
305
|
+
private handleVisibilityChange;
|
|
306
|
+
private handleIntersection;
|
|
307
|
+
private handleDwellComplete;
|
|
308
|
+
private notifyViewable;
|
|
309
|
+
/**
|
|
310
|
+
* Calls back once per render cycle when the slot has met the IAB viewable
|
|
311
|
+
* standard this adapter measures (immediately if it already has). Works
|
|
312
|
+
* before the slot is observed: the listener waits for observeSlot. Returns
|
|
313
|
+
* an unsubscribe function.
|
|
314
|
+
*/
|
|
315
|
+
/**
|
|
316
|
+
* Names the element to measure for a slot when the creative renders
|
|
317
|
+
* somewhere other than the slot element (a sticky bar, an interstitial).
|
|
318
|
+
* Applies to the current cycle at once and to every later render.
|
|
319
|
+
*/
|
|
320
|
+
setSlotElement(slotId: string, element: HTMLElement): void;
|
|
321
|
+
/**
|
|
322
|
+
* Records a click on the slot's current creative, attributed to the cached
|
|
323
|
+
* winning bid. Repeats within one second are one click. Returns whether a
|
|
324
|
+
* CLICK was recorded.
|
|
325
|
+
*/
|
|
326
|
+
recordClick(slotId: string, options?: {
|
|
327
|
+
metadata?: Record<string, string>;
|
|
328
|
+
}): boolean;
|
|
329
|
+
/**
|
|
330
|
+
* Detects clicks into a cross-origin creative frame: a click inside an
|
|
331
|
+
* iframe moves focus into it and blurs the window. Returns a detach
|
|
332
|
+
* function; every tracker is detached on disable().
|
|
333
|
+
*/
|
|
334
|
+
attachClickTracker(element: HTMLElement, slotId: string): () => void;
|
|
335
|
+
onViewable(slotId: string, callback: (slotId: string) => void): () => void;
|
|
336
|
+
private getCurrentTimeInView;
|
|
337
|
+
private flushSlotTimeInView;
|
|
338
|
+
private flushAllSlotsTimeInView;
|
|
339
|
+
observeSlot(element: HTMLElement | string, slotId?: string, options?: SlotObserveOptions): void;
|
|
340
|
+
unobserveSlot(slotId: string): void;
|
|
341
|
+
/** Names the configured slot an ad unit code belongs to; an empty name forgets it. */
|
|
342
|
+
registerSlot(elementId: string, slot: string | undefined): void;
|
|
343
|
+
destroySlot(slotId: string): void;
|
|
344
|
+
/**
|
|
345
|
+
* Reads a cached winning bid, treating an entry past CACHED_BID_TTL_MS as
|
|
346
|
+
* absent and dropping it. Every read goes through here so a stale bid can
|
|
347
|
+
* never be married to a much later render.
|
|
348
|
+
*/
|
|
349
|
+
private getCachedBid;
|
|
350
|
+
/** Removes every alias pointing at one entry. Aliases are stored by identity. */
|
|
351
|
+
private deleteCachedBidEntry;
|
|
352
|
+
/**
|
|
353
|
+
* Drops expired entries, then evicts oldest-first until the key cap holds.
|
|
354
|
+
* Map iterates in insertion order and one win's aliases are written
|
|
355
|
+
* consecutively, so eviction takes a whole bid's aliases together.
|
|
356
|
+
*/
|
|
357
|
+
private pruneCachedWinningBids;
|
|
358
|
+
/** Records a dedup key, evicting oldest-first at the cap. */
|
|
359
|
+
private addImpressionKey;
|
|
360
|
+
/**
|
|
361
|
+
* The bidder-outcome map for an auction, creating it if absent. Evicts the
|
|
362
|
+
* oldest auction at the cap: without this, any auction whose auctionEnd never
|
|
363
|
+
* fires (abandoned, navigated away from mid-flight) leaks its map forever.
|
|
364
|
+
*/
|
|
365
|
+
private getOrCreateAuctionOutcomes;
|
|
366
|
+
nextSlotAdSession(slotId: string): string;
|
|
367
|
+
hasImpressionEmitted(slotId: string, refreshIndex?: number, auctionId?: string, creativeId?: string, adId?: string): boolean;
|
|
368
|
+
private markImpressionEmitted;
|
|
369
|
+
recordImpression(slotId: string, options?: SlotObserveOptions & {
|
|
370
|
+
bid?: any;
|
|
371
|
+
}): boolean;
|
|
372
|
+
getViewabilityState(slotId: string): SlotViewabilityState | undefined;
|
|
373
|
+
/** The validated ingest endpoint in use, or "" when none passed validation. */
|
|
374
|
+
getEndpoint(): string;
|
|
375
|
+
getRefreshIndex(slotId: string): number;
|
|
376
|
+
triggerSlotRefresh(slotId: string, options?: SlotObserveOptions): void;
|
|
377
|
+
trackRawEvent(level: string, eventName: string, data: any): void;
|
|
378
|
+
/**
|
|
379
|
+
* Record the wrapper's Live Floors decision for an auction and ad unit,
|
|
380
|
+
* before the auction runs. The decision is stamped on the auction's
|
|
381
|
+
* outcome entries for the ad unit at auction end and on the win and
|
|
382
|
+
* impression rows that follow, so every outcome can be split by floor,
|
|
383
|
+
* source and treatment without a join. Integrations without the module
|
|
384
|
+
* never call this and their rows carry no floor fields.
|
|
385
|
+
*/
|
|
386
|
+
recordFloorDecision(auctionId: string, adUnitCode: string, decision: FloorDecision): void;
|
|
387
|
+
private floorDecisionFor;
|
|
388
|
+
/**
|
|
389
|
+
* Enqueues one CONSENT event with the record flattened into metadata under snake_case keys.
|
|
390
|
+
* Deduped on regime|action|tcString|gppString|uspString per pageview.
|
|
391
|
+
*/
|
|
392
|
+
recordConsent(record: ConsentRecord): boolean;
|
|
393
|
+
/**
|
|
394
|
+
* Subscribes to ads:consent on document, and replays the current CMP record if one
|
|
395
|
+
* is available from the configured alias. Returns a detach function.
|
|
396
|
+
*/
|
|
397
|
+
attachCmp(): () => void;
|
|
398
|
+
/** Device storage follows the decision; a refusal also drops the stored session. */
|
|
399
|
+
private followConsent;
|
|
400
|
+
setUserId(userId: string): void;
|
|
401
|
+
setVisitorId(visitorId: string): void;
|
|
402
|
+
setSampleRate(sampleRate?: number): void;
|
|
403
|
+
setSessionId(sessionId: string): void;
|
|
404
|
+
navigate(pageviewId: string, pageUrl: string): void;
|
|
405
|
+
recordAuctionStart(auctionId: string, adUnitCode?: string, bidderCount?: number): void;
|
|
406
|
+
private handleAuctionInit;
|
|
407
|
+
private handleAuctionEnd;
|
|
408
|
+
/**
|
|
409
|
+
* The render cycle an auction ending now would fill for an ad unit: 0 for
|
|
410
|
+
* a slot that has never rendered on this pageview, otherwise one past the
|
|
411
|
+
* cycle it last rendered. The index only advances when a creative renders,
|
|
412
|
+
* so two unfilled refresh auctions in a row report the same cycle; both
|
|
413
|
+
* count as refreshes, which is the point. Stamped on AUCTION_END bidder
|
|
414
|
+
* outcomes in enqueue; there is no per-refresh event.
|
|
415
|
+
*/
|
|
416
|
+
private auctionCycleIndex;
|
|
417
|
+
private handleBidRequested;
|
|
418
|
+
private handleBidResponse;
|
|
419
|
+
private handleBidTimeout;
|
|
420
|
+
private handleBidWon;
|
|
421
|
+
private handleNoBid;
|
|
422
|
+
private handleAdRenderFailed;
|
|
423
|
+
private handleAdRenderSucceeded;
|
|
424
|
+
private isDuplicate;
|
|
425
|
+
private enqueue;
|
|
426
|
+
private isSampledVisitor;
|
|
427
|
+
private shouldSample;
|
|
428
|
+
private requeue;
|
|
429
|
+
private drainBatch;
|
|
430
|
+
private sendFetch;
|
|
431
|
+
private handleSendFailure;
|
|
432
|
+
private flush;
|
|
433
|
+
private batchUrl;
|
|
434
|
+
private flushBeacon;
|
|
435
|
+
private pendingKeyPrefix;
|
|
436
|
+
private persistBatch;
|
|
437
|
+
private removePersistedBatch;
|
|
438
|
+
private schedulePersistedCleanup;
|
|
439
|
+
private resendPersistedBatches;
|
|
440
|
+
private log;
|
|
441
|
+
}
|
|
442
|
+
declare function registerPrebidAnalytics(pbjsGlobalName?: string, defaults?: Partial<AnalyticsConfig>): void;
|
|
443
|
+
|
|
444
|
+
/**
|
|
445
|
+
* Video and Google IMA telemetry: render-triggered impressions, playback milestones,
|
|
446
|
+
* and automatic IMA AdsManager interception.
|
|
447
|
+
*
|
|
448
|
+
* Imports install attachVideoPlayer and attachImaAdsManager onto
|
|
449
|
+
* BidsparkPrebidAnalytics. Core module excludes this for display-only bundles.
|
|
450
|
+
*/
|
|
451
|
+
interface VideoPlayerOptions {
|
|
452
|
+
/** Ad unit code or slot identifier. */
|
|
453
|
+
adUnitCode?: string;
|
|
454
|
+
slotId?: string;
|
|
455
|
+
auctionId?: string;
|
|
456
|
+
transactionId?: string;
|
|
457
|
+
bid?: any;
|
|
458
|
+
metadata?: Record<string, string>;
|
|
459
|
+
refreshIndex?: number;
|
|
460
|
+
/** Track IAB video viewability (2s continuous >=50% in view) and time-in-view. Defaults to true. */
|
|
461
|
+
trackViewability?: boolean;
|
|
462
|
+
/** Callback fired on impression emission. */
|
|
463
|
+
onImpression?: (slotId: string, details: any) => void;
|
|
464
|
+
/** Callback fired at playback milestones (25%, 50%, 75%, 100%). */
|
|
465
|
+
onMilestone?: (milestone: "firstQuartile" | "midpoint" | "thirdQuartile" | "complete", slotId: string) => void;
|
|
466
|
+
/** Callback fired on render or playback error. */
|
|
467
|
+
onError?: (error: any) => void;
|
|
468
|
+
}
|
|
469
|
+
/**
|
|
470
|
+
* Bridges Google IMA AdsManager events to Bidspark analytics: defers IMPRESSION
|
|
471
|
+
* until AdEvent.STARTED/IMPRESSION, tracks quartile milestones, and records AD_ERROR.
|
|
472
|
+
*/
|
|
473
|
+
declare function attachImaAdsManager(analytics: BidsparkPrebidAnalytics, adsManager: any, options?: VideoPlayerOptions): () => void;
|
|
474
|
+
/**
|
|
475
|
+
* Attaches render hooks and viewability tracking to HTML5 video, container, or IMA AdsManager.
|
|
476
|
+
*/
|
|
477
|
+
declare function attachVideoPlayer(analytics: BidsparkPrebidAnalytics, target: any, options?: VideoPlayerOptions): () => void;
|
|
478
|
+
declare module "./prebid-analytics" {
|
|
479
|
+
interface BidsparkPrebidAnalytics {
|
|
480
|
+
/** Bridges Google IMA AdsManager events (started, milestones, errors) to analytics. */
|
|
481
|
+
attachImaAdsManager(adsManager: any, options?: VideoPlayerOptions): () => void;
|
|
482
|
+
/** Attaches playback hooks and viewability tracking to video elements or AdsManager. */
|
|
483
|
+
attachVideoPlayer(target: any, options?: VideoPlayerOptions): () => void;
|
|
484
|
+
}
|
|
485
|
+
}
|
|
486
|
+
/**
|
|
487
|
+
* Test double implementing Google IMA AdsManager event surface.
|
|
488
|
+
* Relays outstream events into analytics adapters with IMA-shaped objects.
|
|
489
|
+
*/
|
|
490
|
+
declare class ImaAdsManagerStub {
|
|
491
|
+
private listeners;
|
|
492
|
+
addEventListener(type: string, listener: (event: any) => void): void;
|
|
493
|
+
removeEventListener(type: string, listener: (event: any) => void): void;
|
|
494
|
+
dispatch(name: string, payload?: any): void;
|
|
495
|
+
destroy(): void;
|
|
496
|
+
private createImaEvent;
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
declare const SAFE_CONTENT_TYPE = "text/plain";
|
|
500
|
+
declare function generateUUID(): string;
|
|
501
|
+
interface BeaconEvent {
|
|
502
|
+
type: TraceEventType;
|
|
503
|
+
metadata: Record<string, string>;
|
|
504
|
+
}
|
|
505
|
+
interface SendEventsOptions {
|
|
506
|
+
endpoint: string;
|
|
507
|
+
propertyId: string;
|
|
508
|
+
pageviewId?: string;
|
|
509
|
+
userId?: string;
|
|
510
|
+
sampleRate?: number;
|
|
511
|
+
events: BeaconEvent[];
|
|
512
|
+
geo?: {
|
|
513
|
+
country?: string;
|
|
514
|
+
region?: string;
|
|
515
|
+
};
|
|
516
|
+
}
|
|
517
|
+
/** Sends events in one batch outside the adapter (for pages where the adapter may not load). */
|
|
518
|
+
declare function sendEvents(opts: SendEventsOptions): boolean;
|
|
519
|
+
|
|
520
|
+
declare const protobufPackage = "bidspark";
|
|
521
|
+
declare const UsageUnit: {
|
|
522
|
+
readonly USAGE_UNIT_UNSPECIFIED: 0;
|
|
523
|
+
readonly AUCTION: 1;
|
|
524
|
+
readonly SERVER_AUCTION: 2;
|
|
525
|
+
readonly UNRECOGNIZED: -1;
|
|
526
|
+
};
|
|
527
|
+
type UsageUnit = typeof UsageUnit[keyof typeof UsageUnit];
|
|
528
|
+
declare namespace UsageUnit {
|
|
529
|
+
type USAGE_UNIT_UNSPECIFIED = typeof UsageUnit.USAGE_UNIT_UNSPECIFIED;
|
|
530
|
+
type AUCTION = typeof UsageUnit.AUCTION;
|
|
531
|
+
type SERVER_AUCTION = typeof UsageUnit.SERVER_AUCTION;
|
|
532
|
+
type UNRECOGNIZED = typeof UsageUnit.UNRECOGNIZED;
|
|
533
|
+
}
|
|
534
|
+
interface UsageEvent {
|
|
535
|
+
unit?: UsageUnit | undefined;
|
|
536
|
+
/** 16-byte UUID: wrapper auctionId, Prebid auctionId, or edge-minted UUID for server auctions */
|
|
537
|
+
usageId?: Uint8Array | undefined;
|
|
538
|
+
/** client clock, informational only */
|
|
539
|
+
timestampMs?: string | undefined;
|
|
540
|
+
/** slots in the round (informational, shown in CSV) */
|
|
541
|
+
slots?: number | undefined;
|
|
542
|
+
}
|
|
543
|
+
declare const UsageEvent: MessageFns<UsageEvent>;
|
|
544
|
+
interface UsageBatch {
|
|
545
|
+
/** in-memory per-pageview UUID, 16 bytes; never persisted to device storage */
|
|
546
|
+
pageviewId?: Uint8Array | undefined;
|
|
547
|
+
/** max 200 */
|
|
548
|
+
events?: UsageEvent[] | undefined;
|
|
549
|
+
}
|
|
550
|
+
declare const UsageBatch: MessageFns<UsageBatch>;
|
|
551
|
+
interface MessageFns<T> {
|
|
552
|
+
encode(message: T, writer?: BinaryWriter): BinaryWriter;
|
|
553
|
+
decode(input: BinaryReader | Uint8Array, length?: number): T;
|
|
554
|
+
}
|
|
555
|
+
|
|
556
|
+
type usage_event_MessageFns<T> = MessageFns<T>;
|
|
557
|
+
declare const usage_event_UsageBatch: typeof UsageBatch;
|
|
558
|
+
declare const usage_event_UsageEvent: typeof UsageEvent;
|
|
559
|
+
declare const usage_event_UsageUnit: typeof UsageUnit;
|
|
560
|
+
declare const usage_event_protobufPackage: typeof protobufPackage;
|
|
561
|
+
declare namespace usage_event {
|
|
562
|
+
export { type usage_event_MessageFns as MessageFns, usage_event_UsageBatch as UsageBatch, usage_event_UsageEvent as UsageEvent, usage_event_UsageUnit as UsageUnit, usage_event_protobufPackage as protobufPackage };
|
|
563
|
+
}
|
|
564
|
+
|
|
565
|
+
declare const USAGE_FLUSH_INTERVAL_MS = 10000;
|
|
566
|
+
declare const MAX_USAGE_BATCH_SIZE = 200;
|
|
567
|
+
interface UsageRecorderOptions {
|
|
568
|
+
endpoint: string;
|
|
569
|
+
propertyId: string;
|
|
570
|
+
pageviewId?: string;
|
|
571
|
+
}
|
|
572
|
+
/**
|
|
573
|
+
* UsageRecorder queues unsampled billable usage events (auctions) and
|
|
574
|
+
* flushes them to /u/{propertyId} independently of analytics sampling,
|
|
575
|
+
* toggles, or custom endpoints.
|
|
576
|
+
*
|
|
577
|
+
* Reads/writes NO device storage (localStorage / sessionStorage / cookies),
|
|
578
|
+
* does not depend on TCF Purpose 1, and carries no visitor identifiers.
|
|
579
|
+
*/
|
|
580
|
+
declare class UsageRecorder {
|
|
581
|
+
private endpoint;
|
|
582
|
+
private propertyId;
|
|
583
|
+
private pageviewIdStr;
|
|
584
|
+
private pageviewIdBytes;
|
|
585
|
+
private queue;
|
|
586
|
+
private flushTimer;
|
|
587
|
+
private boundPageHide;
|
|
588
|
+
private boundVisibilityChange;
|
|
589
|
+
private isDestroyed;
|
|
590
|
+
constructor(opts: UsageRecorderOptions);
|
|
591
|
+
getEndpoint(): string;
|
|
592
|
+
setEndpoint(endpoint: string): void;
|
|
593
|
+
getPropertyId(): string;
|
|
594
|
+
setPropertyId(propertyId: string): void;
|
|
595
|
+
getPageviewId(): string;
|
|
596
|
+
setPageviewId(pageviewId: string): void;
|
|
597
|
+
getQueueLength(): number;
|
|
598
|
+
record(auctionId: string, slots?: number, unit?: UsageUnit): void;
|
|
599
|
+
flush(): boolean;
|
|
600
|
+
destroy(): void;
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
type SlotSize = [number, number];
|
|
604
|
+
type SlotSizes = SlotSize[];
|
|
605
|
+
interface SizeMapping {
|
|
606
|
+
minViewport: [number, number];
|
|
607
|
+
sizes: SlotSizes;
|
|
608
|
+
}
|
|
609
|
+
interface SlotConfig {
|
|
610
|
+
/** Internal slot name, e.g. 'leaderboard'. */
|
|
611
|
+
slot?: string;
|
|
612
|
+
/** CSS selector locating slot container element, e.g. '.ad-slot'. */
|
|
613
|
+
selector?: string;
|
|
614
|
+
/** Accepted slot sizes, e.g. [[300, 250], [728, 90]]. */
|
|
615
|
+
sizes: SlotSizes;
|
|
616
|
+
/** Responsive viewport-to-size mappings. */
|
|
617
|
+
sizeMappings?: SizeMapping[];
|
|
618
|
+
/** Ad unit path for ad server targeting. */
|
|
619
|
+
adUnitPath?: string;
|
|
620
|
+
/** Allowed media types, e.g. ["banner", "video"]. Defaults to ["banner"]. */
|
|
621
|
+
mediaTypes?: string[];
|
|
622
|
+
/** Per-slot refresh interval in ms (0 = disabled). Overrides property default. */
|
|
623
|
+
refreshInterval?: number;
|
|
624
|
+
/** Slot config identifier. */
|
|
625
|
+
id?: string;
|
|
626
|
+
}
|
|
627
|
+
interface AdsGlobal {
|
|
628
|
+
/** Command queue executed after SDK initializes. */
|
|
629
|
+
q?: any[];
|
|
630
|
+
/** True when SDK is fully loaded. */
|
|
631
|
+
loaded?: boolean;
|
|
632
|
+
/** Returns current pageview and session IDs. */
|
|
633
|
+
getContext?: () => {
|
|
634
|
+
pageviewId: string;
|
|
635
|
+
sessionId: string;
|
|
636
|
+
};
|
|
637
|
+
/** Registers slot from CSS selector; reads element dimensions if config omitted. */
|
|
638
|
+
defineSlot?: (selector: string, config?: Partial<SlotConfig>) => void;
|
|
639
|
+
/** Tears down single slot by element ID. */
|
|
640
|
+
destroySlot?: (elementId: string) => void;
|
|
641
|
+
/** Tears down all registered slots. */
|
|
642
|
+
destroyAll?: () => void;
|
|
643
|
+
/** Forces immediate single-slot refresh, bypassing timer. */
|
|
644
|
+
refreshSlot?: (elementId: string) => void;
|
|
645
|
+
/** Forces immediate refresh of all registered slots. */
|
|
646
|
+
refreshAll?: () => void;
|
|
647
|
+
/** Resets analytics and tracking on SPA route transition. */
|
|
648
|
+
navigate?: (url?: string) => void;
|
|
649
|
+
/** Attaches video player hooks (HTML5 video or Google IMA AdsManager) for render telemetry. */
|
|
650
|
+
attachVideoPlayer?: (target: any, options?: any) => () => void;
|
|
651
|
+
/** Attaches Google IMA AdsManager bridge for video render telemetry. */
|
|
652
|
+
attachImaAdsManager?: (adsManager: any, options?: any) => () => void;
|
|
653
|
+
/** Manually records ad impression for custom render pipelines. */
|
|
654
|
+
recordImpression?: (slotId: string, options?: any) => boolean;
|
|
655
|
+
}
|
|
656
|
+
/**
|
|
657
|
+
* Returns global Bidspark SDK stub on `window[alias]`, creating command queue if absent.
|
|
658
|
+
*/
|
|
659
|
+
declare function getAdsGlobal(alias?: string): AdsGlobal;
|
|
660
|
+
|
|
661
|
+
export { type AdsGlobal, type AnalyticsConfig, type BeaconEvent, BidsparkPrebidAnalytics, CACHED_BID_TTL_MS, type CachedWinningBid, type ConsentRecord, DEFAULT_ALIAS, type FloorDecision, ImaAdsManagerStub, LogLevel, MAX_USAGE_BATCH_SIZE, PrebidEventDeduper, SAFE_CONTENT_TYPE, type SendEventsOptions, type SizeMapping, type SlotConfig, type SlotObserveOptions, type SlotSize, type SlotSizes, type SlotViewabilityState, USAGE_FLUSH_INTERVAL_MS, usage_event as UsageProto, UsageRecorder, type UsageRecorderOptions, type VideoPlayerOptions, attachImaAdsManager, attachVideoPlayer, clearStoredSession, clearStoredUserId, generateUUID, getAdsGlobal, getOrCreateSessionId, getOrCreateUserId, getPrebidEventKey, idToBytes, idToString, isSessionActive, isTrustedEndpoint, isVisitorSampled, normalizeLogLevel, normalizeSampleRate, onSessionResume, registerPrebidAnalytics, resetTcfListener, sendEvents, sessionStarted };
|