Browser script API reference

The Bidboost browser script integrates with Prebid.js and optimizes various auction parameters. This reference documents configuration, initialization, and runtime behavior.

We officially support Prebid.js v9.53.5+ and v10.20.0+ and continuously run automated end-to-end tests (i.e. our entire service suite) for those versions. If you need support for older versions, feel free to reach out to us.

Overview

The browser script exposes a global bidboost object with a command queue. Queue your setup work so it runs after the script finishes loading or immediately if it is already present.

window.bidboost ??= {};
window.bidboost.cmd ??= [];
window.bidboost.cmd.push(() => {
  const pipeline = window.bidboost.createAuctionPipeline(...);
  pipeline.run(...);
});

Interface: Bidboost

Interface to the public Bidboost API.

Properties

version: Version of the Bidboost script currently running.
cmd: Queue commands to run upon initialization of the Bidboost script.

Methods

createAuctionPipeline(config: AuctionPipelineUserConfig): AuctionPipeline

Create an independent pipeline to optimize auctions.

Parameters:

config — Configures the new auction pipeline.

loadBidAdapterFactory(options: { pbjsVersion?: string; chunkBaseUrl?: string }): (bidder: string) => Promise<void>

Create a function to load bid adapters on the fly for use with AuctionPipelineUserConfig.loadBidAdapter.

Parameters:

options — Provide either pbjsVersion or chunkBaseUrl to resolve adapter chunks.

Class: AuctionPipeline

Auction pipelines are created with bidboost.createAuctionPipeline() and wrap Prebid.js auctions with Bidboost optimizations and analytics.

Methods

run(requestObj?: RequestBidsOptions): Promise<RequestBidsResult>

Apply optimizations, run an auction using the provided Prebid.js request object and then restore the Prebid.js object. You cannot run multiple concurrent auctions for the very same Prebid.js object.

Parameters:

requestObj — Request object passed to pbjs.requestBids().

See the Prebid.js reference for requestBids for the request object shape.

Interface: AuctionPipelineUserConfig

Configure an independent auction pipeline.

const config = {
  site: "your site",
  adUnits: yourAdUnits,
  userIdModules: yourUserIdModules,
  userIdAccessAllowed: true,
  ignoredBidders: ["someBidder"],
  pbjsGlobalName: "pbjs",
  refreshIntervalMilliseconds: 30_000,
  predictionTimeoutMilliseconds: 500,
  analyticsBatchWindowMilliseconds: 1000,
  loadBidAdapterTimeoutMilliseconds: 500,
  loadBidAdapter: window.bidboost.loadBidAdapterFactory({ pbjsVersion: "v10.20.0" }),
  placementMapper: adUnit => adUnit.code,
  bidderMapper: bidder => bidder,
  reverseBidderMapper: bidder => bidder,
};

Fields

site: Site identifier configured in the Bidboost UI.
adUnits: Ad units and their bidders to use for bid-stream shaping. This requires only the code and bids properties of the Prebid.js ad unit definition, and each bid object only requires the properties bidder and params. For the control group to work correctly, keep your current Prebid.js ad unit setup as-is and define the additional bidders separately, then concat those definitions with Array.concat, then store it in this field. Bidboost will merge this for you. See integration guide for an example.
userIdModules: User ID modules used. This requires only the bidders and storage properties of the Prebid.js user ID module configuration. While this information can be extracted from the Prebid.js configuration, doing so requires the Prebid.js script to be fully loaded and Prebid.js to be fully configured, which may increase the time-to-first-ad. See integration guide for an example.
userIdAccessAllowed: Whether or not the user gave consent for having their user IDs accessed. Bidboost does not read, write, process or transmit the user IDs themselves; Bidboost merely checks for their existence. Failure to set this will result in less accurate predictions, so integration with a CMP and setting this flag is strongly recommended. It is your responsibility to set this flag in a lawful manner. See integration guide for an example.
ignoredBidders: Set of bidders to ignore for the purpose of bid-stream shaping. This is useful if you want to exclude s2s or special bidders, for example.
pbjsGlobalName: Prebid.js global object name, defaults to pbjs.
refreshIntervalMilliseconds: Refresh interval of your auctions. Bidboost fetches another set of predictions a few seconds before the refresh auction starts. If this is unset, Bidboost re-uses the same predictions for the entire page view. This is clamped to be at least 30,000 milliseconds.
predictionTimeoutMilliseconds: Maximum time in milliseconds to wait for predictions to arrive. Defaults to 500ms. Setting this to a lower value may lead to a better time-to-first-ad but may result in less auctions being optimized due to a timeout. Best to tweak this value until both the timeout rate and time-to-first-ad are acceptable.
analyticsBatchWindowMilliseconds: Window in milliseconds for batching analytics data. Defaults to 1000ms. The higher this value, the more analytics events will be batched, which reduces load on both the client and server, but may cause minimal data loss in case the user navigates away during this time despite a last-chance dispatch. Best to tailor this value to your ad setup.
loadBidAdapterTimeoutMilliseconds: Timeout for bid adapters to be loaded by loadBidAdapter. Defaults to 500ms.
loadBidAdapter: Asynchronous function to dynamically load a bid adapter on demand. Using this is recommended if you have over 20 bidders to reduce initial bundle size. Bidboost provides a default implementation at bidboost.loadBidAdapterFactory. If this is undefined, Bidboost will not dynamically load bidders.
placementMapper: Set a function to map a Prebid.js ad unit to the placement identifier configured in the Bidboost UI. Useful for mapping placements from your internal tooling to Bidboost. By default, it returns adUnit.code. See integration guide for an example.
bidderMapper: Set a function to map a Prebid.js bidder to the bidder identifier configured in the Bidboost UI. Useful if you are using bidder aliases instead of the primary codes. By default, it simply returns the passed string. See integration guide for an example.
reverseBidderMapper: Just like bidderMapper, but the reverse. Must be set if bidderMapper is set. See integration guide for an example.