Incoming ad notification

Incoming ad notification alerts your application shortly before an eligible video-on-demand (VOD) mid-roll ad break begins. It gives you time to show a countdown badge, teaser, or banner, for example, "Ad starts in 5s...", before the break starts.

Use this feature when you want to prepare viewers for an upcoming mid-roll ad without hardcoding ad timing in your application.

When an upcoming ad break is eligible and enters the configured lead window, the player emits AdEvent.ADVERT_INCOMING on every whole-second change. Your app listens for that event and shows the countdown UI.

note

Incoming ad notification applies to VOD playback only. It does not apply to live streams or linear channels.

Use Google IMA CSAI

If you use Google IMA, configure incoming ad notification on the IMA player builder and subscribe to the incoming ad event on the ad player instance.

Configure incoming ad lead time

You can configure the lead time before an upcoming mid-roll ad break by calling .adIncomingLeadTimeMs() on the IMA player builder.

Set this value to control when the countdown starts. For example, 8000 means the countdown begins 8 seconds before the ad break.

Method / Property	Type	Default	Description
adIncomingLeadTimeMs()	number	5000 (5 seconds)	Sets the lead time, in milliseconds, before an incoming ad break is reported.

If you omit .adIncomingLeadTimeMs(), or pass a non-positive or non-finite number, the player defaults to 5 seconds (5000 ms).

Example configuration

Create the content player and then configure the ad player builder with your desired lead time. The following example sets a lead time of 8 seconds (8000 ms):

import { createPlayerBuilder as createContentPlayerBuilder } from '@quickplay/player';
import { createPlayerBuilder as createImaPlayerBuilder } from '@quickplay/ads-ima';
import { MediaType } from '@quickplay/player-interface';

// 1. Create the content player
const contentPlayer = createContentPlayerBuilder()
  .mediaElement(videoElement)
  .mediaUrl(contentUrl)
  .mediaType(MediaType.HLS)
  .build();

// 2. Create the ad player with incoming ad lead time configured
const adPlayer = createImaPlayerBuilder()
  .ima(window.google.ima)
  .adRequest({
    adTagUrl: adTagUrl,
    slotWidth: 1920,
    slotHeight: 1080,
  })
  .contentPlayer(contentPlayer)
  .contentVideoElement(videoElement)
  .contentContainerElement(adContainerElement)
  .enablePrefetch(true)
  .adIncomingLeadTimeMs(8000) // Start countdown 8 seconds before mid-roll ad breaks
  .build();

// 3. Start playback
adPlayer.load();

Listen to incoming ad events

The player emits AdEvent.ADVERT_INCOMING on the ad player instance. Subscribe to this event to display, update, and hide your countdown UI.

This event is the signal that your app should show or hide the incoming ad notification.

Event payload

The event payload contains an action property indicating whether to show or hide the countdown:

export type AdIncomingEvent =
  | { action: 'show'; remainingSeconds: number }
  | { action: 'hide' };

Property	Type	Description
action	'show' | 'hide'	'show' indicates upcoming ad break; 'hide' dismisses countdown.
remainingSeconds	number	Whole seconds remaining until the upcoming mid-roll ad starts.

Example event listener

Subscribe to AdEvent.ADVERT_INCOMING after creating the ad player:

import { AdEvent } from '@quickplay/player-interface';
import { AdIncomingEvent } from '@quickplay/player';

interface AdCountdownState {
  isVisible: boolean;
  secondsRemaining: number;
}

const countdownState: AdCountdownState = {
  isVisible: false,
  secondsRemaining: 0,
};

adPlayer.subscribe(AdEvent.ADVERT_INCOMING, (event: AdIncomingEvent) => {
  if (event.action === 'show') {
    countdownState.isVisible = true;
    countdownState.secondsRemaining = event.remainingSeconds;

    // Update your application UI with the remaining countdown time
    updateCountdownUI(`Ad starts in ${event.remainingSeconds}s...`);
  } else if (event.action === 'hide') {
    countdownState.isVisible = false;
    countdownState.secondsRemaining = 0;

    // Hide or remove the countdown banner from the screen
    hideCountdownUI();
  }
});