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.
Behavior | Functions | Description |
Reload (recommended) | reloadAllSlots() | Reloads all slots on the page considering the original slot settings (eg. lazy loaded). Called without parameters.
Eg: htlbid.reloadAllSlots() |
reloadSlot(
) | Reloads all slots matching the slotReference.
Eg: htlbid.reloadSlot('leaderboard') , htlbid.reloadSlot('#htlad-1') , htlbid.reloadSlot('.htlad-leaderboard') | |
reloadSlotsInside( 'CSS Selector' ) | Reloads slots for all HTL Universal Divs inside the target element.
Eg: htlbid.reloadSlotsInside('.sidebar') , htlbid.reloadSlotsInside('#top-container') , htlbid.reloadSlotsInside('body') | |
Unload | unloadAllSlots() | Unloads all divs that are in the HTL BID slot list on the page, even if they haven’t rendered due to lazy loading.
Eg: htlbid.unlaodAllSlots() |
unloadSlot(' slotReference ') | Unloads ad divs referenced by specific slot references used by HTL BID.
Eg: htlbid.unloadSlot('leaderboard_desktop_article') | |
unloadSlotsInside(' Selector ') | Unloads all ad divs that have loaded as children of the selector used. If the divs haven’t rendered ads yet they will not be unloaded.
Eg: htlbid.unloadSlotsInside('body') | |
Refresh (for specific cases only) | refreshAllSlots() | Forces ads that have rendered to be requested and loaded again, without taking into account the original slot settings (eg. lazy loaded ads) or viewability of the ad. It also re-runs the auction.
Eg: htlbid.refreshAllSlots() |
refreshSlot(' Selector ') | Refreshes a single slot by using the HTL slot name as specified in the UI.
Eg: htlbid.refreshSlot('leaderboard') | |
refreshSlotsInside(' Selector ') | Finds all ad units inside an HTML element and refresh them.
Eg: htlbid.refreshSlotsInside('sidebar'); | |
Page Targeting | clearTargeting('keyName') | Deletes the existing page-level targeting set in the setTargeting functions. If no key name is passed, this function will delete ALL current GPT tracked keys.
Eg: htlbid.clearTargeting('post') |
setTargeting('k','v') | Sets the new page-level key-value targeting.
Eg: htlbid.setTargeting('post_id','12345') | |
New Page | newPage() | Calls the function that tracks HTL Pageviews and fires services that need updated key-values during user navigation (eg. Permutive, Moat). Does NOT refresh or call ads.
Eg: htlbid.newPage() |
Order of Operations for User Navigation
newPage()
, clearTargeting('keyName')
, reloadAllSlots()
and remaining navigation functions listed in the table above should not be called.
Additionally, if you add and remove the HTL Divs by from the page as the user navigates through Components, review the information here carefully as you might only need some of the functions to update targeting and newPage() and not Reload. The user navigation related to ads should mirror this flow:
- 1. User in Page A (2 ads) navigates to Page B (3 ads)
- 2. Publisher clears the Page A page-level targeting using
htlbid.clearTargeting('keyName')
or updates the targeting for an existing key withhtlbid.setTargeting('keyName','newValue')
- 3. Publisher sets the new page-level targeting for Page B if it was previously cleared by using
htlbid.setTargeting('newKeyName','keyValue')
- 4. Publisher calls
htlbid.newPage()
- 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. 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. Re-run the HB auctions
- 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. 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 thissetTargeting
call. In this case it’s not necessary to useclearTargeting ('keyName')
, insteadsetTargeting('keyName','value')
can be used to update it. - 2. Remove a key that is no longer needed → To remove unused keys use
htlbid.clearTargeting('keyName')
for every key.
For example, to remove "key1", "key2" and "Key3", but add "key4":
['key1', 'key2', 'key3'].forEach(key => htlbid.clearTargeting(key));htlbid.setTargeting('key4','value4');
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.reloadAllSlots()
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
htlbid.newPage()
window.htlbid.newPage().then(() => {
window.htlbid.forceRefresh();
})
Refresh
htlbid.refreshAllSlots()
window.htlbid.newPage().then(() => {
window.htlbid.refreshAllSlots()
})
window.htlbid.newPage().then(() => {
window.htlbid.refreshSlot('incontent-medrec')
})