Incoming ad notification

Incoming ad notification alerts your app shortly before an upcoming video-on-demand (VOD) ad break begins. It gives you time to show a countdown, for example, "Ad starts in 5s...", alongside your cue-point markers.

Use this feature when you want to prepare viewers for an upcoming ad without hardcoding ad timing in your app.

note

Incoming ad notification applies to VOD ad breaks with Google IMA client-side ad insertion (CSAI).

Configure the incoming ad lead time

Set how long before an ad break the countdown starts by passing adIncomingLeadTimeMs to the advanced FLAdvertisingGoogleIMAFactory.adPlayer(...) API. The default is 5,000 ms.

Parameter	Type	Default	Description
adIncomingLeadTimeMs	Int	5000	Lead time, in milliseconds, before an upcoming ad break begins.

let adPlayer = FLAdvertisingGoogleIMAFactory.adPlayer(
    contentPlayer: player,
    request: adRequest!,
    shouldSupportPIP: UserDefaults.standard.bool(forKey: USE_PIP_ON_CSAI),
    adIncomingLeadTimeMs: 5_000,
    enablePrefetchAds: enablePrefetchState,
    adFrequencyControl: AdFrequencyControlSetting.getConfiguration(),
    playerViewControllerCallback: { [weak vc] in
        guard let vc else {
            preconditionFailure("Player view controller is unavailable")
        }
        return vc
    }
)

Listen to incoming ad updates

The player calls AdEventHandlerDelegate.adIncoming(with:) with an AdIncomingType value for each countdown update.

Value	Description
.show(remainingSeconds)	Show the countdown with the seconds remaining.
.hide	Hide the countdown.

Handle cue points

The player provides cue points through two callbacks. Implement both:

• adPlayerDidProvide(cuepoints:) is deprecated. It still delivers the initial and regular cue-point notifications.
• adPlayerDidProvide(original:unwatched:) delivers the original and unwatched cue points when the unwatched list changes as ad breaks are watched.

extension ViewController: AdPlayerDelegate {
    func adPlayerDidProvide(cuepoints: [Int]) {
        // Receives the initial cue points and regular cue-point updates.
    }

    func adPlayerDidProvide(original cuepoints: [Int], unwatched cues: [Int]) {
        // Receives the original and unwatched cue points when watched state changes.
    }

    func adIncoming(with label: AdIncomingType) {
        switch label {
        case let .show(remainingSeconds):
            // Show the countdown.
        case .hide:
            // Hide the countdown.
        }
    }
}