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 calls AdEventListener.onAdIncoming() with AdIncomingType.Show on every whole-second change. Your app implements that callback and shows the countdown UI.

Use Google IMA CSAI

If you use Google IMA client-side ad insertion (CSAI), configure incoming ad notification on the IMAAdsPlayerFactory.imaAdComposedPlayerWith() overload that takes a CSAIAdsRequest, and register an AdEventListener on the returned AdComposedPlayer.

note

Incoming ad notification is available only for the CSAI overload. The SSAI overload (SSAIAdsRequest) does not accept adIncomingLeadTimeMs.

Configure incoming ad lead time

Pass adIncomingLeadTimeMs to IMAAdsPlayerFactory.imaAdComposedPlayerWith().

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

Parameter	Type	Default	Description
adIncomingLeadTimeMs	Long	5000L (5 seconds)	Sets the lead time, in milliseconds, before an incoming ad break is reported.

warning

adIncomingLeadTimeMs must be greater than zero. A zero or negative value throws IllegalArgumentException when the ad player is created. Omit the parameter to use the 5-second default.

Example configuration

Create the content player and then create the composed ad player with your desired lead time. The following example sets a lead time of 5 seconds (5000 ms):

// Create the ad player with incoming ad lead time configured
val adPlayer = IMAAdsPlayerFactory.imaAdComposedPlayerWith(
  contentPlayer = contentPlayer,
  adRequest = CSAIAdsRequest(adTagUrl = adTagUrl),
  adIncomingLeadTimeMs = 5000L, // Start countdown 5 seconds before mid-roll ad breaks
)

Listen to incoming ad events

The player calls AdEventListener.onAdIncoming() on every registered listener. Override this callback to show, update, and hide your countdown UI.

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

note

AdComposedPlayer holds registered listeners weakly. Keep a strong reference to your AdEventListener for as long as you need the notification, and call unregisterAdListener() when you no longer need it.

Event payload

The callback receives an AdIncomingType, a sealed interface with two variants:

sealed interface AdIncomingType {
  /** An ad break is about to start. [remainingTime] is in seconds. */
  data class Show(val remainingTime: Int) : AdIncomingType

  /** The announced ad break has started. */
  class Hide : AdIncomingType
}

Type	Property	Type	Description
AdIncomingType.Show	remainingTime	Int	Whole seconds remaining until the upcoming mid-roll ad starts.
AdIncomingType.Hide	(none)	-	Dismisses the countdown. The announced ad break has started, or playback seeked away from the window.

Hide is a regular class, not a data class. Match it with is AdIncomingType.Hide, not by equality.

Example event listener

Register the listener on the ad player after creating it:

import com.quickplay.vstb7.player.ad.AdEventListener
import com.quickplay.vstb7.player.ad.AdIncomingType

// Keep a strong reference: AdComposedPlayer holds listeners weakly.
val incomingAdListener = object : AdEventListener {
  override fun onAdIncoming(adIncomingType: AdIncomingType) {
    when (adIncomingType) {
      is AdIncomingType.Show -> {
        // Update your application UI with the remaining countdown time
      }
      is AdIncomingType.Hide -> {
        // Hide or remove the countdown ui from the screen
      }
    }
  }
}

adPlayer.registerAdListener(incomingAdListener)

Behavior

• With the default 5000 ms lead time, Show is sent with remainingTime values 5, 4, 3, 2, 1.
• Pre-roll (0) and post-roll (-1) cue points are ignored. Only mid-roll ad breaks trigger the notification.
• Once-per-second countdown updates are not sent while playback is paused, buffering, or seeking. A seek inside the lead window sends Show for the new position.
• A seek outside the lead window sends Hide.
• Hide is also sent when the playhead reaches the ad break.
• If an ad cue point update no longer lists the shown ad break as unwatched, Hide is sent.
• If Ad Frequency Control decides the ad opportunity is not allowed, nothing is shown for that ad break, including its Hide.