Events

Overview

The Events system allows you to respond to various lifecycle events that occur during ad loading and display. By registering event listeners, you can execute custom code at specific points in the ad lifecycle.

Supported Events

ready

Fired once when Htag is fully initialized and ready to process ad requests.

Event data: None

element.exists

Fired when a placement’s DOM element is found on the page. Can be fired multiple times.

Event data:

{
  elementId: string,  // The placement identifier
  element: HTMLElement  // The DOM element that was found
}

element.requestable

Fired when lazy loading determines the element should request ad data or immediately for non-lazy-loaded placements.

Event data:

{
  elementId: string,     // The placement identifier
  element: HTMLElement,    // The DOM element
}

element.renderable

Fired when lazy loading determines the element should render.

Event data:

{
  elementId: string,  // The placement identifier
  element: HTMLElement, // The DOM element
}

element.beforeRender

Fired before a placement begins rendering, after auction winners have been determined. This event indicates which rendering path will be used (direct or Google Ad Manager).

Timing:

• Direct rendering path (renderPath: 'direct'): Fires immediately before the Prebid.js direct render is initiated
• Google rendering path (renderPath: 'google'): Fires when the SlotResponseReceived event is received from Google Publisher Tag, indicating that the ad response has been received from the server and rendering is about to begin

Note: This event does not fire for blocked placements (e.g., companion placements in a roadblock scenario that don’t render).

Event data:

{
  elementId: string,                   // The placement identifier
  renderPath: 'direct' | 'google'      // Rendering method: 'direct' for Prebid.js direct render, 'google' for Google Ad Manager mediation
}

Render path values:

• 'direct' - Ad will be rendered directly via Prebid.js without Google mediation
• 'google' - Ad will be rendered through Google Ad Manager (includes both mediation and Amazon APS bids)

element.resolve

Fired exactly once when the ad serving process for a placement has been fully resolved and reached its final state. This event fires regardless of the outcome - whether an ad was successfully rendered or no ad could be served.

Event data:

{
  elementId: string,           // The placement identifier
  adId: string | undefined,    // The ad ID if an ad was rendered, undefined if no ad was served
  bidder: string | undefined   // The bidder code if an ad was rendered, undefined if no ad was served
}

auction.resolved

Fired once per auction after all winners have been determined, including roadblock bid evaluation. This event provides a complete map of all placements in the current preload group and their winning decisions.

Event data:

{
  winners: WinnersMap; // Map of elementId to Winner objects (see structure below)
}

WinnersMap structure:

The winners object is a map where keys are element IDs (strings) and values are Winner objects:

{
  'placement-id-1': {
    type: 'direct',
    reason: 'cpm_threshold',
    bid: { /* Prebid BidAdapterBid object */ },
    bidConfig: { /* Original bid configuration */ }
  },
  'placement-id-2': {
    type: 'mediation',
    reason: '',
    bid: { /* Prebid BidAdapterBid object */ }
  },
  'placement-id-3': {
    type: 'blocked',
    reason: 'roadblock',
    parentBid: { /* Parent bid that blocked this placement */ }
  }
  // ... more placements
}

Winner object structure:

{
  type: 'direct' | 'mediation' | 'amazon' | 'blocked',  // Rendering type
  reason: 'cpm_threshold' | 'google_disabled' | 'override' | 'priority' | 'roadblock' | 'amazon' | '',  // Why this rendering path was chosen
  bid?: BidAdapterBid,        // Prebid bid object (if applicable)
  parentBid?: BidAdapterBid | HtagAmazonBid,  // Parent bid for roadblock companions
  bidConfig?: BidConfig,      // Original bid configuration
  renderGroupElementIds?: string[]  // Companion element IDs for roadblock groups
}

Winner type values:

• 'direct' - Ad will be rendered directly via Prebid.js without Google mediation
• 'mediation' - Ad will be rendered through Google Ad Manager with Prebid mediation
• 'amazon' - Amazon APS bid will be rendered through Google Ad Manager
• 'blocked' - Placement blocked by roadblock (won’t render)

Winner reason values:

• 'cpm_threshold' - Bid CPM exceeded maxGoogleCpm threshold, bypassing Google
• 'google_disabled' - skipGoogle configuration enabled for this placement
• 'override' - Bid manually marked as override (must win)
• 'priority' - Priority creative ID matched (bypasses normal auction)
• 'roadblock' - Roadblock bid won, blocking companion placements
• 'amazon' - Amazon APS bid won
• '' (empty string) - Standard mediation path, no special reason

BidAdapterBid object (key fields):

{
  adId: string,           // Unique ad identifier
  adUnitCode: string,     // Placement element ID
  auctionId: string,      // Auction identifier
  bidderCode: string,     // Bidder name (e.g., 'appnexus', 'rubicon')
  cpm: number,            // Bid price
  currency: string,       // Currency code (e.g., 'USD', 'EUR')
  creativeId: string,     // Creative identifier
  width: number,          // Creative width
  height: number,         // Creative height
  mediaTypes: object,     // Media types configuration object (e.g., { banner: { sizes: [[300, 250]] } })
  mediaType: string,      // [Runtime] Winning media type (e.g., 'banner', 'video', 'native')
  timeToRespond: number,  // Bid response time in milliseconds
  ad: string              // Creative HTML content
  // ... additional Prebid.js fields
}

Working with Event Listeners

You can register event listeners using the addEventListener method and remove them using the removeEventListener method.

Related Methods

• addEventListener: Register event listeners
• removeEventListener: Remove event listeners