OptiView Ads SDK on iOS
On iOS and tvOS, the OptiView Ads SDK is a native Swift library that works with the OptiView Player (THEOplayer) and AVPlayer through player adapters, and with any other player through a custom adapter.
Prerequisites
- Retrieve the channel's Break Manifest URL. See Retrieving the required values.
- Check which ad workflows your breaks use. On iOS and tvOS, static assets, VAST, and Google Ad Manager all work with the installation below; nothing extra is needed.
- Install the SDK together with the adapter for your player (see Installation and the player sections below).
Installation
The SDK ships as binary frameworks for iOS and tvOS (iOS 15 / tvOS 15 or later) through CocoaPods or Swift Package Manager. Either way, add the OptiViewAdsRuntime module: it brings in OptiViewAdsSDK and OptiViewAdsCore. Replace <version> with the SDK release you want to use.
CocoaPods
Add the THEOplayer Specs repository as a source next to the CocoaPods CDN in your Podfile, add the runtime pod to your target, and run pod install:
source 'https://github.com/THEOplayer/cocoapods-specs.git'
source 'https://cdn.cocoapods.org/'
target 'MyApp' do
pod 'OptiViewAdsRuntime', '<version>'
end
The runtime pod also brings in the Google IMA SDK, which the SDK uses to play VAST and Google Ad Manager breaks.
Swift Package Manager
Add the package from https://github.com/Dolby-OptiView/optiview-ads-sdk-spm and link the OptiViewAdsRuntime product. Because the frameworks are binary targets, also add the Google IMA package for each platform you build for. The runtime always links against Google IMA, so the package is required even if your breaks only use static assets:
dependencies: [
.package(url: "https://github.com/Dolby-OptiView/optiview-ads-sdk-spm", from: "<version>"),
.package(url: "https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios", from: "3.18.4"), // iOS
.package(url: "https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos", from: "4.2.0"), // tvOS
],
targets: [
.target(name: "MyApp", dependencies: [
.product(name: "OptiViewAdsRuntime", package: "optiview-ads-sdk-spm"),
.product(name: "GoogleInteractiveMediaAds", package: "swift-package-manager-google-interactive-media-ads-ios", condition: .when(platforms: [.iOS])),
.product(name: "GoogleInteractiveMediaAdsTvOS", package: "swift-package-manager-google-interactive-media-ads-tvos", condition: .when(platforms: [.tvOS])),
]),
]
Integration
Create the SDK with an adapter around your player, then start a session with the channel's Break Manifest URL. The example below uses the OptiView Player (THEOplayer) adapter; the other adapters work the same way:
import OptiViewAdsRuntime
import OptiViewAdsAdapterTHEOplayer
let contentAdapter = THEOplayerAdapter(player: theoplayer)
let sdk = OptiViewAds(
config: OptiViewAdsConfig(player: contentAdapter),
renderer: OverlayAdRenderer(overlayContainer: adContainer, contentPlayer: contentAdapter),
manifestSource: URLSessionManifestSource(),
ticker: DispatchSchedulerTicker()
)
try await sdk.startSession(
SessionConfig(
manifestUrl: "https://us.markers.optiview.dolby.com/manifest/v1/ORG-ID/channels/CHANNEL-ID"
)
)
From this point the SDK polls the Break Manifest, schedules the breaks against your player's timeline, plays the ads, and reports the impressions. To verify the integration, schedule a break through the API or dashboard and confirm that it plays out.
Player interception (opt-in)
Interception is off by default. The existing integration example stays reactive.
For AVPlayer, create an InterceptedAVPlayer and give the same instance to your
player layer or view controller and the adapter:
import OptiViewAdsRuntime
let contentPlayer = InterceptedAVPlayer()
playerLayer.player = contentPlayer
let contentAdapter = AVPlayerAdapter(player: contentPlayer)
let config = OptiViewAdsConfig(player: contentAdapter, interceptPlayer: true)
Pass config to OptiViewAds. Keep the integration example's renderer, manifest source and ticker.
Create the SDK and start the session before loading or playing content.
Keep using AVPlayer methods, properties and observations on contentPlayer.
The SDK can hold first play for a preroll and route play, pause, seek, mute and volume during ads.
A plain AVPlayer does not install interception.
For THEOplayer, keep the same player instance and use:
let contentAdapter = THEOplayerAdapter(player: theoplayer)
let config = OptiViewAdsConfig(player: contentAdapter, interceptPlayer: true)
These setups apply to iOS and tvOS.
Supported players
OptiView Player (THEOplayer)
Add the THEOplayer adapter alongside the runtime, as the OptiViewAdsAdapterTHEOplayer pod:
pod 'OptiViewAdsAdapterTHEOplayer', '<version>'
or as the OptiViewAdsAdapterTHEOplayer product of the Swift package:
.product(name: "OptiViewAdsAdapterTHEOplayer", package: "optiview-ads-sdk-spm"),
The THEOplayerAdapter wraps a THEOplayer instance. Ads are rendered in an overlay view stacked above your content player view.
Limitations:
- Requires the THEOplayer iOS SDK 11.15.0 or later and a valid THEOplayer license.
- To let the SDK use the ads manifest URL that THEOplayer discovers for a THEOlive source, enable
manifestUrlDiscoveryand link theTHEOplayerTHEOliveIntegrationproduct.
AVPlayer
The AVPlayerAdapter ships with the runtime and wraps an AVPlayer instance. Ads are rendered in an overlay view stacked above your content player view.
Limitations:
- Requires iOS 15 / tvOS 15 or later.
Custom players
Any other player can be integrated by implementing the SDK's PlayerAdapter protocol, which exposes playback position, timing information, and basic playback controls.