@bidspark/analytics 0.44.0 → 0.46.0

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/dist/index.d.mts CHANGED
@@ -111,7 +111,21 @@ declare function normalizeSampleRate(rate?: number): number;
111
111
  * The same visitor key maps to the same uniform bucket across pageviews and sessions.
112
112
  */
113
113
  declare function isVisitorSampled(visitorKey: string, sampleRate?: number): boolean;
114
+ /**
115
+ * Detects client-side browser automation or headless environments via strong
116
+ * automation flags/UA tokens or >=2 concurrent weak headless anomalies.
117
+ */
118
+ declare function isAutomatedClient(): boolean;
114
119
 
120
+ interface PageEventDetail {
121
+ pageviewId: string;
122
+ sessionId: string;
123
+ }
124
+ type PageEventHandler = (detail: PageEventDetail) => void;
125
+ interface PageEventsConfig {
126
+ pageview?: string | PageEventHandler;
127
+ session?: string | PageEventHandler;
128
+ }
115
129
  interface AnalyticsConfig {
116
130
  endpoint: string;
117
131
  /** Usage endpoint origin (e.g. "https://by.bidspark.io/u"). */
@@ -149,6 +163,8 @@ interface AnalyticsConfig {
149
163
  revenueFlushDelayMs?: number;
150
164
  /** Window global alias for CMP instance. Defaults to "ads". */
151
165
  alias?: string;
166
+ /** Custom DOM event names or callback handlers for pageview and session start. */
167
+ events?: PageEventsConfig;
152
168
  }
153
169
  /** Canonical consent record shape from CMP. */
154
170
  interface ConsentRecord {
@@ -232,7 +248,6 @@ declare function sessionStarted(): boolean;
232
248
  declare function clearStoredSession(): void;
233
249
  declare function getOrCreateUserId(): string;
234
250
  declare function clearStoredUserId(): void;
235
- declare function resetTcfListener(): void;
236
251
  /**
237
252
  * Canonical duplicate-detection key for a Prebid event.
238
253
  */
@@ -245,6 +260,10 @@ declare class PrebidEventDeduper {
245
260
  private seenKeys;
246
261
  isDuplicate(eventName: string, data: any): boolean;
247
262
  }
263
+ declare function parseBidDimensions(bid: any): {
264
+ width: number;
265
+ height: number;
266
+ };
248
267
  declare class BidsparkPrebidAnalytics {
249
268
  private static activeInstances;
250
269
  private static allInstances;
@@ -291,10 +310,15 @@ declare class BidsparkPrebidAnalytics {
291
310
  private recordedConsentKeys;
292
311
  private consentCount;
293
312
  private cmpDetach;
313
+ private sessionResumeUnsub;
294
314
  private pageviewEmitted;
295
315
  private logger;
296
316
  private managesSessionId;
317
+ private configuredUserId;
318
+ private managesVisitorId;
319
+ private visitorKeyLocked;
297
320
  constructor(config: AnalyticsConfig);
321
+ private applyStorageAllowed;
298
322
  setLogLevel(level: LogLevel | string): void;
299
323
  getLogLevel(): LogLevel;
300
324
  enable(): void;
@@ -397,14 +421,23 @@ declare class BidsparkPrebidAnalytics {
397
421
  * is available from the configured alias. Returns a detach function.
398
422
  */
399
423
  attachCmp(): () => void;
400
- /** Device storage follows the decision; a refusal also drops the stored session. */
424
+ /** Device storage follows the decision; a refusal also drops stored session and user IDs. */
401
425
  private followConsent;
402
426
  setUserId(userId: string): void;
403
427
  setVisitorId(visitorId: string): void;
404
428
  setSampleRate(sampleRate?: number): void;
429
+ setEvents(events?: PageEventsConfig): void;
405
430
  setSessionId(sessionId: string): void;
406
- navigate(pageviewId: string, pageUrl: string): void;
407
- recordAuctionStart(auctionId: string, adUnitCode?: string, bidderCount?: number): void;
431
+ getSessionId(): string;
432
+ getPageviewId(): string;
433
+ getContext(): PageEventDetail;
434
+ /**
435
+ * Continues the pageview of the instance this one replaces: re-registering on
436
+ * the same page must not count a second pageview or replay Prebid's history.
437
+ */
438
+ continuePageview(previous: BidsparkPrebidAnalytics): void;
439
+ navigate(pageviewId: string, pageUrl?: string): void;
440
+ recordAuctionStart(auctionId: string, adUnitCode?: string, bidderCount?: number, mediaType?: string): void;
408
441
  private handleAuctionInit;
409
442
  private handleAuctionEnd;
410
443
  /**
@@ -425,6 +458,10 @@ declare class BidsparkPrebidAnalytics {
425
458
  private handleAdRenderSucceeded;
426
459
  private isDuplicate;
427
460
  private enqueue;
461
+ private syncSessionId;
462
+ private syncSessionAndRotateVisitor;
463
+ private announceSession;
464
+ private emitPageEvent;
428
465
  private isSampledVisitor;
429
466
  private shouldSample;
430
467
  private requeue;
@@ -636,6 +673,10 @@ interface AdsGlobal {
636
673
  pageviewId: string;
637
674
  sessionId: string;
638
675
  };
676
+ /** Returns current session ID. */
677
+ getSessionId?: () => string;
678
+ /** Returns current pageview ID. */
679
+ getPageviewId?: () => string;
639
680
  /** Registers slot from CSS selector; reads element dimensions if config omitted. */
640
681
  defineSlot?: (selector: string, config?: Partial<SlotConfig>) => void;
641
682
  /** Tears down single slot by element ID. */
@@ -660,4 +701,4 @@ interface AdsGlobal {
660
701
  */
661
702
  declare function getAdsGlobal(alias?: string): AdsGlobal;
662
703
 
663
- 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 };
704
+ 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, type PageEventDetail, type PageEventHandler, type PageEventsConfig, 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, isAutomatedClient, isSessionActive, isTrustedEndpoint, isVisitorSampled, normalizeLogLevel, normalizeSampleRate, onSessionResume, parseBidDimensions, registerPrebidAnalytics, sendEvents, sessionStarted };
package/dist/index.d.ts CHANGED
@@ -111,7 +111,21 @@ declare function normalizeSampleRate(rate?: number): number;
111
111
  * The same visitor key maps to the same uniform bucket across pageviews and sessions.
112
112
  */
113
113
  declare function isVisitorSampled(visitorKey: string, sampleRate?: number): boolean;
114
+ /**
115
+ * Detects client-side browser automation or headless environments via strong
116
+ * automation flags/UA tokens or >=2 concurrent weak headless anomalies.
117
+ */
118
+ declare function isAutomatedClient(): boolean;
114
119
 
120
+ interface PageEventDetail {
121
+ pageviewId: string;
122
+ sessionId: string;
123
+ }
124
+ type PageEventHandler = (detail: PageEventDetail) => void;
125
+ interface PageEventsConfig {
126
+ pageview?: string | PageEventHandler;
127
+ session?: string | PageEventHandler;
128
+ }
115
129
  interface AnalyticsConfig {
116
130
  endpoint: string;
117
131
  /** Usage endpoint origin (e.g. "https://by.bidspark.io/u"). */
@@ -149,6 +163,8 @@ interface AnalyticsConfig {
149
163
  revenueFlushDelayMs?: number;
150
164
  /** Window global alias for CMP instance. Defaults to "ads". */
151
165
  alias?: string;
166
+ /** Custom DOM event names or callback handlers for pageview and session start. */
167
+ events?: PageEventsConfig;
152
168
  }
153
169
  /** Canonical consent record shape from CMP. */
154
170
  interface ConsentRecord {
@@ -232,7 +248,6 @@ declare function sessionStarted(): boolean;
232
248
  declare function clearStoredSession(): void;
233
249
  declare function getOrCreateUserId(): string;
234
250
  declare function clearStoredUserId(): void;
235
- declare function resetTcfListener(): void;
236
251
  /**
237
252
  * Canonical duplicate-detection key for a Prebid event.
238
253
  */
@@ -245,6 +260,10 @@ declare class PrebidEventDeduper {
245
260
  private seenKeys;
246
261
  isDuplicate(eventName: string, data: any): boolean;
247
262
  }
263
+ declare function parseBidDimensions(bid: any): {
264
+ width: number;
265
+ height: number;
266
+ };
248
267
  declare class BidsparkPrebidAnalytics {
249
268
  private static activeInstances;
250
269
  private static allInstances;
@@ -291,10 +310,15 @@ declare class BidsparkPrebidAnalytics {
291
310
  private recordedConsentKeys;
292
311
  private consentCount;
293
312
  private cmpDetach;
313
+ private sessionResumeUnsub;
294
314
  private pageviewEmitted;
295
315
  private logger;
296
316
  private managesSessionId;
317
+ private configuredUserId;
318
+ private managesVisitorId;
319
+ private visitorKeyLocked;
297
320
  constructor(config: AnalyticsConfig);
321
+ private applyStorageAllowed;
298
322
  setLogLevel(level: LogLevel | string): void;
299
323
  getLogLevel(): LogLevel;
300
324
  enable(): void;
@@ -397,14 +421,23 @@ declare class BidsparkPrebidAnalytics {
397
421
  * is available from the configured alias. Returns a detach function.
398
422
  */
399
423
  attachCmp(): () => void;
400
- /** Device storage follows the decision; a refusal also drops the stored session. */
424
+ /** Device storage follows the decision; a refusal also drops stored session and user IDs. */
401
425
  private followConsent;
402
426
  setUserId(userId: string): void;
403
427
  setVisitorId(visitorId: string): void;
404
428
  setSampleRate(sampleRate?: number): void;
429
+ setEvents(events?: PageEventsConfig): void;
405
430
  setSessionId(sessionId: string): void;
406
- navigate(pageviewId: string, pageUrl: string): void;
407
- recordAuctionStart(auctionId: string, adUnitCode?: string, bidderCount?: number): void;
431
+ getSessionId(): string;
432
+ getPageviewId(): string;
433
+ getContext(): PageEventDetail;
434
+ /**
435
+ * Continues the pageview of the instance this one replaces: re-registering on
436
+ * the same page must not count a second pageview or replay Prebid's history.
437
+ */
438
+ continuePageview(previous: BidsparkPrebidAnalytics): void;
439
+ navigate(pageviewId: string, pageUrl?: string): void;
440
+ recordAuctionStart(auctionId: string, adUnitCode?: string, bidderCount?: number, mediaType?: string): void;
408
441
  private handleAuctionInit;
409
442
  private handleAuctionEnd;
410
443
  /**
@@ -425,6 +458,10 @@ declare class BidsparkPrebidAnalytics {
425
458
  private handleAdRenderSucceeded;
426
459
  private isDuplicate;
427
460
  private enqueue;
461
+ private syncSessionId;
462
+ private syncSessionAndRotateVisitor;
463
+ private announceSession;
464
+ private emitPageEvent;
428
465
  private isSampledVisitor;
429
466
  private shouldSample;
430
467
  private requeue;
@@ -636,6 +673,10 @@ interface AdsGlobal {
636
673
  pageviewId: string;
637
674
  sessionId: string;
638
675
  };
676
+ /** Returns current session ID. */
677
+ getSessionId?: () => string;
678
+ /** Returns current pageview ID. */
679
+ getPageviewId?: () => string;
639
680
  /** Registers slot from CSS selector; reads element dimensions if config omitted. */
640
681
  defineSlot?: (selector: string, config?: Partial<SlotConfig>) => void;
641
682
  /** Tears down single slot by element ID. */
@@ -660,4 +701,4 @@ interface AdsGlobal {
660
701
  */
661
702
  declare function getAdsGlobal(alias?: string): AdsGlobal;
662
703
 
663
- 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 };
704
+ 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, type PageEventDetail, type PageEventHandler, type PageEventsConfig, 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, isAutomatedClient, isSessionActive, isTrustedEndpoint, isVisitorSampled, normalizeLogLevel, normalizeSampleRate, onSessionResume, parseBidDimensions, registerPrebidAnalytics, sendEvents, sessionStarted };