BiddingStack Web SDK

Setup and pass page level KV pairs for Google Ad Manager

You can pass page level custom KV data into Google Ad Manager with the following API:

window.dataLayer = window.dataLayer || []
dataLayer.push({
  event: 'gam.targeting',
  KEY_NAME: VALUES,
})

For example:

window.dataLayer = window.dataLayer || []
dataLayer.push({
  event: 'gam.targeting',
  keywords: ['English Premier League'],
  pageType: 'article',
})

Disable advertising on a specific URL:

You can use the following API to disable the advertising on a URL:

window.dataLayer = window.dataLayer || []
dataLayer.push({
  event: 'bs.targeting',
  articleType: 'noads',
});

Less ads on a specific URL:

You can use the following API to enable less ads rule for the advertising on a URL:

window.dataLayer = window.dataLayer || []
dataLayer.push({
  event: 'bs.targeting',
  articleType: 'lessads',
});

Note: Create and enable lessads delivery rules to disable some ad slots.

Teardown and bootstrap the ad engine with API

if (window.BIDDINGSTACK) {
  window.BIDDINGSTACK.api.teardown()
  window.BIDDINGSTACK.api.bootstrap()
}

Discover new ad slots on the page

If the website utilises infinite scrolling, there could be new ad slots added to the page dynamically. You have to call the following API after content is rendered on the page, and then the engine will fill ads into the new ad slots.

if (window.BIDDINGSTACK) {
  window.BIDDINGSTACK.api.discoverSlots()
}

Updating and Persisting Key-Value Targeting for Google Ad Manager

You can store custom key-value (KV) data in the user's browser and pass it to Google Ad Manager using the following API:

if (window.BIDDINGSTACK) {
  window.BIDDINGSTACK.api.setGAMTargeting(key, value)
}

For example:

if (window.BIDDINGSTACK) {
  window.BIDDINGSTACK.api.setGAMTargeting("audience_seg", ["Sports", "Shopping"])
}

// or

if (window.BIDDINGSTACK) {
  window.BIDDINGSTACK.api.setGAMTargeting("audience_seg", "Sports")
}

// or remove the KV

if (window.BIDDINGSTACK) {
  window.BIDDINGSTACK.api.setGAMTargeting("audience_seg", null)
}

In this example:

• Replace "audience_seg" with your desired key.
• ["Sports", "Shopping"] represents an array of values associated with the key.

Stop ad slot refresh from GAM creative

A GAM creative can stop its own ad slot from refreshing by sending a postMessage to the top window. The SDK listens for bs_stop_refresh messages and identifies the requesting slot by matching the message source against iframes in each slot container.

From inside the creative:

window.top.postMessage({ type: 'bs_stop_refresh' }, '*')

Once received, the ad slot that contains the creative's iframe will stop refreshing for the remainder of the page session. This is useful for creatives that contain interactive content (e.g. games, videos, forms) where an automatic refresh would disrupt the user experience.

Refill an ad slot when a video creative gets no ad

A video creative served into an ad slot (for example the BiddingStack Video Player in Only Ads Mode) can end up with nothing to show when its VAST request returns no ad, a malformed response, a request failure, or a load timeout. Without a fallback, the creative would leave a blank slot for the rest of the page session.

To avoid this, the creative tells the page tag that it got no ad:

window.top.postMessage({ type: 'bs_vast_empty', code: VAST_ERROR_CODE }, '*')

code is optional and only used for logging (the BiddingStack Video Player sends the IMA error code).

The SDK identifies the slot by matching the message source against the iframes in each slot container, then refills that slot once: it re-runs the Prebid auction for the slot and refreshes it in GPT with the extra targeting bs_novideo=1. The refill happens only once per slot, and the blank render does not count toward the viewability refresh timer.

For the refill to be filled by something other than the same video creative, add the targeting bs_novideo is none of 1 to every GAM line item that serves a video creative. See bs_novideo in the Google Ad Manager setup guide.

The BiddingStack Video Player sends this message automatically when it runs in Only Ads Mode inside an ad iframe, so no extra work is needed on the creative side.