Handle user navigation

Single Page Apps or sites updating sections dynamically with Javascript need to use specific functions to emulate user navigation. Replicating user navigation is needed to ensure targeting and ad loading is updated correctly.

If you are sending manual pageview events to Google Analytics or similar systems to track pageviews, then you should use that same structure to call the HTL BID functions to track pageviews with htlbid.newPage().

Table of Contents

• Table of Contents
• HTL BID functions to implement user navigation
• Order of Operations for User Navigation
• Using Refresh vs. Reload
• Set Targeting and Clear Targeting
• Example Code

HTL BID functions to implement user navigation

• Reload → Reloads ad slots by first destroying the inner divs and then re-calling the ads. This resets the HTL divs to their original state, including lazy loading settings.
• Unload → Unloads a div removing all child ad divs leaving only the HTL Div in the DOM.
• Refresh → Refreshes slots that have already rendered, requesting them again and re-running the auction. Refresh doesn’t consider the initial settings such as lazy loading.
• Targeting → Updates, adds or removes page-level targeting that will be passed to GAM.
• New Page → Calls the HTL BID pageview tracker, as well as third party services that need to be updated with user navigation. This function is needed for SPAs.

Order of Operations for User Navigation

The user navigation related to ads should mirror this flow:

1. 1. User in Page A (2 ads) navigates to Page B (3 ads)
2. 2. Publisher clears the Page A page-level targeting using htlbid.clearTargeting('keyName') or updates the targeting for an existing key with htlbid.setTargeting('keyName','newValue')
3. 3. Publisher sets the new page-level targeting for Page B if it was previously cleared by using htlbid.setTargeting('newKeyName','keyValue')
4. 4. Publisher calls htlbid.newPage()
5. 5. Publisher calls htlbid.reloadAllSlots() to reload the 2 existing slots, the third slot will be requested once the new div is added to the page separately
6. 6. Publisher adds new slot div, HTL BID will request an ad once the new div is added to the page

Using Refresh vs. Reload

• Reloading recreates all divs and defines new GPT ad slots, making these new GPT ad slots available for HTL BID to detect and run the auction when applicable. Reloading takes into account slot settings, such as lazy loading, to determine if the slot should be requested. Reloading a slot can be thought of as if a brand new div were being added to the page, including all the slot settings/attributes.
• Refreshing requests the ad for existing GPT ad slots, without taking into account slot settings (eg. lazy loaded ads). Refreshing will request ads for all slots that have rendered, regardless of their viewability at the time of refresh. Refreshing will execute the following:
1. 1. Re-run the HB auctions
2. 2. Call the GPT refresh function

Set Targeting and Clear Targeting

Page-level key-values need to be updated to pass the correct values while the user navigates. The most common scenarios needed are:

1. 1. Update an existing key value → To update existing key-values you can call htlbid.setTargeting('keyName','value') using a key that already exists. This will update the value for that key on any ad requests that follow this setTargeting call. In this case it’s not necessary to use clearTargeting ('keyName'), instead setTargeting('keyName','value') can be used to update it.

For example, to remove "key1", "key2" and "Key3", but add "key4":

Copy

['key1', 'key2', 'key3'].forEach(key => htlbid.clearTargeting(key));htlbid.setTargeting('key4','value4');

2. 2. Remove a key that is no longer needed → To remove unused keys use htlbid.clearTargeting('keyName') for every key.
⚠️
Calling htlbid.clearTargeting() without values will delete ALL keys. It is not recommended to use this function without passing the key names unless it is ok to remove all keys from the page.

Example Code

Reload Slots

htlbid.cmd.push(() => {
  htlbid.clearTargeting("post_id") 
	htlbid.setTargeting("post_id", "12346");
  htlbid.newPage().then(() => {
    htlbid.reloadAllSlots();
		// insert any new divs needed
  });
});

htlbid.cmd.push(() => {
  htlbid.clearTargeting("post_id") 
	htlbid.setTargeting("post_id", "12346");
  htlbid.newPage().then(() => {
    htlbid.reloadSlotsInside('#top-container')
  });
});

htlbid.cmd.push(() => {
  htlbid.newPage().then(() => {
    htlbid.reloadSlot('leaderboard-top')
  });
});

New Page

window.htlbid.newPage().then(() => {
  window.htlbid.forceRefresh();
})

Refresh

window.htlbid.newPage().then(() => {
  window.htlbid.refreshAllSlots()
})

window.htlbid.newPage().then(() => {
  window.htlbid.refreshSlot('incontent-medrec')
})