API Reference

The API reference is intended for Javascript developers who need more control over the ad lifecycle, especially for Single Page Applications or highly-dynamic, javascript-heavy websites. For the standard DIV-based usage, see: Step 3: Place HTL BID DIVs where you want the ads to appear

htlbid.createAd({slotName: 'my_medrec', slotElement: node})

Create a new ad slot as a child of the target node.

• slotName - the name of an ad slot in the HTL BID UI
• slotElement - the DOM node where the ad slot will be inserted

Calling createAd() returns a string containing a unique ID for the new slot. This ID can be used to destroy in slot in the future by calling destroyAd()

// insert a new ad as a child of #sidebar
htlbid.cmd.push(() => {
  const target = document.getElementById('sidebar');
  const slotId = htlbid.createAd({
    slotName: 'my_medrec',
    slotElement: target,
  })
});

htlbid.destroyAd(slotId)

Destroys an existing ad slot

• slotId - the unique ID of the slot to be destroyed

The slotId parameter is the unique ID generated as the result of calling htlbid.createAd(). The behavior here is analogous to setTimeout/clearTimeout in Javascript.

// create a new slot
let slotId = null;
htlbid.cmd.push(() => {
  const target = document.getElementById('sidebar');
  slotId = htlbid.createAd({
    slotName: 'my_medrec',
    slotElement: target,
  });
});

// .. later, destroy that slot
htlbid.cmd.push(() => {
  htlbid.destroyAd(slotId);
});

htlbid.pubads().clearTargeting(key)

Clear all GAM targeting key-values for the specified key. May be called with zero arguments to clear all targeting for all keys.

htlbid.cmd.push(() => {
  htlbid.pubads().clearTargeting('pos');
});

htlbid.pubads().setTargeting(key, value)

Add a page-level GAM targeting key-value for the specified key and value.

htlbid.cmd.push(() => {
  htlbid.pubads().setTargeting('pos', 'top');
});

htlbid.forceRefresh(['slot-id-1', 'slot-id-2'])

Refresh the specified ads on the page. May be called with zero arguments to refresh all ads.

Calling forceRefresh() re-runs the entire header bidding auction for the specified slot(s).

htlbid.cmd.push(() => {
  htlbid.forceRefresh('slot-id-1');
});