Client-side ad insertion (CSAI) for tvOS

When you use the player in your iOS or tvOS applications, you can incorporate client-side advertisements to monetize content and engage your viewers.

The Apple SDK supports IMA3-based Video Ad Serving Template (VAST) and Video Multiple Ad Playlist (VMAP) ad integrations. It also accommodates popular third-party software-building tools like Google's Interactive Media Ads (IMA) SDK. With these technologies, you can customize your viewer's ad experiences and manage ad schedules and breaks within the player.

For more information related to listening to ad events, managing media playback, and handling advertising errors, see the following pages:

• Listen for events
• Manage media playback
• Handle errors

Before you start

To configure advertisements for use with the player in your iOS or tvOS application, you must meet the following requirements:

• Make sure to download Google IMA SDK iOS 3.20.0 (exact version) and Google IMA SDK tvOS 4.11.1 (exact version) depending on your project. You need this dependency to integrate multimedia ads into the player and your application.
• If you're configuring ads with Wowza Video platform media, make sure you have access to Wowza Video to complete the advertising configuration. You must also generate a player token in Wowza Video and set up the player to use this token.

Configure ads with Wowza Video

If you're using the MediaOVP media type to load your video, you can configure advertisements in our Wowza Video platform. The next two sections describe how to set up ads for your video and live stream content when using the Apple SDK.

Set up ads for videos

To configure your player with the Apple SDK and define how it loads ads for video content from Wowza Video, use the following steps.

1. Begin by adding your video content on the Videos page in Wowza Video.
2. Once you create the video, go to the video's Metadata tab and note the media Id . This serves as the mediaId value to load Wowza media when using our SDKs. For more, see Retrieve a video ID .
3. Go to Advertising > Ad tags in Wowza Video to create your ad tags .
4. Go to Advertising > Ad schedules in Wowza video to create your ad schedule . To set up a DAI ad schedule, see Create a Google Ad Manager DAI ad schedule in Wowza Video. Save your ad schedule.
5. Go to Players > Configurations in Wowza Video to add a new player configuration . When you add the player configuration, select the ad schedule you created in step 4 from the Ad Schedule dropdown. Save your changes.
6. Once you create the player configuration, go to the General tab for this configuration and note the configuration Id . This serves as the playerId value to load Wowza media when working with our SDKs.

After the previous steps, you can use the mediaId and playerId values to load the Wowza Video media. These example values are placeholders and must be replaced with your own:

let platformMedia = MediaOVP(mediaId: "5bf95d0e-edb8-4fb8-8b4c-65afa6e2a8ee", playerId: "854eb3d3-ff01-43e6-80ad-97192ea68641")
let player.load(ovp: platformMedia)

Set up ads for live streams

To configure your player with the Apple SDK and define how it loads ads for live stream content from Wowza Video, use these steps. For live streams, you can only include pre-roll advertisements.

1. Begin by adding your live stream on the Live streams page in Wowza Video.
2. Once you create the live stream, go to the live stream's Overview tab, check the Playback section, and note the media Id . This serves as the mediaId value to load Wowza media when using our SDKs. For more, see Retrieve a live stream ID .
3. Go to Advertising > Ad tags in Wowza Video to create your ad tags .
4. Go to Advertising > Ad Schedules in Wowza Video to create your ad schedule . Make sure to only add an option from the Pre-roll dropdown. Save this ad schedule.
5. Go to Players > Configurations in Wowza Video to add a new player configuration . When you add the player configuration, select the ad schedule you created in step 4 from the Ad Schedule dropdown. Save your changes.
6. Once you create the player configuration, go to the General tab for this configuration and note the configuration Id . This serves as the playerId value to load Wowza media when working with our SDKs.

After the previous steps, you can use the mediaId and playerId values to load the Wowza Video media. These example values are placeholders and must be replaced with your own:

let platformMedia = MediaOVP(mediaId: "zxxtsj2b", playerId: "513852a4-18c8-474a-88c7-dc54d4f03555")
let player.load(ovp: platformMedia)

Configure ads programmatically

The next few sections cover the configuration required to programmatically work with Google's IMA SDK. You must provide a valid ad schedule so the IMA SDK can prepare and load your advertisements. The AdSchedule protocol represents an ad schedule, serving as the basis for the two types of ad schedules available, AdSheduleWaterfall and AdScheduleRemote.

Set up AdScheduleWaterfall

The AdScheduleWaterfall structure represents an ad schedule waterfall for media content. It implements the AdSchedule protocol to provide a waterfall-like sequence of ad breaks, helping to specify pre-roll, mid-roll, and post-roll ad breaks for media content.

Use this model when utilizing multiple VAST protocols and setting them up programmatically. The VMAP protocol can't be used with this struct. You can use the following properties with the AdScheduleWaterfall struct.

Properties

You can declare these properties using the AdBreak struct, which defines an ad break array consisting of ad tags and an optional offset. The instance properties for the AdBreak struct are listed in the following table.

Example with MediaExternal

You can create an AdScheduleWaterfall instance with pre-roll, mid-roll, and post-roll, where each AdBreak consists of one or more ad tag URLs (such as VAST) and an offset that indicates the time when the break should start. This example creates an ad schedule that consists of:

• A pre-roll break with a single ad (offset is ignored).
• A mid-roll break with three ads, starting 15 seconds into the playback.
• A post-roll break with a single ad (offset is ignored).

let preRollBreak = AdBreak(adTags: ["https://link.to.a.vast.file"])
let midRollBreak = AdBreak(
  adTags: ["https://link.to.a.vast.file", "https://link.to.a.vast.file"],
  offset: 15
)
let postRollBreak = AdBreak(adTags: ["https://link.to.a.vast.file"])

let adSchedule = AdScheduleWaterfall(
  preAdBreak: preRollBreak,
  midAdBreak: midRollBreak,
  postAdBreak: postRollBreak
)

// Add ads manually when using external media
let externalMedia = MediaExternal(
    mediaUrl: URL(string: "https://link.to.a.media.file")!,
    adSchedule: adSchedule
)

Set up AdScheduleRemote

AdScheduleRemote is another structure that implements the AdSchedule protocol. It provides the remote VMAP URL pointing to an ad schedule resource. The remote ad schedule can be fetched and parsed to determine ad breaks for the media content. You can use the following properties with this struct.

Properties

Example with MediaExternal

You can create an AdScheduleRemote instance with a URL to an ad playlist such as VMAP. Make sure that the provided link points to a valid playlist file.

let mediaURL =  URL(string: "https://link.to.a.media.file")!
let adScheduleURL = AdScheduleRemote(url: "https://link.to.a.vmap.file")

// Add ads manually when using external media
let externalMedia = MediaExternal(url: mediaURL, adSchedule: adScheduleURL)