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 e8fc0999d86c..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/web/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..c5d1d0397e7b 100644 --- a/ads/getting-started/index.mdx +++ b/ads/getting-started/index.mdx @@ -9,7 +9,7 @@ import RebrandingNotice from '../callouts/_rebranding_notice.md'; -These guides provide the steps required to get started with OptiView Ads. They cover the deployment and API integration of the Signaling Service into your existing workflow, as well as the integration of OptiView Ads into your application using various OptiView Player SDKs. +These guides provide the steps required to get started with OptiView Ads. They cover the deployment and API integration of the Signaling Service into your existing workflow, as well as the integration of OptiView Ads into your application. import DocCardList from '@theme/DocCardList'; 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/integrations/google/pod-serving.mdx b/ads/integrations/google/pod-serving.mdx index 6016f149de15..96b3eb6cefa3 100644 --- a/ads/integrations/google/pod-serving.mdx +++ b/ads/integrations/google/pod-serving.mdx @@ -144,14 +144,12 @@ Additionally, creating a pod break that starts too close to the live point is re ## Related resources -| Resource | Relationship | -| --------------------------------------------------------------- | ------------------------------------------------------------------------ | -| [Google Ad Manager](./index.mdx) | The prerequisites shared by both Google delivery modes. | -| [Google DAI](./dai.mdx) | Server-side (SSAI) delivery for platforms without server-guided support. | -| [Channels](../../concepts/channels.mdx) | Hold the custom asset key used for Google Pod Serving. | -| [Breaks](../../concepts/breaks.mdx) | Carry the vendor asset that Google uses to make ad decisions. | -| [Break Manifest](../../concepts/break-manifest.mdx) | The manifest that announces the channel's breaks to players. | -| [Ad tag parameters](../../how-to-guides/ad-tag-parameters.md) | Passing ad tag parameters from the player. | -| [Getting started on Web](../../getting-started/web.mdx) | Set up an OptiView player with pod serving on web. | -| [Getting started on iOS](../../getting-started/ios.mdx) | Set up an OptiView player with pod serving on iOS. | -| [Getting started on Android](../../getting-started/android.mdx) | Set up an OptiView player with pod serving on Android. | +| Resource | Relationship | +| ------------------------------------------------------------- | ------------------------------------------------------------------------ | +| [Google Ad Manager](./index.mdx) | The prerequisites shared by both Google delivery modes. | +| [Google DAI](./dai.mdx) | Server-side (SSAI) delivery for platforms without server-guided support. | +| [Channels](../../concepts/channels.mdx) | Hold the custom asset key used for Google Pod Serving. | +| [Breaks](../../concepts/breaks.mdx) | Carry the vendor asset that Google uses to make ad decisions. | +| [Break Manifest](../../concepts/break-manifest.mdx) | The manifest that announces the channel's breaks to players. | +| [Ad tag parameters](../../how-to-guides/ad-tag-parameters.md) | Passing ad tag parameters from the player. | +| [Player integration](../../player-integration/index.mdx) | Set up a player with pod serving. | diff --git a/ads/player-integration/index.mdx b/ads/player-integration/index.mdx new file mode 100644 index 000000000000..8544000d1a49 --- /dev/null +++ b/ads/player-integration/index.mdx @@ -0,0 +1,18 @@ +--- +sidebar_position: 1 +sidebar_label: Player integration +--- + +# Player integration + +To play the ad breaks you schedule with OptiView Ads, your application needs a player integration that consumes the channel's [Break Manifest](../concepts/break-manifest.mdx). There are two integration paths: + +## OptiView Ads SDK (recommended) + +The [OptiView Ads SDK](./optiview-ads-sdk/index.mdx) lets you **bring your own player**. It handles the Break Manifest logic and ad tracking/analytics for you, while your application keeps full control over content playback. It is available for Web, Android, iOS, and React Native, with ready-made adapters for popular players. + +This is the recommended path for any new integration. + +## OptiView Player (legacy) + +The [OptiView Player](./optiview-player/index.mdx) SDKs ship with a built-in OptiView Ads integration that handles the Break Manifest logic, the Google IMA/DAI integrations, and OptiView Ads impressions. Use this path if your application is already built on OptiView Player. diff --git a/ads/player-integration/optiview-ads-sdk/android.mdx b/ads/player-integration/optiview-ads-sdk/android.mdx new file mode 100644 index 000000000000..3f1b157f83bc --- /dev/null +++ b/ads/player-integration/optiview-ads-sdk/android.mdx @@ -0,0 +1,58 @@ +--- +sidebar_position: 3 +sidebar_label: Android +--- + +# OptiView Ads SDK on Android + +On Android and Android TV, the OptiView Ads SDK is a native Kotlin library that works with the **OptiView Player (THEOplayer)** and **Media3 / ExoPlayer** 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](./index.mdx#retrieving-the-required-values). +2. For [Google Pod Serving](../../integrations/google/pod-serving.mdx), have your Google Ad Manager `networkCode` and the channel's `customAssetKey` at hand. +3. Add the OptiView Ads SDK for Android to your project. Contact us for access to the SDK artifacts. + +## 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: + +```kotlin +val sdk = OptiViewAds( + config = OptiViewAdsConfig(player = THEOplayerAdapter(theoPlayerView.player)), + renderer = OverlayAdRenderer(adContainer), +) + +sdk.startSession( + SessionConfig( + manifestUrl = "https://us.markers.optiview.dolby.com/manifest/v1/ORG-ID/channels/CHANNEL-ID", + customAssetKey = "CUSTOM-ASSET-KEY", + ) +) +``` + +From this point the SDK polls the [Break Manifest](../../concepts/break-manifest.mdx), 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) + +The `THEOplayerAdapter` wraps the `Player` of a `THEOplayerView`. Ads are rendered in an overlay view stacked above your content player view. + +**Limitations:** + +- Requires a valid THEOplayer license. +- Wallclock-scheduled breaks require the stream to carry `EXT-X-PROGRAM-DATE-TIME` tags. Without them, wallclock breaks cannot be matched. + +### Media3 / ExoPlayer + +The `ExoPlayerAdapter` wraps a Media3 `ExoPlayer` instance. Ads are rendered in an overlay view stacked above your content player view. + +**Limitations:** + +- Requires Media3 / ExoPlayer 1.4 or later and Android 5.0 (API level 21) or later. +- Wallclock-scheduled breaks require the stream to carry `EXT-X-PROGRAM-DATE-TIME` tags. Without them, wallclock breaks cannot be matched. + +### Custom players + +Any other player can be integrated by implementing the SDK's `PlayerAdapter` interface, which exposes playback position, timing information, and basic playback controls. Contact us for the adapter interface reference. diff --git a/ads/player-integration/optiview-ads-sdk/index.mdx b/ads/player-integration/optiview-ads-sdk/index.mdx new file mode 100644 index 000000000000..75286c76d360 --- /dev/null +++ b/ads/player-integration/optiview-ads-sdk/index.mdx @@ -0,0 +1,65 @@ +--- +sidebar_position: 1 +sidebar_label: OptiView Ads SDK +--- + +# OptiView Ads SDK + +The OptiView Ads SDK is the recommended way to integrate OptiView Ads into your application. It is **player-agnostic**: you bring your own player, and the SDK takes care of the OptiView Ads specifics: + +- **Break Manifest logic:** the SDK polls the channel's [Break Manifest](../../concepts/break-manifest.mdx) and schedules the announced breaks against your player's timeline. You do not implement any polling or scheduling yourself. +- **Ad playback:** the SDK renders the scheduled ads, including the different [break layouts](../../concepts/breaks.mdx#layouts), on top of your content player. +- **Ad tracking and analytics:** the SDK reports the ad impressions and tracking events for the ads it plays. + +The SDK is available for [Web](./web.mdx), [Android](./android.mdx), [iOS](./ios.mdx), and [React Native](./react-native.mdx). + +## How the SDK works with your player + +The SDK never talks to your player directly. All player interaction goes through a small **player adapter** interface, which exposes the playback state the SDK needs — most importantly the stream's timing information (such as the `EXT-X-PROGRAM-DATE-TIME` position on a live HLS stream) that breaks are scheduled against. The SDK ships ready-made adapters for popular players on each platform, and you can implement the adapter interface yourself for any other player. + +## Configuration + +Configuration is split into two levels: + +- **SDK configuration** is provided once, when you create the SDK instance. It describes your player and how ads should be presented. +- **Session configuration** is provided per channel, when you start a monetization session. It identifies the channel to monetize. + +### SDK configuration + +| Property | Description | +| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `player` | The adapter that wraps your content player. **Required.** | +| `container` | The element or view in which the SDK renders ads, stacked above your content player. **Required.** | +| `mode` | The ad insertion model: `sgai` (server-guided, the default) or `ssai` (server-side, for streams where the ads are stitched into the media stream). | +| `gam` | Google Ad Manager configuration for [Google Pod Serving](../../integrations/google/pod-serving.mdx): contains your `networkCode`. | +| `debug` | Enables verbose logging during development. | + +The SDK also exposes optional presentation settings — such as ad preloading, break chaining, and tune-in behavior — with sensible defaults. The platform pages describe the platform-specific options. + +### Session configuration + +| Property | Description | +| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `manifestUrl` | The channel's Break Manifest URL. **Required.** See [Retrieving the required values](#retrieving-the-required-values). | +| `customAssetKey` | The Google Pod Serving custom asset key of the channel. Required to play Google Ad Manager breaks. See [Google Pod Serving](../../integrations/google/pod-serving.mdx). | +| `assetParameters` | Session-level ad parameters, merged with the break's `assetParameters` and forwarded to Google as `adTagParameters`. Use these for player-side values such as device identifiers. See [Ad tag parameters](../../integrations/google/pod-serving.mdx#ad-tag-parameters). | + +## Retrieving the required values + +- **Break Manifest URL (`manifestUrl`):** every channel exposes its Break Manifest on a public endpoint. The URL follows the pattern `https://us.markers.optiview.dolby.com/manifest/v1/{orgId}/channels/{channelId}` (replace `us.` with `eu.` for the EU region), using your organization ID and the channel's ID. See the [Break Manifest endpoint](../../concepts/break-manifest.mdx#endpoint) for details. +- **Google `networkCode` and `customAssetKey`:** these come from your Google Ad Manager setup. See the [Google Ad Manager prerequisites](../../integrations/google/index.mdx) and [Google Pod Serving](../../integrations/google/pod-serving.mdx). + +## Choose a platform + +import DocCardList from '@theme/DocCardList'; + + + +## Related resources + +| Resource | Description | +| --------------------------------------------------------------- | ------------------------------------------------------------- | +| [Break Manifest](../../concepts/break-manifest.mdx) | The contract between the OptiView Ads backend and the player. | +| [Channels](../../concepts/channels.mdx) | The channel whose Break Manifest the SDK polls. | +| [Breaks](../../concepts/breaks.mdx) | The breaks the SDK schedules and plays. | +| [Google Pod Serving](../../integrations/google/pod-serving.mdx) | Google Ad Manager configuration for pod-served breaks. | diff --git a/ads/player-integration/optiview-ads-sdk/ios.mdx b/ads/player-integration/optiview-ads-sdk/ios.mdx new file mode 100644 index 000000000000..e69075db415d --- /dev/null +++ b/ads/player-integration/optiview-ads-sdk/ios.mdx @@ -0,0 +1,58 @@ +--- +sidebar_position: 4 +sidebar_label: iOS +--- + +# 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](./index.mdx#retrieving-the-required-values). +2. For [Google Pod Serving](../../integrations/google/pod-serving.mdx), have your Google Ad Manager `networkCode` and the channel's `customAssetKey` at hand. +3. Add the OptiView Ads SDK for iOS to your project. Contact us for access to the SDK artifacts. + +## 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", + customAssetKey: "CUSTOM-ASSET-KEY" + ) +) +``` + +From this point the SDK polls the [Break Manifest](../../concepts/break-manifest.mdx), 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) + +The `THEOplayerAdapter` wraps a `THEOplayer` instance. Ads are rendered in an overlay view stacked above your content player view. + +**Limitations:** + +- Requires a valid THEOplayer license. +- Wallclock-scheduled breaks require the stream to carry `EXT-X-PROGRAM-DATE-TIME` tags. Without them, wallclock breaks cannot be matched. + +### AVPlayer + +The `AVPlayerAdapter` 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. +- Wallclock-scheduled breaks require the stream to carry `EXT-X-PROGRAM-DATE-TIME` tags. Without them, wallclock breaks cannot be matched. + +### Custom players + +Any other player can be integrated by implementing the SDK's `PlayerAdapter` interface, which exposes playback position, timing information, and basic playback controls. Contact us for the adapter interface reference. diff --git a/ads/player-integration/optiview-ads-sdk/react-native.mdx b/ads/player-integration/optiview-ads-sdk/react-native.mdx new file mode 100644 index 000000000000..ba29c618d730 --- /dev/null +++ b/ads/player-integration/optiview-ads-sdk/react-native.mdx @@ -0,0 +1,57 @@ +--- +sidebar_position: 5 +sidebar_label: React Native +--- + +# OptiView Ads SDK on React Native + +On React Native, the OptiView Ads SDK bridges the native Android and iOS SDKs behind a typed JavaScript API. All timing-sensitive break scheduling runs natively, so playback stays smooth regardless of the JavaScript thread's load. + +## Prerequisites + +1. Retrieve the channel's Break Manifest URL. See [Retrieving the required values](./index.mdx#retrieving-the-required-values). +2. For [Google Pod Serving](../../integrations/google/pod-serving.mdx), have your Google Ad Manager `networkCode` and the channel's `customAssetKey` at hand. +3. Add the OptiView Ads SDK for React Native to your project. Contact us for access to the SDK artifacts. + +## Integration + +Attach the SDK to your host player once it is ready, then start a session with the channel's Break Manifest URL. The example below uses the OptiView Player (`react-native-theoplayer`): + +```tsx +import { THEOplayerView } from 'react-native-theoplayer'; +import { createOptiViewAds } from '@dolby-optiview/ads-react-native'; + +const onPlayerReady = async (player) => { + player.source = { sources: [{ src: CONTENT_URL, type: 'application/x-mpegurl' }] }; + const ads = createOptiViewAds({ nativeHandle: player.nativeHandle }); + await ads.startSession({ + manifestUrl: 'https://us.markers.optiview.dolby.com/manifest/v1/ORG-ID/channels/CHANNEL-ID', + customAssetKey: 'CUSTOM-ASSET-KEY', + }); +}; + +; +``` + +From this point the SDK polls the [Break Manifest](../../concepts/break-manifest.mdx), 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 (react-native-theoplayer) + +The SDK attaches to a `THEOplayerView` through its native player handle. + +**Limitations:** + +- Requires the React Native new architecture (TurboModules / Fabric). +- Wallclock-scheduled breaks require the stream to carry `EXT-X-PROGRAM-DATE-TIME` tags. Without them, wallclock breaks cannot be matched. + +### react-native-video + +The SDK attaches to a `react-native-video` player through its native player handle. + +**Limitations:** + +- Requires `react-native-video` v6. +- Requires the React Native new architecture (TurboModules / Fabric). +- Wallclock-scheduled breaks require the stream to carry `EXT-X-PROGRAM-DATE-TIME` tags. Without them, wallclock breaks cannot be matched. diff --git a/ads/player-integration/optiview-ads-sdk/web.mdx b/ads/player-integration/optiview-ads-sdk/web.mdx new file mode 100644 index 000000000000..551f824001e9 --- /dev/null +++ b/ads/player-integration/optiview-ads-sdk/web.mdx @@ -0,0 +1,94 @@ +--- +sidebar_position: 2 +sidebar_label: Web +--- + +# OptiView Ads SDK on Web + +On Web, the OptiView Ads SDK works with any HLS-capable player through a player adapter. Ready-made adapters are available for the **OptiView Player (THEOplayer)**, **HLS.js**, **Shaka Player**, and the browser's **native `