Headerbidding

This submodule is optional. Configures and manages the Prebid.js header bidding library

Constructor

new Headerbidding(main)

Constructor of Headerbidding class

Parameters
Name Type Description
main Object

Instance of the main CpexPackage class

Members

winningBids

Access to winning bids

winningBidsVideo

Access to video winning bids

Methods

call() @public

Starts Prebid.js auction, calls SSPs

passback(elementId) @public

Passback functions for headerbidding

Parameters
Name Type Description
elementId string

Id of the ad container element for which the passback should be triggered.

reRender(elementId, adUnit, excludeBidders) @public

When adserver library renders the winning creative into the page, this method is fired from HB creative itself. Tries to catch and render custom formats. If it doesn't, it adds another iframe for HB creative and lets prebid render the actual ad there.

Parameters
Name Type Description
elementId string

Id of the ad container element where the ad should be rendered. This is usually the same as the adUnit code, but can be different if specified in settings or by the publisher.
adUnit string

AdUnit code corresponding to the ad being rendered, used to find the winning bid. If not provided, elementId is used as adUnit code.
excludeBidders Array

Array of bidder codes for which the creative should be rendered without CPEx modifications, directly from prebid. Used for R2B2.

(async) refresh(adUnitCodes, auctionTimeout, renderAt) → {Promise.<Object>} @public

Run only HB auction, with option to specify a subset of configured adUnits. Returns a promise that resolves once the auction is finished

Parameters
Name Type Description
adUnitCodes Array

Array of adUnit codes to refresh - optional
auctionTimeout Number

timeout for the auction, in milliseconds (maximum time to wait for bids) - optional
renderAt Number

timestamp (ms) at which the ad should render, waits after auction if needed - optional
Returns

Resolves to auction result, containing bids

Type: 
Promise.<Object>

calculateBucket(cpmCZK) → {number} @internal

Method using logarithmic function to set price buckets. They have to be the same as the server uses. Here is an example of the values: https://docs.google.com/spreadsheets/d/1lnAnKost7KoHCGGRVlaDdjU0JnsqiWc0rHdMXsK1hoI

Parameters
Name Type Description
cpmCZK number

CPM value in CZK
Returns

Price bucket (tier) from 1 to 16

Type: 
number

callAdserverIfEnabled() @internal

Calls adserver only if enabled in settings

(async) clearAdsAfterRefresh(adUnitCodes) @internal

Clears ads before refresh, to remove previous custom formats rendered outside of their containers

Parameters
Name Type Description
adUnitCodes Array

Array of adUnit codes that are being refreshed, used to find corresponding elementIds for clearing

(async) configure() @internal

Configures Prebid

filterAdUnitsAfterAuction(bids) @internal

Filters adUnits after auction, based on custom filters (originating in adunit sheets)

Parameters
Name Type Description
bids Array

Array of bid objects returned from the auction, used to check conditions for filtering (e.g. presence of skin format)

filterAdUnitsBeforeAuction(adUnits) → {Array} @internal

Filters adUnits before auction, based on custom filters (originating in adunit sheets) Filters include: screen width, url, presence of variables or cookies. If any filter condition is met, the adUnit is removed from the auction.

Parameters
Name Type Description
adUnits Array

Array of adUnit objects to filter
Returns

Filtered array of adUnit objects

Type: 
Array

getBucket(cpmCZK) → {number} @internal

Simple finding of bucket based on numbers in an array (tier is index +1)

Parameters
Name Type Description
cpmCZK number

CPM value in CZK
Returns

Price bucket (tier) from 1 to (number of buckets + 1)

Type: 
number

(async) getElementIds(adUnitCodes) → {Promise.<Array>} @internal

Returns elementIds for a list of adUnit codes

Parameters
Name Type Description
adUnitCodes Array

Array of adUnit codes to get elementIds for
Returns

Resolves to an array of elementIds corresponding to the provided adUnit codes

Type: 
Promise.<Array>

(async) load() @internal

Loads Prebid.js library

logBids(params) @internal

Log winning bids for debugging

Parameters
Name Type Description
params Object | Array

Object containing parameters for logging

Properties

Name Type Description
bids Object | Array

Object containing all bids returned from the auction, grouped by adUnit code, or an array of bid objects. Used to determine which winning bids are from the current auction and which are cached from previous auctions.

prepareHbIframe(elementId, ad, width, height, attributes) → {HTMLIFrameElement} @internal

Add iframe with optional custom css

Parameters
Name Type Description
elementId string

Id of the ad container element where the iframe should be added
ad Object

Ad object containing the element and optional iframeCSS for custom styling
width number

Width of the iframe to be added, usually taken from the winning bid
height number

Height of the iframe to be added, usually taken from the winning bid
attributes Object

Additional attributes to be added to the iframe element, such as data attributes for analytics
Returns

The created iframe element

Type: 
HTMLIFrameElement

prepareMetaData(winningBid, elementId, metaData) @internal

Prepares an object with useful information for debubbing. Merges info from both adserver and prebid.

Parameters
Name Type Description
winningBid Object

The winning bid object returned from the auction.
elementId string

Id of the ad container element where the ad is rendered.
metaData Object

Optional object to merge additional metadata into.

processBids(params) @internal

Called when auction ends, saves winning bids and dispatches events

Parameters
Name Type Description
params Object

Object containing auction results

Properties

Name Type Description
bids Object

Object containing all bids returned from the auction, grouped by adUnit code. Used for filtering and logging.
adUnitCodes Array

Array of adUnit codes that were part of the auction, used for filtering which events to dispatch

(async) setAdUnits(adUnitSubset) @internal

Sets adUnits that are in the current page, also look for aliases

Parameters
Name Type Description
adUnitSubset Array

Array of adUnit codes to set, if not provided, all adUnits from settings are set - optional

setBidTier(bidResponse) → {number} @internal

Determines price tier granularity. Buckets are either calculated or taken from a fixed array of numbers in settings.

Parameters
Name Type Description
bidResponse Object

Bid response object from Prebid, containing CPM and other info about the bid
Returns

Price bucket (tier) number, which is used for ad server targeting

Type: 
number

triggerBidWon() @internal

Manually trigger bidWon event in prebid. Used for impression analytics on video formats

useBids(params) @internal

Renders winning bids, either directly (hbOnly) or via adserver call

Parameters
Name Type Description
params Object

Object containing parameters for rendering

Properties

Name Type Description
hbOnly boolean

If true, only headerbidding bids are rendered, without calling the adserver. If false, the adserver is called to render the winning creatives, with headerbidding targeting.
adUnitCodes Array

Array of adUnit codes to render, if not provided, all adUnits are rendered