Skip to main content

BidRoll Library API

The BidRoll Library interface provides methods and properties to interact with the BidRoll library. Below are the details of each method and property.

Methods​

init​

Signature: init(implementationConfig: Partial<BidRollConfig>): void

Called when the site-side implementation is ready to initialize the library with their own configuration or the autoload functionality is enabled.

  • implementationConfig: A partial configuration object of type BidRollConfig to customize the library's behavior for the site.

refresh​

Signature: refresh(units: Array<UnitDesignation>, auctionTargeting?: Record<string, string>): void

Called when the site-side implementation is ready to refresh or load in a certain set of ad units. If the autoload functionality is enabled, this method will be called automatically.

  • units: An array of UnitDesignation representing the ad units to be refreshed or loaded.
  • auctionTargeting (Optional): Additional targeting information for the auction.

See also: detectAndRefresh

newPageView​

Signature: newPageView(implementationConfig: NewPageViewInfo): void

Alternative method to call after init to indicate a new page view has occurred via client runtime actions such as infinite scroll or client-side routing library.

  • implementationConfig: Information about the new page view. It includes a pageViewId (deprecated) and a flag destroyActiveUnits to indicate whether or not to destroy active units.

setConfig​

Signature: setConfig(config: Partial<BidRollConfig>): void

Function for setting/updating the BidRoll Configuration.

  • config: A partial configuration object of type BidRollConfig to set or update the library's configuration.

getConfig​

Signature: getConfig(): BidRollConfig

Function for getting the BidRoll Configuration.

setPageTargeting​

Signature: setPageTargeting(key: string, value: string): void

Function for setting the page targeting for a specific key.

  • key: The key for which the targeting value will be set.
  • value: The value to set for the specified targeting key.

setPageTargeting​

Signature: setPageTargeting(targeting: Record<string, string>): void

Function for setting multiple page targeting values at once.

  • targeting: An object containing multiple targeting key-value pairs to set.

getPageTargeting​

Signature: getPageTargeting(): Record<string, string>

Function for getting the current page targeting.

  • Returns: An object containing the current page targeting key-value pairs.

clearPageTargeting​

Signature: clearPageTargeting(key?: string | string[] | { keep?: string[]; clear?: string[]; }): void

Function for clearing page targeting for specific keys or all keys.

  • key (Optional): Specifies the targeting keys to clear. It can be a string, an array of strings, or an object with keep and clear properties.

getUnitTargeting​

Signature: getUnitTargeting(unit: string | Partial<UnitConfig>, key?: string): string | Record<string, string>

Function getter for unit targeting.

  • unit: The unit code or unit config for which to get the targeting value.

  • key (Optional): The targeting key for which to get the value.

  • Returns: A specific targeting value or an object containing all targeting values for the unit.

setUnitTargeting​

Signature: setUnitTargeting(unit: string | Partial<UnitConfig>, key: string, value: string): void

Function setter for unit targeting.

  • unit: The unit code or unit config for which to set the targeting value.
  • key: The targeting key to set.
  • value: The targeting value to set.

clearUnitTargeting​

Signature: clearUnitTargeting(unit: string | Partial<UnitConfig>, key?: string | string[] | { keep?: string[]; clear?: string[]; }): void

Function for clearing all or specific targeting for a unit.

  • unit: The unit code or unit config for which to clear the targeting.
  • key (Optional): Specifies the targeting keys to clear. It can be a string, an array of strings, or an object with keep and clear properties.

getUnits​

Signature: getUnits(codes: string | string[]): undefined | UnitConfig | Array<UnitConfig>

Function for getting the unit config.

  • codes: The unit code or an array of unit codes to retrieve the unit configuration.

  • Returns: The UnitConfig object if a single unit code is provided, an array of UnitConfig objects if an array of unit codes is provided, or undefined if no unit config is found.

getAmazonBids​

Signature: getAmazonBids(): Array<{ amznbid: string; amzniid: string; amznp: string; amznsz: string; size: string; slotID: string; }>

Gets all currently tracked Amazon bids.

  • Returns: An array of objects representing Amazon bids with properties amznbid, amzniid, amznp, amznsz, size, and slotID.

detectAndRefresh​

Signature: detectAndRefresh(units: Array<UnitDesignation>, auctionTargeting?: Record<string, string>): void

Alternative method for refreshing ads that also re-checks the DOM for new ad unit elements (if any) that have rendered matching the unit element specification.

  • units: An explicit array of unit designations to refresh.
  • auctionTargeting (Optional): Optional targeting to apply to all units.

See also: refresh

clearSlots​

Signature: clearSlots(unitCodes?: string | string[]): void

Clears googletag slots in a way that BidRoll can register the slot as cleared.

  • unitCodes (Optional): The unit code or an array of unit codes. If provided, only slots corresponding to the specified unit codes will be cleared. If not provided, all slots will be cleared.

destroySlots​

Signature: destroySlots(unitCodes?: string | string[]): void

Destroys googletag slots in a way that BidRoll can register the slot as destroyed.

  • unitCodes (Optional): The unit code or an array of unit codes. If provided, only slots corresponding to the specified unit codes will be destroyed. If not provided, all slots will be destroyed.

getPrebidBids​

Signature: getPrebidBids(): Array<BrPrebidBid>

Gets all currently tracked prebid bids.

  • Returns: An array of BrPrebidBid objects representing prebid bids.

getPrebidWinningBids​

Signature: getPrebidWinningBids(): Array<BrPrebidBid>

Gets all currently tracked prebid winning bids.

  • Returns: An array of BrPrebidBid objects representing prebid winning bids.

getPrebidPendingBids​

Signature: getPrebidPendingBids(): Array<BrPrebidBid>

Gets all currently tracked prebid pending bids.

  • Returns: An array of BrPrebidBid objects representing prebid pending bids.

getPrebidRenderedBids​

Signature: getPrebidRenderedBids(): Array<BrPrebidBid>

Gets all currently tracked prebid rendered bids.

  • Returns: An array of BrPrebidBid objects representing prebid rendered bids.

getPrebidErrorBids​

Signature: getPrebidErrorBids(): Array<BrPrebidBid>

Gets all currently tracked prebid error bids.

  • Returns: An array of BrPrebidBid objects representing prebid error bids.

Properties​

status​

Type: status: BidRollStatus

Status of the BidRoll library. This property is read-only and represents the current status of the BidRoll library. The possible values of BidRollStatus are DEFINED, LOADED, and INITIALIZED.

version​

Type: version: string

The version of the BidRoll library. This value is read only.

epochVersion​

Type: epochVersion: number

The epoch version of the BidRoll library. This value is read only.

meta​

Type: meta: BidRollMeta

The metadata object for the BidRoll library. This property is read-only and contains various metadata information about the library.

  • version: string: The semantic version of the library.
  • epochVersion: number: The epoch version of the library.
  • org: string: The organization this bundle was built for.
  • site: string: The site this bundle was built for.
  • build: string: The build name of this bundle.
  • commit: string: The commit hash of this bundle.

modules​

Type: modules: string[]

The modules that are included in this bundle. It is an array of strings representing the names of the included modules.

pageTargeting​

Type: pageTargeting: Record<string, string>

Variable tracking the current page targeting. It is an object containing key-value pairs representing the page targeting information.

queue​

Type: queue: { push: (fn: () => void) => void }

The BidRoll Queue that mimics an array-like interface for pushing functions to be executed after the BidRoll library has loaded. The push function can be used to add functions to be executed in the queue.