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})`

⚠️

Check with HTL on the compatibility of createAd with your integration.

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');
});

// 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, }) });

// 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); });