# 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

1. Retrieve the channel's Break Manifest URL. See [Retrieving the required values](https://docs-preview.optiview.dolby.com/pr-943/ads/player-integration/optiview-ads-sdk.md#retrieving-the-required-values).
2. Check which [ad workflows](https://docs-preview.optiview.dolby.com/pr-943/ads/player-integration/optiview-ads-sdk.md#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.
3. Install the SDK together with the adapter for your player (see [Installation](#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`:

```ruby
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](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows/live/vast.md) and [Google Ad Manager](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows/live/google-ad-manager.md) 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:

```swift
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:

```swift
let sdk = OptiViewAds(
    config: OptiViewAdsConfig(player: THEOplayerAdapter(player: theoplayer)),
    renderer: OverlayAdRenderer(container: adContainer)
)

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](https://docs-preview.optiview.dolby.com/pr-943/ads/concepts/break-manifest.md), 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.

## Supported players

### OptiView Player (THEOplayer)

Add the THEOplayer adapter alongside the runtime, as the `OptiViewAdsAdapterTHEOplayer` pod:

```ruby
pod 'OptiViewAdsAdapterTHEOplayer', '<version>'
```

or as the `OptiViewAdsAdapterTHEOplayer` product of the Swift package:

```swift
.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 or later and a valid THEOplayer license.

### 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`](https://docs-preview.optiview.dolby.com/pr-943/ads/v2/api-reference/ios/OptiViewAdsCore/documentation/optiviewadscore/playeradapter) protocol, which exposes playback position, timing information, and basic playback controls.