diff --git a/ads/getting-started/android.mdx b/ads/getting-started/android.mdx deleted file mode 100644 index 46230eda55d1..000000000000 --- a/ads/getting-started/android.mdx +++ /dev/null @@ -1,133 +0,0 @@ ---- -sidebar_position: 3 -sidebar_label: Android -sidebar_custom_props: { 'icon': 'android' } ---- - -# Getting started with OptiView Ads on Android - -This guide will get you started to integrate OptiView Ads in your OptiView Player Android SDK: configure the license, update dependencies and set the source description. - -## Prerequisites - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -1. You need to have an OptiView Player license which is compatible with OptiView Ads. This can be done through the [player portal](https://portal.theoplayer.com). -2. You need a correctly deployed [OptiView Ads signaling service](signaling-service.mdx). -3. Add the OptiView Player Android SDK to your project by following our [Getting started](/theoplayer/getting-started/sdks/android/getting-started) guide. Make sure to [set up an OptiView Ads-compatible license](/theoplayer/getting-started/sdks/android/getting-started/#setting-up-the-license) in your app. -4. Add the OptiView Ads integration as a dependency in your module-level `build.gradle` file: - - - - ```groovy - dependencies { - implementation "com.theoplayer.theoplayer-sdk-android:core:9.+" - // highlight-next-line - implementation "com.theoplayer.theoplayer-sdk-android:integration-ads-theoads:9.+" - } - ``` - - - ```kotlin - dependencies { - implementation("com.theoplayer.theoplayer-sdk-android:core:9.+") - // highlight-next-line - implementation("com.theoplayer.theoplayer-sdk-android:integration-theoads:9.+") - } - ``` - - - - -## Integration - -To make use of the OptiView Ads integration, create and add the `TheoAdsIntegration` to your `THEOplayerView`: - -```kotlin -import com.theoplayer.android.api.THEOplayerView -import com.theoplayer.android.api.ads.theoads.TheoAdsIntegration -import com.theoplayer.android.api.ads.theoads.TheoAdsIntegrationFactory.createTheoAdsIntegration - -class MyActivity : Activity() { - private lateinit var theoPlayerView: THEOplayerView - private lateinit var theoAdsIntegration: TheoAdsIntegration - - override fun onCreate(savedInstanceState: Bundle?) { - super.onCreate(savedInstanceState) - setContentView(R.layout.activity_main) - - theoPlayerView = findViewById(R.id.theoplayer) - - theoAdsIntegration = createTheoAdsIntegration(theoPlayerView) - theoPlayerView.player.addIntegration(theoAdsIntegration) - } -} -``` - -Then, configure a source containing a `TheoAdDescription`: - -```kotlin -import com.theoplayer.android.api.ads.theoads.TheoAdDescription -import com.theoplayer.android.api.source.SourceDescription -import com.theoplayer.android.api.source.SourceType -import com.theoplayer.android.api.source.TypedSource - -theoPlayerView.player.source = SourceDescription.Builder( - TypedSource.Builder("PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI") - .type(SourceType.HLS) - .hlsDateRange(true) - .build() -).ads( - TheoAdDescription( - networkCode = "NETWORK-CODE", - customAssetKey = "CUSTOM-ASSET-KEY" - ) -).build() -``` - -- Notice that the `src` is different as usual. For OptiView Ads, a signaling server needs to be set up which acts as a proxy to parse the given manifest and insert the ad interstitials. More information can be found [here](signaling-service.mdx). -- The `hlsDateRange` flag needs to be set to `true` as the ad markers are done using `EXT-X-DATERANGE` tags. -- The `ads` object needs to be a `TheoAdDescription`. Furthermore, the `networkCode` and `customAssetKey` needs to be set according to your configured Google account. - -## Integrating with Open Video UI - -When using the [Open Video UI for Android](/open-video-ui/android/), you need to create and add the `TheoAdsIntegration` before creating your `DefaultUI` or `UIController`. You can then create an OptiView Ads-enabled source and set it as `player.source`: - -```kotlin -import androidx.activity.compose.setContent -import com.theoplayer.android.ui.rememberPlayer - -setContent { - val player = rememberPlayer() - LaunchedEffect(player) { - player.theoplayerView?.let { theoPlayerView -> - val theoAdsIntegration = createTheoAdsIntegration(theoPlayerView) - theoPlayerView.player.addIntegration(theoAdsIntegration) - } - - player.source = SourceDescription.Builder( - TypedSource.Builder("PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI") - .type(SourceType.HLS) - .hlsDateRange(true) - .build() - ).ads( - TheoAdDescription( - networkCode = "NETWORK-CODE", - customAssetKey = "CUSTOM-ASSET-KEY" - ) - ).build() - } - - DefaultUI( - player = player - ) -} -``` - -## More information - -- [API references](pathname:///theoplayer/v8/api-reference/android/com/theoplayer/android/api/ads/theoads/package-summary.html) -- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) -- [The Advantages of Server-Guided Ad Insertion](https://optiview.dolby.com/solutions/personalized-advertising/) -- [Is Server-Guided Ad Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://optiview.dolby.com/resources/blog/advertising/what-is-sgai-server-guided-ad-insertion-in-streaming/) diff --git a/ads/getting-started/chromecast.mdx b/ads/getting-started/chromecast.mdx deleted file mode 100644 index 7e6a45999ebf..000000000000 --- a/ads/getting-started/chromecast.mdx +++ /dev/null @@ -1,74 +0,0 @@ ---- -sidebar_position: 6 -sidebar_label: Chromecast CAF -sidebar_custom_props: { 'icon': 'web' } ---- - -# Getting started with OptiView Ads on Chromecast CAF - -This guide will get you started with OptiView Ads using the OptiView Player Chromecast CAF SDK. -! NOTE: Currently the Chromecast CAF SDK only supports image overlays from OptiView Ads. - -## Prerequisites - -1. You need to have an OptiView Player license which is compatible with OptiView Ads. This can be done through the [player portal](https://portal.theoplayer.com). -2. You need a correctly deployed [OptiView Ads signaling service](signaling-service.mdx). -3. Your THEOplayer SDK needs to have the `theoads` feature enabled. - - As of OptiView Player version 8.2.0, this feature is enabled by default in the main `theoplayer` package so we recommend to use at least this version, preferably the latest available version. - You can install this package with the following command: - - ```bash - npm install theoplayer - ``` - -4. You need to have a Chromecast Developer account to deploy your custom CAF receiver. - -## Integration - -### Configuring the Chromecast receiver - -OptiView Ads is supported using the default Chromecast Shaka player for HLS on Chromecast CAF. To enable this, before starting the Chromecast application, configure it to use Shaka. -Also, you need to load the OptiView Player Chromecast CAF SDK. - -Here is an example of a bare-bones CAF receiver app you can use as a starting point for basic playback without any custom UI: - -```html - - - Optiview Chromecast Receiver App - - - - - - - - - - - - -``` - -! NOTE: We recommend to self-host the THEOplayer Chromecast CAF SDK to avoid dependency issues and lock the version you are using. More information on self-hosting can be found [here](https://optiview.dolby.com/docs/theoplayer/faq/self-hosting-theoplayer/). - -### Configuring the Chromecast sender - -The Optiview Chromecast features are only available through our own player SDK. Setting up the Chromecast functionality is documented on our main documentation portal: -https://optiview.dolby.com/docs/theoplayer/how-to-guides/cast/chromecast/introduction/ - -Our player SDKs will take care of handling the communication between the Chromecast sender and receiver. - -## More information - -- [API references](pathname:///theoplayer/v11/api-reference/web/interfaces/TheoAdDescription.html) -- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) -- [The Advantages of Server-Guided Ad Insertion](https://optiview.dolby.com/solutions/personalized-advertising/) -- [Is Server-Guided Ad-Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://optiview.dolby.com/resources/blog/advertising/what-is-sgai-server-guided-ad-insertion-in-streaming/) diff --git a/ads/getting-started/index.mdx b/ads/getting-started/index.mdx index 3bcac379b49a..f9ad5b59a0ec 100644 --- a/ads/getting-started/index.mdx +++ b/ads/getting-started/index.mdx @@ -14,3 +14,7 @@ These guides provide the steps required to get started with OptiView Ads. They c import DocCardList from '@theme/DocCardList'; + +## Integrate a player + +Choose an integration path in the [Player integration](/ads/player-integration/) section. The recommended OptiView Player guides cover Web, Android, iOS, Chromecast CAF, and React Native. You can also integrate an open-source or native player directly against the Break Manifest and SSAI cue contracts. diff --git a/ads/getting-started/ios.mdx b/ads/getting-started/ios.mdx deleted file mode 100644 index 477bb1e134d2..000000000000 --- a/ads/getting-started/ios.mdx +++ /dev/null @@ -1,147 +0,0 @@ ---- -sidebar_position: 3 -sidebar_label: iOS -sidebar_custom_props: { 'icon': 'apple' } ---- - -# Getting started with OptiView Ads on iOS - -This guide will get you started to integrate OptiView Ads in your OptiView Player iOS SDK: configure the license, update dependencies and set the source description. - -## Prerequisites - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -1. You need to have an OptiView Player license which is compatible with OptiView Ads. This can be done through the [player portal](https://portal.theoplayer.com). -2. You need a correctly deployed [OptiView Ads signaling service](signaling-service.mdx). -3. Add the OptiView Player iOS SDK to your project by following our [Getting started](/theoplayer/getting-started/sdks/ios/getting-started) guide. Make sure to [set up an OptiView Ads-compatible license](/theoplayer/getting-started/sdks/ios/getting-started/#theoplayer-license) in your app. -4. Add the OptiView Ads integration as a dependency to your project: - - - - 1. Add the `THEOplayer-Integration-THEOads` pod to your Podfile: - ```sh - pod 'THEOplayer-Integration-THEOads', '~> ' - ``` - 2. Install the new pod: - ```sh - pod install - ``` - - - 1. Open your Xcode project and navigate to File > Add Package Dependencies... - - ![Screenshot of Xcode file menu](../assets/img/ios-xcode-file-menu.png) - - 2. Add `theoplayer-sdk-apple` package by entering the following url: - ```sh - https://github.com/THEOplayer/theoplayer-sdk-apple - ``` - ![Screenshot of SwiftPM menu](../assets/img/ios-swiftpm-menu.png) - - 3. Select `THEOplayerTHEOadsIntegration` from the package products list and add it to your target. - - ![Screenshot of SwiftPM product selection](../assets/img/ios-swiftpm-product-selection.png) - - - - - -5. Add Google IMA SDK as a dependency to your project: - - - - 1. The `THEOplayer-Integration-THEOads` pod has a dependency on `GoogleAds-IMA-iOS-SDK` which should be installed automatically. - - - 1. Open your Xcode project and navigate to File > Add Package Dependencies... - - ![Screenshot of Xcode file menu](../assets/img/ios-xcode-file-menu.png) - - 2. Add `swift-package-manager-google-interactive-media-ads-ios` package by entering the following url: - ```sh - https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios - ``` - ![Screenshot of SwiftPM menu](../assets/img/ios-swiftpm-menu-google.png) - - 3. Select `GoogleInteractiveMediaAds` from the package products list and add it to your target. - - ![Screenshot of SwiftPM product selection](../assets/img/ios-swiftpm-product-selection-google.png) - - - - - -## Integration - -To make use of the OptiView Ads integration, create and add the `THEOadsIntegration` to your `THEOplayer` instance: - -```swift -import UIKit -import THEOplayerSDK -import THEOplayerTHEOadsIntegration - -class ViewController: UIViewController { - var theoplayer: THEOplayer! - var theoads: THEOadsIntegration! - - override func viewDidLoad() { - super.viewDidLoad() - self.theoplayer = THEOplayer(configuration: THEOplayerConfigurationBuilder().build()) - self.theoplayer.frame = view.bounds - self.theoplayer.addAsSubview(of: view) - self.theoads = THEOadsIntegrationFactory.createIntegration(on: self.theoplayer) - self.theoplayer.addIntegration(self.theoads) - } - -} -``` - -Then, configure a source containing a `THEOAdDescription`: - -```swift -import UIKit -import THEOplayerSDK -import THEOplayerTHEOadsIntegration - -class ViewController: UIViewController { - var theoplayer: THEOplayer! - var theoads: THEOadsIntegration! - - override func viewDidLoad() { - super.viewDidLoad() - self.theoplayer = THEOplayer(configuration: THEOplayerConfigurationBuilder().build()) - self.theoplayer.frame = view.bounds - self.theoplayer.addAsSubview(of: view) - self.theoads = THEOadsIntegrationFactory.createIntegration(on: self.theoplayer) - self.theoplayer.addIntegration(self.theoads) - - let source = "PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI" - let typedSource = TypedSource( - src: source, - type: "application/x-mpegurl", - hlsDateRange: true - ) - let theoad = THEOAdDescription( - networkCode: "NETWORK-CODE", - customAssetKey: "CUSTOM-ASSET-KEY" - ) - let sourceDescription = SourceDescription(source: typedSource, ads: [theoad]) - self.theoplayer.source = sourceDescription - self.theoplayer.play() - } - -} -``` - -- Notice that the `src` is different as usual. For OptiView Ads, a signaling server needs to be set up which acts as a proxy to parse the given manifest and insert the ad interstitials. - More information can be found [here](signaling-service.mdx). -- The `hlsDateRange` flag needs to be set to `true` as the ad markers are done using `EXT-X-DATERANGE` tags. -- The `ads` array needs to contain a `THEOAdDescription`. Furthermore, the `networkCode` and `customAssetKey` needs to be set according to your configured Google account. - -## More information - -- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) -- [The Advantages of Server-Guided Ad Insertion](https://optiview.dolby.com/solutions/personalized-advertising/) -- [Is Server-Guided Ad Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://optiview.dolby.com/resources/blog/advertising/what-is-sgai-server-guided-ad-insertion-in-streaming/) diff --git a/ads/getting-started/react-native.mdx b/ads/getting-started/react-native.mdx deleted file mode 100644 index 8170943a1a97..000000000000 --- a/ads/getting-started/react-native.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -sidebar_position: 5 -sidebar_label: React Native -sidebar_custom_props: { 'icon': 'react' } ---- - -# Getting started with OptiView Ads on React Native - -This guide will get you started with OptiView Ads in your OptiView Player React Native SDK: configure the license, update dependencies and set the source description. - -## Prerequisites - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -1. You need to have an OptiView Player license which is compatible with OptiView Ads. This can be done through the [player portal](https://portal.theoplayer.com). -2. You need a correctly deployed [OptiView Ads signaling service](signaling-service.mdx). -3. Enable the OptiView Ads integration based on the target platform: - - - - The Android SDK is modular-based, so to enable OptiView Ads, simply include the extension by setting this flag in your gradle.properties: - ```groovy - # Enable THEOplayer Extensions (default: disabled) - THEOplayer_extensionTHEOads = true - ``` - - - To enable OptiView Ads you can add the "THEOADS" feature flag to react-native-theoplayer.json (or theoplayer-config.json) - - - Add a dependency to an OptiView Ads-enabled THEOplayer package: - ```bash - $ npm i theoplayer@npm:@theoplayer/theoads - ``` - - In addition, since OptiView Ads integrates with Google DAI Pod Serving, it is required to load the Google DAI script on your page: - - ```html - - ``` - - - - - -## Integration - -This guide assumes you know how to set up React Native with OptiView Player. -For more information regarding this check out the [OptiView Player getting started](/theoplayer/getting-started/frameworks/react-native/getting-started/). - -### Player configuration - -To make use of the OptiView Ads integration, only a specific source needs to be set: - -```javascript -player.source = { - sources: { - src: 'PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI', - type: 'application/x-mpegurl', - hlsDateRange: true, - }, - ads: [ - { - integration: 'theoads', - networkCode: 'NETWORK-CODE', - customAssetKey: 'CUSTOM-ASSET-KEY', - }, - ], -}; -``` - -- Notice that the `src` is different as usual. For OptiView Ads, a signaling server needs to be set up which acts as a proxy to parse the given manifest and insert the ad interstitials. - More information can be found [here](signaling-service.mdx). -- The `hlsDateRange` flag needs to be set to `true` as the ad markers are done using `EXT-X-DATERANGE` tags. -- The `ads` object needs to have its integration set to `theoads`. Furthermore, the `networkCode` and `customAssetKey` needs to be set according to your configured Google account. - -## More information - -- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) -- [The Advantages of Server-Guided Ad Insertion](https://optiview.dolby.com/solutions/personalized-advertising/) -- [Is Server-Guided Ad Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://optiview.dolby.com/resources/blog/advertising/what-is-sgai-server-guided-ad-insertion-in-streaming/) diff --git a/ads/getting-started/web.mdx b/ads/getting-started/web.mdx deleted file mode 100644 index ec585bfb2553..000000000000 --- a/ads/getting-started/web.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: Web -sidebar_custom_props: { 'icon': 'web' } ---- - -# Getting started with OptiView Ads on Web - -This guide will get you started with OptiView Ads in your OptiView Player Web SDK: configure the license, update dependencies and set the source description. - -## Prerequisites - -1. You need to have an OptiView Player license which is compatible with OptiView Ads. This can be done through the [player portal](https://portal.theoplayer.com). -2. You need a correctly deployed [OptiView Ads signaling service](signaling-service.mdx). -3. Your THEOplayer SDK needs to have the `theoads` feature enabled. - - As of OptiView Player version 8.2.0, this feature is enabled by default in the main `theoplayer` package so we recommend to use at least this version, preferably the latest available version. - You can install this package with the following command: - - ```bash - npm install theoplayer - ``` - -## Integration - -This guide assumes you know how to set up OptiView Player. For more information regarding this, check out the [OptiView Player getting started](/theoplayer/getting-started/sdks/web/getting-started/). - -### Google DAI library - -Since OptiView Ads integrates with Google DAI Pod Serving, it is required to load the Google DAI script on your page: - -```html - -``` - -### Player configuration - -To make use of the OptiView Ads integration, first enable the feature in your player configuration: - -```javascript -const player = new THEOplayer.Player(element, { - libraryLocation: 'YOUR-LIBRARY-LOCATION', - license: 'YOUR-LICENSE-WITH-OPTIVIEW-ADS', - ads: { - theoads: true, - }, -}); -``` - -Then, specify a source with an OptiView Ads-enabled ad description: - -```javascript -player.source = { - sources: { - src: 'PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI', - type: 'application/x-mpegurl', - hlsDateRange: true, - }, - ads: [ - { - integration: 'theoads', - networkCode: 'NETWORK-CODE', - customAssetKey: 'CUSTOM-ASSET-KEY', - }, - ], -}; -``` - -- Notice that the `src` is different as usual. For OptiView Ads, a signaling server needs to be set up which acts as a proxy to parse the given manifest and insert the ad interstitials. More information can be found [here](signaling-service.mdx). -- The `hlsDateRange` flag needs to be set to `true` as the ad markers are done using `EXT-X-DATERANGE` tags. -- The `ads` object needs to have its integration set to `theoads`. Furthermore, the `networkCode` and `customAssetKey` needs to be set according to your configured Google account. - -## Integrating with Open Video UI - -OptiView Ads works seamlessly together with [Open Video UI for Web](/open-video-ui/web/). You can pass your OptiView Ads-enabled source directly to the UI's `source` property: - -```html - - -``` - -It should look something like this: - -![Screenshot of Open Video UI playing an OptiView Ads stream](../assets/img/web-ui.png) - -## More information - -- [API references](pathname:///theoplayer/v11/api-reference/web/interfaces/TheoAdDescription.html) -- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) -- [The Advantages of Server-Guided Ad Insertion](https://optiview.dolby.com/solutions/personalized-advertising/) -- [Is Server-Guided Ad-Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://optiview.dolby.com/resources/blog/advertising/what-is-sgai-server-guided-ad-insertion-in-streaming/) diff --git a/ads/player-integration/bring-your-own-player/avplayer.mdx b/ads/player-integration/bring-your-own-player/avplayer.mdx new file mode 100644 index 000000000000..bb7d434e5e4c --- /dev/null +++ b/ads/player-integration/bring-your-own-player/avplayer.mdx @@ -0,0 +1,37 @@ +--- +sidebar_position: 5 +sidebar_label: AVPlayer +--- + +# Integrate with AVPlayer + +AVFoundation provides HLS date-range metadata through `AVPlayerItemMetadataCollector` and `AVDateRangeMetadataGroup`. Apple also provides HLS interstitial APIs through `AVPlayerInterstitialEvent`, `AVPlayerInterstitialEventController`, and `AVPlayerInterstitialEventMonitor`. See the [AVPlayerItemMetadataCollector documentation](https://developer.apple.com/documentation/avfoundation/avplayeritemmetadatacollector), [AVDateRangeMetadataGroup](https://developer.apple.com/documentation/avfoundation/avdaterangemetadatagroup), and [AVPlayerInterstitialEvent](https://developer.apple.com/documentation/avfoundation/avplayerinterstitialevent). + +```swift +let playerItem = AVPlayerItem(url: URL(string: "https://ADS-HOST/channel/monetized/master.m3u8")!) +let collector = AVPlayerItemMetadataCollector() + +collector.setDelegate(self, queue: .main) +playerItem.add(collector) + +func metadataCollector( + _ metadataCollector: AVPlayerItemMetadataCollector, + didCollect metadataGroups: [AVDateRangeMetadataGroup], + indexes: IndexSet, + for track: AVPlayerItemTrack +) { + for group in metadataGroups { + scheduleFullScreenAd( + start: group.startDate, + duration: group.endDate.timeIntervalSince(group.startDate) + ) + } +} + +let player = AVPlayer(playerItem: playerItem) +player.play() +``` + +For applications using Apple's interstitial flow, configure an `AVPlayerInterstitialEventController` with the HLS interstitial events and observe it with `AVPlayerInterstitialEventMonitor`. The Break Manifest remains an alternative: fetch `/manifest/v1/{orgId}/channels/{channelId}` immediately, retry failures after 10 seconds, and use its idle/active polling values. + +AVPlayer does not provide OptiView layout rendering or OptiView impression reporting; those remain application responsibilities. diff --git a/ads/player-integration/bring-your-own-player/exoplayer-media3.mdx b/ads/player-integration/bring-your-own-player/exoplayer-media3.mdx new file mode 100644 index 000000000000..ae4df48ecc3c --- /dev/null +++ b/ads/player-integration/bring-your-own-player/exoplayer-media3.mdx @@ -0,0 +1,48 @@ +--- +sidebar_position: 4 +sidebar_label: ExoPlayer / Media3 +--- + +# Integrate with ExoPlayer / Media3 + +Media3 exposes HLS metadata through `Player.Listener.onMetadata`. Depending on the Media3 version and stream configuration, HLS interstitials can also be handled with `HlsInterstitialsAdsLoader`. See the [Media3 HLS guide](https://developer.android.com/media/media3/exoplayer/hls), [`Player.Listener`](https://developer.android.com/reference/androidx/media3/common/Player.Listener), and [`HlsInterstitialsAdsLoader`](https://developer.android.com/reference/androidx/media3/exoplayer/hls/HlsInterstitialsAdsLoader). + +## Read HLS metadata + +```kotlin +class BreakMetadataListener( + private val onBreak: (id: String, durationSeconds: Double) -> Unit +) : Player.Listener { + override fun onMetadata(metadata: Metadata) { + for (index in 0 until metadata.length()) { + val entry: Metadata.Entry = metadata[index] + // Inspect the entry's SCTE-35 or date-range representation for your + // Media3 version, then schedule a full-screen ad in application code. + onBreak(entry.toString(), 0.0) + } + } +} + +val player = ExoPlayer.Builder(context).build() +player.addListener(BreakMetadataListener(::scheduleFullScreenAd)) +player.setMediaItem(MediaItem.fromUri("https://ADS-HOST/channel/monetized/master.m3u8")) +player.prepare() +player.play() +``` + +Use `HlsInterstitialsAdsLoader` when your application wants Media3's HLS interstitial support rather than inspecting metadata entries directly. It still does not provide OptiView layout rendering or OptiView impression reporting. + +## Poll the Break Manifest instead + +```kotlin +suspend fun loadBreakManifest(): BreakManifest { + val request = Request.Builder() + .url("https://ADS-HOST/manifest/v1/ORG-ID/channels/CHANNEL-ID") + .build() + val response = httpClient.newCall(request).execute() + if (!response.isSuccessful) error("Break Manifest HTTP ${response.code}") + return json.decodeFromString(response.body!!.string()) +} +``` + +Make the first request immediately, retry failures after 10 seconds, and use the response's `polling.idle` or `polling.active` value for continuous polling. diff --git a/ads/player-integration/bring-your-own-player/hls-js.mdx b/ads/player-integration/bring-your-own-player/hls-js.mdx new file mode 100644 index 000000000000..06d94091e59d --- /dev/null +++ b/ads/player-integration/bring-your-own-player/hls-js.mdx @@ -0,0 +1,64 @@ +--- +sidebar_position: 2 +sidebar_label: hls.js +--- + +# Integrate with hls.js + +hls.js exposes parsed HLS date ranges on the active `LevelDetails.dateRanges` map. Use the `LEVEL_UPDATED` event to inspect refreshed media-playlist details. See the [hls.js `LevelDetails` API](https://hlsjs.video-dev.org/api-docs/hls.js.leveldetails) and [events API](https://hlsjs.video-dev.org/api-docs/hls.js.events). + +## Option 1: poll the Break Manifest + +The following example makes an immediate request, retries failures after 10 seconds, and changes the polling interval based on whether the response contains an active break. It treats the first successful response as sufficient for a minimal integration; remove the `oneShot` guard for continuous scheduling. + +```javascript +const manifestUrl = 'https://ADS-HOST/manifest/v1/ORG-ID/channels/CHANNEL-ID'; +let timer; +let oneShot = true; + +async function loadBreakManifest() { + try { + const response = await fetch(manifestUrl); + if (!response.ok) throw new Error(`Break Manifest HTTP ${response.status}`); + + const manifest = await response.json(); + scheduleBreaks(manifest.breaks); + + if (oneShot) return; + const active = manifest.breaks.some((breakItem) => isActive(breakItem)); + timer = setTimeout(loadBreakManifest, (active ? manifest.polling.active : manifest.polling.idle) * 1000); + } catch (error) { + console.error('Break Manifest request failed', error); + timer = setTimeout(loadBreakManifest, 10_000); + } +} + +loadBreakManifest(); +``` + +`scheduleBreaks` is application code: render the `single` full-screen experience at each break's `start` for its `duration`, and apply any supported `controls`. + +## Option 2: read injected DATERANGE cues + +```javascript +const hls = new Hls(); +hls.loadSource('https://ADS-HOST/channel/monetized/master.m3u8'); +hls.attachMedia(video); + +hls.on(Hls.Events.LEVEL_UPDATED, (_event, data) => { + const dateRanges = data.details?.dateRanges ?? {}; + for (const [id, dateRange] of Object.entries(dateRanges)) { + if (!dateRange) continue; + const start = dateRange.startDate; + const duration = dateRange.duration ?? dateRange.plannedDuration; + startFullScreenAd({ id, start, duration }); + } +}); +``` + +The injected OUT and IN tags carry the break ID, wallclock dates, duration, and hexadecimal SCTE-35 attributes. hls.js does not render the ad experience for you; your application must coordinate the video element and ad UI. + +## More information + +- [hls.js `LevelDetails`](https://hlsjs.video-dev.org/api-docs/hls.js.leveldetails) +- [hls.js `Events`](https://hlsjs.video-dev.org/api-docs/hls.js.events) diff --git a/ads/player-integration/bring-your-own-player/index.mdx b/ads/player-integration/bring-your-own-player/index.mdx new file mode 100644 index 000000000000..1720e2336779 --- /dev/null +++ b/ads/player-integration/bring-your-own-player/index.mdx @@ -0,0 +1,77 @@ +--- +sidebar_position: 1 +sidebar_label: Bring your own player +--- + +# Bring your own player + +OptiView Ads does not require OptiView Player. Open-source and native players can integrate using either of these open contracts: + +1. **Break Manifest polling:** request `GET /manifest/v1/{orgId}/channels/{channelId}` directly and schedule the returned breaks. +2. **SSAI cue consumption:** play the channel's proxied monetized HLS URL and consume the `EXT-X-DATERANGE` cues injected into its media playlist. + +OptiView provides no first-party ad adapter or plugin for these players. You are responsible for rendering ads, scheduling transitions, and implementing ad tracking. + +For channel polling configuration and channel-level SSAI DAI integrations, see [Channels](../../concepts/channels). + +## Break Manifest contract + +The endpoint supports CORS for `GET` and `OPTIONS`: + +```text +GET /manifest/v1/{orgId}/channels/{channelId} +``` + +A response has this shape: + +```json +{ + "version": "1.0.0", + "timebase": "wallclock", + "polling": { + "idle": 10, + "active": 1 + }, + "breaks": [ + { + "id": "break-123", + "start": "2026-01-01T12:00:00.000Z", + "duration": 30, + "controls": { + "skipOffset": 5, + "snapback": true + }, + "variant": { + "format": "single", + "assets": [] + } + } + ] +} +``` + +`timebase` is `wallclock` or `pts`. A wallclock break uses an ISO-8601 `start`; a PTS break uses a numeric `start`. `variant` may be one variant object or an array. Each variant has a `format` of `single`, `double`, `lshape_ad`, `lshape_content`, or `overlay`. + +Consumers should accept any `1.x` manifest version. Make an immediate request when loading the stream. If a request fails, retry after 10 seconds. After a successful response, use `polling.idle` (default 10 seconds) when no break is active and `polling.active` (default 1 second) during an active break. The first successful response is sufficient for a minimal integration; continuous polling is what keeps upcoming breaks fresh. + +Successful responses are JSON and carry `Cache-Control: public, max-age=`. A missing channel returns `404` with a short negative cache. + +## SSAI `EXT-X-DATERANGE` cues + +The SSAI path requires an `SSAI_DAI` channel integration. It carries Google DAI asset keys, and the service fans each signaled break out to Google DAI pod serving for those keys. Only wallclock channels receive injected cues; PTS channels do not. + +The proxy rewrites the media playlist and inserts two tags per break immediately before the segment whose wallclock window contains the cue: + +```text +#EXT-X-DATERANGE:ID="",START-DATE="",PLANNED-DURATION=,SCTE35-OUT= +#EXT-X-DATERANGE:ID="",START-DATE="",END-DATE="",DURATION=,SCTE35-IN= +``` + +There is no `CLASS` attribute and no custom `X-` attribute. `SCTE35-OUT` and `SCTE35-IN` contain hexadecimal SCTE-35 payloads. + +The open-source player examples show both approaches: + +- [hls.js](./hls-js) +- [Shaka Player](./shaka-player) +- [ExoPlayer / Media3](./exoplayer-media3) +- [AVPlayer](./avplayer) diff --git a/ads/player-integration/bring-your-own-player/shaka-player.mdx b/ads/player-integration/bring-your-own-player/shaka-player.mdx new file mode 100644 index 000000000000..58d2fc0f6635 --- /dev/null +++ b/ads/player-integration/bring-your-own-player/shaka-player.mdx @@ -0,0 +1,35 @@ +--- +sidebar_position: 3 +sidebar_label: Shaka Player +--- + +# Integrate with Shaka Player + +Shaka Player parses HLS `EXT-X-DATERANGE` data into timeline regions. Listen for `timelineregionadded`, `timelineregionenter`, and `timelineregionexit`; the event detail is a `shaka.extern.TimelineRegionInfo` object. See the [Shaka `Player` event API](https://shaka-player-demo.appspot.com/docs/api/shaka.Player.html#event:timelineregionadded) and [`TimelineRegionInfo`](https://shaka-player-demo.appspot.com/docs/api/shaka.extern.html#TimelineRegionInfo). + +```javascript +const player = new shaka.Player(video); + +player.addEventListener('timelineregionadded', (event) => { + const region = event.detail; + if (region.schemeIdUri === 'urn:scte:scte35:2013:bin') { + startFullScreenAd({ + id: region.id, + start: region.startTime, + duration: region.endTime - region.startTime, + }); + } +}); + +player.addEventListener('timelineregionenter', (event) => { + handleBreakStart(event.detail); +}); + +player.addEventListener('timelineregionexit', (event) => { + handleBreakEnd(event.detail); +}); + +await player.load('https://ADS-HOST/channel/monetized/master.m3u8'); +``` + +Use the [Break Manifest endpoint](../../../concepts/channels) instead when you want to schedule breaks before their HLS cue reaches the player. Shaka does not provide OptiView layout rendering or OptiView impression reporting; those remain application responsibilities. diff --git a/ads/player-integration/index.mdx b/ads/player-integration/index.mdx new file mode 100644 index 000000000000..7c03333ed433 --- /dev/null +++ b/ads/player-integration/index.mdx @@ -0,0 +1,46 @@ +--- +sidebar_position: 1 +sidebar_label: Player integration +--- + +# Player integration + +OptiView Ads is designed to work with the [OptiView Player](./optiview-player/), but you are not required to use it. The [Break Manifest](./bring-your-own-player/) and SSAI `EXT-X-DATERANGE` cue injection are open contracts that you can integrate with your own player. + +## Choose an integration path + +- **[OptiView Player](./optiview-player/)** is the recommended path. The Web, Android, and iOS SDKs handle Break Manifest polling, ad scheduling, Google IMA/DAI integration, and OptiView impression reporting. Chromecast CAF and React Native have platform-specific capabilities described in their guides. +- **[Bring your own player](./bring-your-own-player/)** is for open-source and native players. Poll the Break Manifest yourself, or consume the SSAI cues injected into a proxied media playlist. OptiView does not provide first-party adapters for these players. + +## Capability matrix + +| Capability | OptiView Player Web / Android / iOS | Chromecast CAF | React Native | hls.js | Shaka Player | ExoPlayer / Media3 | AVPlayer | +| ---------------------------------- | ----------------------------------------------------------------- | ------------------------------- | ------------------------ | --------------------- | ------------------------ | ----------------------------------- | ------------------------------------------------ | +| Automatic Break Manifest handling | Yes | Via sender/receiver integration | Platform-dependent | No | No | No | No | +| `breakManifestUrl` support | Yes | No | No | N/A | N/A | N/A | N/A | +| SSAI `EXT-X-DATERANGE` consumption | Yes | Receiver handles supported cues | Platform-dependent | Yes, application code | Yes, as timeline regions | Yes, via metadata/interstitial APIs | Yes, via AVFoundation metadata/interstitial APIs | +| Single (full-screen) ad | Yes | Yes | Yes | Application code | Application code | Application code | Application code | +| Double box | Defined in schema; not currently selected by current schedulers\* | No | Not currently selected\* | Application code | Application code | Application code | Application code | +| L-shape | Defined in schema; not currently selected by current schedulers\* | No | Not currently selected\* | Application code | Application code | Application code | Application code | +| Overlay | Defined in schema; not currently selected by current schedulers\* | Image overlays only | Not currently selected\* | Application code | Application code | Application code | Application code | +| Google IMA / DAI integration | Built in | Built in for supported CAF flow | Platform-dependent | Application code | Application code | Application code | Application code | +| OptiView impression reporting | Yes | No | No | No | No | No | No | + +The Break Manifest schema defines `single`, `double`, `lshape_ad`, `lshape_content`, and `overlay`. The current Web, Android, and iOS OptiView Player schedulers select the `single` layout only. Chromecast CAF currently supports image overlays only. + +## How ads are delivered and tracked + +OptiView Ads uses **server-guided ad insertion (SGAI)**: + +1. A channel's Break Manifest, or injected HLS cues, signals when an ad break occurs. +2. Google DAI / Pod Serving performs server-side ad decisioning and stitching. The OptiView Player configuration identifies the Google account with `networkCode` and `customAssetKey`. +3. The client-side Google IMA SDK handles the ad request and tracking. On Web this is the `ima3_dai.js` library; on iOS it is the `GoogleInteractiveMediaAds` SDK. + +Google IMA and Google DAI are related but different: IMA is the client-side library, while DAI / Pod Serving is the server-side ad-decisioning and stitching service. + +There are two impression types: + +- **OptiView impression beacon:** sent by OptiView Player once per ad experience with the player's `adbreakbegin` event. It is linked to the player license, contains no viewer data, and is visible in the portal. See [Ad impression tracking](../how-to-guides/ad-impressions.md). +- **Google ad-server impressions:** the standard IMA/DAI creative impression and tracking pings sent to Google Ad Manager. + +BYO players do not emit the OptiView impression beacon. They can still generate Google impressions if they implement the applicable IMA or ad-tracking integration. diff --git a/ads/player-integration/optiview-player/android.mdx b/ads/player-integration/optiview-player/android.mdx new file mode 100644 index 000000000000..25d25048c513 --- /dev/null +++ b/ads/player-integration/optiview-player/android.mdx @@ -0,0 +1,78 @@ +--- +sidebar_position: 3 +sidebar_label: Android +sidebar_custom_props: { 'icon': 'android' } +--- + +# OptiView Ads on Android + +This guide configures OptiView Ads in the OptiView Player Android SDK 11.x. + +## Prerequisites + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +1. Obtain an OptiView Player license compatible with OptiView Ads from the [player portal](https://portal.theoplayer.com). +2. Add the OptiView Player Android SDK by following the [Android getting started guide](/theoplayer/getting-started/sdks/android/getting-started). +3. Add the integration in your module-level Gradle file. + + + + +```groovy +dependencies { + implementation "com.theoplayer.theoplayer-sdk-android:core:11.+" + implementation "com.theoplayer.theoplayer-sdk-android:integration-ads-theoads:11.+" +} +``` + + + + +```kotlin +dependencies { + implementation("com.theoplayer.theoplayer-sdk-android:core:11.+") + implementation("com.theoplayer.theoplayer-sdk-android:integration-ads-theoads:11.+") +} +``` + + + + +## Integration + +```kotlin +val theoAdsIntegration = TheoAdsIntegrationFactory.createTheoAdsIntegration(theoPlayerView) +theoPlayerView.player.addIntegration(theoAdsIntegration) + +theoPlayerView.player.source = SourceDescription.Builder( + TypedSource.Builder("CHANNEL-MONETIZED-HLS-URL") + .type(SourceType.HLS) + .hlsDateRange(true) + .build() +).ads( + TheoAdDescription( + networkCode = "NETWORK-CODE", + customAssetKey = "CUSTOM-ASSET-KEY", + breakManifestUrl = "https://ADS-HOST/manifest/v1/ORG-ID/channels/CHANNEL-ID", + adTagParameters = mapOf("key" to "value") + ) +).build() +``` + +`breakManifestUrl` points to the v2 Break Manifest. `hlsDateRange(true)` enables handling of the SSAI cues in the channel's monetized HLS media playlist. + +## Integrating with Open Video UI + +Create and add `TheoAdsIntegration` before creating your UI, then use the same `SourceDescription` configuration above with [Open Video UI for Android](/open-video-ui/android/). + +## Verify + +Load the channel's monetized HLS source and start playback. Confirm that the Break Manifest or SSAI cues schedule a break, the ad renders, and the OptiView impression appears in the portal. + +## More information + +- [Android `TheoAdDescription` API](https://optiview.dolby.com/docs/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/theoads/TheoAdDescription.html) +- [Ad impression tracking](../../../how-to-guides/ad-impressions) +- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) diff --git a/ads/player-integration/optiview-player/chromecast.mdx b/ads/player-integration/optiview-player/chromecast.mdx new file mode 100644 index 000000000000..f54529dc13eb --- /dev/null +++ b/ads/player-integration/optiview-player/chromecast.mdx @@ -0,0 +1,48 @@ +--- +sidebar_position: 5 +sidebar_label: Chromecast CAF +sidebar_custom_props: { 'icon': 'web' } +--- + +# OptiView Ads on Chromecast CAF + +:::note +Chromecast CAF currently supports image overlays only from OptiView Ads. +::: + +## Prerequisites + +1. Obtain an OptiView Player license compatible with OptiView Ads from the [player portal](https://portal.theoplayer.com). +2. Install the sender and receiver packages: + + ```bash + npm install @opentelly/theoplayer-chromecast-sdk @opentelly/theoplayer-chromecast-receiver + ``` + +3. Have a Chromecast Developer account to deploy your custom CAF receiver. + +## Integration + +Use the receiver package with the CAF receiver framework and enable Shaka for HLS: + +```html + + +``` + +```javascript +const castReceiverOptions = new cast.framework.CastReceiverOptions(); +castReceiverOptions.useShakaForHls = true; +cast.framework.CastReceiverContext.getInstance().start(castReceiverOptions); +``` + +Configure the sender with the OptiView Player Chromecast SDK and the channel's monetized playback URL. Chromecast CAF uses the sender/receiver integration; it does not expose `breakManifestUrl` as a direct SDK configuration field. + +## Verify + +Cast the channel's monetized HLS source and start playback. Confirm that the scheduled break renders its supported image overlay, then verify the receiver completes the ad experience. + +## More information + +- [Chromecast integration](https://optiview.dolby.com/docs/theoplayer/how-to-guides/cast/chromecast/introduction/) +- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) diff --git a/ads/player-integration/optiview-player/index.mdx b/ads/player-integration/optiview-player/index.mdx new file mode 100644 index 000000000000..e02f1ff7d8c4 --- /dev/null +++ b/ads/player-integration/optiview-player/index.mdx @@ -0,0 +1,25 @@ +--- +sidebar_position: 1 +sidebar_label: OptiView Player +--- + +# OptiView Player + +OptiView Player is the recommended integration path for OptiView Ads. Its platform SDKs handle the Break Manifest and HLS cue details so your application can focus on playback and presentation. + +Built-in capabilities include: + +- Automatic Break Manifest polling through `breakManifestUrl` on Web, Android, and iOS. +- Google IMA / DAI integration using `networkCode`, `customAssetKey`, and optional `adTagParameters`. +- HLS `EXT-X-DATERANGE` handling for the channel's monetized playback URL. +- OptiView impression reporting on supported OptiView Player integrations. + +The Break Manifest schema defines five formats: `single`, `double`, `lshape_ad`, `lshape_content`, and `overlay`. The current Web, Android, and iOS schedulers select `single` only; the other formats are schema capabilities and are not currently selected by those schedulers. Chromecast CAF currently supports image overlays only. + +Choose a platform: + +- [Web](./web) +- [Android](./android) +- [iOS](./ios) +- [Chromecast CAF](./chromecast) +- [React Native](./react-native) diff --git a/ads/player-integration/optiview-player/ios.mdx b/ads/player-integration/optiview-player/ios.mdx new file mode 100644 index 000000000000..5355302f30a1 --- /dev/null +++ b/ads/player-integration/optiview-player/ios.mdx @@ -0,0 +1,81 @@ +--- +sidebar_position: 4 +sidebar_label: iOS +sidebar_custom_props: { 'icon': 'apple' } +--- + +# OptiView Ads on iOS + +This guide configures OptiView Ads in the OptiView Player iOS SDK 11.x. + +## Prerequisites + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +1. Obtain an OptiView Player license compatible with OptiView Ads from the [player portal](https://portal.theoplayer.com). +2. Add `THEOplayer-Integration-THEOads` to your project. + + + + +```ruby +pod 'THEOplayer-Integration-THEOads', '~> 11.6.1' +``` + + + + +Add `https://github.com/THEOplayer/theoplayer-sdk-apple` and select `THEOplayerTHEOadsIntegration`. + +![Screenshot of Xcode file menu](../../assets/img/ios-xcode-file-menu.png) + +![Screenshot of SwiftPM menu](../../assets/img/ios-swiftpm-menu.png) + +![Screenshot of SwiftPM product selection](../../assets/img/ios-swiftpm-product-selection.png) + + + + +3. Add Google IMA. CocoaPods uses `GoogleAds-IMA-iOS-SDK`; SwiftPM uses the `GoogleInteractiveMediaAds` product. + + ![Screenshot of Xcode file menu for Google IMA](../../assets/img/ios-xcode-file-menu.png) + + ![Screenshot of SwiftPM menu for Google IMA](../../assets/img/ios-swiftpm-menu-google.png) + + ![Screenshot of SwiftPM Google product selection](../../assets/img/ios-swiftpm-product-selection-google.png) + +## Integration + +```swift +import THEOplayerSDK +import THEOplayerTHEOadsIntegration + +let theoads = THEOadsIntegrationFactory.createIntegration(on: theoplayer) +theoplayer.addIntegration(theoads) + +let typedSource = TypedSource( + src: "CHANNEL-MONETIZED-HLS-URL", + type: "application/x-mpegurl", + hlsDateRange: true +) +let theoad = THEOAdDescription( + networkCode: "NETWORK-CODE", + customAssetKey: "CUSTOM-ASSET-KEY", + breakManifestUrl: URL(string: "https://ADS-HOST/manifest/v1/ORG-ID/channels/CHANNEL-ID"), + adTagParameters: ["key": "value"] +) +theoplayer.source = SourceDescription(source: typedSource, ads: [theoad]) +``` + +`breakManifestUrl` points to the v2 Break Manifest. `hlsDateRange` enables handling of the SSAI cues in the channel's monetized HLS media playlist. + +## Verify + +Load the channel's monetized HLS source and start playback. Confirm that the Break Manifest or SSAI cues schedule a break, the ad renders, and the OptiView impression appears in the portal. + +## More information + +- [iOS `THEOAdDescription` API](https://optiview.dolby.com/docs/theoplayer/v11/api-reference/ios/Structs/THEOAdDescription.html) +- [Ad impression tracking](../../../how-to-guides/ad-impressions) +- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) diff --git a/ads/player-integration/optiview-player/react-native.mdx b/ads/player-integration/optiview-player/react-native.mdx new file mode 100644 index 000000000000..7743f70f02b2 --- /dev/null +++ b/ads/player-integration/optiview-player/react-native.mdx @@ -0,0 +1,75 @@ +--- +sidebar_position: 6 +sidebar_label: React Native +sidebar_custom_props: { 'icon': 'react' } +--- + +# OptiView Ads on React Native + +The React Native integration is independently versioned. This guide targets `react-native-theoplayer` **11.4.0**, while the OptiView Player SDK root is 11.6.1. + +## Prerequisites + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +1. Obtain an OptiView Player license compatible with OptiView Ads from the [player portal](https://portal.theoplayer.com). +2. Install `react-native-theoplayer` 11.4.0 and enable the THEOads platform feature. + + + + +Set `THEOplayer_extensionTHEOads = true` in `gradle.properties`. + + + + +Add the `THEOADS` feature flag to `react-native-theoplayer.json` (or `theoplayer-config.json`). + + + + +```bash +npm install react-native-theoplayer@11.4.0 +``` + +Load the Google DAI library: + +```html + +``` + + + + +## Integration + +```javascript +player.source = { + sources: { + src: 'CHANNEL-MONETIZED-HLS-URL', + type: 'application/x-mpegurl', + hlsDateRange: true, + }, + ads: [ + { + integration: 'theoads', + networkCode: 'NETWORK-CODE', + customAssetKey: 'CUSTOM-ASSET-KEY', + adTagParameters: { key: 'value' }, + }, + ], +}; +``` + +React Native supports `adTagParameters`, but does not expose `breakManifestUrl`. Use the platform's OptiView Player integration for Break Manifest handling and the channel's monetized HLS URL. + +## Verify + +Load the channel's monetized HLS source and start playback. Confirm that the platform integration schedules a break from the Break Manifest or SSAI cues, the ad renders, and the OptiView impression appears in the portal. + +## More information + +- [React Native player getting started](/theoplayer/getting-started/frameworks/react-native/getting-started/) +- [Ad impression tracking](../../../how-to-guides/ad-impressions) +- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) diff --git a/ads/player-integration/optiview-player/web.mdx b/ads/player-integration/optiview-player/web.mdx new file mode 100644 index 000000000000..f1078a0a05bf --- /dev/null +++ b/ads/player-integration/optiview-player/web.mdx @@ -0,0 +1,72 @@ +--- +sidebar_position: 2 +sidebar_label: Web +sidebar_custom_props: { 'icon': 'web' } +--- + +# OptiView Ads on Web + +This guide configures OptiView Ads in the OptiView Player Web SDK 11.x. + +## Prerequisites + +1. Obtain an OptiView Player license compatible with OptiView Ads from the [player portal](https://portal.theoplayer.com). +2. Use the channel's monetized HLS playback URL (proxy/CDN). +3. Install the Web SDK: + + ```bash + npm install @opentelly/theoplayer + ``` + +## Integration + +Load the Google DAI library: + +```html + +``` + +Configure the player and source: + +```javascript +const player = new THEOplayer.Player(element, { + libraryLocation: 'YOUR-LIBRARY-LOCATION', + license: 'YOUR-LICENSE-WITH-OPTIVIEW-ADS', + ads: { theoads: true }, +}); + +player.source = { + sources: { + src: 'CHANNEL-MONETIZED-HLS-URL', + type: 'application/x-mpegurl', + hlsDateRange: true, + }, + ads: [ + { + integration: 'theoads', + networkCode: 'NETWORK-CODE', + customAssetKey: 'CUSTOM-ASSET-KEY', + breakManifestUrl: 'https://ADS-HOST/manifest/v1/ORG-ID/channels/CHANNEL-ID', + adTagParameters: { key: 'value' }, + }, + ], +}; +``` + +`breakManifestUrl` is the v2 Break Manifest endpoint. `hlsDateRange: true` enables handling of the SSAI cues in the monetized HLS media playlist. + +## Integrating with Open Video UI + +OptiView Ads works with [Open Video UI for Web](/open-video-ui/web/). Pass the same source and ad description to the UI's `source` property. + +![Screenshot of Open Video UI playing an OptiView Ads stream](../../assets/img/web-ui.png) + +## Verify + +Load the channel's monetized HLS source and start playback. Confirm that a break is scheduled from the Break Manifest or SSAI cues, the ad renders, and the OptiView impression appears in the portal. + +## More information + +- [Web `TheoAdDescription` API](https://optiview.dolby.com/docs/theoplayer/v11/api-reference/web/interfaces/TheoAdDescription.html) +- [Ad impression tracking](../../../how-to-guides/ad-impressions) +- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) diff --git a/redirectsAds.json b/redirectsAds.json index de04cf674b56..ed0023a6fdc5 100644 --- a/redirectsAds.json +++ b/redirectsAds.json @@ -65,15 +65,15 @@ }, { "from": "/theoads/getting-started/android/", - "to": "/ads/getting-started/android/" + "to": "/ads/player-integration/optiview-player/android/" }, { "from": "/theoads/getting-started/ios/", - "to": "/ads/getting-started/ios/" + "to": "/ads/player-integration/optiview-player/ios/" }, { "from": "/theoads/getting-started/react-native/", - "to": "/ads/getting-started/react-native/" + "to": "/ads/player-integration/optiview-player/react-native/" }, { "from": "/theoads/getting-started/signaling-service/", @@ -81,6 +81,26 @@ }, { "from": "/theoads/getting-started/web/", - "to": "/ads/getting-started/web/" + "to": "/ads/player-integration/optiview-player/web/" + }, + { + "from": "/ads/getting-started/web/", + "to": "/ads/player-integration/optiview-player/web/" + }, + { + "from": "/ads/getting-started/android/", + "to": "/ads/player-integration/optiview-player/android/" + }, + { + "from": "/ads/getting-started/ios/", + "to": "/ads/player-integration/optiview-player/ios/" + }, + { + "from": "/ads/getting-started/chromecast/", + "to": "/ads/player-integration/optiview-player/chromecast/" + }, + { + "from": "/ads/getting-started/react-native/", + "to": "/ads/player-integration/optiview-player/react-native/" } ] diff --git a/sidebarsAds.ts b/sidebarsAds.ts index 6582d8d51443..d245baee0c58 100644 --- a/sidebarsAds.ts +++ b/sidebarsAds.ts @@ -43,6 +43,63 @@ const sidebars: SidebarsConfig = { link: { type: 'doc', id: 'getting-started/index' }, items: [{ type: 'autogenerated', dirName: 'getting-started' }], }, + { + type: 'category', + label: 'Player integration', + description: 'Connect OptiView Ads to a player.', + collapsed: false, + customProps: { + icon: '▶️', + }, + link: { type: 'doc', id: 'player-integration/index' }, + items: [ + { + type: 'category', + label: 'OptiView Player', + customProps: { icon: '🎬' }, + link: { type: 'doc', id: 'player-integration/optiview-player/index' }, + items: [ + 'player-integration/optiview-player/web', + 'player-integration/optiview-player/android', + 'player-integration/optiview-player/ios', + 'player-integration/optiview-player/chromecast', + 'player-integration/optiview-player/react-native', + { + type: 'link', + label: 'Web TheoAdDescription API', + href: 'https://optiview.dolby.com/docs/theoplayer/v11/api-reference/web/interfaces/TheoAdDescription.html', + }, + { + type: 'link', + label: 'Android TheoAdDescription API', + href: 'https://optiview.dolby.com/docs/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/theoads/TheoAdDescription.html', + }, + { + type: 'link', + label: 'iOS THEOAdDescription API', + href: 'https://optiview.dolby.com/docs/theoplayer/v11/api-reference/ios/Structs/THEOAdDescription.html', + }, + { + type: 'link', + label: 'React Native TheoAdDescription API', + href: 'https://theoplayer.github.io/react-native-theoplayer/api/interfaces/TheoAdDescription.html', + }, + ], + }, + { + type: 'category', + label: 'Bring your own player', + customProps: { icon: '🧩' }, + link: { type: 'doc', id: 'player-integration/bring-your-own-player/index' }, + items: [ + 'player-integration/bring-your-own-player/hls-js', + 'player-integration/bring-your-own-player/shaka-player', + 'player-integration/bring-your-own-player/exoplayer-media3', + 'player-integration/bring-your-own-player/avplayer', + ], + }, + ], + }, { type: 'category', label: 'How-to guides', @@ -82,19 +139,7 @@ const sidebars: SidebarsConfig = { type: 'link', label: 'Web', customProps: { icon: 'web' }, - href: 'pathname:///theoplayer/v9/api-reference/web/interfaces/TheoAdDescription.html', - }, - { - type: 'link', - label: 'Android', - customProps: { icon: 'android' }, - href: 'pathname:///theoplayer/v9/api-reference/android/com/theoplayer/android/api/ads/theoads/package-summary.html', - }, - { - type: 'link', - label: 'React Native', - customProps: { icon: 'react' }, - href: 'https://theoplayer.github.io/react-native-theoplayer/api/interfaces/TheoAdDescription.html', + href: 'https://optiview.dolby.com/docs/theoplayer/v11/api-reference/web/interfaces/TheoAdDescription.html', }, ], }, diff --git a/theoplayer/getting-started/01-sdks/02-android/01-features.md b/theoplayer/getting-started/01-sdks/02-android/01-features.md index f06b0cc9d938..684252b87f2a 100644 --- a/theoplayer/getting-started/01-sdks/02-android/01-features.md +++ b/theoplayer/getting-started/01-sdks/02-android/01-features.md @@ -98,7 +98,7 @@ With Android THEOplayer SDK we currently support the following feature integrati | Chromecast | `integration-cast:+` | 3.4.0+ | [Chromecast Documentation](../../../how-to-guides/03-cast/01-chromecast/00-introduction.md#android-sdk) | | AWS MediaTailor | `integration-ads-mediatailor:+` | 4.0.0+ | [AWS MediaTailor Documentation](../../../how-to-guides/01-ads/12-mediatailor.md#android-sdk) | | Google DAI | `integration-ads-dai:+` | 4.3.0+ | [Google DAI Documentation](../../../how-to-guides/01-ads/08-google-dai.md#android-sdk) | -| Optiview Ads | `integration-ads-theoads:+` | 8.2.0+ | [Optiview Ads Documentation](/ads/getting-started/android/) | +| Optiview Ads | `integration-ads-theoads:+` | 8.2.0+ | [Optiview Ads Documentation](/ads/player-integration/optiview-player/android/) | | Millicast | `integration-millicast:+` | 8.2.0+ | [Millicast Documentation](pathname:///millicast/android-player/) | | Jetpack Media3 | `integration-media3:+` | 8.10.0+ | [Media3 Documentation](../../../how-to-guides/android/media3/getting-started.mdx) | diff --git a/theoplayer_versioned_docs/version-v10/getting-started/01-sdks/02-android/01-features.md b/theoplayer_versioned_docs/version-v10/getting-started/01-sdks/02-android/01-features.md index 052414866181..dc780d9ac89a 100644 --- a/theoplayer_versioned_docs/version-v10/getting-started/01-sdks/02-android/01-features.md +++ b/theoplayer_versioned_docs/version-v10/getting-started/01-sdks/02-android/01-features.md @@ -98,7 +98,7 @@ With Android THEOplayer SDK we currently support the following feature integrati | Chromecast | `integration-cast:+` | 3.4.0+ | [Chromecast Documentation](../../../how-to-guides/03-cast/01-chromecast/00-introduction.md#android-sdk) | | AWS MediaTailor | `integration-ads-mediatailor:+` | 4.0.0+ | [AWS MediaTailor Documentation](../../../how-to-guides/01-ads/12-mediatailor.md#android-sdk) | | Google DAI | `integration-ads-dai:+` | 4.3.0+ | [Google DAI Documentation](../../../how-to-guides/01-ads/08-google-dai.md#android-sdk) | -| Optiview Ads | `integration-ads-theoads:+` | 8.2.0+ | [Optiview Ads Documentation](/ads/getting-started/android/) | +| Optiview Ads | `integration-ads-theoads:+` | 8.2.0+ | [Optiview Ads Documentation](/ads/player-integration/optiview-player/android/) | | Millicast | `integration-millicast:+` | 8.2.0+ | [Millicast Documentation](pathname:///millicast/android-player/) | | Jetpack Media3 | `integration-media3:+` | 8.10.0+ | [Media3 Documentation](../../../how-to-guides/android/media3/getting-started.mdx) | diff --git a/theoplayer_versioned_docs/version-v8/getting-started/01-sdks/02-android/01-features.md b/theoplayer_versioned_docs/version-v8/getting-started/01-sdks/02-android/01-features.md index 22ac07897eb3..0a5dde20aa97 100644 --- a/theoplayer_versioned_docs/version-v8/getting-started/01-sdks/02-android/01-features.md +++ b/theoplayer_versioned_docs/version-v8/getting-started/01-sdks/02-android/01-features.md @@ -98,7 +98,7 @@ With Android THEOplayer SDK we currently support the following feature integrati | Chromecast | `integration-cast:+` | 3.4.0+ | [Chromecast Documentation](../../../how-to-guides/03-cast/01-chromecast/00-introduction.md#android-sdk) | | AWS MediaTailor | `integration-ads-mediatailor:+` | 4.0.0+ | [AWS MediaTailor Documentation](../../../how-to-guides/01-ads/12-mediatailor.md#android-sdk) | | Google DAI | `integration-ads-dai:+` | 4.3.0+ | [Google DAI Documentation](../../../how-to-guides/01-ads/08-google-dai.md#android-sdk) | -| THEOads | `integration-ads-theoads:+` | 8.2.0+ | [THEOads Documentation](/ads/getting-started/android/) | +| THEOads | `integration-ads-theoads:+` | 8.2.0+ | [THEOads Documentation](/ads/player-integration/optiview-player/android/) | | Millicast | `integration-millicast:+` | 8.2.0+ | [Millicast Documentation](../../../how-to-guides/android/millicast/getting-started.mdx) | | Jetpack Media3 | `integration-media3:+` | 8.10.0+ | [Media3 Documentation](../../../how-to-guides/android/media3/getting-started.mdx) | diff --git a/theoplayer_versioned_docs/version-v9/getting-started/01-sdks/02-android/01-features.md b/theoplayer_versioned_docs/version-v9/getting-started/01-sdks/02-android/01-features.md index f62e5969cdfd..696c9d1097fe 100644 --- a/theoplayer_versioned_docs/version-v9/getting-started/01-sdks/02-android/01-features.md +++ b/theoplayer_versioned_docs/version-v9/getting-started/01-sdks/02-android/01-features.md @@ -98,7 +98,7 @@ With Android THEOplayer SDK we currently support the following feature integrati | Chromecast | `integration-cast:+` | 3.4.0+ | [Chromecast Documentation](../../../how-to-guides/03-cast/01-chromecast/00-introduction.md#android-sdk) | | AWS MediaTailor | `integration-ads-mediatailor:+` | 4.0.0+ | [AWS MediaTailor Documentation](../../../how-to-guides/01-ads/12-mediatailor.md#android-sdk) | | Google DAI | `integration-ads-dai:+` | 4.3.0+ | [Google DAI Documentation](../../../how-to-guides/01-ads/08-google-dai.md#android-sdk) | -| Optiview Ads | `integration-ads-theoads:+` | 8.2.0+ | [Optiview Ads Documentation](/ads/getting-started/android/) | +| Optiview Ads | `integration-ads-theoads:+` | 8.2.0+ | [Optiview Ads Documentation](/ads/player-integration/optiview-player/android/) | | Millicast | `integration-millicast:+` | 8.2.0+ | [Millicast Documentation](pathname:///millicast/android-player/) | | Jetpack Media3 | `integration-media3:+` | 8.10.0+ | [Media3 Documentation](../../../how-to-guides/android/media3/getting-started.mdx) |