Installing the code

In this section

Follow the required steps to install the HTL BID code

1. Add the htlbid.js script to your website
2. Add the htlbid.css stylesheet to your website
3. Place HTL BID DIVs where you want ads to appear
4. Add javascript to set targeting metadata
5. Add javascript to initialize HTL BID

Some publishers implement advanced functionality

• Override the GAM Ad Unit
• Slot-level targeting
• React and Single Page Apps

For more details, see:

• Troubleshooting
• API Reference
• Gotchas

1. Add the htlbid.js script to your website

You must add the htlbid.js script tag to your website. The script tag looks like this, and the exact path will depend on the domain name that has been configured in the HTL BID UI for your website.

<script async src="https://htlbid.com/v3/example.com/htlbid.js"></script>

It is possible to setup two different versions of the script if you want to test changes on staging before deploying to production. Check advanced features for details.

2. Add the htlbid.css stylesheet to your website

You should also add the htlbid.css stylesheet to your website.

In order to improve your Core Web Vitals score and limit Cumulative Layout Shift, HTL BID will generate custom CSS rules for each of your configured ad slots.

<link type="text/css" rel="stylesheet" href="https://htlbid.com/v3/example.com/htlbid.css" />

3. Place HTL BID DIVs where you want the ads to appear

You must place special DIVs into your HTML where you want ads to appear. Each DIV has a class attribute that corresponds to an ad slot in HTL BID.

For example, suppose that an ad slot named top_leaderboard has been configured in the UI. You would place the corresponding DIV into your HTML where you want that slot to appear.

<div class="htlad-top_leaderboard"></div>

The HTLBID user interface has a complete list of the ad slots and corresponding DIVs that are configured for your website.

The same DIV may be repeated multiple times on the page if you have multiple ad slots with an identical configuration. Extra behavior can be added using data-* attributes. See advanced features for more details.

4. Set targeting metadata

Most publishers will add some targeting metadata to their ad requests. This step is technically optional, but highly recommended. Targeting metadata can be used to run specific ads on specific parts of your website.

The sample code below assumes three keys named post_id, page_type and category which exist in typical CMS systems. These are simply suggestions and can choose whichever key-values make sense for your website.

window.htlbid = window.htlbid || {};
window.htlbid.cmd = window.htlbid.cmd || [];
window.htlbid.cmd.push(() => {
  window.htlbid.setTargeting("post_id", "");
  window.htlbid.setTargeting("page_type", "article");
  window.htlbid.setTargeting("category", "entertainment");
});

5. Add javascript to initialize HTL BID

Finally, you need to call the htlbid.layout() function to initialize HTL BID.

This function causes HTL BID to:

• request and render all existing ad slots
• monitor the page for new ad slots

window.htlbid = window.htlbid || {};
window.htlbid.cmd = window.htlbid.cmd || [];
window.htlbid.cmd.push(() => {
  window.htlbid.setTargeting("post_id", "");
  window.htlbid.setTargeting("page_type", "article");
  window.htlbid.setTargeting("category", "entertainment");

  // add this line
  window.htlbid.layout();
});

The htlbid.layout() function should be called

• as early as possible in the page load
• sometimes after calling setTargeting()

Advanced Setup

Depending on your GAM configuration, you may need to set certain slot properties dynamically at runtime, rather than configuring them in the user interface.

For example, to override the GAM Ad Unit, you can use the inline data-unit attribute

<div
  class="htlad-leaderboard"
  data-unit="/1234/leaderboard/sports">
</div>

Most attributes allow runtime overrides by setting DIV-level attributes.

• See the complete list of DIV Attributes