refreshAds

Overview

The refreshAds method refreshes ads on the page, either all ads or specific placements. This is useful for single-page applications (SPAs) when the page content changes without a full page reload.

Example

// Refresh all ads
window.htag.api('1').refreshAds();

// Refresh specific placements
window.htag.api('1').refreshAds({ elementIds: ['div1', 'div2'] });

// Force refresh even if URL hasn't changed
window.htag.api('1').refreshAds({ force: true });

// Mark as page transition even when refreshing specific elements
window.htag.api('1').refreshAds({ elementIds: ['div1'], pageTransition: true });

Parameters

• options (optional): An object with the following properties:
  • elementIds (array, optional): An array of element IDs to refresh. If not provided, all placements will be refreshed.
  • force (boolean, optional): If true, ads will be refreshed even if the URL hasn’t changed.
  • pageTransition (boolean, optional): If true, the refresh is considered a page transition, which affects effect cleanup.

Return Value

Returns the Htag API object, allowing for method chaining.

URL Check

By default, Htag checks if the current URL is the same as the previous one. If the URL hasn’t changed, ads won’t be refreshed unless you set the force option to true. This prevents unnecessary ad refreshes and improves performance.

Page Transition

A refresh is considered a page transition in two cases:

1. When no specific elements are specified (elementIds is not provided)
2. When the pageTransition option is set to true

Page transitions trigger additional behaviors like cleaning up effects with the htag:refresh-page tag, clearing High Impact won-group memory, resetting no-reload flags for both roadblock and high-impact placements, and resuming dynamic placement polling after stopDynamicPlacements().

If you call refreshAds() without elementIds, the page-transition path still does not run when the current URL matches the previous URL and force is not set. In that case the refresh is skipped entirely.

Side Effects

When you call refreshAds, several things happen:

1. Lazy Loading Override: For non-page-transition refreshes (e.g. timer-based reloads), lazy loading is forced for all affected placements to improve viewability. On page transitions, the original lazy loading configuration is restored. See Lazy Loading for details.

2. Effects Cleanup:

   • htag:refresh-page tag (for page transitions)
   • ad:{elementId} tags for each refreshed placement
   • raw-script:all tag

3. Raw JS Execution: Scripts marked with runOnce: false are executed again.

4. Keywords Update: New keywords are fetched from the Semantiq service for the new URL.

5. Additional Refetching:

   • Priority creative IDs are refetched
   • Geo information is refetched

6. High-Impact and Roadblock State (page transitions only):

   • Won high-impact group memory is cleared, allowing new high-impact competition
   • No-reload flags for roadblock and high-impact placements are reset

7. Dynamic Placement Polling (page transitions only):

   • Polling stopped with stopDynamicPlacements is resumed
   • Placement-only refreshes such as refreshAds({ elementIds: ['div1'] }) do not resume polling unless pageTransition: true is also set

Related Concepts

• Effects: Learn about managing side effects
• High Impact: Reload protection for high-impact groups
• Raw JS: Learn about executing custom JavaScript
• Roadblock: Coordinated ad delivery across placements
• Semantiq: Learn about contextual targeting