@bidkernel/analytics

Vanilla JS bindings, TypeScript types, and standalone Prebid.js analytics adapter for Bidkernel.

Collects Prebid auction telemetry (auctions, bid requests/responses, wins, timeouts, no-bids, render failures), batches events into protobuf payloads, and delivers them to the property ingest endpoint via sendBeacon on page hide with automatic retry backoff.

Install

npm install @bidkernel/analytics

Standalone bundle (self-hosted, zero external bandwidth cost):

curl -Lo bidkernel-analytics.js https://unpkg.com/@bidkernel/analytics/dist/analytics.global.js

<script async src="/js/bidkernel-analytics.js"></script>

The standalone bundle is also exposed via ./standalone: import "@bidkernel/analytics/standalone". Defaults endpoint to production ingest (https://by.bidkernel.io/t); custom domains must specify endpoint via config.

Usage with Prebid.js

Register as a standard Prebid analytics provider:

import { registerPrebidAnalytics } from "@bidkernel/analytics";

registerPrebidAnalytics("pbjs", { endpoint: "https://by.bidkernel.io/t" });

pbjs.que.push(function () {
  pbjs.enableAnalytics([{ provider: "bidkernel", options: { propertyId: "YOUR_PROPERTY_ID" } }]);
});

If loaded after auctions start, the adapter replays pbjs.getEvents() history. Events deduplicate across the replay/live boundary.

Direct instantiation without enableAnalytics:

import { BidkernelPrebidAnalytics } from "@bidkernel/analytics";

const analytics = new BidkernelPrebidAnalytics({
  endpoint: "https://by.bidkernel.io/t",
  propertyId: "YOUR_PROPERTY_ID",
});
analytics.enable();

Configuration

| Option | Default | Description | | ----------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | endpoint | - | Ingest base URL ({endpoint}/{propertyId}). Standalone bundle defaults to https://by.bidkernel.io/t. Must be an absolute https:// URL (or loopback http://). Invalid endpoints fail closed. First registration pins ingest origin; subsequent calls cannot redirect across origins. | | propertyId | - | Bidkernel property ID. | | pbjsGlobalName | "pbjs" | Window global holding the Prebid instance. | | attachPbjsListeners | true | Set false when feeding events manually via trackRawEvent. | | auctionEnabled | true | Collect auction lifecycle events. | | warningsEnabled | true | Collect warning events. | | userId | "" | User identifier. Not auto-generated; see User identity. | | sessionId / pageviewId | generated | Override identity; defaults to managed 30-minute visitor sessions. See Sessions. | | deviceType / country / region | server-derived | Optional client hints; resolved server-side. | | logLevel | "INFO" | Console log verbosity (DEBUG, INFO, WARN, ERROR). |

SPA route transitions: call analytics.navigate(newPageviewId, newUrl) to flush the previous pageview and reset session timing.

Sessions

A session is a 30-minute window of visitor activity. It starts with a pageview and extends on user interaction (pointerdown, keydown, scroll, touch, tab visibility). Ad events do not extend sessions; idle tabs stop refreshing 30 minutes after last user interaction. Subsequent interaction mints a new sessionId.

The adapter reports events regardless of session state. The Bidkernel SDK uses isSessionActive() and onSessionResume(listener) to halt refreshes when inactive.

Explicit sessionId values are never rotated.

User identity

The adapter never auto-generates userId. Without an explicit ID, warehouse events record a NULL user_id.

Supply a stable first-party identifier (e.g. cookie UUID, never PII) when enabling analytics:

pbjs.enableAnalytics([
  {
    provider: "bidkernel",
    options: {
      propertyId: "YOUR_PROPERTY_ID",
      userId: getOrCreateFirstPartyUserId(),
    },
  },
]);

Or set post-consent on an instance:

analytics.setUserId(userId);

Batches stamp userId at send time; set as early as possible.

Releasing

Publishing is automated by .github/workflows/packages.yml. Pushes to main publish to npm only when version in package.json changes.

For user-visible changes:

1. Bump version in package.json (semver).
2. Add matching entry in CHANGELOG.md.

Bidkernel SDK bindings

getbidkernel() returns the typed window.bidkernel command queue stub (initializing if missing), exposing SlotConfig and AdsGlobal interfaces:

import { getbidkernel } from "@bidkernel/analytics";

getbidkernel().q.push(() => {
  // SDK ready
});