Skip to content
Audienzz Documentation

handlePriorityCreative

The handlePriorityCreative hook allows you to control the behavior when a priority creative is available. Priority creatives are special ads (typically from Xandr) that are guaranteed to win the auction. This hook lets you customize what happens when such creatives are encountered.

htag calls it once per auction for each priority creative, whichever stage owns that creative — the ordinary per-placement selection, or the allocator that resolves creatives claiming companion placements.

Example

Section titled “Example”
window.htag = window.htag || {};
window.htag.handlePriorityCreative = function (elementId, winnerAdId) {
  // Log priority creative usage for analytics
  console.log(`Priority creative displayed for element: ${elementId}`);


  // Apply custom tracking for priority creatives
  if (typeof gtag !== 'undefined') {
    gtag('event', 'priority_creative_shown', {
      element_id: elementId,
      ad_id: winnerAdId || 'unknown',
    });
  }


  // Return the winner ad ID to proceed with default behavior
  return winnerAdId;
};

Parameters

Section titled “Parameters”
  • elementId (string): The ID of the placement element where the priority creative will be displayed
  • winnerAdId (string): The ID of the winning ad

Return Value

Section titled “Return Value”
  • string: The ad ID to use for rendering the priority creative
  • undefined: Skip rendering the priority creative

For a creative that claims companion placements — a skin or a roadblock — returning undefined does not force the placement to stay empty. It withdraws the creative’s exemption from the revenue comparison, so it competes on CPM like any other bid and only wins if it is worth what it would blank.

Section titled “Related Concepts”