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.

Side Effects

When you call refreshAds, several things happen:

1. Effects Cleanup:

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

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

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

4. Additional Refetching:

   • Priority creative IDs are refetched
   • Geo information is refetched

Related Concepts

• Effects: Learn about managing side effects
• Raw JS: Learn about executing custom JavaScript
• Semantiq: Learn about contextual targeting