Instance Method
schedule(adItem:)
Schedules an ad for playback for the active source.
@objc(scheduleAdItem:) func schedule(adItem: AdItem)
Parameters
- adItem
The ad item to be scheduled.
Discussion
Note
Calling this API has no effect when the player has no active source.
Pause ads
When using the experimental pause trigger, this method schedules a pause-ad opportunity instead of a timeline ad break. Pause-ad opportunities become eligible one second after confirmed content playback enters a paused state. The initial state before playback starts is not eligible.
At most one pause ad can start per continuous pause. If another ad presentation, seeking, or time shifting interrupts the activation delay, the full delay restarts when content remains paused and presentation becomes eligible again. Pending pause-ad opportunities are cleared when the active source changes. Pause ads are not presented during Cast or AirPlay. They are also suppressed during Picture-in-Picture managed by a PlayerView. Pause-ad activation, loading, and new presentation are suspended while the application is inactive. A pending opportunity restarts the full activation delay when the application becomes active again, while an already-visible pause ad remains presented. Application activity is the app-wide state reported by UIApplication. In apps with multiple scenes, a pause ad may still be presented for a player whose scene is not in the foreground while another scene of the same app is active.
Seeking or time shifting while a pause ad is visible dismisses it with NonLinearAdFinishedEvent. No other pause ad starts until content resumes and pauses again.
If the registered container is not visible (detached, hidden, offscreen, fully clipped, or with alpha <= 0.01 on itself or an ancestor) when presentation is attempted, the creative is tracked as notUsed without emitting an AdErrorEvent. The opportunity remains pending, and a fresh creative is loaded on the next eligible pause.
Pause-ad presentation currently supports VAST sources configured with AdSourceType.bitmovin and containing a static PNG or JPEG NonLinear resource.
On iOS, tapping a pause-ad creative with a VAST clickthrough URL sends click tracking, emits AdClickedEvent, and opens the URL automatically. Creative clickthrough is not supported on tvOS.
Pause ads are not supported on visionOS. Pause ad items scheduled there are ignored.
With the System Player UI on iOS, pause ads are not shown during AVKit fullscreen. Entering fullscreen finishes a visible pause ad. A pause that begins in fullscreen presents nothing and keeps its opportunity pending; if content is still paused after returning inline, the full activation delay restarts and a fresh creative is loaded.