<!--
{
  "availability" : [
    "iOS: 15.0.0 -",
    "iPadOS: 15.0.0 -",
    "macCatalyst: 15.0.0 -",
    "macOS: 12.0.0 -",
    "tvOS: 15.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 8.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "AVFoundation",
  "identifier" : "/documentation/AVFoundation/AVPlayerInterstitialEvent",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "AVFoundation"
    ],
    "preciseIdentifier" : "c:objc(cs)AVPlayerInterstitialEvent"
  },
  "title" : "AVPlayerInterstitialEvent"
}
-->

# AVPlayerInterstitialEvent

An object that provides instructions for how a player presents interstitial content.

```
class AVPlayerInterstitialEvent
```

## Overview

An interstitial event defines a [`date`](/documentation/AVFoundation/AVPlayerInterstitialEvent/date) or [`time`](/documentation/AVFoundation/AVPlayerInterstitialEvent/time), on the timeline of its [`primaryItem`](/documentation/AVFoundation/AVPlayerInterstitialEvent/primaryItem), at which playback of interstitial content begins. It specifies the alternative interstitial content to play as an array of one or more template player items. The system uses the configuration of the event’s [`templateItems`](/documentation/AVFoundation/AVPlayerInterstitialEvent/templateItems) to build new player item instances to present the interstitial content.

Use [`AVPlayerInterstitialEventMonitor`](/documentation/AVFoundation/AVPlayerInterstitialEventMonitor) to observe the scheduling and progress of interstitial events. If your app requires specifying the schedule of interstitial events, use [`AVPlayerInterstitialEventController`](/documentation/AVFoundation/AVPlayerInterstitialEventController) instead.

> Note:
> ``doc://com.apple.avfoundation/documentation/AVFoundation/AVPlayerInterstitialEvent`` was previously an immutable type. Starting in iOS 16, tvOS 16, macOS 13, and watchOS 9, it’s now a mutable type, which allows you to create and customize an event before setting it on an ``doc://com.apple.avfoundation/documentation/AVFoundation/AVPlayerInterstitialEventController``.

## Topics

### Creating an event

[`init(primaryItem:time:)`](/documentation/AVFoundation/AVPlayerInterstitialEvent/init(primaryItem:time:))

Creates an interstitial event for the specified time.

[`init(primaryItem:date:)`](/documentation/AVFoundation/AVPlayerInterstitialEvent/init(primaryItem:date:))

Creates an interstitial event for the specified date.

[`init(primaryItem:identifier:time:templateItems:restrictions:resumptionOffset:playoutLimit:userDefinedAttributes:)`](/documentation/AVFoundation/AVPlayerInterstitialEvent/init(primaryItem:identifier:time:templateItems:restrictions:resumptionOffset:playoutLimit:userDefinedAttributes:))

Creates an interstitial event, with user-defined attributes, for the specified time.

[`init(primaryItem:identifier:date:templateItems:restrictions:resumptionOffset:playoutLimit:userDefinedAttributes:)`](/documentation/AVFoundation/AVPlayerInterstitialEvent/init(primaryItem:identifier:date:templateItems:restrictions:resumptionOffset:playoutLimit:userDefinedAttributes:))

Creates an interstitial event, with user-defined attributes, for the specified date.

[`interstitialEventWithPrimaryItem:identifier:time:templateItems:restrictions:resumptionOffset:playoutLimit:userDefinedAttributes:`](/documentation/AVFoundation/AVPlayerInterstitialEvent/interstitialEventWithPrimaryItem:identifier:time:templateItems:restrictions:resumptionOffset:playoutLimit:userDefinedAttributes:)

Creates an interstitial event, with user-defined attributes, for the specified time.

[`interstitialEventWithPrimaryItem:identifier:date:templateItems:restrictions:resumptionOffset:playoutLimit:userDefinedAttributes:`](/documentation/AVFoundation/AVPlayerInterstitialEvent/interstitialEventWithPrimaryItem:identifier:date:templateItems:restrictions:resumptionOffset:playoutLimit:userDefinedAttributes:)

Creates an interstitial event, with user-defined attributes, for the specified date.

### Identifying events

[`identifier`](/documentation/AVFoundation/AVPlayerInterstitialEvent/identifier)

An identifier for the event.

### Accessing player items

[`primaryItem`](/documentation/AVFoundation/AVPlayerInterstitialEvent/primaryItem)

The player item that represents the primary content.

[`templateItems`](/documentation/AVFoundation/AVPlayerInterstitialEvent/templateItems)

An array of player item configurations to use as templates for player items that play interstitial content.

### Configuring cues

[`cue`](/documentation/AVFoundation/AVPlayerInterstitialEvent/cue-swift.property)

A cue to schedule interstitial event playback at a predefined position during primary playback.

[`AVPlayerInterstitialEvent.Cue`](/documentation/AVFoundation/AVPlayerInterstitialEvent/Cue-swift.struct)

A structure that defines standard cues to play interstitial content.

### Inspecting timing

[`time`](/documentation/AVFoundation/AVPlayerInterstitialEvent/time)

A time within the timeline of the primary content that playback of interstitial content begins.

[`date`](/documentation/AVFoundation/AVPlayerInterstitialEvent/date)

A date within the date range of the primary content that playback of interstitial content begins.

[`willPlayOnce`](/documentation/AVFoundation/AVPlayerInterstitialEvent/willPlayOnce)

A Boolean value that indicates whether to schedule this event one time only and suppress subsequent replay.

[`resumptionOffset`](/documentation/AVFoundation/AVPlayerInterstitialEvent/resumptionOffset)

A time offset at which playback of primary content resumes after interstitial content finishes.

[`playoutLimit`](/documentation/AVFoundation/AVPlayerInterstitialEvent/playoutLimit)

The time offset at which playback of the interstitial ends.

[`alignsStartWithPrimarySegmentBoundary`](/documentation/AVFoundation/AVPlayerInterstitialEvent/alignsStartWithPrimarySegmentBoundary)

A Boolean value that indicates whether the start time of interstitial playback should snap to a segment boundary of the primary asset.

[`alignsResumptionWithPrimarySegmentBoundary`](/documentation/AVFoundation/AVPlayerInterstitialEvent/alignsResumptionWithPrimarySegmentBoundary)

A Boolean value that indicates whether the resumption time of primary playback should snap to a segment boundary of the primary asset.

### Managing restrictions

[`restrictions`](/documentation/AVFoundation/AVPlayerInterstitialEvent/restrictions-swift.property)

The restrictions the event imposes on the playback of interstitial content.

[`AVPlayerInterstitialEvent.Restrictions`](/documentation/AVFoundation/AVPlayerInterstitialEvent/Restrictions-swift.struct)

Constants that define restrictions on the playback of interstitial content.

### Accessing asset lists

[`assetListResponse`](/documentation/AVFoundation/AVPlayerInterstitialEvent/assetListResponse)

The asset list JSON response as a dictionary.

### Accessing attributes

[`userDefinedAttributes`](/documentation/AVFoundation/AVPlayerInterstitialEvent/userDefinedAttributes)

Attributes of the event that the vendor or app defines.

### Inspecting timeline occupancy

[`timelineOccupancy`](/documentation/AVFoundation/AVPlayerInterstitialEvent/timelineOccupancy-swift.property)

An event’s occupancy on the integrated timeline.

[`AVPlayerInterstitialEvent.TimelineOccupancy`](/documentation/AVFoundation/AVPlayerInterstitialEvent/TimelineOccupancy-swift.enum)

Constants that specify how an event occupies time on an integrated timeline.

[`supplementsPrimaryContent`](/documentation/AVFoundation/AVPlayerInterstitialEvent/supplementsPrimaryContent)

A Boolean value that indicates whether an event supplements the primary content and should present with the primary item.

[`contentMayVary`](/documentation/AVFoundation/AVPlayerInterstitialEvent/contentMayVary)

A Boolean value that indicates whether an event’s content is dynamic and the server may respond with different interstitial assets for other participants in a coordinated playback session.

[`plannedDuration`](/documentation/AVFoundation/AVPlayerInterstitialEvent/plannedDuration)

The planned duration of the event.

### Managing skipping behavior

[`skipControlLocalizedLabelBundleKey`](/documentation/AVFoundation/AVPlayerInterstitialEvent/skipControlLocalizedLabelBundleKey)

The key defined in the AVPlayerInterstitialEventController’s localizedStringsBundle that points to the localized label for the skip button.

[`skipControlTimeRange`](/documentation/AVFoundation/AVPlayerInterstitialEvent/skipControlTimeRange)

The time range within the duration of the interstitial event for which a skip button should be displayed.

[`AVPlayerInterstitialEvent.SkippableEventState`](/documentation/AVFoundation/AVPlayerInterstitialEvent/SkippableEventState)

These constants describe the state for a skippable AVPlayerInterstitialEvent.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)